svn_cmdline.h

Go to the documentation of this file.
00001 /**
00002  * @copyright
00003  * ====================================================================
00004  * Copyright (c) 2000-2004 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 #ifndef DOXYGEN_SHOULD_SKIP_THIS
00029 #define APR_WANT_STDIO
00030 #endif
00031 #include <apr_want.h>
00032 #include <apr_getopt.h>
00033 
00034 #include "svn_utf.h"
00035 #include "svn_auth.h"
00036 #include "svn_config.h"
00037 
00038 #ifdef __cplusplus
00039 extern "C" {
00040 #endif /* __cplusplus */
00041 
00042 
00043 /** Set up the locale for character conversion, and initialize APR.
00044  * If @a error_stream is non-null, print error messages to the stream,
00045  * using @a progname as the program name. Return @c EXIT_SUCCESS if
00046  * successful, otherwise @c EXIT_FAILURE.
00047  *
00048  * @note This function should be called exactly once at program startup,
00049  *       before calling any other APR or Subversion functions.
00050  */
00051 int svn_cmdline_init(const char *progname, FILE *error_stream);
00052 
00053 
00054 /** Set @a *dest to an output-encoded C string from UTF-8 C string @a
00055  * src; allocate @a *dest in @a pool.
00056  */
00057 svn_error_t *svn_cmdline_cstring_from_utf8(const char **dest,
00058                                            const char *src,
00059                                            apr_pool_t *pool);
00060 
00061 /** Like svn_utf_cstring_from_utf8_fuzzy(), but converts to an
00062  * output-encoded C string. */
00063 const char *svn_cmdline_cstring_from_utf8_fuzzy(const char *src,
00064                                                 apr_pool_t *pool);
00065 
00066 /** Set @a *dest to a UTF-8-encoded C string from input-encoded C
00067  * string @a src; allocate @a *dest in @a pool.
00068  */
00069 svn_error_t * svn_cmdline_cstring_to_utf8(const char **dest,
00070                                           const char *src,
00071                                           apr_pool_t *pool);
00072 
00073 /** Set @a *dest to an output-encoded natively-formatted path string
00074  * from canonical path @a src; allocate @a *dest in @a pool.
00075  */
00076 svn_error_t *svn_cmdline_path_local_style_from_utf8(const char **dest,
00077                                                     const char *src,
00078                                                     apr_pool_t *pool);
00079 
00080 /** Write to stdout, using a printf-like format string @a fmt, passed
00081  * through apr_pvsprintf().  All string arguments are in UTF-8; the output
00082  * is converted to the output encoding.  Use @a pool for temporary
00083  * allocation.
00084  *
00085  * @since New in 1.1.
00086  */
00087 svn_error_t *svn_cmdline_printf(apr_pool_t *pool,
00088                                 const char *fmt,
00089                                 ...)
00090        __attribute__((format(printf, 2, 3)));
00091 
00092 /** Write to the stdio @a stream, using a printf-like format string @a fmt,
00093  * passed through apr_pvsprintf().  All string arguments are in UTF-8;
00094  * the output is converted to the output encoding.  Use @a pool for
00095  * temporary allocation.
00096  *
00097  * @since New in 1.1.
00098  */
00099 svn_error_t *svn_cmdline_fprintf(FILE *stream,
00100                                  apr_pool_t *pool,
00101                                  const char *fmt,
00102                                  ...)
00103        __attribute__((format(printf, 3, 4)));
00104 
00105 /** Output the @a string to the stdio @a stream, converting from UTF-8
00106  * to the output encoding.  Use @a pool for temporary allocation.
00107  *
00108  * @since New in 1.1.
00109  */
00110 svn_error_t *svn_cmdline_fputs(const char *string,
00111                                FILE *stream,
00112                                apr_pool_t *pool);
00113 
00114 /** Flush output buffers of the stdio @a stream, returning an error if that
00115  * fails.  This is just a wrapper for the standard fflush() function for
00116  * consistent error handling. 
00117  *
00118  * @since New in 1.1.
00119  */
00120 svn_error_t *svn_cmdline_fflush(FILE *stream);
00121 
00122 /** Return the name of the output encoding allocated in @a pool, or @c
00123  * APR_LOCALE_CHARSET if the output encoding is the same as the locale
00124  * encoding.
00125  *
00126  * @since New in 1.3.
00127  */
00128 const char *svn_cmdline_output_encoding(apr_pool_t *pool);
00129 
00130 /** Handle @a error in preparation for immediate exit from a
00131  * command-line client.  Specifically:
00132  *
00133  * Call svn_handle_error2(@a error, stderr, FALSE, @a prefix), clear
00134  * @a error, destroy @a pool iff it is non-NULL, and return EXIT_FAILURE.
00135  *
00136  * @since New in 1.3.
00137  */
00138 int svn_cmdline_handle_exit_error(svn_error_t *error,
00139                                   apr_pool_t *pool,
00140                                   const char *prefix);
00141 
00142 /** Prompt the user for input, using @a prompt_str for the prompt and
00143  * returning the user's response in @a result, allocated in @a pool.
00144  *
00145  * @since New in 1.4.
00146  */
00147 svn_error_t *
00148 svn_cmdline_prompt_user(const char **result,
00149                         const char *prompt_str,
00150                         apr_pool_t *pool);
00151 
00152 /** A cancellation function/baton pair to be passed as the baton argument
00153  * to the @c svn_cmdline_*_prompt functions.
00154  *
00155  * @since New in 1.4.
00156  */
00157 typedef struct svn_cmdline_prompt_baton_t {
00158   svn_cancel_func_t cancel_func;
00159   void *cancel_baton;
00160 } svn_cmdline_prompt_baton_t;
00161 
00162 /** An implementation of @c svn_auth_simple_prompt_func_t that prompts
00163  * the user for keyboard input on the command line.
00164  *
00165  * @since New in 1.4.
00166  *
00167  * Expects a @c svn_cmdline_prompt_baton_t to be passed as @a baton.
00168  */
00169 svn_error_t *
00170 svn_cmdline_auth_simple_prompt(svn_auth_cred_simple_t **cred_p,
00171                                void *baton,
00172                                const char *realm,
00173                                const char *username,
00174                                svn_boolean_t may_save,
00175                                apr_pool_t *pool);
00176 
00177 
00178 /** An implementation of @c svn_auth_username_prompt_func_t that prompts
00179  * the user for their username via the command line.
00180  *
00181  * @since New in 1.4.
00182  *
00183  * Expects a @c svn_cmdline_prompt_baton_t to be passed as @a baton.
00184  */
00185 svn_error_t *
00186 svn_cmdline_auth_username_prompt(svn_auth_cred_username_t **cred_p,
00187                                  void *baton,
00188                                  const char *realm,
00189                                  svn_boolean_t may_save,
00190                                  apr_pool_t *pool);
00191 
00192 
00193 /** An implementation of @c svn_auth_ssl_server_trust_prompt_func_t that
00194  * asks the user if they trust a specific ssl server via the command line.
00195  *
00196  * @since New in 1.4.
00197  *
00198  * Expects a @c svn_cmdline_prompt_baton_t to be passed as @a baton.
00199  */
00200 svn_error_t *
00201 svn_cmdline_auth_ssl_server_trust_prompt
00202   (svn_auth_cred_ssl_server_trust_t **cred_p,
00203    void *baton,
00204    const char *realm,
00205    apr_uint32_t failures,
00206    const svn_auth_ssl_server_cert_info_t *cert_info,
00207    svn_boolean_t may_save,
00208    apr_pool_t *pool);
00209 
00210 
00211 /** An implementation of @c svn_auth_ssl_client_cert_prompt_func_t that
00212  * prompts the user for the filename of their SSL client certificate via
00213  * the command line.
00214  *
00215  * @since New in 1.4.
00216  *
00217  * Expects a @c svn_cmdline_prompt_baton_t to be passed as @a baton.
00218  */
00219 svn_error_t *
00220 svn_cmdline_auth_ssl_client_cert_prompt
00221   (svn_auth_cred_ssl_client_cert_t **cred_p,
00222    void *baton,
00223    const char *realm,
00224    svn_boolean_t may_save,
00225    apr_pool_t *pool);
00226 
00227 
00228 /** An implementation of @c svn_auth_ssl_client_cert_pw_prompt_func_t that
00229  * prompts the user for their SSL certificate password via the command line.
00230  *
00231  * @since New in 1.4.
00232  *
00233  * Expects a @c svn_cmdline_prompt_baton_t to be passed as @a baton.
00234  */
00235 svn_error_t *
00236 svn_cmdline_auth_ssl_client_cert_pw_prompt
00237   (svn_auth_cred_ssl_client_cert_pw_t **cred_p,
00238    void *baton,
00239    const char *realm,
00240    svn_boolean_t may_save,
00241    apr_pool_t *pool);
00242 
00243 /** Initialize auth baton @a ab with the standard set of authentication
00244  * providers used by the command line client.  @a non_interactive,
00245  * @a username, @a password, @a config_dir, and @a auth_cache are the 
00246  * values of the command line options of the same names.  @a cfg is the
00247  * @c SVN_CONFIG_CATEGORY_CONFIG configuration, and @a cancel_func and
00248  * @a cancel_baton control the cancellation of the prompting providers
00249  * that are initialized.  @a pool is used for all allocations.
00250  *
00251  * @since New in 1.4.
00252  */
00253 svn_error_t *
00254 svn_cmdline_setup_auth_baton(svn_auth_baton_t **ab,
00255                              svn_boolean_t non_interactive,
00256                              const char *username,
00257                              const char *password,
00258                              const char *config_dir,
00259                              svn_boolean_t no_auth_cache,
00260                              svn_config_t *cfg,
00261                              svn_cancel_func_t cancel_func,
00262                              void *cancel_baton,
00263                              apr_pool_t *pool);
00264 
00265 /** Wrapper for apr_getopt_init(), which see.
00266  *
00267  * @since New in 1.4.
00268  * 
00269  * On OS400 V5R4, prior to calling apr_getopt_init(), converts each of the
00270  * @a argc strings in @a argv[] in place from EBCDIC to UTF-8, allocating
00271  * each new UTF-8 string in @a pool.
00272  *
00273  * This is a private API for Subversion's own use.
00274  */
00275 svn_error_t *
00276 svn_cmdline__getopt_init(apr_getopt_t **os,
00277                          int argc,
00278                          const char *argv[],
00279                          apr_pool_t *pool);
00280 
00281 #ifdef __cplusplus
00282 }
00283 #endif /* __cplusplus */
00284 
00285 #endif /* SVN_CMDLINE_H */

Generated on Thu Aug 6 17:28:24 2009 for Subversion by  doxygen 1.5.1