00001 /** 00002 * @copyright 00003 * ==================================================================== 00004 * Licensed to the Apache Software Foundation (ASF) under one 00005 * or more contributor license agreements. See the NOTICE file 00006 * distributed with this work for additional information 00007 * regarding copyright ownership. The ASF licenses this file 00008 * to you under the Apache License, Version 2.0 (the 00009 * "License"); you may not use this file except in compliance 00010 * with the License. You may obtain a copy of the License at 00011 * 00012 * http://www.apache.org/licenses/LICENSE-2.0 00013 * 00014 * Unless required by applicable law or agreed to in writing, 00015 * software distributed under the License is distributed on an 00016 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 00017 * KIND, either express or implied. See the License for the 00018 * specific language governing permissions and limitations 00019 * under the License. 00020 * ==================================================================== 00021 * @endcopyright 00022 * 00023 * @file svn_config.h 00024 * @brief Accessing SVN configuration files. 00025 */ 00026 00027 00028 00029 #ifndef SVN_CONFIG_H 00030 #define SVN_CONFIG_H 00031 00032 #include <apr.h> /* for apr_int64_t */ 00033 #include <apr_pools.h> /* for apr_pool_t */ 00034 #include <apr_hash.h> /* for apr_hash_t */ 00035 00036 #include "svn_types.h" 00037 #include "svn_io.h" 00038 00039 #ifdef __cplusplus 00040 extern "C" { 00041 #endif /* __cplusplus */ 00042 00043 00044 /************************************************************************** 00045 *** *** 00046 *** For a description of the SVN configuration file syntax, see *** 00047 *** your ~/.subversion/README, which is written out automatically by *** 00048 *** svn_config_ensure(). *** 00049 *** *** 00050 **************************************************************************/ 00051 00052 00053 /** Opaque structure describing a set of configuration options. */ 00054 typedef struct svn_config_t svn_config_t; 00055 00056 00057 /*** Configuration Defines ***/ 00058 00059 /** 00060 * @name Client configuration files strings 00061 * Strings for the names of files, sections, and options in the 00062 * client configuration files. 00063 * @{ 00064 */ 00065 00066 /* This list of #defines is intentionally presented as a nested list 00067 that matches the in-config hierarchy. */ 00068 00069 #define SVN_CONFIG_CATEGORY_SERVERS "servers" 00070 #define SVN_CONFIG_SECTION_GROUPS "groups" 00071 #define SVN_CONFIG_SECTION_GLOBAL "global" 00072 #define SVN_CONFIG_OPTION_HTTP_PROXY_HOST "http-proxy-host" 00073 #define SVN_CONFIG_OPTION_HTTP_PROXY_PORT "http-proxy-port" 00074 #define SVN_CONFIG_OPTION_HTTP_PROXY_USERNAME "http-proxy-username" 00075 #define SVN_CONFIG_OPTION_HTTP_PROXY_PASSWORD "http-proxy-password" 00076 #define SVN_CONFIG_OPTION_HTTP_PROXY_EXCEPTIONS "http-proxy-exceptions" 00077 #define SVN_CONFIG_OPTION_HTTP_TIMEOUT "http-timeout" 00078 #define SVN_CONFIG_OPTION_HTTP_COMPRESSION "http-compression" 00079 #define SVN_CONFIG_OPTION_NEON_DEBUG_MASK "neon-debug-mask" 00080 #define SVN_CONFIG_OPTION_HTTP_AUTH_TYPES "http-auth-types" 00081 #define SVN_CONFIG_OPTION_SSL_AUTHORITY_FILES "ssl-authority-files" 00082 #define SVN_CONFIG_OPTION_SSL_TRUST_DEFAULT_CA "ssl-trust-default-ca" 00083 #define SVN_CONFIG_OPTION_SSL_CLIENT_CERT_FILE "ssl-client-cert-file" 00084 #define SVN_CONFIG_OPTION_SSL_CLIENT_CERT_PASSWORD "ssl-client-cert-password" 00085 #define SVN_CONFIG_OPTION_SSL_PKCS11_PROVIDER "ssl-pkcs11-provider" 00086 #define SVN_CONFIG_OPTION_HTTP_LIBRARY "http-library" 00087 #define SVN_CONFIG_OPTION_STORE_PASSWORDS "store-passwords" 00088 #define SVN_CONFIG_OPTION_STORE_PLAINTEXT_PASSWORDS "store-plaintext-passwords" 00089 #define SVN_CONFIG_OPTION_STORE_AUTH_CREDS "store-auth-creds" 00090 #define SVN_CONFIG_OPTION_STORE_SSL_CLIENT_CERT_PP "store-ssl-client-cert-pp" 00091 #define SVN_CONFIG_OPTION_STORE_SSL_CLIENT_CERT_PP_PLAINTEXT \ 00092 "store-ssl-client-cert-pp-plaintext" 00093 #define SVN_CONFIG_OPTION_USERNAME "username" 00094 /** @since New in 1.8. */ 00095 #define SVN_CONFIG_OPTION_HTTP_BULK_UPDATES "http-bulk-updates" 00096 /** @since New in 1.8. */ 00097 #define SVN_CONFIG_OPTION_HTTP_MAX_CONNECTIONS "http-max-connections" 00098 00099 #define SVN_CONFIG_CATEGORY_CONFIG "config" 00100 #define SVN_CONFIG_SECTION_AUTH "auth" 00101 /** @since New in 1.6. */ 00102 #define SVN_CONFIG_OPTION_PASSWORD_STORES "password-stores" 00103 /** @since New in 1.6. */ 00104 #define SVN_CONFIG_OPTION_KWALLET_WALLET "kwallet-wallet" 00105 /** @since New in 1.6. */ 00106 #define SVN_CONFIG_OPTION_KWALLET_SVN_APPLICATION_NAME_WITH_PID "kwallet-svn-application-name-with-pid" 00107 /** @since New in 1.8. */ 00108 #define SVN_CONFIG_OPTION_SSL_CLIENT_CERT_FILE_PROMPT "ssl-client-cert-file-prompt" 00109 /* The majority of options of the "auth" section 00110 * has been moved to SVN_CONFIG_CATEGORY_SERVERS. */ 00111 #define SVN_CONFIG_SECTION_HELPERS "helpers" 00112 #define SVN_CONFIG_OPTION_EDITOR_CMD "editor-cmd" 00113 #define SVN_CONFIG_OPTION_DIFF_CMD "diff-cmd" 00114 /** @since New in 1.7. */ 00115 #define SVN_CONFIG_OPTION_DIFF_EXTENSIONS "diff-extensions" 00116 #define SVN_CONFIG_OPTION_DIFF3_CMD "diff3-cmd" 00117 #define SVN_CONFIG_OPTION_DIFF3_HAS_PROGRAM_ARG "diff3-has-program-arg" 00118 #define SVN_CONFIG_OPTION_MERGE_TOOL_CMD "merge-tool-cmd" 00119 #define SVN_CONFIG_SECTION_MISCELLANY "miscellany" 00120 #define SVN_CONFIG_OPTION_GLOBAL_IGNORES "global-ignores" 00121 #define SVN_CONFIG_OPTION_LOG_ENCODING "log-encoding" 00122 #define SVN_CONFIG_OPTION_USE_COMMIT_TIMES "use-commit-times" 00123 /** @deprecated Not used by Subversion since 2003/r847039 (well before 1.0) */ 00124 #define SVN_CONFIG_OPTION_TEMPLATE_ROOT "template-root" 00125 #define SVN_CONFIG_OPTION_ENABLE_AUTO_PROPS "enable-auto-props" 00126 #define SVN_CONFIG_OPTION_NO_UNLOCK "no-unlock" 00127 #define SVN_CONFIG_OPTION_MIMETYPES_FILE "mime-types-file" 00128 #define SVN_CONFIG_OPTION_PRESERVED_CF_EXTS "preserved-conflict-file-exts" 00129 /** @since New in 1.7. */ 00130 #define SVN_CONFIG_OPTION_INTERACTIVE_CONFLICTS "interactive-conflicts" 00131 /** @since New in 1.7. */ 00132 #define SVN_CONFIG_OPTION_MEMORY_CACHE_SIZE "memory-cache-size" 00133 #define SVN_CONFIG_SECTION_TUNNELS "tunnels" 00134 #define SVN_CONFIG_SECTION_AUTO_PROPS "auto-props" 00135 /** @since New in 1.8. */ 00136 #define SVN_CONFIG_SECTION_WORKING_COPY "working-copy" 00137 /** @since New in 1.8. */ 00138 #define SVN_CONFIG_OPTION_SQLITE_EXCLUSIVE "exclusive-locking" 00139 /** @since New in 1.8. */ 00140 #define SVN_CONFIG_OPTION_SQLITE_EXCLUSIVE_CLIENTS "exclusive-locking-clients" 00141 /** @} */ 00142 00143 /** @name Repository conf directory configuration files strings 00144 * Strings for the names of sections and options in the 00145 * repository conf directory configuration files. 00146 * @{ 00147 */ 00148 /* For repository svnserve.conf files */ 00149 #define SVN_CONFIG_SECTION_GENERAL "general" 00150 #define SVN_CONFIG_OPTION_ANON_ACCESS "anon-access" 00151 #define SVN_CONFIG_OPTION_AUTH_ACCESS "auth-access" 00152 #define SVN_CONFIG_OPTION_PASSWORD_DB "password-db" 00153 #define SVN_CONFIG_OPTION_REALM "realm" 00154 #define SVN_CONFIG_OPTION_AUTHZ_DB "authz-db" 00155 /** @since New in 1.8. */ 00156 #define SVN_CONFIG_OPTION_GROUPS_DB "groups-db" 00157 /** @since New in 1.7. */ 00158 #define SVN_CONFIG_OPTION_FORCE_USERNAME_CASE "force-username-case" 00159 /** @since New in 1.8. */ 00160 #define SVN_CONFIG_OPTION_HOOKS_ENV "hooks-env" 00161 #define SVN_CONFIG_SECTION_SASL "sasl" 00162 #define SVN_CONFIG_OPTION_USE_SASL "use-sasl" 00163 #define SVN_CONFIG_OPTION_MIN_SSF "min-encryption" 00164 #define SVN_CONFIG_OPTION_MAX_SSF "max-encryption" 00165 00166 /* For repository password database */ 00167 #define SVN_CONFIG_SECTION_USERS "users" 00168 /** @} */ 00169 00170 /*** Configuration Default Values ***/ 00171 00172 /* '*' matches leading dots, e.g. '*.rej' matches '.foo.rej'. */ 00173 /* We want this to be printed on two lines in the generated config file, 00174 * but we don't want the # character to end up in the variable. 00175 */ 00176 #ifndef DOXYGEN_SHOULD_SKIP_THIS 00177 #define SVN_CONFIG__DEFAULT_GLOBAL_IGNORES_LINE_1 \ 00178 "*.o *.lo *.la *.al .libs *.so *.so.[0-9]* *.a *.pyc *.pyo __pycache__" 00179 #define SVN_CONFIG__DEFAULT_GLOBAL_IGNORES_LINE_2 \ 00180 "*.rej *~ #*# .#* .*.swp .DS_Store" 00181 #endif 00182 00183 #define SVN_CONFIG_DEFAULT_GLOBAL_IGNORES \ 00184 SVN_CONFIG__DEFAULT_GLOBAL_IGNORES_LINE_1 " " \ 00185 SVN_CONFIG__DEFAULT_GLOBAL_IGNORES_LINE_2 00186 00187 #define SVN_CONFIG_TRUE "TRUE" 00188 #define SVN_CONFIG_FALSE "FALSE" 00189 #define SVN_CONFIG_ASK "ASK" 00190 00191 /* Default values for some options. Should be passed as default values 00192 * to svn_config_get and friends, instead of hard-coding the defaults in 00193 * multiple places. */ 00194 #define SVN_CONFIG_DEFAULT_OPTION_STORE_PASSWORDS TRUE 00195 #define SVN_CONFIG_DEFAULT_OPTION_STORE_PLAINTEXT_PASSWORDS SVN_CONFIG_ASK 00196 #define SVN_CONFIG_DEFAULT_OPTION_STORE_AUTH_CREDS TRUE 00197 #define SVN_CONFIG_DEFAULT_OPTION_STORE_SSL_CLIENT_CERT_PP TRUE 00198 #define SVN_CONFIG_DEFAULT_OPTION_STORE_SSL_CLIENT_CERT_PP_PLAINTEXT \ 00199 SVN_CONFIG_ASK 00200 #define SVN_CONFIG_DEFAULT_OPTION_HTTP_MAX_CONNECTIONS 4 00201 00202 /** Read configuration information from the standard sources and merge it 00203 * into the hash @a *cfg_hash. If @a config_dir is not NULL it specifies a 00204 * directory from which to read the configuration files, overriding all 00205 * other sources. Otherwise, first read any system-wide configurations 00206 * (from a file or from the registry), then merge in personal 00207 * configurations (again from file or registry). The hash and all its data 00208 * are allocated in @a pool. 00209 * 00210 * @a *cfg_hash is a hash whose keys are @c const char * configuration 00211 * categories (@c SVN_CONFIG_CATEGORY_SERVERS, 00212 * @c SVN_CONFIG_CATEGORY_CONFIG, etc.) and whose values are the @c 00213 * svn_config_t * items representing the configuration values for that 00214 * category. 00215 */ 00216 svn_error_t * 00217 svn_config_get_config(apr_hash_t **cfg_hash, 00218 const char *config_dir, 00219 apr_pool_t *pool); 00220 00221 /** Set @a *cfgp to an empty @c svn_config_t structure, 00222 * allocated in @a result_pool. 00223 * 00224 * Pass TRUE to @a section_names_case_sensitive if 00225 * section names are to be populated case sensitively. 00226 * 00227 * Pass TRUE to @a option_names_case_sensitive if 00228 * option names are to be populated case sensitively. 00229 * 00230 * @since New in 1.8. 00231 */ 00232 svn_error_t * 00233 svn_config_create2(svn_config_t **cfgp, 00234 svn_boolean_t section_names_case_sensitive, 00235 svn_boolean_t option_names_case_sensitive, 00236 apr_pool_t *result_pool); 00237 00238 /** Similar to svn_config_create2, but always passes @c FALSE to 00239 * @a option_names_case_sensitive. 00240 * 00241 * @since New in 1.7. 00242 * @deprecated Provided for backward compatibility with 1.7 API. 00243 */ 00244 SVN_DEPRECATED 00245 svn_error_t * 00246 svn_config_create(svn_config_t **cfgp, 00247 svn_boolean_t section_names_case_sensitive, 00248 apr_pool_t *result_pool); 00249 00250 /** Read configuration data from @a file (a file or registry path) into 00251 * @a *cfgp, allocated in @a pool. 00252 * 00253 * If @a file does not exist, then if @a must_exist, return an error, 00254 * otherwise return an empty @c svn_config_t. 00255 * 00256 * If @a section_names_case_sensitive is @c TRUE, populate section name hashes 00257 * case sensitively, except for the @c "DEFAULT" section. 00258 * 00259 * If @a option_names_case_sensitive is @c TRUE, populate option name hashes 00260 * case sensitively. 00261 * 00262 * @since New in 1.8. 00263 */ 00264 svn_error_t * 00265 svn_config_read3(svn_config_t **cfgp, 00266 const char *file, 00267 svn_boolean_t must_exist, 00268 svn_boolean_t section_names_case_sensitive, 00269 svn_boolean_t option_names_case_sensitive, 00270 apr_pool_t *result_pool); 00271 00272 /** Similar to svn_config_read3, but always passes @c FALSE to 00273 * @a option_names_case_sensitive. 00274 * 00275 * @since New in 1.7. 00276 * @deprecated Provided for backward compatibility with 1.7 API. 00277 */ 00278 SVN_DEPRECATED 00279 svn_error_t * 00280 svn_config_read2(svn_config_t **cfgp, 00281 const char *file, 00282 svn_boolean_t must_exist, 00283 svn_boolean_t section_names_case_sensitive, 00284 apr_pool_t *result_pool); 00285 00286 /** Similar to svn_config_read2, but always passes @c FALSE to 00287 * @a section_names_case_sensitive. 00288 * 00289 * @deprecated Provided for backward compatibility with 1.6 API. 00290 */ 00291 SVN_DEPRECATED 00292 svn_error_t * 00293 svn_config_read(svn_config_t **cfgp, 00294 const char *file, 00295 svn_boolean_t must_exist, 00296 apr_pool_t *result_pool); 00297 00298 /** Read configuration data from @a stream into @a *cfgp, allocated in 00299 * @a result_pool. 00300 * 00301 * If @a section_names_case_sensitive is @c TRUE, populate section name hashes 00302 * case sensitively, except for the @c "DEFAULT" section. 00303 * 00304 * If @a option_names_case_sensitive is @c TRUE, populate option name hashes 00305 * case sensitively. 00306 * 00307 * @since New in 1.8. 00308 */ 00309 00310 svn_error_t * 00311 svn_config_parse(svn_config_t **cfgp, 00312 svn_stream_t *stream, 00313 svn_boolean_t section_names_case_sensitive, 00314 svn_boolean_t option_names_case_sensitive, 00315 apr_pool_t *result_pool); 00316 00317 /** Like svn_config_read(), but merges the configuration data from @a file 00318 * (a file or registry path) into @a *cfg, which was previously returned 00319 * from svn_config_read(). This function invalidates all value 00320 * expansions in @a cfg, so that the next svn_config_get() takes the 00321 * modifications into account. 00322 */ 00323 svn_error_t * 00324 svn_config_merge(svn_config_t *cfg, 00325 const char *file, 00326 svn_boolean_t must_exist); 00327 00328 00329 /** Find the value of a (@a section, @a option) pair in @a cfg, set @a 00330 * *valuep to the value. 00331 * 00332 * If @a cfg is @c NULL, just sets @a *valuep to @a default_value. If 00333 * the value does not exist, expand and return @a default_value. @a 00334 * default_value can be NULL. 00335 * 00336 * The returned value will be valid at least until the next call to 00337 * svn_config_get(), or for the lifetime of @a default_value. It is 00338 * safest to consume the returned value immediately. 00339 * 00340 * This function may change @a cfg by expanding option values. 00341 */ 00342 void 00343 svn_config_get(svn_config_t *cfg, 00344 const char **valuep, 00345 const char *section, 00346 const char *option, 00347 const char *default_value); 00348 00349 /** Add or replace the value of a (@a section, @a option) pair in @a cfg with 00350 * @a value. 00351 * 00352 * This function invalidates all value expansions in @a cfg. 00353 * 00354 * To remove an option, pass NULL for the @a value. 00355 */ 00356 void 00357 svn_config_set(svn_config_t *cfg, 00358 const char *section, 00359 const char *option, 00360 const char *value); 00361 00362 /** Like svn_config_get(), but for boolean values. 00363 * 00364 * Parses the option as a boolean value. The recognized representations 00365 * are 'TRUE'/'FALSE', 'yes'/'no', 'on'/'off', '1'/'0'; case does not 00366 * matter. Returns an error if the option doesn't contain a known string. 00367 */ 00368 svn_error_t * 00369 svn_config_get_bool(svn_config_t *cfg, 00370 svn_boolean_t *valuep, 00371 const char *section, 00372 const char *option, 00373 svn_boolean_t default_value); 00374 00375 /** Like svn_config_set(), but for boolean values. 00376 * 00377 * Sets the option to 'TRUE'/'FALSE', depending on @a value. 00378 */ 00379 void 00380 svn_config_set_bool(svn_config_t *cfg, 00381 const char *section, 00382 const char *option, 00383 svn_boolean_t value); 00384 00385 /** Like svn_config_get(), but for 64-bit signed integers. 00386 * 00387 * Parses the @a option in @a section of @a cfg as an integer value, 00388 * setting @a *valuep to the result. If the option is not found, sets 00389 * @a *valuep to @a default_value. If the option is found but cannot 00390 * be converted to an integer, returns an error. 00391 * 00392 * @since New in 1.8. 00393 */ 00394 svn_error_t * 00395 svn_config_get_int64(svn_config_t *cfg, 00396 apr_int64_t *valuep, 00397 const char *section, 00398 const char *option, 00399 apr_int64_t default_value); 00400 00401 /** Like svn_config_set(), but for 64-bit signed integers. 00402 * 00403 * Sets the value of @a option in @a section of @a cfg to the signed 00404 * decimal @a value. 00405 * 00406 * @since New in 1.8. 00407 */ 00408 void 00409 svn_config_set_int64(svn_config_t *cfg, 00410 const char *section, 00411 const char *option, 00412 apr_int64_t value); 00413 00414 /** Like svn_config_get(), but only for yes/no/ask values. 00415 * 00416 * Parse @a option in @a section and set @a *valuep to one of 00417 * SVN_CONFIG_TRUE, SVN_CONFIG_FALSE, or SVN_CONFIG_ASK. If there is 00418 * no setting for @a option, then parse @a default_value and set 00419 * @a *valuep accordingly. If @a default_value is NULL, the result is 00420 * undefined, and may be an error; we recommend that you pass one of 00421 * SVN_CONFIG_TRUE, SVN_CONFIG_FALSE, or SVN_CONFIG_ASK for @a default value. 00422 * 00423 * Valid representations are (at least) "true"/"false", "yes"/"no", 00424 * "on"/"off", "1"/"0", and "ask"; they are case-insensitive. Return 00425 * an SVN_ERR_BAD_CONFIG_VALUE error if either @a default_value or 00426 * @a option's value is not a valid representation. 00427 * 00428 * @since New in 1.6. 00429 */ 00430 svn_error_t * 00431 svn_config_get_yes_no_ask(svn_config_t *cfg, 00432 const char **valuep, 00433 const char *section, 00434 const char *option, 00435 const char* default_value); 00436 00437 /** Like svn_config_get_bool(), but for tristate values. 00438 * 00439 * Set @a *valuep to #svn_tristate_true, #svn_tristate_false, or 00440 * #svn_tristate_unknown, depending on the value of @a option in @a 00441 * section of @a cfg. True and false values are the same as for 00442 * svn_config_get_bool(); @a unknown_value specifies the option value 00443 * allowed for third state (#svn_tristate_unknown). 00444 * 00445 * Use @a default_value as the default value if @a option cannot be 00446 * found. 00447 * 00448 * @since New in 1.8. 00449 */ 00450 svn_error_t * 00451 svn_config_get_tristate(svn_config_t *cfg, 00452 svn_tristate_t *valuep, 00453 const char *section, 00454 const char *option, 00455 const char *unknown_value, 00456 svn_tristate_t default_value); 00457 00458 /** Similar to @c svn_config_section_enumerator2_t, but is not 00459 * provided with a memory pool argument. 00460 * 00461 * See svn_config_enumerate_sections() for the details of this type. 00462 * 00463 * @deprecated Provided for backwards compatibility with the 1.2 API. 00464 */ 00465 typedef svn_boolean_t (*svn_config_section_enumerator_t)(const char *name, 00466 void *baton); 00467 00468 /** Similar to svn_config_enumerate_sections2(), but uses a memory pool of 00469 * @a cfg instead of one that is explicitly provided. 00470 * 00471 * @deprecated Provided for backwards compatibility with the 1.2 API. 00472 */ 00473 SVN_DEPRECATED 00474 int 00475 svn_config_enumerate_sections(svn_config_t *cfg, 00476 svn_config_section_enumerator_t callback, 00477 void *baton); 00478 00479 /** A callback function used in enumerating config sections. 00480 * 00481 * See svn_config_enumerate_sections2() for the details of this type. 00482 * 00483 * @since New in 1.3. 00484 */ 00485 typedef svn_boolean_t (*svn_config_section_enumerator2_t)(const char *name, 00486 void *baton, 00487 apr_pool_t *pool); 00488 00489 /** Enumerate the sections, passing @a baton and the current section's name 00490 * to @a callback. Continue the enumeration if @a callback returns @c TRUE. 00491 * Return the number of times @a callback was called. 00492 * 00493 * ### See kff's comment to svn_config_enumerate2(). It applies to this 00494 * function, too. ### 00495 * 00496 * @a callback's @a name parameter is only valid for the duration of the call. 00497 * 00498 * @since New in 1.3. 00499 */ 00500 int 00501 svn_config_enumerate_sections2(svn_config_t *cfg, 00502 svn_config_section_enumerator2_t callback, 00503 void *baton, apr_pool_t *pool); 00504 00505 /** Similar to @c svn_config_enumerator2_t, but is not 00506 * provided with a memory pool argument. 00507 * See svn_config_enumerate() for the details of this type. 00508 * 00509 * @deprecated Provided for backwards compatibility with the 1.2 API. 00510 */ 00511 typedef svn_boolean_t (*svn_config_enumerator_t)(const char *name, 00512 const char *value, 00513 void *baton); 00514 00515 /** Similar to svn_config_enumerate2(), but uses a memory pool of 00516 * @a cfg instead of one that is explicitly provided. 00517 * 00518 * @deprecated Provided for backwards compatibility with the 1.2 API. 00519 */ 00520 SVN_DEPRECATED 00521 int 00522 svn_config_enumerate(svn_config_t *cfg, 00523 const char *section, 00524 svn_config_enumerator_t callback, 00525 void *baton); 00526 00527 00528 /** A callback function used in enumerating config options. 00529 * 00530 * See svn_config_enumerate2() for the details of this type. 00531 * 00532 * @since New in 1.3. 00533 */ 00534 typedef svn_boolean_t (*svn_config_enumerator2_t)(const char *name, 00535 const char *value, 00536 void *baton, 00537 apr_pool_t *pool); 00538 00539 /** Enumerate the options in @a section, passing @a baton and the current 00540 * option's name and value to @a callback. Continue the enumeration if 00541 * @a callback returns @c TRUE. Return the number of times @a callback 00542 * was called. 00543 * 00544 * ### kff asks: A more usual interface is to continue enumerating 00545 * while @a callback does not return error, and if @a callback does 00546 * return error, to return the same error (or a wrapping of it) 00547 * from svn_config_enumerate(). What's the use case for 00548 * svn_config_enumerate()? Is it more likely to need to break out 00549 * of an enumeration early, with no error, than an invocation of 00550 * @a callback is likely to need to return an error? ### 00551 * 00552 * @a callback's @a name and @a value parameters are only valid for the 00553 * duration of the call. 00554 * 00555 * @since New in 1.3. 00556 */ 00557 int 00558 svn_config_enumerate2(svn_config_t *cfg, 00559 const char *section, 00560 svn_config_enumerator2_t callback, 00561 void *baton, 00562 apr_pool_t *pool); 00563 00564 /** 00565 * Return @c TRUE if @a section exists in @a cfg, @c FALSE otherwise. 00566 * 00567 * @since New in 1.4. 00568 */ 00569 svn_boolean_t 00570 svn_config_has_section(svn_config_t *cfg, 00571 const char *section); 00572 00573 /** Enumerate the group @a master_section in @a cfg. Each variable 00574 * value is interpreted as a list of glob patterns (separated by comma 00575 * and optional whitespace). Return the name of the first variable 00576 * whose value matches @a key, or @c NULL if no variable matches. 00577 */ 00578 const char * 00579 svn_config_find_group(svn_config_t *cfg, 00580 const char *key, 00581 const char *master_section, 00582 apr_pool_t *pool); 00583 00584 /** Retrieve value corresponding to @a option_name in @a cfg, or 00585 * return @a default_value if none is found. 00586 * 00587 * The config will first be checked for a default. 00588 * If @a server_group is not @c NULL, the config will also be checked 00589 * for an override in a server group, 00590 * 00591 */ 00592 const char * 00593 svn_config_get_server_setting(svn_config_t *cfg, 00594 const char* server_group, 00595 const char* option_name, 00596 const char* default_value); 00597 00598 /** Retrieve value into @a result_value corresponding to @a option_name for a 00599 * given @a server_group in @a cfg, or return @a default_value if none is 00600 * found. 00601 * 00602 * The config will first be checked for a default, then will be checked for 00603 * an override in a server group. If the value found is not a valid integer, 00604 * a @c svn_error_t* will be returned. 00605 */ 00606 svn_error_t * 00607 svn_config_get_server_setting_int(svn_config_t *cfg, 00608 const char *server_group, 00609 const char *option_name, 00610 apr_int64_t default_value, 00611 apr_int64_t *result_value, 00612 apr_pool_t *pool); 00613 00614 00615 /** Set @a *valuep according to @a option_name for a given 00616 * @a server_group in @a cfg, or set to @a default_value if no value is 00617 * specified. 00618 * 00619 * Check first a default, then for an override in a server group. If 00620 * a value is found but is not a valid boolean, return an 00621 * SVN_ERR_BAD_CONFIG_VALUE error. 00622 * 00623 * @since New in 1.6. 00624 */ 00625 svn_error_t * 00626 svn_config_get_server_setting_bool(svn_config_t *cfg, 00627 svn_boolean_t *valuep, 00628 const char *server_group, 00629 const char *option_name, 00630 svn_boolean_t default_value); 00631 00632 00633 00634 /** Try to ensure that the user's ~/.subversion/ area exists, and create 00635 * no-op template files for any absent config files. Use @a pool for any 00636 * temporary allocation. If @a config_dir is not @c NULL it specifies a 00637 * directory from which to read the config overriding all other sources. 00638 * 00639 * Don't error if something exists but is the wrong kind (for example, 00640 * ~/.subversion exists but is a file, or ~/.subversion/servers exists 00641 * but is a directory). 00642 * 00643 * Also don't error if trying to create something and failing -- it's 00644 * okay for the config area or its contents not to be created. 00645 * However, if creating a config template file succeeds, return an 00646 * error if unable to initialize its contents. 00647 */ 00648 svn_error_t * 00649 svn_config_ensure(const char *config_dir, 00650 apr_pool_t *pool); 00651 00652 00653 00654 00655 /** Accessing cached authentication data in the user config area. 00656 * 00657 * @defgroup cached_authentication_data Cached authentication data 00658 * @{ 00659 */ 00660 00661 00662 /** A hash-key pointing to a realmstring. Every file containing 00663 * authentication data should have this key. 00664 */ 00665 #define SVN_CONFIG_REALMSTRING_KEY "svn:realmstring" 00666 00667 /** Use @a cred_kind and @a realmstring to locate a file within the 00668 * ~/.subversion/auth/ area. If the file exists, initialize @a *hash 00669 * and load the file contents into the hash, using @a pool. If the 00670 * file doesn't exist, set @a *hash to NULL. 00671 * 00672 * If @a config_dir is not NULL it specifies a directory from which to 00673 * read the config overriding all other sources. 00674 * 00675 * Besides containing the original credential fields, the hash will 00676 * also contain @c SVN_CONFIG_REALMSTRING_KEY. The caller can examine 00677 * this value as a sanity-check that the correct file was loaded. 00678 * 00679 * The hashtable will contain <tt>const char *</tt> keys and 00680 * <tt>svn_string_t *</tt> values. 00681 */ 00682 svn_error_t * 00683 svn_config_read_auth_data(apr_hash_t **hash, 00684 const char *cred_kind, 00685 const char *realmstring, 00686 const char *config_dir, 00687 apr_pool_t *pool); 00688 00689 /** Use @a cred_kind and @a realmstring to create or overwrite a file 00690 * within the ~/.subversion/auth/ area. Write the contents of @a hash into 00691 * the file. If @a config_dir is not NULL it specifies a directory to read 00692 * the config overriding all other sources. 00693 * 00694 * Also, add @a realmstring to the file, with key @c 00695 * SVN_CONFIG_REALMSTRING_KEY. This allows programs (or users) to 00696 * verify exactly which set credentials live within the file. 00697 * 00698 * The hashtable must contain <tt>const char *</tt> keys and 00699 * <tt>svn_string_t *</tt> values. 00700 */ 00701 svn_error_t * 00702 svn_config_write_auth_data(apr_hash_t *hash, 00703 const char *cred_kind, 00704 const char *realmstring, 00705 const char *config_dir, 00706 apr_pool_t *pool); 00707 00708 00709 /** Callback for svn_config_walk_auth_data(). 00710 * 00711 * Called for each credential walked by that function (and able to be 00712 * fully purged) to allow perusal and selective removal of credentials. 00713 * 00714 * @a cred_kind and @a realmstring specify the key of the credential. 00715 * @a hash contains the hash data associated with the record. 00716 * 00717 * Before returning set @a *delete_cred to TRUE to remove the credential from 00718 * the cache; leave @a *delete_cred unchanged or set it to FALSE to keep the 00719 * credential. 00720 * 00721 * Implementations may return #SVN_ERR_CEASE_INVOCATION to indicate 00722 * that the callback should not be called again. Note that when that 00723 * error is returned, the value of @a delete_cred will still be 00724 * honored and action taken if necessary. (For other returned errors, 00725 * @a delete_cred is ignored by svn_config_walk_auth_data().) 00726 * 00727 * @since New in 1.8. 00728 */ 00729 typedef svn_error_t * 00730 (*svn_config_auth_walk_func_t)(svn_boolean_t *delete_cred, 00731 void *cleanup_baton, 00732 const char *cred_kind, 00733 const char *realmstring, 00734 apr_hash_t *hash, 00735 apr_pool_t *scratch_pool); 00736 00737 /** Call @a walk_func with @a walk_baton and information describing 00738 * each credential cached within the Subversion auth store located 00739 * under @a config_dir. If the callback sets its delete_cred return 00740 * flag, delete the associated credential. 00741 * 00742 * If @a config_dir is not NULL, it must point to an alternative 00743 * config directory location. If it is NULL, the default location 00744 * is used. 00745 * 00746 * @note @a config_dir may only be NULL in 1.8.2 and later. 00747 * 00748 * @note Removing credentials from the config-based disk store will 00749 * not purge them from any open svn_auth_baton_t instance. Consider 00750 * using svn_auth_forget_credentials() -- from the @a cleanup_func, 00751 * even -- for this purpose. 00752 * 00753 * @note Removing credentials from the config-based disk store will 00754 * not also remove any related credentials from third-party password 00755 * stores. (Implementations of @a walk_func which delete credentials 00756 * may wish to consult the "passtype" element of @a hash, if any, to 00757 * see if a third-party store -- such as "gnome-keyring" or "kwallet" 00758 * is being used to hold the most sensitive portion of the credentials 00759 * for this @a cred_kind and @a realmstring.) 00760 * 00761 * @see svn_auth_forget_credentials() 00762 * 00763 * @since New in 1.8. 00764 */ 00765 svn_error_t * 00766 svn_config_walk_auth_data(const char *config_dir, 00767 svn_config_auth_walk_func_t walk_func, 00768 void *walk_baton, 00769 apr_pool_t *scratch_pool); 00770 00771 /** Put the absolute path to the user's configuration directory, 00772 * or to a file within that directory, into @a *path. 00773 * 00774 * If @a config_dir is not NULL, it must point to an alternative 00775 * config directory location. If it is NULL, the default location 00776 * is used. If @a fname is not NULL, it must specify the last 00777 * component of the path to be returned. This can be used to create 00778 * a path to any file in the configuration directory. 00779 * 00780 * Do all allocations in @a pool. 00781 * 00782 * Hint: 00783 * To get the user configuration file, pass @c SVN_CONFIG_CATEGORY_CONFIG 00784 * for @a fname. To get the servers configuration file, pass 00785 * @c SVN_CONFIG_CATEGORY_SERVERS for @a fname. 00786 * 00787 * @since New in 1.6. 00788 */ 00789 svn_error_t * 00790 svn_config_get_user_config_path(const char **path, 00791 const char *config_dir, 00792 const char *fname, 00793 apr_pool_t *pool); 00794 00795 /** Create a deep copy of the config object @a src and return 00796 * it in @a cfgp, allocating the memory in @a pool. 00797 * 00798 * @since New in 1.8. 00799 */ 00800 svn_error_t * 00801 svn_config_dup(svn_config_t **cfgp, 00802 svn_config_t *src, 00803 apr_pool_t *pool); 00804 00805 /** Create a deep copy of the config hash @a src_hash and return 00806 * it in @a cfg_hash, allocating the memory in @a pool. 00807 * 00808 * @since New in 1.8. 00809 */ 00810 svn_error_t * 00811 svn_config_copy_config(apr_hash_t **cfg_hash, 00812 apr_hash_t *src_hash, 00813 apr_pool_t *pool); 00814 00815 /** @} */ 00816 00817 #ifdef __cplusplus 00818 } 00819 #endif /* __cplusplus */ 00820 00821 #endif /* SVN_CONFIG_H */