subversion/include/svn_config.h

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