Subversion
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
svn_config.h
Go to the documentation of this file.
1 /**
2  * @copyright
3  * ====================================================================
4  * Licensed to the Apache Software Foundation (ASF) under one
5  * or more contributor license agreements. See the NOTICE file
6  * distributed with this work for additional information
7  * regarding copyright ownership. The ASF licenses this file
8  * to you under the Apache License, Version 2.0 (the
9  * "License"); you may not use this file except in compliance
10  * with the License. You may obtain a copy of the License at
11  *
12  * http://www.apache.org/licenses/LICENSE-2.0
13  *
14  * Unless required by applicable law or agreed to in writing,
15  * software distributed under the License is distributed on an
16  * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
17  * KIND, either express or implied. See the License for the
18  * specific language governing permissions and limitations
19  * under the License.
20  * ====================================================================
21  * @endcopyright
22  *
23  * @file svn_config.h
24  * @brief Accessing SVN configuration files.
25  */
26 
27 
28 
29 #ifndef SVN_CONFIG_H
30 #define SVN_CONFIG_H
31 
32 #include <apr.h> /* for apr_int64_t */
33 #include <apr_pools.h> /* for apr_pool_t */
34 #include <apr_hash.h> /* for apr_hash_t */
35 
36 #include "svn_types.h"
37 #include "svn_io.h"
38 
39 #ifdef __cplusplus
40 extern "C" {
41 #endif /* __cplusplus */
42 
43 
44 /**************************************************************************
45  *** ***
46  *** For a description of the SVN configuration file syntax, see ***
47  *** your ~/.subversion/README, which is written out automatically by ***
48  *** svn_config_ensure(). ***
49  *** ***
50  **************************************************************************/
51 
52 
53 /** Opaque structure describing a set of configuration options. */
54 typedef struct svn_config_t svn_config_t;
55 
56 
57 /*** Configuration Defines ***/
58 
59 /**
60  * @name Client configuration files strings
61  * Strings for the names of files, sections, and options in the
62  * client configuration files.
63  * @{
64  */
65 
66  /* This list of #defines is intentionally presented as a nested list
67  that matches the in-config hierarchy. */
68 
69 #define SVN_CONFIG_CATEGORY_SERVERS "servers"
70 #define SVN_CONFIG_SECTION_GROUPS "groups"
71 #define SVN_CONFIG_SECTION_GLOBAL "global"
72 #define SVN_CONFIG_OPTION_HTTP_PROXY_HOST "http-proxy-host"
73 #define SVN_CONFIG_OPTION_HTTP_PROXY_PORT "http-proxy-port"
74 #define SVN_CONFIG_OPTION_HTTP_PROXY_USERNAME "http-proxy-username"
75 #define SVN_CONFIG_OPTION_HTTP_PROXY_PASSWORD "http-proxy-password"
76 #define SVN_CONFIG_OPTION_HTTP_PROXY_EXCEPTIONS "http-proxy-exceptions"
77 #define SVN_CONFIG_OPTION_HTTP_TIMEOUT "http-timeout"
78 #define SVN_CONFIG_OPTION_HTTP_COMPRESSION "http-compression"
79 #define SVN_CONFIG_OPTION_NEON_DEBUG_MASK "neon-debug-mask"
80 #define SVN_CONFIG_OPTION_HTTP_AUTH_TYPES "http-auth-types"
81 #define SVN_CONFIG_OPTION_SSL_AUTHORITY_FILES "ssl-authority-files"
82 #define SVN_CONFIG_OPTION_SSL_TRUST_DEFAULT_CA "ssl-trust-default-ca"
83 #define SVN_CONFIG_OPTION_SSL_CLIENT_CERT_FILE "ssl-client-cert-file"
84 #define SVN_CONFIG_OPTION_SSL_CLIENT_CERT_PASSWORD "ssl-client-cert-password"
85 #define SVN_CONFIG_OPTION_SSL_PKCS11_PROVIDER "ssl-pkcs11-provider"
86 #define SVN_CONFIG_OPTION_HTTP_LIBRARY "http-library"
87 #define SVN_CONFIG_OPTION_STORE_PASSWORDS "store-passwords"
88 #define SVN_CONFIG_OPTION_STORE_PLAINTEXT_PASSWORDS "store-plaintext-passwords"
89 #define SVN_CONFIG_OPTION_STORE_AUTH_CREDS "store-auth-creds"
90 #define SVN_CONFIG_OPTION_STORE_SSL_CLIENT_CERT_PP "store-ssl-client-cert-pp"
91 #define SVN_CONFIG_OPTION_STORE_SSL_CLIENT_CERT_PP_PLAINTEXT \
92  "store-ssl-client-cert-pp-plaintext"
93 #define SVN_CONFIG_OPTION_USERNAME "username"
94 /** @since New in 1.8. */
95 #define SVN_CONFIG_OPTION_HTTP_BULK_UPDATES "http-bulk-updates"
96 /** @since New in 1.8. */
97 #define SVN_CONFIG_OPTION_HTTP_MAX_CONNECTIONS "http-max-connections"
98 /** @since New in 1.9. */
99 #define SVN_CONFIG_OPTION_HTTP_CHUNKED_REQUESTS "http-chunked-requests"
100 
101 /** @since New in 1.9. */
102 #define SVN_CONFIG_OPTION_SERF_LOG_COMPONENTS "serf-log-components"
103 /** @since New in 1.9. */
104 #define SVN_CONFIG_OPTION_SERF_LOG_LEVEL "serf-log-level"
105 
106 
107 #define SVN_CONFIG_CATEGORY_CONFIG "config"
108 #define SVN_CONFIG_SECTION_AUTH "auth"
109 /** @since New in 1.6. */
110 #define SVN_CONFIG_OPTION_PASSWORD_STORES "password-stores"
111 /** @since New in 1.6. */
112 #define SVN_CONFIG_OPTION_KWALLET_WALLET "kwallet-wallet"
113 /** @since New in 1.6. */
114 #define SVN_CONFIG_OPTION_KWALLET_SVN_APPLICATION_NAME_WITH_PID "kwallet-svn-application-name-with-pid"
115 /** @since New in 1.8. */
116 #define SVN_CONFIG_OPTION_SSL_CLIENT_CERT_FILE_PROMPT "ssl-client-cert-file-prompt"
117 /* The majority of options of the "auth" section
118  * has been moved to SVN_CONFIG_CATEGORY_SERVERS. */
119 #define SVN_CONFIG_SECTION_HELPERS "helpers"
120 #define SVN_CONFIG_OPTION_EDITOR_CMD "editor-cmd"
121 #define SVN_CONFIG_OPTION_DIFF_CMD "diff-cmd"
122 /** @since New in 1.7. */
123 #define SVN_CONFIG_OPTION_DIFF_EXTENSIONS "diff-extensions"
124 #define SVN_CONFIG_OPTION_DIFF3_CMD "diff3-cmd"
125 #define SVN_CONFIG_OPTION_DIFF3_HAS_PROGRAM_ARG "diff3-has-program-arg"
126 #define SVN_CONFIG_OPTION_MERGE_TOOL_CMD "merge-tool-cmd"
127 #define SVN_CONFIG_SECTION_MISCELLANY "miscellany"
128 #define SVN_CONFIG_OPTION_GLOBAL_IGNORES "global-ignores"
129 #define SVN_CONFIG_OPTION_LOG_ENCODING "log-encoding"
130 #define SVN_CONFIG_OPTION_USE_COMMIT_TIMES "use-commit-times"
131 /** @deprecated Not used by Subversion since 2003/r847039 (well before 1.0) */
132 #define SVN_CONFIG_OPTION_TEMPLATE_ROOT "template-root"
133 #define SVN_CONFIG_OPTION_ENABLE_AUTO_PROPS "enable-auto-props"
134 /** @since New in 1.9. */
135 #define SVN_CONFIG_OPTION_ENABLE_MAGIC_FILE "enable-magic-file"
136 #define SVN_CONFIG_OPTION_NO_UNLOCK "no-unlock"
137 #define SVN_CONFIG_OPTION_MIMETYPES_FILE "mime-types-file"
138 #define SVN_CONFIG_OPTION_PRESERVED_CF_EXTS "preserved-conflict-file-exts"
139 /** @since New in 1.7. */
140 #define SVN_CONFIG_OPTION_INTERACTIVE_CONFLICTS "interactive-conflicts"
141 /** @since New in 1.7. */
142 #define SVN_CONFIG_OPTION_MEMORY_CACHE_SIZE "memory-cache-size"
143 /** @since New in 1.9. */
144 #define SVN_CONFIG_OPTION_DIFF_IGNORE_CONTENT_TYPE "diff-ignore-content-type"
145 #define SVN_CONFIG_SECTION_TUNNELS "tunnels"
146 #define SVN_CONFIG_SECTION_AUTO_PROPS "auto-props"
147 /** @since New in 1.8. */
148 #define SVN_CONFIG_SECTION_WORKING_COPY "working-copy"
149 /** @since New in 1.8. */
150 #define SVN_CONFIG_OPTION_SQLITE_EXCLUSIVE "exclusive-locking"
151 /** @since New in 1.8. */
152 #define SVN_CONFIG_OPTION_SQLITE_EXCLUSIVE_CLIENTS "exclusive-locking-clients"
153 /** @since New in 1.9. */
154 #define SVN_CONFIG_OPTION_SQLITE_BUSY_TIMEOUT "busy-timeout"
155 /** @} */
156 
157 /** @name Repository conf directory configuration files strings
158  * Strings for the names of sections and options in the
159  * repository conf directory configuration files.
160  * @{
161  */
162 /* For repository svnserve.conf files */
163 #define SVN_CONFIG_SECTION_GENERAL "general"
164 #define SVN_CONFIG_OPTION_ANON_ACCESS "anon-access"
165 #define SVN_CONFIG_OPTION_AUTH_ACCESS "auth-access"
166 #define SVN_CONFIG_OPTION_PASSWORD_DB "password-db"
167 #define SVN_CONFIG_OPTION_REALM "realm"
168 #define SVN_CONFIG_OPTION_AUTHZ_DB "authz-db"
169 /** @since New in 1.8. */
170 #define SVN_CONFIG_OPTION_GROUPS_DB "groups-db"
171 /** @since New in 1.7. */
172 #define SVN_CONFIG_OPTION_FORCE_USERNAME_CASE "force-username-case"
173 /** @since New in 1.8. */
174 #define SVN_CONFIG_OPTION_HOOKS_ENV "hooks-env"
175 #define SVN_CONFIG_SECTION_SASL "sasl"
176 #define SVN_CONFIG_OPTION_USE_SASL "use-sasl"
177 #define SVN_CONFIG_OPTION_MIN_SSF "min-encryption"
178 #define SVN_CONFIG_OPTION_MAX_SSF "max-encryption"
179 
180 /* For repository password database */
181 #define SVN_CONFIG_SECTION_USERS "users"
182 /** @} */
183 
184 /*** Configuration Default Values ***/
185 
186 /* '*' matches leading dots, e.g. '*.rej' matches '.foo.rej'. */
187 /* We want this to be printed on two lines in the generated config file,
188  * but we don't want the # character to end up in the variable.
189  */
190 #ifndef DOXYGEN_SHOULD_SKIP_THIS
191 #define SVN_CONFIG__DEFAULT_GLOBAL_IGNORES_LINE_1 \
192  "*.o *.lo *.la *.al .libs *.so *.so.[0-9]* *.a *.pyc *.pyo __pycache__"
193 #define SVN_CONFIG__DEFAULT_GLOBAL_IGNORES_LINE_2 \
194  "*.rej *~ #*# .#* .*.swp .DS_Store [Tt]humbs.db"
195 #endif
196 
197 #define SVN_CONFIG_DEFAULT_GLOBAL_IGNORES \
198  SVN_CONFIG__DEFAULT_GLOBAL_IGNORES_LINE_1 " " \
199  SVN_CONFIG__DEFAULT_GLOBAL_IGNORES_LINE_2
200 
201 #define SVN_CONFIG_TRUE "TRUE"
202 #define SVN_CONFIG_FALSE "FALSE"
203 #define SVN_CONFIG_ASK "ASK"
204 
205 /* Default values for some options. Should be passed as default values
206  * to svn_config_get and friends, instead of hard-coding the defaults in
207  * multiple places. */
208 #define SVN_CONFIG_DEFAULT_OPTION_STORE_PASSWORDS TRUE
209 #define SVN_CONFIG_DEFAULT_OPTION_STORE_PLAINTEXT_PASSWORDS SVN_CONFIG_ASK
210 #define SVN_CONFIG_DEFAULT_OPTION_STORE_AUTH_CREDS TRUE
211 #define SVN_CONFIG_DEFAULT_OPTION_STORE_SSL_CLIENT_CERT_PP TRUE
212 #define SVN_CONFIG_DEFAULT_OPTION_STORE_SSL_CLIENT_CERT_PP_PLAINTEXT \
213  SVN_CONFIG_ASK
214 #define SVN_CONFIG_DEFAULT_OPTION_HTTP_MAX_CONNECTIONS 4
215 
216 /** Read configuration information from the standard sources and merge it
217  * into the hash @a *cfg_hash. If @a config_dir is not NULL it specifies a
218  * directory from which to read the configuration files, overriding all
219  * other sources. Otherwise, first read any system-wide configurations
220  * (from a file or from the registry), then merge in personal
221  * configurations (again from file or registry). The hash and all its data
222  * are allocated in @a pool.
223  *
224  * @a *cfg_hash is a hash whose keys are @c const char * configuration
225  * categories (@c SVN_CONFIG_CATEGORY_SERVERS,
226  * @c SVN_CONFIG_CATEGORY_CONFIG, etc.) and whose values are the @c
227  * svn_config_t * items representing the configuration values for that
228  * category.
229  */
230 svn_error_t *
231 svn_config_get_config(apr_hash_t **cfg_hash,
232  const char *config_dir,
233  apr_pool_t *pool);
234 
235 /** Set @a *cfgp to an empty @c svn_config_t structure,
236  * allocated in @a result_pool.
237  *
238  * Pass TRUE to @a section_names_case_sensitive if
239  * section names are to be populated case sensitively.
240  *
241  * Pass TRUE to @a option_names_case_sensitive if
242  * option names are to be populated case sensitively.
243  *
244  * @since New in 1.8.
245  */
246 svn_error_t *
248  svn_boolean_t section_names_case_sensitive,
249  svn_boolean_t option_names_case_sensitive,
250  apr_pool_t *result_pool);
251 
252 /** Similar to svn_config_create2, but always passes @c FALSE to
253  * @a option_names_case_sensitive.
254  *
255  * @since New in 1.7.
256  * @deprecated Provided for backward compatibility with 1.7 API.
257  */
259 svn_error_t *
261  svn_boolean_t section_names_case_sensitive,
262  apr_pool_t *result_pool);
263 
264 /** Read configuration data from @a file (a file or registry path) into
265  * @a *cfgp, allocated in @a pool.
266  *
267  * If @a file does not exist, then if @a must_exist, return an error,
268  * otherwise return an empty @c svn_config_t.
269  *
270  * If @a section_names_case_sensitive is @c TRUE, populate section name hashes
271  * case sensitively, except for the @c "DEFAULT" section.
272  *
273  * If @a option_names_case_sensitive is @c TRUE, populate option name hashes
274  * case sensitively.
275  *
276  * @since New in 1.8.
277  */
278 svn_error_t *
280  const char *file,
281  svn_boolean_t must_exist,
282  svn_boolean_t section_names_case_sensitive,
283  svn_boolean_t option_names_case_sensitive,
284  apr_pool_t *result_pool);
285 
286 /** Similar to svn_config_read3, but always passes @c FALSE to
287  * @a option_names_case_sensitive.
288  *
289  * @since New in 1.7.
290  * @deprecated Provided for backward compatibility with 1.7 API.
291  */
293 svn_error_t *
295  const char *file,
296  svn_boolean_t must_exist,
297  svn_boolean_t section_names_case_sensitive,
298  apr_pool_t *result_pool);
299 
300 /** Similar to svn_config_read2, but always passes @c FALSE to
301  * @a section_names_case_sensitive.
302  *
303  * @deprecated Provided for backward compatibility with 1.6 API.
304  */
306 svn_error_t *
308  const char *file,
309  svn_boolean_t must_exist,
310  apr_pool_t *result_pool);
311 
312 /** Read configuration data from @a stream into @a *cfgp, allocated in
313  * @a result_pool.
314  *
315  * If @a section_names_case_sensitive is @c TRUE, populate section name hashes
316  * case sensitively, except for the @c "DEFAULT" section.
317  *
318  * If @a option_names_case_sensitive is @c TRUE, populate option name hashes
319  * case sensitively.
320  *
321  * @since New in 1.8.
322  */
323 
324 svn_error_t *
326  svn_stream_t *stream,
327  svn_boolean_t section_names_case_sensitive,
328  svn_boolean_t option_names_case_sensitive,
329  apr_pool_t *result_pool);
330 
331 /** Like svn_config_read(), but merges the configuration data from @a file
332  * (a file or registry path) into @a *cfg, which was previously returned
333  * from svn_config_read(). This function invalidates all value
334  * expansions in @a cfg, so that the next svn_config_get() takes the
335  * modifications into account.
336  */
337 svn_error_t *
339  const char *file,
340  svn_boolean_t must_exist);
341 
342 
343 /** Find the value of a (@a section, @a option) pair in @a cfg, set @a
344  * *valuep to the value.
345  *
346  * If @a cfg is @c NULL, just sets @a *valuep to @a default_value. If
347  * the value does not exist, expand and return @a default_value. @a
348  * default_value can be NULL.
349  *
350  * The returned value will be valid at least until the next call to
351  * svn_config_get(), or for the lifetime of @a default_value. It is
352  * safest to consume the returned value immediately.
353  *
354  * This function may change @a cfg by expanding option values.
355  */
356 void
358  const char **valuep,
359  const char *section,
360  const char *option,
361  const char *default_value);
362 
363 /** Add or replace the value of a (@a section, @a option) pair in @a cfg with
364  * @a value.
365  *
366  * This function invalidates all value expansions in @a cfg.
367  *
368  * To remove an option, pass NULL for the @a value.
369  */
370 void
372  const char *section,
373  const char *option,
374  const char *value);
375 
376 /** Like svn_config_get(), but for boolean values.
377  *
378  * Parses the option as a boolean value. The recognized representations
379  * are 'TRUE'/'FALSE', 'yes'/'no', 'on'/'off', '1'/'0'; case does not
380  * matter. Returns an error if the option doesn't contain a known string.
381  */
382 svn_error_t *
384  svn_boolean_t *valuep,
385  const char *section,
386  const char *option,
387  svn_boolean_t default_value);
388 
389 /** Like svn_config_set(), but for boolean values.
390  *
391  * Sets the option to 'TRUE'/'FALSE', depending on @a value.
392  */
393 void
395  const char *section,
396  const char *option,
397  svn_boolean_t value);
398 
399 /** Like svn_config_get(), but for 64-bit signed integers.
400  *
401  * Parses the @a option in @a section of @a cfg as an integer value,
402  * setting @a *valuep to the result. If the option is not found, sets
403  * @a *valuep to @a default_value. If the option is found but cannot
404  * be converted to an integer, returns an error.
405  *
406  * @since New in 1.8.
407  */
408 svn_error_t *
410  apr_int64_t *valuep,
411  const char *section,
412  const char *option,
413  apr_int64_t default_value);
414 
415 /** Like svn_config_set(), but for 64-bit signed integers.
416  *
417  * Sets the value of @a option in @a section of @a cfg to the signed
418  * decimal @a value.
419  *
420  * @since New in 1.8.
421  */
422 void
424  const char *section,
425  const char *option,
426  apr_int64_t value);
427 
428 /** Like svn_config_get(), but only for yes/no/ask values.
429  *
430  * Parse @a option in @a section and set @a *valuep to one of
431  * SVN_CONFIG_TRUE, SVN_CONFIG_FALSE, or SVN_CONFIG_ASK. If there is
432  * no setting for @a option, then parse @a default_value and set
433  * @a *valuep accordingly. If @a default_value is NULL, the result is
434  * undefined, and may be an error; we recommend that you pass one of
435  * SVN_CONFIG_TRUE, SVN_CONFIG_FALSE, or SVN_CONFIG_ASK for @a default value.
436  *
437  * Valid representations are (at least) "true"/"false", "yes"/"no",
438  * "on"/"off", "1"/"0", and "ask"; they are case-insensitive. Return
439  * an SVN_ERR_BAD_CONFIG_VALUE error if either @a default_value or
440  * @a option's value is not a valid representation.
441  *
442  * @since New in 1.6.
443  */
444 svn_error_t *
446  const char **valuep,
447  const char *section,
448  const char *option,
449  const char* default_value);
450 
451 /** Like svn_config_get_bool(), but for tristate values.
452  *
453  * Set @a *valuep to #svn_tristate_true, #svn_tristate_false, or
454  * #svn_tristate_unknown, depending on the value of @a option in @a
455  * section of @a cfg. True and false values are the same as for
456  * svn_config_get_bool(); @a unknown_value specifies the option value
457  * allowed for third state (#svn_tristate_unknown).
458  *
459  * Use @a default_value as the default value if @a option cannot be
460  * found.
461  *
462  * @since New in 1.8.
463  */
464 svn_error_t *
466  svn_tristate_t *valuep,
467  const char *section,
468  const char *option,
469  const char *unknown_value,
470  svn_tristate_t default_value);
471 
472 /** Similar to @c svn_config_section_enumerator2_t, but is not
473  * provided with a memory pool argument.
474  *
475  * See svn_config_enumerate_sections() for the details of this type.
476  *
477  * @deprecated Provided for backwards compatibility with the 1.2 API.
478  */
479 typedef svn_boolean_t (*svn_config_section_enumerator_t)(const char *name,
480  void *baton);
481 
482 /** Similar to svn_config_enumerate_sections2(), but uses a memory pool of
483  * @a cfg instead of one that is explicitly provided.
484  *
485  * @deprecated Provided for backwards compatibility with the 1.2 API.
486  */
488 int
491  void *baton);
492 
493 /** A callback function used in enumerating config sections.
494  *
495  * See svn_config_enumerate_sections2() for the details of this type.
496  *
497  * @since New in 1.3.
498  */
500  void *baton,
501  apr_pool_t *pool);
502 
503 /** Enumerate the sections, passing @a baton and the current section's name
504  * to @a callback. Continue the enumeration if @a callback returns @c TRUE.
505  * Return the number of times @a callback was called.
506  *
507  * ### See kff's comment to svn_config_enumerate2(). It applies to this
508  * function, too. ###
509  *
510  * @a callback's @a name parameter is only valid for the duration of the call.
511  *
512  * @since New in 1.3.
513  */
514 int
517  void *baton, apr_pool_t *pool);
518 
519 /** Similar to @c svn_config_enumerator2_t, but is not
520  * provided with a memory pool argument.
521  * See svn_config_enumerate() for the details of this type.
522  *
523  * @deprecated Provided for backwards compatibility with the 1.2 API.
524  */
525 typedef svn_boolean_t (*svn_config_enumerator_t)(const char *name,
526  const char *value,
527  void *baton);
528 
529 /** Similar to svn_config_enumerate2(), but uses a memory pool of
530  * @a cfg instead of one that is explicitly provided.
531  *
532  * @deprecated Provided for backwards compatibility with the 1.2 API.
533  */
535 int
537  const char *section,
538  svn_config_enumerator_t callback,
539  void *baton);
540 
541 
542 /** A callback function used in enumerating config options.
543  *
544  * See svn_config_enumerate2() for the details of this type.
545  *
546  * @since New in 1.3.
547  */
548 typedef svn_boolean_t (*svn_config_enumerator2_t)(const char *name,
549  const char *value,
550  void *baton,
551  apr_pool_t *pool);
552 
553 /** Enumerate the options in @a section, passing @a baton and the current
554  * option's name and value to @a callback. Continue the enumeration if
555  * @a callback returns @c TRUE. Return the number of times @a callback
556  * was called.
557  *
558  * ### kff asks: A more usual interface is to continue enumerating
559  * while @a callback does not return error, and if @a callback does
560  * return error, to return the same error (or a wrapping of it)
561  * from svn_config_enumerate(). What's the use case for
562  * svn_config_enumerate()? Is it more likely to need to break out
563  * of an enumeration early, with no error, than an invocation of
564  * @a callback is likely to need to return an error? ###
565  *
566  * @a callback's @a name and @a value parameters are only valid for the
567  * duration of the call.
568  *
569  * @since New in 1.3.
570  */
571 int
573  const char *section,
574  svn_config_enumerator2_t callback,
575  void *baton,
576  apr_pool_t *pool);
577 
578 /**
579  * Return @c TRUE if @a section exists in @a cfg, @c FALSE otherwise.
580  *
581  * @since New in 1.4.
582  */
585  const char *section);
586 
587 /** Enumerate the group @a master_section in @a cfg. Each variable
588  * value is interpreted as a list of glob patterns (separated by comma
589  * and optional whitespace). Return the name of the first variable
590  * whose value matches @a key, or @c NULL if no variable matches.
591  */
592 const char *
594  const char *key,
595  const char *master_section,
596  apr_pool_t *pool);
597 
598 /** Retrieve value corresponding to @a option_name in @a cfg, or
599  * return @a default_value if none is found.
600  *
601  * The config will first be checked for a default.
602  * If @a server_group is not @c NULL, the config will also be checked
603  * for an override in a server group,
604  *
605  */
606 const char *
608  const char* server_group,
609  const char* option_name,
610  const char* default_value);
611 
612 /** Retrieve value into @a result_value corresponding to @a option_name for a
613  * given @a server_group in @a cfg, or return @a default_value if none is
614  * found.
615  *
616  * The config will first be checked for a default, then will be checked for
617  * an override in a server group. If the value found is not a valid integer,
618  * a @c svn_error_t* will be returned.
619  */
620 svn_error_t *
622  const char *server_group,
623  const char *option_name,
624  apr_int64_t default_value,
625  apr_int64_t *result_value,
626  apr_pool_t *pool);
627 
628 
629 /** Set @a *valuep according to @a option_name for a given
630  * @a server_group in @a cfg, or set to @a default_value if no value is
631  * specified.
632  *
633  * Check first a default, then for an override in a server group. If
634  * a value is found but is not a valid boolean, return an
635  * SVN_ERR_BAD_CONFIG_VALUE error.
636  *
637  * @since New in 1.6.
638  */
639 svn_error_t *
641  svn_boolean_t *valuep,
642  const char *server_group,
643  const char *option_name,
644  svn_boolean_t default_value);
645 
646 
647 
648 /** Try to ensure that the user's ~/.subversion/ area exists, and create
649  * no-op template files for any absent config files. Use @a pool for any
650  * temporary allocation. If @a config_dir is not @c NULL it specifies a
651  * directory from which to read the config overriding all other sources.
652  *
653  * Don't error if something exists but is the wrong kind (for example,
654  * ~/.subversion exists but is a file, or ~/.subversion/servers exists
655  * but is a directory).
656  *
657  * Also don't error if trying to create something and failing -- it's
658  * okay for the config area or its contents not to be created.
659  * However, if creating a config template file succeeds, return an
660  * error if unable to initialize its contents.
661  */
662 svn_error_t *
663 svn_config_ensure(const char *config_dir,
664  apr_pool_t *pool);
665 
666 
667 
668 
669 /** Accessing cached authentication data in the user config area.
670  *
671  * @defgroup cached_authentication_data Cached authentication data
672  * @{
673  */
674 
675 
676 /**
677  * Attributes of authentication credentials.
678  *
679  * The values of these keys are C strings.
680  *
681  * @note Some of these hash keys were also used in versions < 1.9 but were
682  * not part of the public API (except #SVN_CONFIG_REALMSTRING_KEY which
683  * has been present since 1.0).
684  *
685  * @defgroup cached_authentication_data_attributes Cached authentication data attributes
686  * @{
687  */
688 
689 /** A hash-key pointing to a realmstring. This attribute is mandatory.
690  *
691  * @since New in 1.0.
692  */
693 #define SVN_CONFIG_REALMSTRING_KEY "svn:realmstring"
694 
695 /** A hash-key for usernames.
696  * @since New in 1.9.
697  */
698 #define SVN_CONFIG_AUTHN_USERNAME_KEY "username"
699 
700 /** A hash-key for passwords.
701  * The password may be in plaintext or encrypted form, depending on
702  * the authentication provider.
703  * @since New in 1.9.
704  */
705 #define SVN_CONFIG_AUTHN_PASSWORD_KEY "password"
706 
707 /** A hash-key for passphrases,
708  * such as SSL client ceritifcate passphrases. The passphrase may be in
709  * plaintext or encrypted form, depending on the authentication provider.
710  * @since New in 1.9.
711  */
712 #define SVN_CONFIG_AUTHN_PASSPHRASE_KEY "passphrase"
713 
714 /** A hash-key for the type of a password or passphrase. The type
715  * indicates which provider owns the credential.
716  * @since New in 1.9.
717  */
718 #define SVN_CONFIG_AUTHN_PASSTYPE_KEY "passtype"
719 
720 /** A hash-key for SSL certificates. The value is the base64-encoded DER form
721  * certificate.
722  * @since New in 1.9.
723  * @note The value is not human readable.
724  */
725 #define SVN_CONFIG_AUTHN_ASCII_CERT_KEY "ascii_cert"
726 
727 /** A hash-key for recorded SSL certificate verification
728  * failures. Failures encoded as an ASCII integer containing any of the
729  * SVN_AUTH_SSL_* SSL server certificate failure bits defined in svn_auth.h.
730  * @since New in 1.9.
731  */
732 #define SVN_CONFIG_AUTHN_FAILURES_KEY "failures"
733 
734 
735 /** @} */
736 
737 /** Use @a cred_kind and @a realmstring to locate a file within the
738  * ~/.subversion/auth/ area. If the file exists, initialize @a *hash
739  * and load the file contents into the hash, using @a pool. If the
740  * file doesn't exist, set @a *hash to NULL.
741  *
742  * If @a config_dir is not NULL it specifies a directory from which to
743  * read the config overriding all other sources.
744  *
745  * Besides containing the original credential fields, the hash will
746  * also contain @c SVN_CONFIG_REALMSTRING_KEY. The caller can examine
747  * this value as a sanity-check that the correct file was loaded.
748  *
749  * The hashtable will contain <tt>const char *</tt> keys and
750  * <tt>svn_string_t *</tt> values.
751  */
752 svn_error_t *
753 svn_config_read_auth_data(apr_hash_t **hash,
754  const char *cred_kind,
755  const char *realmstring,
756  const char *config_dir,
757  apr_pool_t *pool);
758 
759 /** Use @a cred_kind and @a realmstring to create or overwrite a file
760  * within the ~/.subversion/auth/ area. Write the contents of @a hash into
761  * the file. If @a config_dir is not NULL it specifies a directory to read
762  * the config overriding all other sources.
763  *
764  * Also, add @a realmstring to the file, with key @c
765  * SVN_CONFIG_REALMSTRING_KEY. This allows programs (or users) to
766  * verify exactly which set credentials live within the file.
767  *
768  * The hashtable must contain <tt>const char *</tt> keys and
769  * <tt>svn_string_t *</tt> values.
770  */
771 svn_error_t *
772 svn_config_write_auth_data(apr_hash_t *hash,
773  const char *cred_kind,
774  const char *realmstring,
775  const char *config_dir,
776  apr_pool_t *pool);
777 
778 
779 /** Callback for svn_config_walk_auth_data().
780  *
781  * Called for each credential walked by that function (and able to be
782  * fully purged) to allow perusal and selective removal of credentials.
783  *
784  * @a cred_kind and @a realmstring specify the key of the credential.
785  * @a hash contains the hash data associated with the record. @a walk_baton
786  * is the baton passed to svn_config_walk_auth_data().
787  *
788  * Before returning set @a *delete_cred to TRUE to remove the credential from
789  * the cache; leave @a *delete_cred unchanged or set it to FALSE to keep the
790  * credential.
791  *
792  * Implementations may return #SVN_ERR_CEASE_INVOCATION to indicate
793  * that the callback should not be called again. Note that when that
794  * error is returned, the value of @a delete_cred will still be
795  * honored and action taken if necessary. (For other returned errors,
796  * @a delete_cred is ignored by svn_config_walk_auth_data().)
797  *
798  * @since New in 1.8.
799  */
800 typedef svn_error_t *
801 (*svn_config_auth_walk_func_t)(svn_boolean_t *delete_cred,
802  void *walk_baton,
803  const char *cred_kind,
804  const char *realmstring,
805  apr_hash_t *hash,
806  apr_pool_t *scratch_pool);
807 
808 /** Call @a walk_func with @a walk_baton and information describing
809  * each credential cached within the Subversion auth store located
810  * under @a config_dir. If the callback sets its delete_cred return
811  * flag, delete the associated credential.
812  *
813  * If @a config_dir is not NULL, it must point to an alternative
814  * config directory location. If it is NULL, the default location
815  * is used.
816  *
817  * @note @a config_dir may only be NULL in 1.8.2 and later.
818  *
819  * @note Removing credentials from the config-based disk store will
820  * not purge them from any open svn_auth_baton_t instance. Consider
821  * using svn_auth_forget_credentials() -- from the @a walk_func,
822  * even -- for this purpose.
823  *
824  * @note Removing credentials from the config-based disk store will
825  * not also remove any related credentials from third-party password
826  * stores. (Implementations of @a walk_func which delete credentials
827  * may wish to consult the "passtype" element of @a hash, if any, to
828  * see if a third-party store -- such as "gnome-keyring" or "kwallet"
829  * is being used to hold the most sensitive portion of the credentials
830  * for this @a cred_kind and @a realmstring.)
831  *
832  * @see svn_auth_forget_credentials()
833  *
834  * @since New in 1.8.
835  */
836 svn_error_t *
837 svn_config_walk_auth_data(const char *config_dir,
838  svn_config_auth_walk_func_t walk_func,
839  void *walk_baton,
840  apr_pool_t *scratch_pool);
841 
842 /** Put the absolute path to the user's configuration directory,
843  * or to a file within that directory, into @a *path.
844  *
845  * If @a config_dir is not NULL, it must point to an alternative
846  * config directory location. If it is NULL, the default location
847  * is used. If @a fname is not NULL, it must specify the last
848  * component of the path to be returned. This can be used to create
849  * a path to any file in the configuration directory.
850  *
851  * Do all allocations in @a pool.
852  *
853  * Hint:
854  * To get the user configuration file, pass @c SVN_CONFIG_CATEGORY_CONFIG
855  * for @a fname. To get the servers configuration file, pass
856  * @c SVN_CONFIG_CATEGORY_SERVERS for @a fname.
857  *
858  * @since New in 1.6.
859  */
860 svn_error_t *
861 svn_config_get_user_config_path(const char **path,
862  const char *config_dir,
863  const char *fname,
864  apr_pool_t *pool);
865 
866 /** Create a deep copy of the config object @a src and return
867  * it in @a cfgp, allocating the memory in @a pool.
868  *
869  * @since New in 1.8.
870  */
871 svn_error_t *
873  const svn_config_t *src,
874  apr_pool_t *pool);
875 
876 /** Create a deep copy of the config hash @a src_hash and return
877  * it in @a cfg_hash, allocating the memory in @a pool.
878  *
879  * @since New in 1.8.
880  */
881 svn_error_t *
882 svn_config_copy_config(apr_hash_t **cfg_hash,
883  apr_hash_t *src_hash,
884  apr_pool_t *pool);
885 
886 /** @} */
887 
888 #ifdef __cplusplus
889 }
890 #endif /* __cplusplus */
891 
892 #endif /* SVN_CONFIG_H */