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