svn_config.h revision 299742
1/** 2 * @copyright 3 * ==================================================================== 4 * Licensed to the Apache Software Foundation (ASF) under one 5 * or more contributor license agreements. See the NOTICE file 6 * distributed with this work for additional information 7 * regarding copyright ownership. The ASF licenses this file 8 * to you under the Apache License, Version 2.0 (the 9 * "License"); you may not use this file except in compliance 10 * with the License. You may obtain a copy of the License at 11 * 12 * http://www.apache.org/licenses/LICENSE-2.0 13 * 14 * Unless required by applicable law or agreed to in writing, 15 * software distributed under the License is distributed on an 16 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 17 * KIND, either express or implied. See the License for the 18 * specific language governing permissions and limitations 19 * under the License. 20 * ==================================================================== 21 * @endcopyright 22 * 23 * @file svn_config.h 24 * @brief Accessing SVN configuration files. 25 */ 26 27 28 29#ifndef SVN_CONFIG_H 30#define SVN_CONFIG_H 31 32#include <apr.h> /* for apr_int64_t */ 33#include <apr_pools.h> /* for apr_pool_t */ 34#include <apr_hash.h> /* for apr_hash_t */ 35 36#include "svn_types.h" 37#include "svn_io.h" 38 39#ifdef __cplusplus 40extern "C" { 41#endif /* __cplusplus */ 42 43 44/************************************************************************** 45 *** *** 46 *** For a description of the SVN configuration file syntax, see *** 47 *** your ~/.subversion/README, which is written out automatically by *** 48 *** svn_config_ensure(). *** 49 *** *** 50 **************************************************************************/ 51 52 53/** Opaque structure describing a set of configuration options. */ 54typedef struct svn_config_t svn_config_t; 55 56 57/*** Configuration Defines ***/ 58 59/** 60 * @name Client configuration files strings 61 * Strings for the names of files, sections, and options in the 62 * client configuration files. 63 * @{ 64 */ 65 66 /* This list of #defines is intentionally presented as a nested list 67 that matches the in-config hierarchy. */ 68 69#define SVN_CONFIG_CATEGORY_SERVERS "servers" 70#define SVN_CONFIG_SECTION_GROUPS "groups" 71#define SVN_CONFIG_SECTION_GLOBAL "global" 72#define SVN_CONFIG_OPTION_HTTP_PROXY_HOST "http-proxy-host" 73#define SVN_CONFIG_OPTION_HTTP_PROXY_PORT "http-proxy-port" 74#define SVN_CONFIG_OPTION_HTTP_PROXY_USERNAME "http-proxy-username" 75#define SVN_CONFIG_OPTION_HTTP_PROXY_PASSWORD "http-proxy-password" 76#define SVN_CONFIG_OPTION_HTTP_PROXY_EXCEPTIONS "http-proxy-exceptions" 77#define SVN_CONFIG_OPTION_HTTP_TIMEOUT "http-timeout" 78#define SVN_CONFIG_OPTION_HTTP_COMPRESSION "http-compression" 79/** @deprecated Not used since 1.8. */ 80#define SVN_CONFIG_OPTION_NEON_DEBUG_MASK "neon-debug-mask" 81/** @since New in 1.5. */ 82#define SVN_CONFIG_OPTION_HTTP_AUTH_TYPES "http-auth-types" 83#define SVN_CONFIG_OPTION_SSL_AUTHORITY_FILES "ssl-authority-files" 84#define SVN_CONFIG_OPTION_SSL_TRUST_DEFAULT_CA "ssl-trust-default-ca" 85#define SVN_CONFIG_OPTION_SSL_CLIENT_CERT_FILE "ssl-client-cert-file" 86#define SVN_CONFIG_OPTION_SSL_CLIENT_CERT_PASSWORD "ssl-client-cert-password" 87/** @deprecated Not used since 1.8. 88 * @since New in 1.5. */ 89#define SVN_CONFIG_OPTION_SSL_PKCS11_PROVIDER "ssl-pkcs11-provider" 90/** @since New in 1.5. */ 91#define SVN_CONFIG_OPTION_HTTP_LIBRARY "http-library" 92/** @since New in 1.1. */ 93#define SVN_CONFIG_OPTION_STORE_PASSWORDS "store-passwords" 94/** @since New in 1.6. */ 95#define SVN_CONFIG_OPTION_STORE_PLAINTEXT_PASSWORDS "store-plaintext-passwords" 96#define SVN_CONFIG_OPTION_STORE_AUTH_CREDS "store-auth-creds" 97/** @since New in 1.6. */ 98#define SVN_CONFIG_OPTION_STORE_SSL_CLIENT_CERT_PP "store-ssl-client-cert-pp" 99/** @since New in 1.6. */ 100#define SVN_CONFIG_OPTION_STORE_SSL_CLIENT_CERT_PP_PLAINTEXT \ 101 "store-ssl-client-cert-pp-plaintext" 102#define SVN_CONFIG_OPTION_USERNAME "username" 103/** @since New in 1.8. */ 104#define SVN_CONFIG_OPTION_HTTP_BULK_UPDATES "http-bulk-updates" 105/** @since New in 1.8. */ 106#define SVN_CONFIG_OPTION_HTTP_MAX_CONNECTIONS "http-max-connections" 107/** @since New in 1.9. */ 108#define SVN_CONFIG_OPTION_HTTP_CHUNKED_REQUESTS "http-chunked-requests" 109 110/** @since New in 1.9. */ 111#define SVN_CONFIG_OPTION_SERF_LOG_COMPONENTS "serf-log-components" 112/** @since New in 1.9. */ 113#define SVN_CONFIG_OPTION_SERF_LOG_LEVEL "serf-log-level" 114 115 116#define SVN_CONFIG_CATEGORY_CONFIG "config" 117#define SVN_CONFIG_SECTION_AUTH "auth" 118/** @since New in 1.6. */ 119#define SVN_CONFIG_OPTION_PASSWORD_STORES "password-stores" 120/** @since New in 1.6. */ 121#define SVN_CONFIG_OPTION_KWALLET_WALLET "kwallet-wallet" 122/** @since New in 1.6. */ 123#define SVN_CONFIG_OPTION_KWALLET_SVN_APPLICATION_NAME_WITH_PID "kwallet-svn-application-name-with-pid" 124/** @since New in 1.8. */ 125#define SVN_CONFIG_OPTION_SSL_CLIENT_CERT_FILE_PROMPT "ssl-client-cert-file-prompt" 126/* The majority of options of the "auth" section 127 * has been moved to SVN_CONFIG_CATEGORY_SERVERS. */ 128#define SVN_CONFIG_SECTION_HELPERS "helpers" 129#define SVN_CONFIG_OPTION_EDITOR_CMD "editor-cmd" 130#define SVN_CONFIG_OPTION_DIFF_CMD "diff-cmd" 131/** @since New in 1.7. */ 132#define SVN_CONFIG_OPTION_DIFF_EXTENSIONS "diff-extensions" 133#define SVN_CONFIG_OPTION_DIFF3_CMD "diff3-cmd" 134#define SVN_CONFIG_OPTION_DIFF3_HAS_PROGRAM_ARG "diff3-has-program-arg" 135/** @since New in 1.5. */ 136#define SVN_CONFIG_OPTION_MERGE_TOOL_CMD "merge-tool-cmd" 137#define SVN_CONFIG_SECTION_MISCELLANY "miscellany" 138#define SVN_CONFIG_OPTION_GLOBAL_IGNORES "global-ignores" 139#define SVN_CONFIG_OPTION_LOG_ENCODING "log-encoding" 140#define SVN_CONFIG_OPTION_USE_COMMIT_TIMES "use-commit-times" 141/** @deprecated Not used by Subversion since 2003/r847039 (well before 1.0) */ 142#define SVN_CONFIG_OPTION_TEMPLATE_ROOT "template-root" 143#define SVN_CONFIG_OPTION_ENABLE_AUTO_PROPS "enable-auto-props" 144/** @since New in 1.9. */ 145#define SVN_CONFIG_OPTION_ENABLE_MAGIC_FILE "enable-magic-file" 146/** @since New in 1.2. */ 147#define SVN_CONFIG_OPTION_NO_UNLOCK "no-unlock" 148/** @since New in 1.5. */ 149#define SVN_CONFIG_OPTION_MIMETYPES_FILE "mime-types-file" 150/** @since New in 1.5. */ 151#define SVN_CONFIG_OPTION_PRESERVED_CF_EXTS "preserved-conflict-file-exts" 152/** @since New in 1.7. */ 153#define SVN_CONFIG_OPTION_INTERACTIVE_CONFLICTS "interactive-conflicts" 154/** @since New in 1.7. */ 155#define SVN_CONFIG_OPTION_MEMORY_CACHE_SIZE "memory-cache-size" 156/** @since New in 1.9. */ 157#define SVN_CONFIG_OPTION_DIFF_IGNORE_CONTENT_TYPE "diff-ignore-content-type" 158#define SVN_CONFIG_SECTION_TUNNELS "tunnels" 159#define SVN_CONFIG_SECTION_AUTO_PROPS "auto-props" 160/** @since New in 1.8. */ 161#define SVN_CONFIG_SECTION_WORKING_COPY "working-copy" 162/** @since New in 1.8. */ 163#define SVN_CONFIG_OPTION_SQLITE_EXCLUSIVE "exclusive-locking" 164/** @since New in 1.8. */ 165#define SVN_CONFIG_OPTION_SQLITE_EXCLUSIVE_CLIENTS "exclusive-locking-clients" 166/** @since New in 1.9. */ 167#define SVN_CONFIG_OPTION_SQLITE_BUSY_TIMEOUT "busy-timeout" 168/** @} */ 169 170/** @name Repository conf directory configuration files strings 171 * Strings for the names of sections and options in the 172 * repository conf directory configuration files. 173 * @{ 174 */ 175/* For repository svnserve.conf files */ 176#define SVN_CONFIG_SECTION_GENERAL "general" 177#define SVN_CONFIG_OPTION_ANON_ACCESS "anon-access" 178#define SVN_CONFIG_OPTION_AUTH_ACCESS "auth-access" 179#define SVN_CONFIG_OPTION_PASSWORD_DB "password-db" 180#define SVN_CONFIG_OPTION_REALM "realm" 181#define SVN_CONFIG_OPTION_AUTHZ_DB "authz-db" 182/** @since New in 1.8. */ 183#define SVN_CONFIG_OPTION_GROUPS_DB "groups-db" 184/** @since New in 1.7. */ 185#define SVN_CONFIG_OPTION_FORCE_USERNAME_CASE "force-username-case" 186/** @since New in 1.8. */ 187#define SVN_CONFIG_OPTION_HOOKS_ENV "hooks-env" 188/** @since New in 1.5. */ 189#define SVN_CONFIG_SECTION_SASL "sasl" 190/** @since New in 1.5. */ 191#define SVN_CONFIG_OPTION_USE_SASL "use-sasl" 192/** @since New in 1.5. */ 193#define SVN_CONFIG_OPTION_MIN_SSF "min-encryption" 194/** @since New in 1.5. */ 195#define SVN_CONFIG_OPTION_MAX_SSF "max-encryption" 196 197/* For repository password database */ 198#define SVN_CONFIG_SECTION_USERS "users" 199/** @} */ 200 201/*** Configuration Default Values ***/ 202 203/* '*' matches leading dots, e.g. '*.rej' matches '.foo.rej'. */ 204/* We want this to be printed on two lines in the generated config file, 205 * but we don't want the # character to end up in the variable. 206 */ 207#ifndef DOXYGEN_SHOULD_SKIP_THIS 208#define SVN_CONFIG__DEFAULT_GLOBAL_IGNORES_LINE_1 \ 209 "*.o *.lo *.la *.al .libs *.so *.so.[0-9]* *.a *.pyc *.pyo __pycache__" 210#define SVN_CONFIG__DEFAULT_GLOBAL_IGNORES_LINE_2 \ 211 "*.rej *~ #*# .#* .*.swp .DS_Store [Tt]humbs.db" 212#endif 213 214#define SVN_CONFIG_DEFAULT_GLOBAL_IGNORES \ 215 SVN_CONFIG__DEFAULT_GLOBAL_IGNORES_LINE_1 " " \ 216 SVN_CONFIG__DEFAULT_GLOBAL_IGNORES_LINE_2 217 218#define SVN_CONFIG_TRUE "TRUE" 219#define SVN_CONFIG_FALSE "FALSE" 220#define SVN_CONFIG_ASK "ASK" 221 222/* Default values for some options. Should be passed as default values 223 * to svn_config_get and friends, instead of hard-coding the defaults in 224 * multiple places. */ 225#define SVN_CONFIG_DEFAULT_OPTION_STORE_PASSWORDS TRUE 226#define SVN_CONFIG_DEFAULT_OPTION_STORE_PLAINTEXT_PASSWORDS SVN_CONFIG_ASK 227#define SVN_CONFIG_DEFAULT_OPTION_STORE_AUTH_CREDS TRUE 228#define SVN_CONFIG_DEFAULT_OPTION_STORE_SSL_CLIENT_CERT_PP TRUE 229#define SVN_CONFIG_DEFAULT_OPTION_STORE_SSL_CLIENT_CERT_PP_PLAINTEXT \ 230 SVN_CONFIG_ASK 231#define SVN_CONFIG_DEFAULT_OPTION_HTTP_MAX_CONNECTIONS 4 232 233/** Read configuration information from the standard sources and merge it 234 * into the hash @a *cfg_hash. If @a config_dir is not NULL it specifies a 235 * directory from which to read the configuration files, overriding all 236 * other sources. Otherwise, first read any system-wide configurations 237 * (from a file or from the registry), then merge in personal 238 * configurations (again from file or registry). The hash and all its data 239 * are allocated in @a pool. 240 * 241 * @a *cfg_hash is a hash whose keys are @c const char * configuration 242 * categories (@c SVN_CONFIG_CATEGORY_SERVERS, 243 * @c SVN_CONFIG_CATEGORY_CONFIG, etc.) and whose values are the @c 244 * svn_config_t * items representing the configuration values for that 245 * category. 246 */ 247svn_error_t * 248svn_config_get_config(apr_hash_t **cfg_hash, 249 const char *config_dir, 250 apr_pool_t *pool); 251 252/** Set @a *cfgp to an empty @c svn_config_t structure, 253 * allocated in @a result_pool. 254 * 255 * Pass TRUE to @a section_names_case_sensitive if 256 * section names are to be populated case sensitively. 257 * 258 * Pass TRUE to @a option_names_case_sensitive if 259 * option names are to be populated case sensitively. 260 * 261 * @since New in 1.8. 262 */ 263svn_error_t * 264svn_config_create2(svn_config_t **cfgp, 265 svn_boolean_t section_names_case_sensitive, 266 svn_boolean_t option_names_case_sensitive, 267 apr_pool_t *result_pool); 268 269/** Similar to svn_config_create2, but always passes @c FALSE to 270 * @a option_names_case_sensitive. 271 * 272 * @since New in 1.7. 273 * @deprecated Provided for backward compatibility with 1.7 API. 274 */ 275SVN_DEPRECATED 276svn_error_t * 277svn_config_create(svn_config_t **cfgp, 278 svn_boolean_t section_names_case_sensitive, 279 apr_pool_t *result_pool); 280 281/** Read configuration data from @a file (a file or registry path) into 282 * @a *cfgp, allocated in @a pool. 283 * 284 * If @a file does not exist, then if @a must_exist, return an error, 285 * otherwise return an empty @c svn_config_t. 286 * 287 * If @a section_names_case_sensitive is @c TRUE, populate section name hashes 288 * case sensitively, except for the @c "DEFAULT" section. 289 * 290 * If @a option_names_case_sensitive is @c TRUE, populate option name hashes 291 * case sensitively. 292 * 293 * @since New in 1.8. 294 */ 295svn_error_t * 296svn_config_read3(svn_config_t **cfgp, 297 const char *file, 298 svn_boolean_t must_exist, 299 svn_boolean_t section_names_case_sensitive, 300 svn_boolean_t option_names_case_sensitive, 301 apr_pool_t *result_pool); 302 303/** Similar to svn_config_read3, but always passes @c FALSE to 304 * @a option_names_case_sensitive. 305 * 306 * @since New in 1.7. 307 * @deprecated Provided for backward compatibility with 1.7 API. 308 */ 309SVN_DEPRECATED 310svn_error_t * 311svn_config_read2(svn_config_t **cfgp, 312 const char *file, 313 svn_boolean_t must_exist, 314 svn_boolean_t section_names_case_sensitive, 315 apr_pool_t *result_pool); 316 317/** Similar to svn_config_read2, but always passes @c FALSE to 318 * @a section_names_case_sensitive. 319 * 320 * @deprecated Provided for backward compatibility with 1.6 API. 321 */ 322SVN_DEPRECATED 323svn_error_t * 324svn_config_read(svn_config_t **cfgp, 325 const char *file, 326 svn_boolean_t must_exist, 327 apr_pool_t *result_pool); 328 329/** Read configuration data from @a stream into @a *cfgp, allocated in 330 * @a result_pool. 331 * 332 * If @a section_names_case_sensitive is @c TRUE, populate section name hashes 333 * case sensitively, except for the @c "DEFAULT" section. 334 * 335 * If @a option_names_case_sensitive is @c TRUE, populate option name hashes 336 * case sensitively. 337 * 338 * @since New in 1.8. 339 */ 340 341svn_error_t * 342svn_config_parse(svn_config_t **cfgp, 343 svn_stream_t *stream, 344 svn_boolean_t section_names_case_sensitive, 345 svn_boolean_t option_names_case_sensitive, 346 apr_pool_t *result_pool); 347 348/** Like svn_config_read(), but merges the configuration data from @a file 349 * (a file or registry path) into @a *cfg, which was previously returned 350 * from svn_config_read(). This function invalidates all value 351 * expansions in @a cfg, so that the next svn_config_get() takes the 352 * modifications into account. 353 */ 354svn_error_t * 355svn_config_merge(svn_config_t *cfg, 356 const char *file, 357 svn_boolean_t must_exist); 358 359 360/** Find the value of a (@a section, @a option) pair in @a cfg, set @a 361 * *valuep to the value. 362 * 363 * If @a cfg is @c NULL, just sets @a *valuep to @a default_value. If 364 * the value does not exist, expand and return @a default_value. @a 365 * default_value can be NULL. 366 * 367 * The returned value will be valid at least until the next call to 368 * svn_config_get(), or for the lifetime of @a default_value. It is 369 * safest to consume the returned value immediately. 370 * 371 * This function may change @a cfg by expanding option values. 372 */ 373void 374svn_config_get(svn_config_t *cfg, 375 const char **valuep, 376 const char *section, 377 const char *option, 378 const char *default_value); 379 380/** Add or replace the value of a (@a section, @a option) pair in @a cfg with 381 * @a value. 382 * 383 * This function invalidates all value expansions in @a cfg. 384 * 385 * To remove an option, pass NULL for the @a value. 386 */ 387void 388svn_config_set(svn_config_t *cfg, 389 const char *section, 390 const char *option, 391 const char *value); 392 393/** Like svn_config_get(), but for boolean values. 394 * 395 * Parses the option as a boolean value. The recognized representations 396 * are 'TRUE'/'FALSE', 'yes'/'no', 'on'/'off', '1'/'0'; case does not 397 * matter. Returns an error if the option doesn't contain a known string. 398 */ 399svn_error_t * 400svn_config_get_bool(svn_config_t *cfg, 401 svn_boolean_t *valuep, 402 const char *section, 403 const char *option, 404 svn_boolean_t default_value); 405 406/** Like svn_config_set(), but for boolean values. 407 * 408 * Sets the option to 'TRUE'/'FALSE', depending on @a value. 409 */ 410void 411svn_config_set_bool(svn_config_t *cfg, 412 const char *section, 413 const char *option, 414 svn_boolean_t value); 415 416/** Like svn_config_get(), but for 64-bit signed integers. 417 * 418 * Parses the @a option in @a section of @a cfg as an integer value, 419 * setting @a *valuep to the result. If the option is not found, sets 420 * @a *valuep to @a default_value. If the option is found but cannot 421 * be converted to an integer, returns an error. 422 * 423 * @since New in 1.8. 424 */ 425svn_error_t * 426svn_config_get_int64(svn_config_t *cfg, 427 apr_int64_t *valuep, 428 const char *section, 429 const char *option, 430 apr_int64_t default_value); 431 432/** Like svn_config_set(), but for 64-bit signed integers. 433 * 434 * Sets the value of @a option in @a section of @a cfg to the signed 435 * decimal @a value. 436 * 437 * @since New in 1.8. 438 */ 439void 440svn_config_set_int64(svn_config_t *cfg, 441 const char *section, 442 const char *option, 443 apr_int64_t value); 444 445/** Like svn_config_get(), but only for yes/no/ask values. 446 * 447 * Parse @a option in @a section and set @a *valuep to one of 448 * SVN_CONFIG_TRUE, SVN_CONFIG_FALSE, or SVN_CONFIG_ASK. If there is 449 * no setting for @a option, then parse @a default_value and set 450 * @a *valuep accordingly. If @a default_value is NULL, the result is 451 * undefined, and may be an error; we recommend that you pass one of 452 * SVN_CONFIG_TRUE, SVN_CONFIG_FALSE, or SVN_CONFIG_ASK for @a default value. 453 * 454 * Valid representations are (at least) "true"/"false", "yes"/"no", 455 * "on"/"off", "1"/"0", and "ask"; they are case-insensitive. Return 456 * an SVN_ERR_BAD_CONFIG_VALUE error if either @a default_value or 457 * @a option's value is not a valid representation. 458 * 459 * @since New in 1.6. 460 */ 461svn_error_t * 462svn_config_get_yes_no_ask(svn_config_t *cfg, 463 const char **valuep, 464 const char *section, 465 const char *option, 466 const char* default_value); 467 468/** Like svn_config_get_bool(), but for tristate values. 469 * 470 * Set @a *valuep to #svn_tristate_true, #svn_tristate_false, or 471 * #svn_tristate_unknown, depending on the value of @a option in @a 472 * section of @a cfg. True and false values are the same as for 473 * svn_config_get_bool(); @a unknown_value specifies the option value 474 * allowed for third state (#svn_tristate_unknown). 475 * 476 * Use @a default_value as the default value if @a option cannot be 477 * found. 478 * 479 * @since New in 1.8. 480 */ 481svn_error_t * 482svn_config_get_tristate(svn_config_t *cfg, 483 svn_tristate_t *valuep, 484 const char *section, 485 const char *option, 486 const char *unknown_value, 487 svn_tristate_t default_value); 488 489/** Similar to @c svn_config_section_enumerator2_t, but is not 490 * provided with a memory pool argument. 491 * 492 * See svn_config_enumerate_sections() for the details of this type. 493 * 494 * @deprecated Provided for backwards compatibility with the 1.2 API. 495 */ 496typedef svn_boolean_t (*svn_config_section_enumerator_t)(const char *name, 497 void *baton); 498 499/** Similar to svn_config_enumerate_sections2(), but uses a memory pool of 500 * @a cfg instead of one that is explicitly provided. 501 * 502 * @deprecated Provided for backwards compatibility with the 1.2 API. 503 */ 504SVN_DEPRECATED 505int 506svn_config_enumerate_sections(svn_config_t *cfg, 507 svn_config_section_enumerator_t callback, 508 void *baton); 509 510/** A callback function used in enumerating config sections. 511 * 512 * See svn_config_enumerate_sections2() for the details of this type. 513 * 514 * @since New in 1.3. 515 */ 516typedef svn_boolean_t (*svn_config_section_enumerator2_t)(const char *name, 517 void *baton, 518 apr_pool_t *pool); 519 520/** Enumerate the sections, passing @a baton and the current section's name 521 * to @a callback. Continue the enumeration if @a callback returns @c TRUE. 522 * Return the number of times @a callback was called. 523 * 524 * ### See kff's comment to svn_config_enumerate2(). It applies to this 525 * function, too. ### 526 * 527 * @a callback's @a name parameter is only valid for the duration of the call. 528 * 529 * @since New in 1.3. 530 */ 531int 532svn_config_enumerate_sections2(svn_config_t *cfg, 533 svn_config_section_enumerator2_t callback, 534 void *baton, apr_pool_t *pool); 535 536/** Similar to @c svn_config_enumerator2_t, but is not 537 * provided with a memory pool argument. 538 * See svn_config_enumerate() for the details of this type. 539 * 540 * @deprecated Provided for backwards compatibility with the 1.2 API. 541 */ 542typedef svn_boolean_t (*svn_config_enumerator_t)(const char *name, 543 const char *value, 544 void *baton); 545 546/** Similar to svn_config_enumerate2(), but uses a memory pool of 547 * @a cfg instead of one that is explicitly provided. 548 * 549 * @deprecated Provided for backwards compatibility with the 1.2 API. 550 */ 551SVN_DEPRECATED 552int 553svn_config_enumerate(svn_config_t *cfg, 554 const char *section, 555 svn_config_enumerator_t callback, 556 void *baton); 557 558 559/** A callback function used in enumerating config options. 560 * 561 * See svn_config_enumerate2() for the details of this type. 562 * 563 * @since New in 1.3. 564 */ 565typedef svn_boolean_t (*svn_config_enumerator2_t)(const char *name, 566 const char *value, 567 void *baton, 568 apr_pool_t *pool); 569 570/** Enumerate the options in @a section, passing @a baton and the current 571 * option's name and value to @a callback. Continue the enumeration if 572 * @a callback returns @c TRUE. Return the number of times @a callback 573 * was called. 574 * 575 * ### kff asks: A more usual interface is to continue enumerating 576 * while @a callback does not return error, and if @a callback does 577 * return error, to return the same error (or a wrapping of it) 578 * from svn_config_enumerate(). What's the use case for 579 * svn_config_enumerate()? Is it more likely to need to break out 580 * of an enumeration early, with no error, than an invocation of 581 * @a callback is likely to need to return an error? ### 582 * 583 * @a callback's @a name and @a value parameters are only valid for the 584 * duration of the call. 585 * 586 * @since New in 1.3. 587 */ 588int 589svn_config_enumerate2(svn_config_t *cfg, 590 const char *section, 591 svn_config_enumerator2_t callback, 592 void *baton, 593 apr_pool_t *pool); 594 595/** 596 * Return @c TRUE if @a section exists in @a cfg, @c FALSE otherwise. 597 * 598 * @since New in 1.4. 599 */ 600svn_boolean_t 601svn_config_has_section(svn_config_t *cfg, 602 const char *section); 603 604/** Enumerate the group @a master_section in @a cfg. Each variable 605 * value is interpreted as a list of glob patterns (separated by comma 606 * and optional whitespace). Return the name of the first variable 607 * whose value matches @a key, or @c NULL if no variable matches. 608 */ 609const char * 610svn_config_find_group(svn_config_t *cfg, 611 const char *key, 612 const char *master_section, 613 apr_pool_t *pool); 614 615/** Retrieve value corresponding to @a option_name in @a cfg, or 616 * return @a default_value if none is found. 617 * 618 * The config will first be checked for a default. 619 * If @a server_group is not @c NULL, the config will also be checked 620 * for an override in a server group, 621 * 622 */ 623const char * 624svn_config_get_server_setting(svn_config_t *cfg, 625 const char* server_group, 626 const char* option_name, 627 const char* default_value); 628 629/** Retrieve value into @a result_value corresponding to @a option_name for a 630 * given @a server_group in @a cfg, or return @a default_value if none is 631 * found. 632 * 633 * The config will first be checked for a default, then will be checked for 634 * an override in a server group. If the value found is not a valid integer, 635 * a @c svn_error_t* will be returned. 636 */ 637svn_error_t * 638svn_config_get_server_setting_int(svn_config_t *cfg, 639 const char *server_group, 640 const char *option_name, 641 apr_int64_t default_value, 642 apr_int64_t *result_value, 643 apr_pool_t *pool); 644 645 646/** Set @a *valuep according to @a option_name for a given 647 * @a server_group in @a cfg, or set to @a default_value if no value is 648 * specified. 649 * 650 * Check first a default, then for an override in a server group. If 651 * a value is found but is not a valid boolean, return an 652 * SVN_ERR_BAD_CONFIG_VALUE error. 653 * 654 * @since New in 1.6. 655 */ 656svn_error_t * 657svn_config_get_server_setting_bool(svn_config_t *cfg, 658 svn_boolean_t *valuep, 659 const char *server_group, 660 const char *option_name, 661 svn_boolean_t default_value); 662 663 664 665/** Try to ensure that the user's ~/.subversion/ area exists, and create 666 * no-op template files for any absent config files. Use @a pool for any 667 * temporary allocation. If @a config_dir is not @c NULL it specifies a 668 * directory from which to read the config overriding all other sources. 669 * 670 * Don't error if something exists but is the wrong kind (for example, 671 * ~/.subversion exists but is a file, or ~/.subversion/servers exists 672 * but is a directory). 673 * 674 * Also don't error if trying to create something and failing -- it's 675 * okay for the config area or its contents not to be created. 676 * However, if creating a config template file succeeds, return an 677 * error if unable to initialize its contents. 678 */ 679svn_error_t * 680svn_config_ensure(const char *config_dir, 681 apr_pool_t *pool); 682 683 684 685 686/** Accessing cached authentication data in the user config area. 687 * 688 * @defgroup cached_authentication_data Cached authentication data 689 * @{ 690 */ 691 692 693/** 694 * Attributes of authentication credentials. 695 * 696 * The values of these keys are C strings. 697 * 698 * @note Some of these hash keys were also used in versions < 1.9 but were 699 * not part of the public API (except #SVN_CONFIG_REALMSTRING_KEY which 700 * has been present since 1.0). 701 * 702 * @defgroup cached_authentication_data_attributes Cached authentication data attributes 703 * @{ 704 */ 705 706/** A hash-key pointing to a realmstring. This attribute is mandatory. 707 * 708 * @since New in 1.0. 709 */ 710#define SVN_CONFIG_REALMSTRING_KEY "svn:realmstring" 711 712/** A hash-key for usernames. 713 * @since New in 1.9. 714 */ 715#define SVN_CONFIG_AUTHN_USERNAME_KEY "username" 716 717/** A hash-key for passwords. 718 * The password may be in plaintext or encrypted form, depending on 719 * the authentication provider. 720 * @since New in 1.9. 721 */ 722#define SVN_CONFIG_AUTHN_PASSWORD_KEY "password" 723 724/** A hash-key for passphrases, 725 * such as SSL client ceritifcate passphrases. The passphrase may be in 726 * plaintext or encrypted form, depending on the authentication provider. 727 * @since New in 1.9. 728 */ 729#define SVN_CONFIG_AUTHN_PASSPHRASE_KEY "passphrase" 730 731/** A hash-key for the type of a password or passphrase. The type 732 * indicates which provider owns the credential. 733 * @since New in 1.9. 734 */ 735#define SVN_CONFIG_AUTHN_PASSTYPE_KEY "passtype" 736 737/** A hash-key for SSL certificates. The value is the base64-encoded DER form 738 * certificate. 739 * @since New in 1.9. 740 * @note The value is not human readable. 741 */ 742#define SVN_CONFIG_AUTHN_ASCII_CERT_KEY "ascii_cert" 743 744/** A hash-key for recorded SSL certificate verification 745 * failures. Failures encoded as an ASCII integer containing any of the 746 * SVN_AUTH_SSL_* SSL server certificate failure bits defined in svn_auth.h. 747 * @since New in 1.9. 748 */ 749#define SVN_CONFIG_AUTHN_FAILURES_KEY "failures" 750 751 752/** @} */ 753 754/** Use @a cred_kind and @a realmstring to locate a file within the 755 * ~/.subversion/auth/ area. If the file exists, initialize @a *hash 756 * and load the file contents into the hash, using @a pool. If the 757 * file doesn't exist, set @a *hash to NULL. 758 * 759 * If @a config_dir is not NULL it specifies a directory from which to 760 * read the config overriding all other sources. 761 * 762 * Besides containing the original credential fields, the hash will 763 * also contain @c SVN_CONFIG_REALMSTRING_KEY. The caller can examine 764 * this value as a sanity-check that the correct file was loaded. 765 * 766 * The hashtable will contain <tt>const char *</tt> keys and 767 * <tt>svn_string_t *</tt> values. 768 */ 769svn_error_t * 770svn_config_read_auth_data(apr_hash_t **hash, 771 const char *cred_kind, 772 const char *realmstring, 773 const char *config_dir, 774 apr_pool_t *pool); 775 776/** Use @a cred_kind and @a realmstring to create or overwrite a file 777 * within the ~/.subversion/auth/ area. Write the contents of @a hash into 778 * the file. If @a config_dir is not NULL it specifies a directory to read 779 * the config overriding all other sources. 780 * 781 * Also, add @a realmstring to the file, with key @c 782 * SVN_CONFIG_REALMSTRING_KEY. This allows programs (or users) to 783 * verify exactly which set credentials live within the file. 784 * 785 * The hashtable must contain <tt>const char *</tt> keys and 786 * <tt>svn_string_t *</tt> values. 787 */ 788svn_error_t * 789svn_config_write_auth_data(apr_hash_t *hash, 790 const char *cred_kind, 791 const char *realmstring, 792 const char *config_dir, 793 apr_pool_t *pool); 794 795 796/** Callback for svn_config_walk_auth_data(). 797 * 798 * Called for each credential walked by that function (and able to be 799 * fully purged) to allow perusal and selective removal of credentials. 800 * 801 * @a cred_kind and @a realmstring specify the key of the credential. 802 * @a hash contains the hash data associated with the record. @a walk_baton 803 * is the baton passed to svn_config_walk_auth_data(). 804 * 805 * Before returning set @a *delete_cred to TRUE to remove the credential from 806 * the cache; leave @a *delete_cred unchanged or set it to FALSE to keep the 807 * credential. 808 * 809 * Implementations may return #SVN_ERR_CEASE_INVOCATION to indicate 810 * that the callback should not be called again. Note that when that 811 * error is returned, the value of @a delete_cred will still be 812 * honored and action taken if necessary. (For other returned errors, 813 * @a delete_cred is ignored by svn_config_walk_auth_data().) 814 * 815 * @since New in 1.8. 816 */ 817typedef svn_error_t * 818(*svn_config_auth_walk_func_t)(svn_boolean_t *delete_cred, 819 void *walk_baton, 820 const char *cred_kind, 821 const char *realmstring, 822 apr_hash_t *hash, 823 apr_pool_t *scratch_pool); 824 825/** Call @a walk_func with @a walk_baton and information describing 826 * each credential cached within the Subversion auth store located 827 * under @a config_dir. If the callback sets its delete_cred return 828 * flag, delete the associated credential. 829 * 830 * If @a config_dir is not NULL, it must point to an alternative 831 * config directory location. If it is NULL, the default location 832 * is used. 833 * 834 * @note @a config_dir may only be NULL in 1.8.2 and later. 835 * 836 * @note Removing credentials from the config-based disk store will 837 * not purge them from any open svn_auth_baton_t instance. Consider 838 * using svn_auth_forget_credentials() -- from the @a walk_func, 839 * even -- for this purpose. 840 * 841 * @note Removing credentials from the config-based disk store will 842 * not also remove any related credentials from third-party password 843 * stores. (Implementations of @a walk_func which delete credentials 844 * may wish to consult the "passtype" element of @a hash, if any, to 845 * see if a third-party store -- such as "gnome-keyring" or "kwallet" 846 * is being used to hold the most sensitive portion of the credentials 847 * for this @a cred_kind and @a realmstring.) 848 * 849 * @see svn_auth_forget_credentials() 850 * 851 * @since New in 1.8. 852 */ 853svn_error_t * 854svn_config_walk_auth_data(const char *config_dir, 855 svn_config_auth_walk_func_t walk_func, 856 void *walk_baton, 857 apr_pool_t *scratch_pool); 858 859/** Put the absolute path to the user's configuration directory, 860 * or to a file within that directory, into @a *path. 861 * 862 * If @a config_dir is not NULL, it must point to an alternative 863 * config directory location. If it is NULL, the default location 864 * is used. If @a fname is not NULL, it must specify the last 865 * component of the path to be returned. This can be used to create 866 * a path to any file in the configuration directory. 867 * 868 * Do all allocations in @a pool. 869 * 870 * Hint: 871 * To get the user configuration file, pass @c SVN_CONFIG_CATEGORY_CONFIG 872 * for @a fname. To get the servers configuration file, pass 873 * @c SVN_CONFIG_CATEGORY_SERVERS for @a fname. 874 * 875 * @since New in 1.6. 876 */ 877svn_error_t * 878svn_config_get_user_config_path(const char **path, 879 const char *config_dir, 880 const char *fname, 881 apr_pool_t *pool); 882 883/** Create a deep copy of the config object @a src and return 884 * it in @a cfgp, allocating the memory in @a pool. 885 * 886 * @since New in 1.8. 887 */ 888svn_error_t * 889svn_config_dup(svn_config_t **cfgp, 890 const svn_config_t *src, 891 apr_pool_t *pool); 892 893/** Create a deep copy of the config hash @a src_hash and return 894 * it in @a cfg_hash, allocating the memory in @a pool. 895 * 896 * @since New in 1.8. 897 */ 898svn_error_t * 899svn_config_copy_config(apr_hash_t **cfg_hash, 900 apr_hash_t *src_hash, 901 apr_pool_t *pool); 902 903/** @} */ 904 905#ifdef __cplusplus 906} 907#endif /* __cplusplus */ 908 909#endif /* SVN_CONFIG_H */ 910