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