Subversion 1.6.16

svn_cmdline.h

Go to the documentation of this file.
00001 /**
00002  * @copyright
00003  * ====================================================================
00004  * Copyright (c) 2000-2004, 2008-2009 CollabNet.  All rights reserved.
00005  *
00006  * This software is licensed as described in the file COPYING, which
00007  * you should have received as part of this distribution.  The terms
00008  * are also available at http://subversion.tigris.org/license-1.html.
00009  * If newer versions of this license are posted there, you may use a
00010  * newer version instead, at your option.
00011  *
00012  * This software consists of voluntary contributions made by many
00013  * individuals.  For exact contribution history, see the revision
00014  * history and logs, available at http://subversion.tigris.org/.
00015  * ====================================================================
00016  * @endcopyright
00017  *
00018  * @file svn_cmdline.h
00019  * @brief Support functions for command line programs
00020  */
00021 
00022 
00023 
00024 
00025 #ifndef SVN_CMDLINE_H
00026 #define SVN_CMDLINE_H
00027 
00028 #include <apr_pools.h>
00029 #include <apr_getopt.h>
00030 
00031 #ifndef DOXYGEN_SHOULD_SKIP_THIS
00032 #define APR_WANT_STDIO
00033 #endif
00034 #include <apr_want.h>
00035 
00036 #include "svn_types.h"
00037 #include "svn_auth.h"
00038 #include "svn_config.h"
00039 
00040 #ifdef __cplusplus
00041 extern "C" {
00042 #endif /* __cplusplus */
00043 
00044 
00045 /** Set up the locale for character conversion, and initialize APR.
00046  * If @a error_stream is non-NULL, print error messages to the stream,
00047  * using @a progname as the program name.  Attempt to set @c stdout to
00048  * line-buffered mode, and @a error_stream to unbuffered mode.  Return
00049  * @c EXIT_SUCCESS if successful, otherwise @c EXIT_FAILURE.
00050  *
00051  * @note This function should be called exactly once at program startup,
00052  *       before calling any other APR or Subversion functions.
00053  */
00054 int
00055 svn_cmdline_init(const char *progname,
00056                  FILE *error_stream);
00057 
00058 
00059 /** Set @a *dest to an output-encoded C string from UTF-8 C string @a
00060  * src; allocate @a *dest in @a pool.
00061  */
00062 svn_error_t *
00063 svn_cmdline_cstring_from_utf8(const char **dest,
00064                               const char *src,
00065                               apr_pool_t *pool);
00066 
00067 /** Like svn_utf_cstring_from_utf8_fuzzy(), but converts to an
00068  * output-encoded C string. */
00069 const char *
00070 svn_cmdline_cstring_from_utf8_fuzzy(const char *src,
00071                                     apr_pool_t *pool);
00072 
00073 /** Set @a *dest to a UTF-8-encoded C string from input-encoded C
00074  * string @a src; allocate @a *dest in @a pool.
00075  */
00076 svn_error_t *
00077 svn_cmdline_cstring_to_utf8(const char **dest,
00078                             const char *src,
00079                             apr_pool_t *pool);
00080 
00081 /** Set @a *dest to an output-encoded natively-formatted path string
00082  * from canonical path @a src; allocate @a *dest in @a pool.
00083  */
00084 svn_error_t *
00085 svn_cmdline_path_local_style_from_utf8(const char **dest,
00086                                        const char *src,
00087                                        apr_pool_t *pool);
00088 
00089 /** Write to stdout, using a printf-like format string @a fmt, passed
00090  * through apr_pvsprintf().  All string arguments are in UTF-8; the output
00091  * is converted to the output encoding.  Use @a pool for temporary
00092  * allocation.
00093  *
00094  * @since New in 1.1.
00095  */
00096 svn_error_t *
00097 svn_cmdline_printf(apr_pool_t *pool,
00098                    const char *fmt,
00099                    ...)
00100        __attribute__((format(printf, 2, 3)));
00101 
00102 /** Write to the stdio @a stream, using a printf-like format string @a fmt,
00103  * passed through apr_pvsprintf().  All string arguments are in UTF-8;
00104  * the output is converted to the output encoding.  Use @a pool for
00105  * temporary allocation.
00106  *
00107  * @since New in 1.1.
00108  */
00109 svn_error_t *
00110 svn_cmdline_fprintf(FILE *stream,
00111                     apr_pool_t *pool,
00112                     const char *fmt,
00113                     ...)
00114        __attribute__((format(printf, 3, 4)));
00115 
00116 /** Output the @a string to the stdio @a stream, converting from UTF-8
00117  * to the output encoding.  Use @a pool for temporary allocation.
00118  *
00119  * @since New in 1.1.
00120  */
00121 svn_error_t *
00122 svn_cmdline_fputs(const char *string,
00123                   FILE *stream,
00124                   apr_pool_t *pool);
00125 
00126 /** Flush output buffers of the stdio @a stream, returning an error if that
00127  * fails.  This is just a wrapper for the standard fflush() function for
00128  * consistent error handling.
00129  *
00130  * @since New in 1.1.
00131  */
00132 svn_error_t *
00133 svn_cmdline_fflush(FILE *stream);
00134 
00135 /** Return the name of the output encoding allocated in @a pool, or @c
00136  * APR_LOCALE_CHARSET if the output encoding is the same as the locale
00137  * encoding.
00138  *
00139  * @since New in 1.3.
00140  */
00141 const char *
00142 svn_cmdline_output_encoding(apr_pool_t *pool);
00143 
00144 /** Handle @a error in preparation for immediate exit from a
00145  * command-line client.  Specifically:
00146  *
00147  * Call svn_handle_error2(@a error, stderr, FALSE, @a prefix), clear
00148  * @a error, destroy @a pool iff it is non-NULL, and return EXIT_FAILURE.
00149  *
00150  * @since New in 1.3.
00151  */
00152 int
00153 svn_cmdline_handle_exit_error(svn_error_t *error,
00154                               apr_pool_t *pool,
00155                               const char *prefix);
00156 
00157 /** A cancellation function/baton pair, and the path to the configuration
00158  * directory. To be passed as the baton argument to the
00159  * @c svn_cmdline_*_prompt functions.
00160  *
00161  * @since New in 1.6.
00162  */
00163 typedef struct svn_cmdline_prompt_baton2_t {
00164   svn_cancel_func_t cancel_func;
00165   void *cancel_baton;
00166   const char *config_dir;
00167 } svn_cmdline_prompt_baton2_t;
00168 
00169 /** Like svn_cmdline_prompt_baton2_t, but without the path to the
00170  * configuration directory.
00171  *
00172  * @since New in 1.4.
00173  * @deprecated Provided for backward compatibility with the 1.5 API.
00174  */
00175 typedef struct svn_cmdline_prompt_baton_t {
00176   svn_cancel_func_t cancel_func;
00177   void *cancel_baton;
00178 } svn_cmdline_prompt_baton_t;
00179 
00180 /** Prompt the user for input, using @a prompt_str for the prompt and
00181  * @a baton (which may be @c NULL) for cancellation, and returning the
00182  * user's response in @a result, allocated in @a pool.
00183  *
00184  * @since New in 1.5.
00185  */
00186 svn_error_t *
00187 svn_cmdline_prompt_user2(const char **result,
00188                          const char *prompt_str,
00189                          svn_cmdline_prompt_baton_t *baton,
00190                          apr_pool_t *pool);
00191 
00192 /** Similar to svn_cmdline_prompt_user2, but without cancellation
00193  * support.
00194  *
00195  * @deprecated Provided for backward compatibility with the 1.4 API.
00196  */
00197 SVN_DEPRECATED
00198 svn_error_t *
00199 svn_cmdline_prompt_user(const char **result,
00200                         const char *prompt_str,
00201                         apr_pool_t *pool);
00202 
00203 /** An implementation of @c svn_auth_simple_prompt_func_t that prompts
00204  * the user for keyboard input on the command line.
00205  *
00206  * @since New in 1.4.
00207  *
00208  * Expects a @c svn_cmdline_prompt_baton_t to be passed as @a baton.
00209  */
00210 svn_error_t *
00211 svn_cmdline_auth_simple_prompt(svn_auth_cred_simple_t **cred_p,
00212                                void *baton,
00213                                const char *realm,
00214                                const char *username,
00215                                svn_boolean_t may_save,
00216                                apr_pool_t *pool);
00217 
00218 
00219 /** An implementation of @c svn_auth_username_prompt_func_t that prompts
00220  * the user for their username via the command line.
00221  *
00222  * @since New in 1.4.
00223  *
00224  * Expects a @c svn_cmdline_prompt_baton_t to be passed as @a baton.
00225  */
00226 svn_error_t *
00227 svn_cmdline_auth_username_prompt(svn_auth_cred_username_t **cred_p,
00228                                  void *baton,
00229                                  const char *realm,
00230                                  svn_boolean_t may_save,
00231                                  apr_pool_t *pool);
00232 
00233 
00234 /** An implementation of @c svn_auth_ssl_server_trust_prompt_func_t that
00235  * asks the user if they trust a specific ssl server via the command line.
00236  *
00237  * @since New in 1.4.
00238  *
00239  * Expects a @c svn_cmdline_prompt_baton_t to be passed as @a baton.
00240  */
00241 svn_error_t *
00242 svn_cmdline_auth_ssl_server_trust_prompt
00243   (svn_auth_cred_ssl_server_trust_t **cred_p,
00244    void *baton,
00245    const char *realm,
00246    apr_uint32_t failures,
00247    const svn_auth_ssl_server_cert_info_t *cert_info,
00248    svn_boolean_t may_save,
00249    apr_pool_t *pool);
00250 
00251 
00252 /** An implementation of @c svn_auth_ssl_client_cert_prompt_func_t that
00253  * prompts the user for the filename of their SSL client certificate via
00254  * the command line.
00255  *
00256  * Records absolute path of the SSL client certificate file.
00257  *
00258  * @since New in 1.4.
00259  *
00260  * Expects a @c svn_cmdline_prompt_baton_t to be passed as @a baton.
00261  */
00262 svn_error_t *
00263 svn_cmdline_auth_ssl_client_cert_prompt
00264   (svn_auth_cred_ssl_client_cert_t **cred_p,
00265    void *baton,
00266    const char *realm,
00267    svn_boolean_t may_save,
00268    apr_pool_t *pool);
00269 
00270 
00271 /** An implementation of @c svn_auth_ssl_client_cert_pw_prompt_func_t that
00272  * prompts the user for their SSL certificate password via the command line.
00273  *
00274  * @since New in 1.4.
00275  *
00276  * Expects a @c svn_cmdline_prompt_baton_t to be passed as @a baton.
00277  */
00278 svn_error_t *
00279 svn_cmdline_auth_ssl_client_cert_pw_prompt
00280   (svn_auth_cred_ssl_client_cert_pw_t **cred_p,
00281    void *baton,
00282    const char *realm,
00283    svn_boolean_t may_save,
00284    apr_pool_t *pool);
00285 
00286 /** An implementation of @c svn_auth_plaintext_prompt_func_t that
00287  * prompts the user whether storing unencypted passwords to disk is OK.
00288  *
00289  * Expects a @c svn_cmdline_prompt_baton2_t to be passed as @a baton.
00290  *
00291  * @since New in 1.6.
00292  */
00293 svn_error_t *
00294 svn_cmdline_auth_plaintext_prompt(svn_boolean_t *may_save_plaintext,
00295                                   const char *realmstring,
00296                                   void *baton,
00297                                   apr_pool_t *pool);
00298 
00299 /** An implementation of @c svn_auth_plaintext_passphrase_prompt_func_t that
00300  * prompts the user whether storing unencypted passphrase to disk is OK.
00301  *
00302  * Expects a @c svn_cmdline_prompt_baton2_t to be passed as @a baton.
00303  *
00304  * @since New in 1.6.
00305  */
00306 svn_error_t *
00307 svn_cmdline_auth_plaintext_passphrase_prompt(svn_boolean_t *may_save_plaintext,
00308                                              const char *realmstring,
00309                                              void *baton,
00310                                              apr_pool_t *pool);
00311 
00312 
00313 /** Set @a *ab to an authentication baton allocated from @a pool and
00314  * initialized with the standard set of authentication providers used
00315  * by the command line client.
00316  *
00317  * @a non_interactive, @a username, @a password, @a config_dir,
00318  * @a no_auth_cache, and @a trust_server_cert are the values of the
00319  * command line options of the corresponding names.
00320  *
00321  * @a cfg is the @c SVN_CONFIG_CATEGORY_CONFIG configuration, and
00322  * @a cancel_func and @a cancel_baton control the cancellation of the
00323  * prompting providers that are initialized.
00324  *
00325  * Use @a pool for all allocations.
00326  *
00327  * @since New in 1.6.
00328  */
00329 svn_error_t *
00330 svn_cmdline_create_auth_baton(svn_auth_baton_t **ab,
00331                               svn_boolean_t non_interactive,
00332                               const char *username,
00333                               const char *password,
00334                               const char *config_dir,
00335                               svn_boolean_t no_auth_cache,
00336                               svn_boolean_t trust_server_cert,
00337                               svn_config_t *cfg,
00338                               svn_cancel_func_t cancel_func,
00339                               void *cancel_baton,
00340                               apr_pool_t *pool);
00341 
00342 /** Similar to svn_cmdline_create_auth_baton(), but with
00343  * @a trust_server_cert always set to false.
00344  *
00345  * @since New in 1.4.
00346  * @deprecated Provided for backward compatibility with the 1.5 API.
00347  * Use svn_cmdline_create_auth_baton() instead.
00348  *
00349  * @note This deprecation does not follow the usual pattern of putting
00350  * a new number on end of the function's name.  Instead, the new
00351  * function name is distinguished from the old by a grammatical
00352  * improvement: the verb "create" instead of the noun "setup".
00353  */
00354 SVN_DEPRECATED
00355 svn_error_t *
00356 svn_cmdline_setup_auth_baton(svn_auth_baton_t **ab,
00357                              svn_boolean_t non_interactive,
00358                              const char *username,
00359                              const char *password,
00360                              const char *config_dir,
00361                              svn_boolean_t no_auth_cache,
00362                              svn_config_t *cfg,
00363                              svn_cancel_func_t cancel_func,
00364                              void *cancel_baton,
00365                              apr_pool_t *pool);
00366 
00367 /** Wrapper for apr_getopt_init(), which see.
00368  *
00369  * @since New in 1.4.
00370  *
00371  * This is a private API for Subversion's own use.
00372  */
00373 svn_error_t *
00374 svn_cmdline__getopt_init(apr_getopt_t **os,
00375                          int argc,
00376                          const char *argv[],
00377                          apr_pool_t *pool);
00378 
00379 #ifdef __cplusplus
00380 }
00381 #endif /* __cplusplus */
00382 
00383 #endif /* SVN_CMDLINE_H */
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines