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