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

Generated on Sun Dec 21 19:08:26 2008 for Subversion by  doxygen 1.3.9.1