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