src/TortoiseMerge/svninclude/svn_config.h

   1 /**\r
   2  * @copyright\r
   3  * ====================================================================\r
   4  * Copyright (c) 2000-2008 CollabNet.  All rights reserved.\r
   5  *\r
   6  * This software is licensed as described in the file COPYING, which\r
   7  * you should have received as part of this distribution.  The terms\r
   8  * are also available at http://subversion.tigris.org/license-1.html.\r
   9  * If newer versions of this license are posted there, you may use a\r
  10  * newer version instead, at your option.\r
  11  *\r
  12  * This software consists of voluntary contributions made by many\r
  13  * individuals.  For exact contribution history, see the revision\r
  14  * history and logs, available at http://subversion.tigris.org/.\r
  15  * ====================================================================\r
  16  * @endcopyright\r
  17  *\r
  18  * @file svn_config.h\r
  19  * @brief Accessing SVN configuration files.\r
  20  */\r
  21 \r
  22 \r
  23 \f\r
  24 #ifndef SVN_CONFIG_H\r
  25 #define SVN_CONFIG_H\r
  26 \r
  27 #include <apr.h>        /* for apr_int64_t */\r
  28 #include <apr_pools.h>  /* for apr_pool_t */\r
  29 #include <apr_hash.h>   /* for apr_hash_t */\r
  30 \r
  31 #include "svn_types.h"\r
  32 \r
  33 #ifdef __cplusplus\r
  34 extern "C" {\r
  35 #endif /* __cplusplus */\r
  36 \r
  37 \r
  38 /**************************************************************************\r
  39  ***                                                                    ***\r
  40  ***  For a description of the SVN configuration file syntax, see       ***\r
  41  ***  your ~/.subversion/README, which is written out automatically by  ***\r
  42  ***  svn_config_ensure().                                              ***\r
  43  ***                                                                    ***\r
  44  **************************************************************************/\r
  45 \r
  46 \r
  47 /** Opaque structure describing a set of configuration options. */\r
  48 typedef struct svn_config_t svn_config_t;\r
  49 \r
  50 \f\r
  51 /*** Configuration Defines ***/\r
  52 \r
  53 /**\r
  54  * @name Client configuration files strings\r
  55  * Strings for the names of files, sections, and options in the\r
  56  * client configuration files.\r
  57  * @{\r
  58  */\r
  59 #define SVN_CONFIG_CATEGORY_SERVERS        "servers"\r
  60 #define SVN_CONFIG_SECTION_GROUPS               "groups"\r
  61 #define SVN_CONFIG_SECTION_GLOBAL               "global"\r
  62 #define SVN_CONFIG_OPTION_HTTP_PROXY_HOST           "http-proxy-host"\r
  63 #define SVN_CONFIG_OPTION_HTTP_PROXY_PORT           "http-proxy-port"\r
  64 #define SVN_CONFIG_OPTION_HTTP_PROXY_USERNAME       "http-proxy-username"\r
  65 #define SVN_CONFIG_OPTION_HTTP_PROXY_PASSWORD       "http-proxy-password"\r
  66 #define SVN_CONFIG_OPTION_HTTP_PROXY_EXCEPTIONS     "http-proxy-exceptions"\r
  67 #define SVN_CONFIG_OPTION_HTTP_TIMEOUT              "http-timeout"\r
  68 #define SVN_CONFIG_OPTION_HTTP_COMPRESSION          "http-compression"\r
  69 #define SVN_CONFIG_OPTION_NEON_DEBUG_MASK           "neon-debug-mask"\r
  70 #define SVN_CONFIG_OPTION_HTTP_AUTH_TYPES           "http-auth-types"\r
  71 #define SVN_CONFIG_OPTION_SSL_AUTHORITY_FILES       "ssl-authority-files"\r
  72 #define SVN_CONFIG_OPTION_SSL_TRUST_DEFAULT_CA      "ssl-trust-default-ca"\r
  73 #define SVN_CONFIG_OPTION_SSL_CLIENT_CERT_FILE      "ssl-client-cert-file"\r
  74 #define SVN_CONFIG_OPTION_SSL_CLIENT_CERT_PASSWORD  "ssl-client-cert-password"\r
  75 #define SVN_CONFIG_OPTION_SSL_PKCS11_PROVIDER       "ssl-pkcs11-provider"\r
  76 #define SVN_CONFIG_OPTION_HTTP_LIBRARY              "http-library"\r
  77 #define SVN_CONFIG_OPTION_STORE_PASSWORDS           "store-passwords"\r
  78 #define SVN_CONFIG_OPTION_STORE_PLAINTEXT_PASSWORDS "store-plaintext-passwords"\r
  79 #define SVN_CONFIG_OPTION_STORE_AUTH_CREDS          "store-auth-creds"\r
  80 #define SVN_CONFIG_OPTION_STORE_SSL_CLIENT_CERT_PP  "store-ssl-client-cert-pp"\r
  81 #define SVN_CONFIG_OPTION_STORE_SSL_CLIENT_CERT_PP_PLAINTEXT \\r
  82                                           "store-ssl-client-cert-pp-plaintext"\r
  83 #define SVN_CONFIG_OPTION_USERNAME                  "username"\r
  84 \r
  85 #define SVN_CONFIG_CATEGORY_CONFIG          "config"\r
  86 #define SVN_CONFIG_SECTION_AUTH                 "auth"\r
  87 #define SVN_CONFIG_OPTION_PASSWORD_STORES           "password-stores"\r
  88 #define SVN_CONFIG_OPTION_KWALLET_WALLET            "kwallet-wallet"\r
  89 #define SVN_CONFIG_OPTION_KWALLET_SVN_APPLICATION_NAME_WITH_PID "kwallet-svn-application-name-with-pid"\r
  90 /* The majority of options of the "auth" section\r
  91  * has been moved to SVN_CONFIG_CATEGORY_SERVERS. */\r
  92 #define SVN_CONFIG_SECTION_HELPERS              "helpers"\r
  93 #define SVN_CONFIG_OPTION_EDITOR_CMD                "editor-cmd"\r
  94 #define SVN_CONFIG_OPTION_DIFF_CMD                  "diff-cmd"\r
  95 #define SVN_CONFIG_OPTION_DIFF3_CMD                 "diff3-cmd"\r
  96 #define SVN_CONFIG_OPTION_DIFF3_HAS_PROGRAM_ARG     "diff3-has-program-arg"\r
  97 #define SVN_CONFIG_OPTION_MERGE_TOOL_CMD            "merge-tool-cmd"\r
  98 #define SVN_CONFIG_SECTION_MISCELLANY           "miscellany"\r
  99 #define SVN_CONFIG_OPTION_GLOBAL_IGNORES            "global-ignores"\r
 100 #define SVN_CONFIG_OPTION_LOG_ENCODING              "log-encoding"\r
 101 #define SVN_CONFIG_OPTION_USE_COMMIT_TIMES          "use-commit-times"\r
 102 #define SVN_CONFIG_OPTION_TEMPLATE_ROOT             "template-root"\r
 103 #define SVN_CONFIG_OPTION_ENABLE_AUTO_PROPS         "enable-auto-props"\r
 104 #define SVN_CONFIG_OPTION_NO_UNLOCK                 "no-unlock"\r
 105 #define SVN_CONFIG_OPTION_MIMETYPES_FILE            "mime-types-file"\r
 106 #define SVN_CONFIG_OPTION_PRESERVED_CF_EXTS         "preserved-conflict-file-exts"\r
 107 #define SVN_CONFIG_OPTION_INTERACTIVE_CONFLICTS     "interactive-conflicts"\r
 108 #define SVN_CONFIG_SECTION_TUNNELS              "tunnels"\r
 109 #define SVN_CONFIG_SECTION_AUTO_PROPS           "auto-props"\r
 110 /** @} */\r
 111 \r
 112 /** @name Repository conf directory configuration files strings\r
 113  * Strings for the names of sections and options in the\r
 114  * repository conf directory configuration files.\r
 115  * @{\r
 116  */\r
 117 /* For repository svnserve.conf files */\r
 118 #define SVN_CONFIG_SECTION_GENERAL              "general"\r
 119 #define SVN_CONFIG_OPTION_ANON_ACCESS               "anon-access"\r
 120 #define SVN_CONFIG_OPTION_AUTH_ACCESS               "auth-access"\r
 121 #define SVN_CONFIG_OPTION_PASSWORD_DB               "password-db"\r
 122 #define SVN_CONFIG_OPTION_REALM                     "realm"\r
 123 #define SVN_CONFIG_OPTION_AUTHZ_DB                  "authz-db"\r
 124 #define SVN_CONFIG_SECTION_SASL                 "sasl"\r
 125 #define SVN_CONFIG_OPTION_USE_SASL                  "use-sasl"\r
 126 #define SVN_CONFIG_OPTION_MIN_SSF                   "min-encryption"\r
 127 #define SVN_CONFIG_OPTION_MAX_SSF                   "max-encryption"\r
 128 \r
 129 /* For repository password database */\r
 130 #define SVN_CONFIG_SECTION_USERS                "users"\r
 131 /** @} */\r
 132 \r
 133 /*** Configuration Default Values ***/\r
 134 \r
 135 /* '*' matches leading dots, e.g. '*.rej' matches '.foo.rej'. */\r
 136 /* We want this to be printed on two lines in the generated config file,\r
 137  * but we don't want the # character to end up in the variable.\r
 138  */\r
 139 #define SVN_CONFIG__DEFAULT_GLOBAL_IGNORES_LINE_1 \\r
 140   "*.o *.lo *.la *.al .libs *.so *.so.[0-9]* *.a *.pyc *.pyo"\r
 141 #define SVN_CONFIG__DEFAULT_GLOBAL_IGNORES_LINE_2 \\r
 142   "*.rej *~ #*# .#* .*.swp .DS_Store"\r
 143 \r
 144 #define SVN_CONFIG_DEFAULT_GLOBAL_IGNORES \\r
 145   SVN_CONFIG__DEFAULT_GLOBAL_IGNORES_LINE_1 " " \\r
 146   SVN_CONFIG__DEFAULT_GLOBAL_IGNORES_LINE_2\r
 147 \r
 148 #define SVN_CONFIG_TRUE  "TRUE"\r
 149 #define SVN_CONFIG_FALSE "FALSE"\r
 150 #define SVN_CONFIG_ASK   "ASK"\r
 151 \r
 152 /* Default values for some options. Should be passed as default values\r
 153  * to svn_config_get and friends, instead of hard-coding the defaults in\r
 154  * multiple places. */\r
 155 #define SVN_CONFIG_DEFAULT_OPTION_STORE_PASSWORDS            TRUE\r
 156 #define SVN_CONFIG_DEFAULT_OPTION_STORE_PLAINTEXT_PASSWORDS  SVN_CONFIG_ASK\r
 157 #define SVN_CONFIG_DEFAULT_OPTION_STORE_AUTH_CREDS           TRUE\r
 158 #define SVN_CONFIG_DEFAULT_OPTION_STORE_SSL_CLIENT_CERT_PP   TRUE\r
 159 #define SVN_CONFIG_DEFAULT_OPTION_STORE_SSL_CLIENT_CERT_PP_PLAINTEXT \\r
 160                                                              SVN_CONFIG_ASK\r
 161 \r
 162 /** Read configuration information from the standard sources and merge it\r
 163  * into the hash @a *cfg_hash.  If @a config_dir is not NULL it specifies a\r
 164  * directory from which to read the configuration files, overriding all\r
 165  * other sources.  Otherwise, first read any system-wide configurations\r
 166  * (from a file or from the registry), then merge in personal\r
 167  * configurations (again from file or registry).  The hash and all its data\r
 168  * are allocated in @a pool.\r
 169  *\r
 170  * @a *cfg_hash is a hash whose keys are @c const char * configuration\r
 171  * categories (@c SVN_CONFIG_CATEGORY_SERVERS,\r
 172  * @c SVN_CONFIG_CATEGORY_CONFIG, etc.) and whose values are the @c\r
 173  * svn_config_t * items representing the configuration values for that\r
 174  * category.\r
 175  */\r
 176 svn_error_t *\r
 177 svn_config_get_config(apr_hash_t **cfg_hash,\r
 178                       const char *config_dir,\r
 179                       apr_pool_t *pool);\r
 180 \r
 181 \r
 182 /** Read configuration data from @a file (a file or registry path) into\r
 183  * @a *cfgp, allocated in @a pool.\r
 184  *\r
 185  * If @a file does not exist, then if @a must_exist, return an error,\r
 186  * otherwise return an empty @c svn_config_t.\r
 187  */\r
 188 svn_error_t *\r
 189 svn_config_read(svn_config_t **cfgp,\r
 190                 const char *file,\r
 191                 svn_boolean_t must_exist,\r
 192                 apr_pool_t *pool);\r
 193 \r
 194 /** Like svn_config_read(), but merges the configuration data from @a file\r
 195  * (a file or registry path) into @a *cfg, which was previously returned\r
 196  * from svn_config_read().  This function invalidates all value\r
 197  * expansions in @a cfg, so that the next svn_config_get() takes the\r
 198  * modifications into account.\r
 199  */\r
 200 svn_error_t *\r
 201 svn_config_merge(svn_config_t *cfg,\r
 202                  const char *file,\r
 203                  svn_boolean_t must_exist);\r
 204 \r
 205 \r
 206 /** Find the value of a (@a section, @a option) pair in @a cfg, set @a\r
 207  * *valuep to the value.\r
 208  *\r
 209  * If @a cfg is @c NULL, just sets @a *valuep to @a default_value. If\r
 210  * the value does not exist, expand and return @a default_value. @a\r
 211  * default_value can be NULL.\r
 212  *\r
 213  * The returned value will be valid at least until the next call to\r
 214  * svn_config_get(), or for the lifetime of @a default_value. It is\r
 215  * safest to consume the returned value immediately.\r
 216  *\r
 217  * This function may change @a cfg by expanding option values.\r
 218  */\r
 219 void\r
 220 svn_config_get(svn_config_t *cfg,\r
 221                const char **valuep,\r
 222                const char *section,\r
 223                const char *option,\r
 224                const char *default_value);\r
 225 \r
 226 /** Add or replace the value of a (@a section, @a option) pair in @a cfg with\r
 227  * @a value.\r
 228  *\r
 229  * This function invalidates all value expansions in @a cfg.\r
 230  *\r
 231  * To remove an option, pass NULL for the @c value.\r
 232  */\r
 233 void\r
 234 svn_config_set(svn_config_t *cfg,\r
 235                const char *section,\r
 236                const char *option,\r
 237                const char *value);\r
 238 \r
 239 /** Like svn_config_get(), but for boolean values.\r
 240  *\r
 241  * Parses the option as a boolean value. The recognized representations\r
 242  * are 'TRUE'/'FALSE', 'yes'/'no', 'on'/'off', '1'/'0'; case does not\r
 243  * matter. Returns an error if the option doesn't contain a known string.\r
 244  */\r
 245 svn_error_t *\r
 246 svn_config_get_bool(svn_config_t *cfg,\r
 247                     svn_boolean_t *valuep,\r
 248                     const char *section,\r
 249                     const char *option,\r
 250                     svn_boolean_t default_value);\r
 251 \r
 252 /** Like svn_config_set(), but for boolean values.\r
 253  *\r
 254  * Sets the option to 'TRUE'/'FALSE', depending on @a value.\r
 255  */\r
 256 void\r
 257 svn_config_set_bool(svn_config_t *cfg,\r
 258                     const char *section,\r
 259                     const char *option,\r
 260                     svn_boolean_t value);\r
 261 \r
 262 /** Like svn_config_get(), but only for yes/no/ask values.\r
 263  *\r
 264  * Parse @a option in @a section and set @a *valuep to one of\r
 265  * SVN_CONFIG_TRUE, SVN_CONFIG_FALSE, or SVN_CONFIG_ASK.  If there is\r
 266  * no setting for @a option, then parse @a default_value and set\r
 267  * @a *valuep accordingly.  If @a default_value is NULL, the result is\r
 268  * undefined, and may be an error; we recommend that you pass one of\r
 269  * SVN_CONFIG_TRUE, SVN_CONFIG_FALSE, or SVN_CONFIG_ASK for @a default value.\r
 270  *\r
 271  * Valid representations are (at least) "true"/"false", "yes"/"no",\r
 272  * "on"/"off", "1"/"0", and "ask"; they are case-insensitive.  Return\r
 273  * an SVN_ERR_BAD_CONFIG_VALUE error if either @a default_value or\r
 274  * @a option's value is not a valid representation.\r
 275  *\r
 276  * @since New in 1.6.\r
 277  */\r
 278 svn_error_t *\r
 279 svn_config_get_yes_no_ask(svn_config_t *cfg,\r
 280                           const char **valuep,\r
 281                           const char *section,\r
 282                           const char *option,\r
 283                           const char* default_value);\r
 284 \r
 285 /** Similar to @c svn_config_section_enumerator2_t, but is not\r
 286  * provided with a memory pool argument.\r
 287  *\r
 288  * See svn_config_enumerate_sections() for the details of this type.\r
 289  *\r
 290  * @deprecated Provided for backwards compatibility with the 1.2 API.\r
 291  */\r
 292 typedef svn_boolean_t (*svn_config_section_enumerator_t)(const char *name,\r
 293                                                          void *baton);\r
 294 \r
 295 /** Similar to svn_config_enumerate_sections2(), but uses a memory pool of\r
 296  * @a cfg instead of one that is explicitely provided.\r
 297  *\r
 298  * @deprecated Provided for backwards compatibility with the 1.2 API.\r
 299  */\r
 300 SVN_DEPRECATED\r
 301 int\r
 302 svn_config_enumerate_sections(svn_config_t *cfg,\r
 303                               svn_config_section_enumerator_t callback,\r
 304                               void *baton);\r
 305 \r
 306 /** A callback function used in enumerating config sections.\r
 307  *\r
 308  * See svn_config_enumerate_sections2() for the details of this type.\r
 309  *\r
 310  * @since New in 1.3.\r
 311  */\r
 312 typedef svn_boolean_t (*svn_config_section_enumerator2_t)(const char *name,\r
 313                                                           void *baton,\r
 314                                                           apr_pool_t *pool);\r
 315 \r
 316 /** Enumerate the sections, passing @a baton and the current section's name\r
 317  * to @a callback.  Continue the enumeration if @a callback returns @c TRUE.\r
 318  * Return the number of times @a callback was called.\r
 319  *\r
 320  * ### See kff's comment to svn_config_enumerate2().  It applies to this\r
 321  * function, too. ###\r
 322  *\r
 323  * @a callback's @a name parameter is only valid for the duration of the call.\r
 324  *\r
 325  * @since New in 1.3.\r
 326  */\r
 327 int\r
 328 svn_config_enumerate_sections2(svn_config_t *cfg,\r
 329                                svn_config_section_enumerator2_t callback,\r
 330                                void *baton, apr_pool_t *pool);\r
 331 \r
 332 /** Similar to @c svn_config_enumerator2_t, but is not\r
 333  * provided with a memory pool argument.\r
 334  * See svn_config_enumerate() for the details of this type.\r
 335  *\r
 336  * @deprecated Provided for backwards compatibility with the 1.2 API.\r
 337  */\r
 338 typedef svn_boolean_t (*svn_config_enumerator_t)(const char *name,\r
 339                                                  const char *value,\r
 340                                                  void *baton);\r
 341 \r
 342 /** Similar to svn_config_enumerate2(), but uses a memory pool of\r
 343  * @a cfg instead of one that is explicitely provided.\r
 344  *\r
 345  * @deprecated Provided for backwards compatibility with the 1.2 API.\r
 346  */\r
 347 SVN_DEPRECATED\r
 348 int\r
 349 svn_config_enumerate(svn_config_t *cfg,\r
 350                      const char *section,\r
 351                      svn_config_enumerator_t callback,\r
 352                      void *baton);\r
 353 \r
 354 \r
 355 /** A callback function used in enumerating config options.\r
 356  *\r
 357  * See svn_config_enumerate2() for the details of this type.\r
 358  *\r
 359  * @since New in 1.3.\r
 360  */\r
 361 typedef svn_boolean_t (*svn_config_enumerator2_t)(const char *name,\r
 362                                                   const char *value,\r
 363                                                   void *baton,\r
 364                                                   apr_pool_t *pool);\r
 365 \r
 366 /** Enumerate the options in @a section, passing @a baton and the current\r
 367  * option's name and value to @a callback.  Continue the enumeration if\r
 368  * @a callback returns @c TRUE.  Return the number of times @a callback\r
 369  * was called.\r
 370  *\r
 371  * ### kff asks: A more usual interface is to continue enumerating\r
 372  *     while @a callback does not return error, and if @a callback does\r
 373  *     return error, to return the same error (or a wrapping of it)\r
 374  *     from svn_config_enumerate().  What's the use case for\r
 375  *     svn_config_enumerate()?  Is it more likely to need to break out\r
 376  *     of an enumeration early, with no error, than an invocation of\r
 377  *     @a callback is likely to need to return an error? ###\r
 378  *\r
 379  * @a callback's @a name and @a value parameters are only valid for the\r
 380  * duration of the call.\r
 381  *\r
 382  * @since New in 1.3.\r
 383  */\r
 384 int\r
 385 svn_config_enumerate2(svn_config_t *cfg,\r
 386                       const char *section,\r
 387                       svn_config_enumerator2_t callback,\r
 388                       void *baton,\r
 389                       apr_pool_t *pool);\r
 390 \r
 391 /**\r
 392  * Return @c TRUE if @a section exists in @a cfg, @c FALSE otherwise.\r
 393  *\r
 394  * @since New in 1.4.\r
 395  */\r
 396 svn_boolean_t\r
 397 svn_config_has_section(svn_config_t *cfg,\r
 398                        const char *section);\r
 399 \r
 400 /** Enumerate the group @a master_section in @a cfg.  Each variable\r
 401  * value is interpreted as a list of glob patterns (separated by comma\r
 402  * and optional whitespace).  Return the name of the first variable\r
 403  * whose value matches @a key, or @c NULL if no variable matches.\r
 404  */\r
 405 const char *\r
 406 svn_config_find_group(svn_config_t *cfg,\r
 407                       const char *key,\r
 408                       const char *master_section,\r
 409                       apr_pool_t *pool);\r
 410 \r
 411 /** Retrieve value corresponding to @a option_name in @a cfg, or\r
 412  *  return @a default_value if none is found.\r
 413  *\r
 414  *  The config will first be checked for a default.\r
 415  *  If @a server_group is not @c NULL, the config will also be checked\r
 416  *  for an override in a server group,\r
 417  *\r
 418  */\r
 419 const char *\r
 420 svn_config_get_server_setting(svn_config_t *cfg,\r
 421                               const char* server_group,\r
 422                               const char* option_name,\r
 423                               const char* default_value);\r
 424 \r
 425 /** Retrieve value into @a result_value corresponding to @a option_name for a\r
 426  *  given @a server_group in @a cfg, or return @a default_value if none is\r
 427  *  found.\r
 428  *\r
 429  *  The config will first be checked for a default, then will be checked for\r
 430  *  an override in a server group. If the value found is not a valid integer,\r
 431  *  a @c svn_error_t* will be returned.\r
 432  */\r
 433 svn_error_t *\r
 434 svn_config_get_server_setting_int(svn_config_t *cfg,\r
 435                                   const char *server_group,\r
 436                                   const char *option_name,\r
 437                                   apr_int64_t default_value,\r
 438                                   apr_int64_t *result_value,\r
 439                                   apr_pool_t *pool);\r
 440 \r
 441 \r
 442 /** Set @a *valuep according to @a option_name for a given\r
 443  * @a  server_group in @a cfg, or set to @a default_value if no value is\r
 444  * specified.\r
 445  *\r
 446  * Check first a default, then for an override in a server group.  If\r
 447  * a value is found but is not a valid boolean, return an\r
 448  * SVN_ERR_BAD_CONFIG_VALUE error.\r
 449  *\r
 450  * @since New in 1.6.\r
 451  */\r
 452 svn_error_t *\r
 453 svn_config_get_server_setting_bool(svn_config_t *cfg,\r
 454                                    svn_boolean_t *valuep,\r
 455                                    const char *server_group,\r
 456                                    const char *option_name,\r
 457                                    svn_boolean_t default_value);\r
 458 \r
 459 \r
 460 \f\r
 461 /** Try to ensure that the user's ~/.subversion/ area exists, and create\r
 462  * no-op template files for any absent config files.  Use @a pool for any\r
 463  * temporary allocation.  If @a config_dir is not @c NULL it specifies a\r
 464  * directory from which to read the config overriding all other sources.\r
 465  *\r
 466  * Don't error if something exists but is the wrong kind (for example,\r
 467  * ~/.subversion exists but is a file, or ~/.subversion/servers exists\r
 468  * but is a directory).\r
 469  *\r
 470  * Also don't error if trying to create something and failing -- it's\r
 471  * okay for the config area or its contents not to be created.\r
 472  * However, if creating a config template file succeeds, return an\r
 473  * error if unable to initialize its contents.\r
 474  */\r
 475 svn_error_t *\r
 476 svn_config_ensure(const char *config_dir,\r
 477                   apr_pool_t *pool);\r
 478 \r
 479 \r
 480 \r
 481 \f\r
 482 /** Accessing cached authentication data in the user config area.\r
 483  *\r
 484  * @defgroup cached_authentication_data Cached authentication data\r
 485  * @{\r
 486  */\r
 487 \r
 488 \r
 489 /** A hash-key pointing to a realmstring.  Every file containing\r
 490  * authentication data should have this key.\r
 491  */\r
 492 #define SVN_CONFIG_REALMSTRING_KEY  "svn:realmstring"\r
 493 \r
 494 /** Use @a cred_kind and @a realmstring to locate a file within the\r
 495  * ~/.subversion/auth/ area.  If the file exists, initialize @a *hash\r
 496  * and load the file contents into the hash, using @a pool.  If the\r
 497  * file doesn't exist, set @a *hash to NULL.\r
 498  *\r
 499  * If @a config_dir is not NULL it specifies a directory from which to\r
 500  * read the config overriding all other sources.\r
 501  *\r
 502  * Besides containing the original credential fields, the hash will\r
 503  * also contain @c SVN_CONFIG_REALMSTRING_KEY.  The caller can examine\r
 504  * this value as a sanity-check that the correct file was loaded.\r
 505  *\r
 506  * The hashtable will contain <tt>const char *</tt> keys and\r
 507  * <tt>svn_string_t *</tt> values.\r
 508  */\r
 509 svn_error_t *\r
 510 svn_config_read_auth_data(apr_hash_t **hash,\r
 511                           const char *cred_kind,\r
 512                           const char *realmstring,\r
 513                           const char *config_dir,\r
 514                           apr_pool_t *pool);\r
 515 \r
 516 /** Use @a cred_kind and @a realmstring to create or overwrite a file\r
 517  * within the ~/.subversion/auth/ area.  Write the contents of @a hash into\r
 518  * the file.  If @a config_dir is not NULL it specifies a directory to read\r
 519  * the config overriding all other sources.\r
 520  *\r
 521  * Also, add @a realmstring to the file, with key @c\r
 522  * SVN_CONFIG_REALMSTRING_KEY.  This allows programs (or users) to\r
 523  * verify exactly which set credentials live within the file.\r
 524  *\r
 525  * The hashtable must contain <tt>const char *</tt> keys and\r
 526  * <tt>svn_string_t *</tt> values.\r
 527  */\r
 528 svn_error_t *\r
 529 svn_config_write_auth_data(apr_hash_t *hash,\r
 530                            const char *cred_kind,\r
 531                            const char *realmstring,\r
 532                            const char *config_dir,\r
 533                            apr_pool_t *pool);\r
 534 \r
 535 /** Put the absolute path to the user's configuration directory,\r
 536  * or to a file within that directory, into @a *path.\r
 537  *\r
 538  * If @a config_dir is not NULL, it must point to an alternative\r
 539  * config directory location. If it is NULL, the default location\r
 540  * is used.  If @a fname is not NULL, it must specify the last\r
 541  * component of the path to be returned. This can be used to create\r
 542  * a path to any file in the configuration directory.\r
 543  *\r
 544  * Do all allocations in @a pool.\r
 545  *\r
 546  * Hint:\r
 547  * To get the user configuration file, pass @c SVN_CONFIG_CATEGORY_CONFIG\r
 548  * for @a fname. To get the servers configuration file, pass\r
 549  * @c SVN_CONFIG_CATEGORY_SERVERS for @a fname.\r
 550  *\r
 551  * @since New in 1.6.\r
 552  */\r
 553 svn_error_t *\r
 554 svn_config_get_user_config_path(const char **path,\r
 555                                 const char *config_dir,\r
 556                                 const char *fname,\r
 557                                 apr_pool_t *pool);\r
 558 \r
 559 /** @} */\r
 560 \r
 561 #ifdef __cplusplus\r
 562 }\r
 563 #endif /* __cplusplus */\r
 564 \r
 565 #endif /* SVN_CONFIG_H */\r