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