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