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  * Copyright (c) 2000-2004, 2008-2009 CollabNet. All rights reserved.
5  *
6  * This software is licensed as described in the file COPYING, which
7  * you should have received as part of this distribution. The terms
8  * are also available at http://subversion.tigris.org/license-1.html.
9  * If newer versions of this license are posted there, you may use a
10  * newer version instead, at your option.
11  *
12  * This software consists of voluntary contributions made by many
13  * individuals. For exact contribution history, see the revision
14  * history and logs, available at http://subversion.tigris.org/.
15  * ====================================================================
16  * @endcopyright
17  *
18  * @file svn_cmdline.h
19  * @brief Support functions for command line programs
20  */
21 
22 
23 
24 
25 #ifndef SVN_CMDLINE_H
26 #define SVN_CMDLINE_H
27 
28 #include <apr_pools.h>
29 #include <apr_getopt.h>
30 
31 #ifndef DOXYGEN_SHOULD_SKIP_THIS
32 #define APR_WANT_STDIO
33 #endif
34 #include <apr_want.h>
35 
36 #include "svn_types.h"
37 #include "svn_auth.h"
38 #include "svn_config.h"
39 
40 #ifdef __cplusplus
41 extern "C" {
42 #endif /* __cplusplus */
43 
44 
45 /** Set up the locale for character conversion, and initialize APR.
46  * If @a error_stream is non-NULL, print error messages to the stream,
47  * using @a progname as the program name. Attempt to set @c stdout to
48  * line-buffered mode, and @a error_stream to unbuffered mode. Return
49  * @c EXIT_SUCCESS if successful, otherwise @c EXIT_FAILURE.
50  *
51  * @note This function should be called exactly once at program startup,
52  * before calling any other APR or Subversion functions.
53  */
54 int
55 svn_cmdline_init(const char *progname,
56  FILE *error_stream);
57 
58 
59 /** Set @a *dest to an output-encoded C string from UTF-8 C string @a
60  * src; allocate @a *dest in @a pool.
61  */
63 svn_cmdline_cstring_from_utf8(const char **dest,
64  const char *src,
65  apr_pool_t *pool);
66 
67 /** Like svn_utf_cstring_from_utf8_fuzzy(), but converts to an
68  * output-encoded C string. */
69 const char *
71  apr_pool_t *pool);
72 
73 /** Set @a *dest to a UTF-8-encoded C string from input-encoded C
74  * string @a src; allocate @a *dest in @a pool.
75  */
77 svn_cmdline_cstring_to_utf8(const char **dest,
78  const char *src,
79  apr_pool_t *pool);
80 
81 /** Set @a *dest to an output-encoded natively-formatted path string
82  * from canonical path @a src; allocate @a *dest in @a pool.
83  */
86  const char *src,
87  apr_pool_t *pool);
88 
89 /** Write to stdout, using a printf-like format string @a fmt, passed
90  * through apr_pvsprintf(). All string arguments are in UTF-8; the output
91  * is converted to the output encoding. Use @a pool for temporary
92  * allocation.
93  *
94  * @since New in 1.1.
95  */
97 svn_cmdline_printf(apr_pool_t *pool,
98  const char *fmt,
99  ...)
100  __attribute__((format(printf, 2, 3)));
101 
102 /** Write to the stdio @a stream, using a printf-like format string @a fmt,
103  * passed through apr_pvsprintf(). All string arguments are in UTF-8;
104  * the output is converted to the output encoding. Use @a pool for
105  * temporary allocation.
106  *
107  * @since New in 1.1.
108  */
109 svn_error_t *
110 svn_cmdline_fprintf(FILE *stream,
111  apr_pool_t *pool,
112  const char *fmt,
113  ...)
114  __attribute__((format(printf, 3, 4)));
115 
116 /** Output the @a string to the stdio @a stream, converting from UTF-8
117  * to the output encoding. Use @a pool for temporary allocation.
118  *
119  * @since New in 1.1.
120  */
121 svn_error_t *
122 svn_cmdline_fputs(const char *string,
123  FILE *stream,
124  apr_pool_t *pool);
125 
126 /** Flush output buffers of the stdio @a stream, returning an error if that
127  * fails. This is just a wrapper for the standard fflush() function for
128  * consistent error handling.
129  *
130  * @since New in 1.1.
131  */
132 svn_error_t *
133 svn_cmdline_fflush(FILE *stream);
134 
135 /** Return the name of the output encoding allocated in @a pool, or @c
136  * APR_LOCALE_CHARSET if the output encoding is the same as the locale
137  * encoding.
138  *
139  * @since New in 1.3.
140  */
141 const char *
142 svn_cmdline_output_encoding(apr_pool_t *pool);
143 
144 /** Handle @a error in preparation for immediate exit from a
145  * command-line client. Specifically:
146  *
147  * Call svn_handle_error2(@a error, stderr, FALSE, @a prefix), clear
148  * @a error, destroy @a pool iff it is non-NULL, and return EXIT_FAILURE.
149  *
150  * @since New in 1.3.
151  */
152 int
154  apr_pool_t *pool,
155  const char *prefix);
156 
157 /** A cancellation function/baton pair, and the path to the configuration
158  * directory. To be passed as the baton argument to the
159  * @c svn_cmdline_*_prompt functions.
160  *
161  * @since New in 1.6.
162  */
164  svn_cancel_func_t cancel_func;
165  void *cancel_baton;
166  const char *config_dir;
168 
169 /** Like svn_cmdline_prompt_baton2_t, but without the path to the
170  * configuration directory.
171  *
172  * @since New in 1.4.
173  * @deprecated Provided for backward compatibility with the 1.5 API.
174  */
176  svn_cancel_func_t cancel_func;
177  void *cancel_baton;
179 
180 /** Prompt the user for input, using @a prompt_str for the prompt and
181  * @a baton (which may be @c NULL) for cancellation, and returning the
182  * user's response in @a result, allocated in @a pool.
183  *
184  * @since New in 1.5.
185  */
186 svn_error_t *
187 svn_cmdline_prompt_user2(const char **result,
188  const char *prompt_str,
190  apr_pool_t *pool);
191 
192 /** Similar to svn_cmdline_prompt_user2, but without cancellation
193  * support.
194  *
195  * @deprecated Provided for backward compatibility with the 1.4 API.
196  */
198 svn_error_t *
199 svn_cmdline_prompt_user(const char **result,
200  const char *prompt_str,
201  apr_pool_t *pool);
202 
203 /** An implementation of @c svn_auth_simple_prompt_func_t that prompts
204  * the user for keyboard input on the command line.
205  *
206  * @since New in 1.4.
207  *
208  * Expects a @c svn_cmdline_prompt_baton_t to be passed as @a baton.
209  */
210 svn_error_t *
212  void *baton,
213  const char *realm,
214  const char *username,
215  svn_boolean_t may_save,
216  apr_pool_t *pool);
217 
218 
219 /** An implementation of @c svn_auth_username_prompt_func_t that prompts
220  * the user for their username via the command line.
221  *
222  * @since New in 1.4.
223  *
224  * Expects a @c svn_cmdline_prompt_baton_t to be passed as @a baton.
225  */
226 svn_error_t *
228  void *baton,
229  const char *realm,
230  svn_boolean_t may_save,
231  apr_pool_t *pool);
232 
233 
234 /** An implementation of @c svn_auth_ssl_server_trust_prompt_func_t that
235  * asks the user if they trust a specific ssl server via the command line.
236  *
237  * @since New in 1.4.
238  *
239  * Expects a @c svn_cmdline_prompt_baton_t to be passed as @a baton.
240  */
241 svn_error_t *
244  void *baton,
245  const char *realm,
246  apr_uint32_t failures,
247  const svn_auth_ssl_server_cert_info_t *cert_info,
248  svn_boolean_t may_save,
249  apr_pool_t *pool);
250 
251 
252 /** An implementation of @c svn_auth_ssl_client_cert_prompt_func_t that
253  * prompts the user for the filename of their SSL client certificate via
254  * the command line.
255  *
256  * Records absolute path of the SSL client certificate file.
257  *
258  * @since New in 1.4.
259  *
260  * Expects a @c svn_cmdline_prompt_baton_t to be passed as @a baton.
261  */
262 svn_error_t *
265  void *baton,
266  const char *realm,
267  svn_boolean_t may_save,
268  apr_pool_t *pool);
269 
270 
271 /** An implementation of @c svn_auth_ssl_client_cert_pw_prompt_func_t that
272  * prompts the user for their SSL certificate password via the command line.
273  *
274  * @since New in 1.4.
275  *
276  * Expects a @c svn_cmdline_prompt_baton_t to be passed as @a baton.
277  */
278 svn_error_t *
281  void *baton,
282  const char *realm,
283  svn_boolean_t may_save,
284  apr_pool_t *pool);
285 
286 /** An implementation of @c svn_auth_plaintext_prompt_func_t that
287  * prompts the user whether storing unencypted passwords to disk is OK.
288  *
289  * Expects a @c svn_cmdline_prompt_baton2_t to be passed as @a baton.
290  *
291  * @since New in 1.6.
292  */
293 svn_error_t *
295  const char *realmstring,
296  void *baton,
297  apr_pool_t *pool);
298 
299 /** An implementation of @c svn_auth_plaintext_passphrase_prompt_func_t that
300  * prompts the user whether storing unencypted passphrase to disk is OK.
301  *
302  * Expects a @c svn_cmdline_prompt_baton2_t to be passed as @a baton.
303  *
304  * @since New in 1.6.
305  */
306 svn_error_t *
308  const char *realmstring,
309  void *baton,
310  apr_pool_t *pool);
311 
312 
313 /** Set @a *ab to an authentication baton allocated from @a pool and
314  * initialized with the standard set of authentication providers used
315  * by the command line client.
316  *
317  * @a non_interactive, @a username, @a password, @a config_dir,
318  * @a no_auth_cache, and @a trust_server_cert are the values of the
319  * command line options of the corresponding names.
320  *
321  * @a cfg is the @c SVN_CONFIG_CATEGORY_CONFIG configuration, and
322  * @a cancel_func and @a cancel_baton control the cancellation of the
323  * prompting providers that are initialized.
324  *
325  * Use @a pool for all allocations.
326  *
327  * @since New in 1.6.
328  */
329 svn_error_t *
331  svn_boolean_t non_interactive,
332  const char *username,
333  const char *password,
334  const char *config_dir,
335  svn_boolean_t no_auth_cache,
336  svn_boolean_t trust_server_cert,
337  svn_config_t *cfg,
338  svn_cancel_func_t cancel_func,
339  void *cancel_baton,
340  apr_pool_t *pool);
341 
342 /** Similar to svn_cmdline_create_auth_baton(), but with
343  * @a trust_server_cert always set to false.
344  *
345  * @since New in 1.4.
346  * @deprecated Provided for backward compatibility with the 1.5 API.
347  * Use svn_cmdline_create_auth_baton() instead.
348  *
349  * @note This deprecation does not follow the usual pattern of putting
350  * a new number on end of the function's name. Instead, the new
351  * function name is distinguished from the old by a grammatical
352  * improvement: the verb "create" instead of the noun "setup".
353  */
355 svn_error_t *
357  svn_boolean_t non_interactive,
358  const char *username,
359  const char *password,
360  const char *config_dir,
361  svn_boolean_t no_auth_cache,
362  svn_config_t *cfg,
363  svn_cancel_func_t cancel_func,
364  void *cancel_baton,
365  apr_pool_t *pool);
366 
367 /** Wrapper for apr_getopt_init(), which see.
368  *
369  * @since New in 1.4.
370  *
371  * This is a private API for Subversion's own use.
372  */
373 svn_error_t *
374 svn_cmdline__getopt_init(apr_getopt_t **os,
375  int argc,
376  const char *argv[],
377  apr_pool_t *pool);
378 
379 #ifdef __cplusplus
380 }
381 #endif /* __cplusplus */
382 
383 #endif /* SVN_CMDLINE_H */