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