Subversion
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
svn_cmdline.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_cmdline.h
24  * @brief Support functions for command line programs
25  */
26 
27 
28 
29 
30 #ifndef SVN_CMDLINE_H
31 #define SVN_CMDLINE_H
32 
33 #include <apr_pools.h>
34 #include <apr_getopt.h>
35 
36 #ifndef DOXYGEN_SHOULD_SKIP_THIS
37 #define APR_WANT_STDIO
38 #endif
39 #include <apr_want.h>
40 
41 #include "svn_types.h"
42 #include "svn_auth.h"
43 #include "svn_config.h"
44 
45 #ifdef __cplusplus
46 extern "C" {
47 #endif /* __cplusplus */
48 
49 
50 /** Set up the locale for character conversion, and initialize APR.
51  * If @a error_stream is non-NULL, print error messages to the stream,
52  * using @a progname as the program name. Attempt to set @c stdout to
53  * line-buffered mode, and @a error_stream to unbuffered mode. Return
54  * @c EXIT_SUCCESS if successful, otherwise @c EXIT_FAILURE.
55  *
56  * @note This function should be called exactly once at program startup,
57  * before calling any other APR or Subversion functions.
58  */
59 int
60 svn_cmdline_init(const char *progname,
61  FILE *error_stream);
62 
63 
64 /** Set @a *dest to an output-encoded C string from UTF-8 C string @a
65  * src; allocate @a *dest in @a pool.
66  */
68 svn_cmdline_cstring_from_utf8(const char **dest,
69  const char *src,
70  apr_pool_t *pool);
71 
72 /** Like svn_utf_cstring_from_utf8_fuzzy(), but converts to an
73  * output-encoded C string. */
74 const char *
76  apr_pool_t *pool);
77 
78 /** Set @a *dest to a UTF-8-encoded C string from input-encoded C
79  * string @a src; allocate @a *dest in @a pool.
80  */
82 svn_cmdline_cstring_to_utf8(const char **dest,
83  const char *src,
84  apr_pool_t *pool);
85 
86 /** Set @a *dest to an output-encoded natively-formatted path string
87  * from canonical path @a src; allocate @a *dest in @a pool.
88  */
91  const char *src,
92  apr_pool_t *pool);
93 
94 /** Write to stdout, using a printf-like format string @a fmt, passed
95  * through apr_pvsprintf(). All string arguments are in UTF-8; the output
96  * is converted to the output encoding. Use @a pool for temporary
97  * allocation.
98  *
99  * @since New in 1.1.
100  */
101 svn_error_t *
102 svn_cmdline_printf(apr_pool_t *pool,
103  const char *fmt,
104  ...)
105  __attribute__((format(printf, 2, 3)));
106 
107 /** Write to the stdio @a stream, using a printf-like format string @a fmt,
108  * passed through apr_pvsprintf(). All string arguments are in UTF-8;
109  * the output is converted to the output encoding. Use @a pool for
110  * temporary allocation.
111  *
112  * @since New in 1.1.
113  */
114 svn_error_t *
115 svn_cmdline_fprintf(FILE *stream,
116  apr_pool_t *pool,
117  const char *fmt,
118  ...)
119  __attribute__((format(printf, 3, 4)));
120 
121 /** Output the @a string to the stdio @a stream, converting from UTF-8
122  * to the output encoding. Use @a pool for temporary allocation.
123  *
124  * @since New in 1.1.
125  */
126 svn_error_t *
127 svn_cmdline_fputs(const char *string,
128  FILE *stream,
129  apr_pool_t *pool);
130 
131 /** Flush output buffers of the stdio @a stream, returning an error if that
132  * fails. This is just a wrapper for the standard fflush() function for
133  * consistent error handling.
134  *
135  * @since New in 1.1.
136  */
137 svn_error_t *
138 svn_cmdline_fflush(FILE *stream);
139 
140 /** Return the name of the output encoding allocated in @a pool, or @c
141  * APR_LOCALE_CHARSET if the output encoding is the same as the locale
142  * encoding.
143  *
144  * @since New in 1.3.
145  */
146 const char *
147 svn_cmdline_output_encoding(apr_pool_t *pool);
148 
149 /** Handle @a error in preparation for immediate exit from a
150  * command-line client. Specifically:
151  *
152  * Call svn_handle_error2(@a error, stderr, FALSE, @a prefix), clear
153  * @a error, destroy @a pool iff it is non-NULL, and return EXIT_FAILURE.
154  *
155  * @since New in 1.3.
156  */
157 int
159  apr_pool_t *pool,
160  const char *prefix);
161 
162 /** A prompt function/baton pair, and the path to the configuration
163  * directory. To be passed as the baton argument to the
164  * @c svn_cmdline_*_prompt functions.
165  *
166  * @since New in 1.6.
167  */
169  svn_cancel_func_t cancel_func;
170  void *cancel_baton;
171  const char *config_dir;
173 
174 /** Like svn_cmdline_prompt_baton2_t, but without the path to the
175  * configuration directory.
176  *
177  * @since New in 1.4.
178  * @deprecated Provided for backward compatibility with the 1.5 API.
179  */
181  svn_cancel_func_t cancel_func;
182  void *cancel_baton;
184 
185 /** Prompt the user for input, using @a prompt_str for the prompt and
186  * @a baton (which may be @c NULL) for cancellation, and returning the
187  * user's response in @a result, allocated in @a pool.
188  *
189  * @since New in 1.5.
190  */
191 svn_error_t *
192 svn_cmdline_prompt_user2(const char **result,
193  const char *prompt_str,
195  apr_pool_t *pool);
196 
197 /** Similar to svn_cmdline_prompt_user2, but without cancellation
198  * support.
199  *
200  * @deprecated Provided for backward compatibility with the 1.4 API.
201  */
203 svn_error_t *
204 svn_cmdline_prompt_user(const char **result,
205  const char *prompt_str,
206  apr_pool_t *pool);
207 
208 /** An implementation of @c svn_auth_simple_prompt_func_t that prompts
209  * the user for keyboard input on the command line.
210  *
211  * @since New in 1.4.
212  *
213  * Expects a @c svn_cmdline_prompt_baton_t to be passed as @a baton.
214  */
215 svn_error_t *
217  void *baton,
218  const char *realm,
219  const char *username,
220  svn_boolean_t may_save,
221  apr_pool_t *pool);
222 
223 
224 /** An implementation of @c svn_auth_username_prompt_func_t that prompts
225  * the user for their username via the command line.
226  *
227  * @since New in 1.4.
228  *
229  * Expects a @c svn_cmdline_prompt_baton_t to be passed as @a baton.
230  */
231 svn_error_t *
233  void *baton,
234  const char *realm,
235  svn_boolean_t may_save,
236  apr_pool_t *pool);
237 
238 
239 /** An implementation of @c svn_auth_ssl_server_trust_prompt_func_t that
240  * asks the user if they trust a specific ssl server via the command line.
241  *
242  * @since New in 1.4.
243  *
244  * Expects a @c svn_cmdline_prompt_baton_t to be passed as @a baton.
245  */
246 svn_error_t *
249  void *baton,
250  const char *realm,
251  apr_uint32_t failures,
252  const svn_auth_ssl_server_cert_info_t *cert_info,
253  svn_boolean_t may_save,
254  apr_pool_t *pool);
255 
256 
257 /** An implementation of @c svn_auth_ssl_client_cert_prompt_func_t that
258  * prompts the user for the filename of their SSL client certificate via
259  * the command line.
260  *
261  * Records absolute path of the SSL client certificate file.
262  *
263  * @since New in 1.4.
264  *
265  * Expects a @c svn_cmdline_prompt_baton_t to be passed as @a baton.
266  */
267 svn_error_t *
270  void *baton,
271  const char *realm,
272  svn_boolean_t may_save,
273  apr_pool_t *pool);
274 
275 
276 /** An implementation of @c svn_auth_ssl_client_cert_pw_prompt_func_t that
277  * prompts the user for their SSL certificate password via the command line.
278  *
279  * @since New in 1.4.
280  *
281  * Expects a @c svn_cmdline_prompt_baton_t to be passed as @a baton.
282  */
283 svn_error_t *
286  void *baton,
287  const char *realm,
288  svn_boolean_t may_save,
289  apr_pool_t *pool);
290 
291 /** An implementation of @c svn_auth_plaintext_prompt_func_t that
292  * prompts the user whether storing unencrypted passwords to disk is OK.
293  *
294  * Expects a @c svn_cmdline_prompt_baton2_t to be passed as @a baton.
295  *
296  * @since New in 1.6.
297  */
298 svn_error_t *
300  const char *realmstring,
301  void *baton,
302  apr_pool_t *pool);
303 
304 /** An implementation of @c svn_auth_plaintext_passphrase_prompt_func_t that
305  * prompts the user whether storing unencrypted passphrase to disk is OK.
306  *
307  * Expects a @c svn_cmdline_prompt_baton2_t to be passed as @a baton.
308  *
309  * @since New in 1.6.
310  */
311 svn_error_t *
313  const char *realmstring,
314  void *baton,
315  apr_pool_t *pool);
316 
317 
318 /** Set @a *ab to an authentication baton allocated from @a pool and
319  * initialized with the standard set of authentication providers used
320  * by the command line client.
321  *
322  * @a non_interactive, @a username, @a password, @a config_dir,
323  * and @a no_auth_cache are the values of the command line options
324  * of the corresponding names.
325  *
326  * If @a non_interactive is @c TRUE, then the following parameters
327  * control whether an invalid SSL certificate will be accepted
328  * regardless of a specific verification failure:
329  *
330  * @a trust_server_cert_unknown_ca: If @c TRUE, accept certificates
331  * from unknown certificate authorities.
332  *
333  * @a trust_server_cert_cn_mismatch: If @c TRUE, accept certificates
334  * even if the Common Name attribute of the certificate differs from
335  * the hostname of the server.
336  *
337  * @a trust_server_cert_expired: If @c TRUE, accept certificates even
338  * if they are expired.
339  *
340  * @a trust_server_cert_not_yet_valid: If @c TRUE, accept certificates
341  * from the future.
342  *
343  * @a trust_server_cert_other_failure: If @c TRUE, accept certificates
344  * even if any other verification failure than the above occured.
345  *
346  * @a cfg is the @c SVN_CONFIG_CATEGORY_CONFIG configuration, and
347  * @a cancel_func and @a cancel_baton control the cancellation of the
348  * prompting providers that are initialized.
349  *
350  * Use @a pool for all allocations.
351  *
352  * @since New in 1.9.
353  */
354 svn_error_t *
356  svn_boolean_t non_interactive,
357  const char *username,
358  const char *password,
359  const char *config_dir,
360  svn_boolean_t no_auth_cache,
361  svn_boolean_t trust_server_cert_unknown_ca,
362  svn_boolean_t trust_server_cert_cn_mismatch,
363  svn_boolean_t trust_server_cert_expired,
364  svn_boolean_t trust_server_cert_not_yet_valid,
365  svn_boolean_t trust_server_cert_other_failure,
366  svn_config_t *cfg,
367  svn_cancel_func_t cancel_func,
368  void *cancel_baton,
369  apr_pool_t *pool);
370 
371 /* Like svn_cmdline_create_auth_baton2, but with only one trust_server_cert
372  * option which corresponds to trust_server_cert_unknown_ca.
373  *
374  * @deprecated Provided for backward compatibility with the 1.8 API.
375  * @since New in 1.6.
376  */
378 svn_error_t *
379 svn_cmdline_create_auth_baton(svn_auth_baton_t **ab,
380  svn_boolean_t non_interactive,
381  const char *username,
382  const char *password,
383  const char *config_dir,
384  svn_boolean_t no_auth_cache,
385  svn_boolean_t trust_server_cert,
386  svn_config_t *cfg,
387  svn_cancel_func_t cancel_func,
388  void *cancel_baton,
389  apr_pool_t *pool);
390 
391 /** Similar to svn_cmdline_create_auth_baton(), but with
392  * @a trust_server_cert always set to false.
393  *
394  * @since New in 1.4.
395  * @deprecated Provided for backward compatibility with the 1.5 API.
396  * Use svn_cmdline_create_auth_baton() instead.
397  *
398  * @note This deprecation does not follow the usual pattern of putting
399  * a new number on end of the function's name. Instead, the new
400  * function name is distinguished from the old by a grammatical
401  * improvement: the verb "create" instead of the noun "setup".
402  */
404 svn_error_t *
406  svn_boolean_t non_interactive,
407  const char *username,
408  const char *password,
409  const char *config_dir,
410  svn_boolean_t no_auth_cache,
411  svn_config_t *cfg,
412  svn_cancel_func_t cancel_func,
413  void *cancel_baton,
414  apr_pool_t *pool);
415 
416 #ifdef __cplusplus
417 }
418 #endif /* __cplusplus */
419 
420 #endif /* SVN_CMDLINE_H */