Main Page | Modules | Data Structures | File List | Data Fields | Globals | Related Pages

svn_config.h

Go to the documentation of this file.
00001 /** 
00002  * @copyright
00003  * ====================================================================
00004  * Copyright (c) 2000-2004 CollabNet.  All rights reserved.
00005  *
00006  * This software is licensed as described in the file COPYING, which
00007  * you should have received as part of this distribution.  The terms
00008  * are also available at http://subversion.tigris.org/license-1.html.
00009  * If newer versions of this license are posted there, you may use a
00010  * newer version instead, at your option.
00011  *
00012  * This software consists of voluntary contributions made by many
00013  * individuals.  For exact contribution history, see the revision
00014  * history and logs, available at http://subversion.tigris.org/.
00015  * ====================================================================
00016  * @endcopyright
00017  *
00018  * @file svn_config.h
00019  * @brief Accessing SVN configuration files.
00020  */
00021 
00022 
00023 
00024 #ifndef SVN_CONFIG_H
00025 #define SVN_CONFIG_H
00026 
00027 #include <apr_pools.h>
00028 
00029 #include "svn_types.h"
00030 #include "svn_error.h"
00031 
00032 
00033 #ifdef __cplusplus
00034 extern "C" {
00035 #endif /* __cplusplus */
00036 
00037 
00038 /**************************************************************************
00039  ***                                                                    ***
00040  ***  For a description of the SVN configuration file syntax, see       ***
00041  ***  your ~/.subversion/README, which is written out automatically by  ***
00042  ***  svn_config_ensure().                                              ***
00043  ***                                                                    ***
00044  **************************************************************************/
00045 
00046 
00047 /** Opaque structure describing a set of configuration options. */
00048 typedef struct svn_config_t svn_config_t;
00049 
00050 
00051 /*** Configuration Defines ***/
00052 
00053 /**
00054  * @name Client configuration files strings
00055  * Strings for the names of files, sections, and options in the
00056  * client configuration files.
00057  * @{
00058  */
00059 #define SVN_CONFIG_CATEGORY_SERVERS        "servers"
00060 #define SVN_CONFIG_SECTION_GROUPS               "groups"
00061 #define SVN_CONFIG_SECTION_GLOBAL               "global"
00062 #define SVN_CONFIG_OPTION_HTTP_PROXY_HOST           "http-proxy-host"
00063 #define SVN_CONFIG_OPTION_HTTP_PROXY_PORT           "http-proxy-port"
00064 #define SVN_CONFIG_OPTION_HTTP_PROXY_USERNAME       "http-proxy-username"
00065 #define SVN_CONFIG_OPTION_HTTP_PROXY_PASSWORD       "http-proxy-password"
00066 #define SVN_CONFIG_OPTION_HTTP_PROXY_EXCEPTIONS     "http-proxy-exceptions"
00067 #define SVN_CONFIG_OPTION_HTTP_TIMEOUT              "http-timeout"
00068 #define SVN_CONFIG_OPTION_HTTP_COMPRESSION          "http-compression"
00069 #define SVN_CONFIG_OPTION_NEON_DEBUG_MASK           "neon-debug-mask"
00070 #define SVN_CONFIG_OPTION_SSL_AUTHORITY_FILES       "ssl-authority-files"
00071 #define SVN_CONFIG_OPTION_SSL_TRUST_DEFAULT_CA      "ssl-trust-default-ca"
00072 #define SVN_CONFIG_OPTION_SSL_CLIENT_CERT_FILE      "ssl-client-cert-file"
00073 #define SVN_CONFIG_OPTION_SSL_CLIENT_CERT_PASSWORD  "ssl-client-cert-password"
00074 
00075 #define SVN_CONFIG_CATEGORY_CONFIG          "config"
00076 #define SVN_CONFIG_SECTION_AUTH                 "auth"
00077 #define SVN_CONFIG_OPTION_STORE_PASSWORDS           "store-passwords"
00078 #define SVN_CONFIG_OPTION_STORE_AUTH_CREDS          "store-auth-creds"
00079 #define SVN_CONFIG_SECTION_HELPERS              "helpers"
00080 #define SVN_CONFIG_OPTION_EDITOR_CMD                "editor-cmd"
00081 #define SVN_CONFIG_OPTION_DIFF_CMD                  "diff-cmd"
00082 #define SVN_CONFIG_OPTION_DIFF3_CMD                 "diff3-cmd"
00083 #define SVN_CONFIG_OPTION_DIFF3_HAS_PROGRAM_ARG     "diff3-has-program-arg"
00084 #define SVN_CONFIG_SECTION_MISCELLANY           "miscellany"
00085 #define SVN_CONFIG_OPTION_GLOBAL_IGNORES            "global-ignores"
00086 #define SVN_CONFIG_OPTION_LOG_ENCODING              "log-encoding"
00087 #define SVN_CONFIG_OPTION_USE_COMMIT_TIMES          "use-commit-times"
00088 #define SVN_CONFIG_OPTION_TEMPLATE_ROOT             "template-root"
00089 #define SVN_CONFIG_OPTION_ENABLE_AUTO_PROPS         "enable-auto-props"
00090 #define SVN_CONFIG_OPTION_NO_UNLOCK                 "no-unlock"
00091 #define SVN_CONFIG_SECTION_TUNNELS              "tunnels"
00092 #define SVN_CONFIG_SECTION_AUTO_PROPS           "auto-props"
00093 /** @} */
00094 
00095 /** @name Repository conf directory configuration files strings
00096  * Strings for the names of sections and options in the
00097  * repository conf directory configuration files.
00098  * @{
00099  */
00100 /* For repository svnserve.conf files */
00101 #define SVN_CONFIG_SECTION_GENERAL              "general"
00102 #define SVN_CONFIG_OPTION_ANON_ACCESS               "anon-access"
00103 #define SVN_CONFIG_OPTION_AUTH_ACCESS               "auth-access"
00104 #define SVN_CONFIG_OPTION_PASSWORD_DB               "password-db"
00105 #define SVN_CONFIG_OPTION_REALM                     "realm"
00106 #define SVN_CONFIG_OPTION_AUTHZ_DB                  "authz-db"
00107 
00108 /* For repository password database */
00109 #define SVN_CONFIG_SECTION_USERS                "users"
00110 /** @} */
00111 
00112 /*** Configuration Default Values ***/
00113 
00114 #define SVN_CONFIG_DEFAULT_GLOBAL_IGNORES \
00115    "*.o *.lo *.la #*# .*.rej *.rej .*~ *~ .#* .DS_Store"
00116 
00117 #define SVN_CONFIG_TRUE  "true"
00118 #define SVN_CONFIG_FALSE "false"
00119 
00120 
00121 /** Read configuration information from the standard sources and merge it
00122  * into the hash @a *cfg_hash.  If @a config_dir is not NULL it specifies a
00123  * directory from which to read the configuration files, overriding all
00124  * other sources.  Otherwise, first read any system-wide configurations
00125  * (from a file or from the registry), then merge in personal
00126  * configurations (again from file or registry).  The hash and all its data
00127  * are allocated in @a pool.
00128  *
00129  * @a *cfg_hash is a hash whose keys are @c const char * configuration
00130  * categories (@c SVN_CONFIG_CATEGORY_SERVERS,
00131  * @c SVN_CONFIG_CATEGORY_CONFIG, etc.) and whose values are the @c
00132  * svn_config_t * items representing the configuration values for that
00133  * category.  
00134  */
00135 svn_error_t *svn_config_get_config(apr_hash_t **cfg_hash,
00136                                    const char *config_dir,
00137                                    apr_pool_t *pool);
00138 
00139 
00140 /** Read configuration data from @a file (a file or registry path) into
00141  * @a *cfgp, allocated in @a pool.
00142  *
00143  * If @a file does not exist, then if @a must_exist, return an error,
00144  * otherwise return an empty @c svn_config_t.
00145  */
00146 svn_error_t *svn_config_read(svn_config_t **cfgp,
00147                              const char *file,
00148                              svn_boolean_t must_exist,
00149                              apr_pool_t *pool);
00150 
00151 /** Like svn_config_read(), but merges the configuration data from @a file
00152  * (a file or registry path) into @a *cfg, which was previously returned
00153  * from svn_config_read().  This function invalidates all value
00154  * expansions in @a cfg, so that the next svn_config_get() takes the
00155  * modifications into account.
00156  */
00157 svn_error_t *svn_config_merge(svn_config_t *cfg,
00158                               const char *file,
00159                               svn_boolean_t must_exist);
00160 
00161 
00162 /** Find the value of a (@a section, @a option) pair in @a cfg, set @a 
00163  * *valuep to the value.
00164  *
00165  * If @a cfg is @c NULL, just sets @a *valuep to @a default_value. If
00166  * the value does not exist, expand and return @a default_value. @a
00167  * default_value can be NULL.
00168  *
00169  * The returned value will be valid at least until the next call to
00170  * svn_config_get(), or for the lifetime of @a default_value. It is
00171  * safest to consume the returned value immediately.
00172  *
00173  * This function may change @a cfg by expanding option values.
00174  */
00175 void svn_config_get(svn_config_t *cfg, const char **valuep,
00176                     const char *section, const char *option,
00177                     const char *default_value);
00178 
00179 /** Add or replace the value of a (@a section, @a option) pair in @a cfg with 
00180  * @a value.
00181  *
00182  * This function invalidates all value expansions in @a cfg.
00183  */
00184 void svn_config_set(svn_config_t *cfg,
00185                     const char *section, const char *option,
00186                     const char *value);
00187 
00188 /** Like svn_config_get(), but for boolean values.
00189  *
00190  * Parses the option as a boolean value. The recognized representations
00191  * are 'true'/'false', 'yes'/'no', 'on'/'off', '1'/'0'; case does not
00192  * matter. Returns an error if the option doesn't contain a known string.
00193  */
00194 svn_error_t *svn_config_get_bool(svn_config_t *cfg, svn_boolean_t *valuep,
00195                                  const char *section, const char *option,
00196                                  svn_boolean_t default_value);
00197 
00198 /** Like svn_config_set(), but for boolean values.
00199  *
00200  * Sets the option to 'true'/'false', depending on @a value.
00201  */
00202 void svn_config_set_bool(svn_config_t *cfg,
00203                          const char *section, const char *option,
00204                          svn_boolean_t value);
00205 
00206 /** Similar to @c svn_config_section_enumerator2_t, but is not
00207  * provided with a memory pool argument.
00208  *
00209  * See svn_config_enumerate_sections() for the details of this type.
00210  *
00211  * @deprecated Provided for backwards compatibility with the 1.2 API.
00212  */
00213 typedef svn_boolean_t (*svn_config_section_enumerator_t)(const char *name,
00214                                                          void *baton);
00215 
00216 /** Similar to svn_config_enumerate_sections2(), but uses a memory pool of 
00217  * @a cfg instead of one that is explicitely provided.
00218  *
00219  * @deprecated Provided for backwards compatibility with the 1.2 API. 
00220  */
00221 int svn_config_enumerate_sections(svn_config_t *cfg, 
00222                                   svn_config_section_enumerator_t callback,
00223                                   void *baton);
00224 
00225 /** A callback function used in enumerating config sections.
00226  *
00227  * See svn_config_enumerate_sections2() for the details of this type.
00228  *
00229  * @since New in 1.3.
00230  */
00231 typedef svn_boolean_t (*svn_config_section_enumerator2_t)(const char *name,
00232                                                           void *baton,
00233                                                           apr_pool_t *pool);
00234 
00235 /** Enumerate the sections, passing @a baton and the current section's name
00236  * to @a callback.  Continue the enumeration if @a callback returns @c TRUE.
00237  * Return the number of times @a callback was called. 
00238  *
00239  * ### See kff's comment to svn_config_enumerate2().  It applies to this
00240  * function, too. ###
00241  *
00242  * @a callback's @a name and @a name parameters are only valid for the
00243  * duration of the call.
00244  *
00245  * @since New in 1.3.
00246  */
00247 int svn_config_enumerate_sections2(svn_config_t *cfg, 
00248                                    svn_config_section_enumerator2_t callback,
00249                                    void *baton, apr_pool_t *pool);
00250 
00251 /** Similar to @c svn_config_enumerator2_t, but is not
00252  * provided with a memory pool argument.
00253  * See svn_config_enumerate() for the details of this type.
00254  *
00255  * @deprecated Provided for backwards compatibility with the 1.2 API. 
00256  */
00257 typedef svn_boolean_t (*svn_config_enumerator_t)(const char *name,
00258                                                  const char *value,
00259                                                  void *baton);
00260 
00261 /** Similar to svn_config_enumerate2(), but uses a memory pool of 
00262  * @a cfg instead of one that is explicitely provided.
00263  *
00264  * @deprecated Provided for backwards compatibility with the 1.2 API. 
00265  */
00266 int svn_config_enumerate(svn_config_t *cfg, const char *section,
00267                          svn_config_enumerator_t callback, void *baton);
00268 
00269 
00270 /** A callback function used in enumerating config options.
00271  *
00272  * See svn_config_enumerate2() for the details of this type.
00273  *
00274  * @since New in 1.3.
00275  */
00276 typedef svn_boolean_t (*svn_config_enumerator2_t)(const char *name,
00277                                                   const char *value,
00278                                                   void *baton,
00279                                                   apr_pool_t *pool);
00280 
00281 /** Enumerate the options in @a section, passing @a baton and the current
00282  * option's name and value to @a callback.  Continue the enumeration if
00283  * @a callback returns @c TRUE.  Return the number of times @a callback 
00284  * was called.
00285  *
00286  * ### kff asks: A more usual interface is to continue enumerating
00287  *     while @a callback does not return error, and if @a callback does
00288  *     return error, to return the same error (or a wrapping of it)
00289  *     from svn_config_enumerate().  What's the use case for
00290  *     svn_config_enumerate()?  Is it more likely to need to break out
00291  *     of an enumeration early, with no error, than an invocation of
00292  *     @a callback is likely to need to return an error? ###
00293  *
00294  * @a callback's @a name and @a value parameters are only valid for the
00295  * duration of the call.
00296  *
00297  * @since New in 1.3.
00298  */
00299 int svn_config_enumerate2(svn_config_t *cfg, const char *section,
00300                           svn_config_enumerator2_t callback, void *baton,
00301                           apr_pool_t *pool);
00302 
00303 /**
00304  * Return @c TRUE if @a section exists in @a config, @c FALSE otherwise.
00305  *
00306  * @since New in 1.4.
00307  */
00308 svn_boolean_t svn_config_has_section(svn_config_t *cfg, const char *section);
00309 
00310 /** Enumerate the group @a master_section in @a cfg.  Each variable
00311  * value is interpreted as a list of glob patterns (separated by comma
00312  * and optional whitespace).  Return the name of the first variable
00313  * whose value matches @a key, or @c NULL if no variable matches.
00314  */
00315 const char *svn_config_find_group(svn_config_t *cfg, const char *key,
00316                                   const char *master_section,
00317                                   apr_pool_t *pool);
00318 
00319 /** Retrieve value corresponding to @a option_name for a given
00320  *  @a server_group in @a cfg , or return @a default_value if none is found.
00321  *
00322  *  The config will first be checked for a default, then will be checked for
00323  *  an override in a server group.
00324  */
00325 const char *svn_config_get_server_setting(svn_config_t *cfg,
00326                                           const char* server_group,
00327                                           const char* option_name,
00328                                           const char* default_value);
00329 
00330 /** Retrieve value into @a result_value corresponding to @a option_name for a
00331  *  given @a server_group in @a cfg, or return @a default_value if none is
00332  *  found.
00333  *
00334  *  The config will first be checked for a default, then will be checked for
00335  *  an override in a server group. If the value found is not a valid integer,
00336  *  a @c svn_error_t* will be returned.
00337  */
00338 svn_error_t *svn_config_get_server_setting_int(svn_config_t *cfg,
00339                                                const char *server_group,
00340                                                const char *option_name,
00341                                                apr_int64_t default_value,
00342                                                apr_int64_t *result_value,
00343                                                apr_pool_t *pool);
00344 
00345 
00346 /** Try to ensure that the user's ~/.subversion/ area exists, and create
00347  * no-op template files for any absent config files.  Use @a pool for any
00348  * temporary allocation.  If @a config_dir is not @c NULL it specifies a
00349  * directory from which to read the config overriding all other sources.
00350  *
00351  * Don't error if something exists but is the wrong kind (for example,
00352  * ~/.subversion exists but is a file, or ~/.subversion/servers exists
00353  * but is a directory).
00354  *
00355  * Also don't error if trying to create something and failing -- it's
00356  * okay for the config area or its contents not to be created.
00357  * However, if creating a config template file succeeds, return an
00358  * error if unable to initialize its contents.
00359  */
00360 svn_error_t *svn_config_ensure(const char *config_dir, apr_pool_t *pool);
00361 
00362 
00363 
00364 
00365 /** Accessing cached authentication data in the user config area.
00366  *
00367  * @defgroup cached_authentication_data cached authentication data.
00368  * @{
00369  */
00370 
00371 
00372 /** A hash-key pointing to a realmstring.  Every file containing
00373  * authentication data should have this key.
00374  */
00375 #define SVN_CONFIG_REALMSTRING_KEY  "svn:realmstring"
00376 
00377 /** Use @a cred_kind and @a realmstring to locate a file within the
00378  * ~/.subversion/auth/ area.  If the file exists, initialize @a *hash
00379  * and load the file contents into the hash, using @a pool.  If the
00380  * file doesn't exist, set @a *hash to NULL.
00381  *
00382  * If @a config_dir is not NULL it specifies a directory from which to
00383  * read the config overriding all other sources.
00384  *
00385  * Besides containing the original credential fields, the hash will
00386  * also contain @c SVN_CONFIG_REALMSTRING_KEY.  The caller can examine
00387  * this value as a sanity-check that the correct file was loaded.
00388  *
00389  * The hashtable will contain <tt>const char *</tt> keys and
00390  * <tt>svn_string_t *</tt> values.
00391  */
00392 svn_error_t * svn_config_read_auth_data(apr_hash_t **hash,
00393                                         const char *cred_kind,
00394                                         const char *realmstring,
00395                                         const char *config_dir,
00396                                         apr_pool_t *pool);
00397 
00398 /** Use @a cred_kind and @a realmstring to create or overwrite a file
00399  * within the ~/.subversion/auth/ area.  Write the contents of @a hash into
00400  * the file.  If @a config_dir is not NULL it specifies a directory to read
00401  * the config overriding all other sources.
00402  *
00403  * Also, add @a realmstring to the file, with key @c
00404  * SVN_CONFIG_REALMSTRING_KEY.  This allows programs (or users) to
00405  * verify exactly which set credentials live within the file.
00406  *
00407  * The hashtable must contain <tt>const char *</tt> keys and
00408  * <tt>svn_string_t *</tt> values.
00409  */
00410 svn_error_t * svn_config_write_auth_data(apr_hash_t *hash,
00411                                          const char *cred_kind,
00412                                          const char *realmstring,
00413                                          const char *config_dir,
00414                                          apr_pool_t *pool);
00415 
00416 /** @} */
00417 
00418 #ifdef __cplusplus
00419 }
00420 #endif /* __cplusplus */
00421 
00422 #endif /* SVN_CONFIG_H */

Generated on Sat Dec 22 05:38:05 2007 for Subversion by  doxygen 1.3.9.1