subversion/include/svn_cmdline.h

   1 /**
   2  * @copyright
   3  * ====================================================================
   4  * Copyright (c) 2000-2004 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 \f
  24
  25 #ifndef SVN_CMDLINE_H
  26 #define SVN_CMDLINE_H
  27
  28 #ifndef DOXYGEN_SHOULD_SKIP_THIS
  29 #define APR_WANT_STDIO
  30 #endif
  31 #include <apr_want.h>
  32 #include <apr_getopt.h>
  33
  34 #include "svn_utf.h"
  35 #include "svn_auth.h"
  36 #include "svn_config.h"
  37
  38 #ifdef __cplusplus
  39 extern "C" {
  40 #endif /* __cplusplus */
  41
  42
  43 /** Set up the locale for character conversion, and initialize APR.
  44  * If @a error_stream is non-NULL, print error messages to the stream,
  45  * using @a progname as the program name.  Attempt to set @c stdout to
  46  * line-buffered mode, and @a error_stream to unbuffered mode.  Return
  47  * @c EXIT_SUCCESS if successful, otherwise @c EXIT_FAILURE.
  48  *
  49  * @note This function should be called exactly once at program startup,
  50  *       before calling any other APR or Subversion functions.
  51  */
  52 int svn_cmdline_init(const char *progname, FILE *error_stream);
  53
  54
  55 /** Set @a *dest to an output-encoded C string from UTF-8 C string @a
  56  * src; allocate @a *dest in @a pool.
  57  */
  58 svn_error_t *svn_cmdline_cstring_from_utf8(const char **dest,
  59                                            const char *src,
  60                                            apr_pool_t *pool);
  61
  62 /** Like svn_utf_cstring_from_utf8_fuzzy(), but converts to an
  63  * output-encoded C string. */
  64 const char *svn_cmdline_cstring_from_utf8_fuzzy(const char *src,
  65                                                 apr_pool_t *pool);
  66
  67 /** Set @a *dest to a UTF-8-encoded C string from input-encoded C
  68  * string @a src; allocate @a *dest in @a pool.
  69  */
  70 svn_error_t * svn_cmdline_cstring_to_utf8(const char **dest,
  71                                           const char *src,
  72                                           apr_pool_t *pool);
  73
  74 /** Set @a *dest to an output-encoded natively-formatted path string
  75  * from canonical path @a src; allocate @a *dest in @a pool.
  76  */
  77 svn_error_t *svn_cmdline_path_local_style_from_utf8(const char **dest,
  78                                                     const char *src,
  79                                                     apr_pool_t *pool);
  80
  81 /** Write to stdout, using a printf-like format string @a fmt, passed
  82  * through apr_pvsprintf().  All string arguments are in UTF-8; the output
  83  * is converted to the output encoding.  Use @a pool for temporary
  84  * allocation.
  85  *
  86  * @since New in 1.1.
  87  */
  88 svn_error_t *svn_cmdline_printf(apr_pool_t *pool,
  89                                 const char *fmt,
  90                                 ...)
  91        __attribute__((format(printf, 2, 3)));
  92
  93 /** Write to the stdio @a stream, using a printf-like format string @a fmt,
  94  * passed through apr_pvsprintf().  All string arguments are in UTF-8;
  95  * the output is converted to the output encoding.  Use @a pool for
  96  * temporary allocation.
  97  *
  98  * @since New in 1.1.
  99  */
 100 svn_error_t *svn_cmdline_fprintf(FILE *stream,
 101                                  apr_pool_t *pool,
 102                                  const char *fmt,
 103                                  ...)
 104        __attribute__((format(printf, 3, 4)));
 105
 106 /** Output the @a string to the stdio @a stream, converting from UTF-8
 107  * to the output encoding.  Use @a pool for temporary allocation.
 108  *
 109  * @since New in 1.1.
 110  */
 111 svn_error_t *svn_cmdline_fputs(const char *string,
 112                                FILE *stream,
 113                                apr_pool_t *pool);
 114
 115 /** Flush output buffers of the stdio @a stream, returning an error if that
 116  * fails.  This is just a wrapper for the standard fflush() function for
 117  * consistent error handling.
 118  *
 119  * @since New in 1.1.
 120  */
 121 svn_error_t *svn_cmdline_fflush(FILE *stream);
 122
 123 /** Return the name of the output encoding allocated in @a pool, or @c
 124  * APR_LOCALE_CHARSET if the output encoding is the same as the locale
 125  * encoding.
 126  *
 127  * @since New in 1.3.
 128  */
 129 const char *svn_cmdline_output_encoding(apr_pool_t *pool);
 130
 131 /** Handle @a error in preparation for immediate exit from a
 132  * command-line client.  Specifically:
 133  *
 134  * Call svn_handle_error2(@a error, stderr, FALSE, @a prefix), clear
 135  * @a error, destroy @a pool iff it is non-NULL, and return EXIT_FAILURE.
 136  *
 137  * @since New in 1.3.
 138  */
 139 int svn_cmdline_handle_exit_error(svn_error_t *error,
 140                                   apr_pool_t *pool,
 141                                   const char *prefix);
 142
 143 /** A cancellation function/baton pair to be passed as the baton argument
 144  * to the @c svn_cmdline_*_prompt functions.
 145  *
 146  * @since New in 1.4.
 147  */
 148 typedef struct svn_cmdline_prompt_baton_t {
 149   svn_cancel_func_t cancel_func;
 150   void *cancel_baton;
 151 } svn_cmdline_prompt_baton_t;
 152
 153 /** Prompt the user for input, using @a prompt_str for the prompt and
 154  * @a baton (which may be @c NULL) for cancellation, and returning the
 155  * user's response in @a result, allocated in @a pool.
 156  *
 157  * @since New in 1.5.
 158  */
 159 svn_error_t *
 160 svn_cmdline_prompt_user2(const char **result,
 161                          const char *prompt_str,
 162                          svn_cmdline_prompt_baton_t *baton,
 163                          apr_pool_t *pool);
 164
 165 /** Similar to svn_cmdline_prompt_user2, but without cancellation
 166  * support.
 167  *
 168  * @deprecated Provided for backward compatibility with the 1.4 API.
 169  */
 170 svn_error_t *
 171 svn_cmdline_prompt_user(const char **result,
 172                         const char *prompt_str,
 173                         apr_pool_t *pool);
 174
 175 /** An implementation of @c svn_auth_simple_prompt_func_t that prompts
 176  * the user for keyboard input on the command line.
 177  *
 178  * @since New in 1.4.
 179  *
 180  * Expects a @c svn_cmdline_prompt_baton_t to be passed as @a baton.
 181  */
 182 svn_error_t *
 183 svn_cmdline_auth_simple_prompt(svn_auth_cred_simple_t **cred_p,
 184                                void *baton,
 185                                const char *realm,
 186                                const char *username,
 187                                svn_boolean_t may_save,
 188                                apr_pool_t *pool);
 189
 190
 191 /** An implementation of @c svn_auth_username_prompt_func_t that prompts
 192  * the user for their username via the command line.
 193  *
 194  * @since New in 1.4.
 195  *
 196  * Expects a @c svn_cmdline_prompt_baton_t to be passed as @a baton.
 197  */
 198 svn_error_t *
 199 svn_cmdline_auth_username_prompt(svn_auth_cred_username_t **cred_p,
 200                                  void *baton,
 201                                  const char *realm,
 202                                  svn_boolean_t may_save,
 203                                  apr_pool_t *pool);
 204
 205
 206 /** An implementation of @c svn_auth_ssl_server_trust_prompt_func_t that
 207  * asks the user if they trust a specific ssl server via the command line.
 208  *
 209  * @since New in 1.4.
 210  *
 211  * Expects a @c svn_cmdline_prompt_baton_t to be passed as @a baton.
 212  */
 213 svn_error_t *
 214 svn_cmdline_auth_ssl_server_trust_prompt
 215   (svn_auth_cred_ssl_server_trust_t **cred_p,
 216    void *baton,
 217    const char *realm,
 218    apr_uint32_t failures,
 219    const svn_auth_ssl_server_cert_info_t *cert_info,
 220    svn_boolean_t may_save,
 221    apr_pool_t *pool);
 222
 223
 224 /** An implementation of @c svn_auth_ssl_client_cert_prompt_func_t that
 225  * prompts the user for the filename of their SSL client certificate via
 226  * the command line.
 227  *
 228  * @since New in 1.4.
 229  *
 230  * Expects a @c svn_cmdline_prompt_baton_t to be passed as @a baton.
 231  */
 232 svn_error_t *
 233 svn_cmdline_auth_ssl_client_cert_prompt
 234   (svn_auth_cred_ssl_client_cert_t **cred_p,
 235    void *baton,
 236    const char *realm,
 237    svn_boolean_t may_save,
 238    apr_pool_t *pool);
 239
 240
 241 /** An implementation of @c svn_auth_ssl_client_cert_pw_prompt_func_t that
 242  * prompts the user for their SSL certificate password via the command line.
 243  *
 244  * @since New in 1.4.
 245  *
 246  * Expects a @c svn_cmdline_prompt_baton_t to be passed as @a baton.
 247  */
 248 svn_error_t *
 249 svn_cmdline_auth_ssl_client_cert_pw_prompt
 250   (svn_auth_cred_ssl_client_cert_pw_t **cred_p,
 251    void *baton,
 252    const char *realm,
 253    svn_boolean_t may_save,
 254    apr_pool_t *pool);
 255
 256 /** Initialize auth baton @a ab with the standard set of authentication
 257  * providers used by the command line client.  @a non_interactive,
 258  * @a username, @a password, @a config_dir, and @a no_auth_cache are the
 259  * values of the command line options of the same names.  @a cfg is the
 260  * @c SVN_CONFIG_CATEGORY_CONFIG configuration, and @a cancel_func and
 261  * @a cancel_baton control the cancellation of the prompting providers
 262  * that are initialized.  @a pool is used for all allocations.
 263  *
 264  * @since New in 1.4.
 265  */
 266 svn_error_t *
 267 svn_cmdline_setup_auth_baton(svn_auth_baton_t **ab,
 268                              svn_boolean_t non_interactive,
 269                              const char *username,
 270                              const char *password,
 271                              const char *config_dir,
 272                              svn_boolean_t no_auth_cache,
 273                              svn_config_t *cfg,
 274                              svn_cancel_func_t cancel_func,
 275                              void *cancel_baton,
 276                              apr_pool_t *pool);
 277
 278 /** Wrapper for apr_getopt_init(), which see.
 279  *
 280  * @since New in 1.4.
 281  *
 282  * On OS400 V5R4, prior to calling apr_getopt_init(), converts each of the
 283  * @a argc strings in @a argv[] in place from EBCDIC to UTF-8, allocating
 284  * each new UTF-8 string in @a pool.
 285  *
 286  * This is a private API for Subversion's own use.
 287  */
 288 svn_error_t *
 289 svn_cmdline__getopt_init(apr_getopt_t **os,
 290                          int argc,
 291                          const char *argv[],
 292                          apr_pool_t *pool);
 293
 294 #ifdef __cplusplus
 295 }
 296 #endif /* __cplusplus */
 297
 298 #endif /* SVN_CMDLINE_H */