contrib/subversion/subversion/include/svn_config.h

   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 \f
  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 \f
  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 \f
 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 \f
 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 */