src/TortoiseMerge/libsvn_diff/svn_cmdline.h

   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 \f
  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  */
  62 svn_error_t *
  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 *
  70 svn_cmdline_cstring_from_utf8_fuzzy(const char *src,
  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  */
  76 svn_error_t *
  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  */
  84 svn_error_t *
  85 svn_cmdline_path_local_style_from_utf8(const char **dest,
  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  */
  96 svn_error_t *
  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
 153 svn_cmdline_handle_exit_error(svn_error_t *error,
 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  */
 163 typedef struct svn_cmdline_prompt_baton2_t {
 164   svn_cancel_func_t cancel_func;
 165   void *cancel_baton;
 166   const char *config_dir;
 167 } svn_cmdline_prompt_baton2_t;
 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  */
 175 typedef struct svn_cmdline_prompt_baton_t {
 176   svn_cancel_func_t cancel_func;
 177   void *cancel_baton;
 178 } svn_cmdline_prompt_baton_t;
 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,
 189                          svn_cmdline_prompt_baton_t *baton,
 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  */
 197 SVN_DEPRECATED
 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 *
 211 svn_cmdline_auth_simple_prompt(svn_auth_cred_simple_t **cred_p,
 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 *
 227 svn_cmdline_auth_username_prompt(svn_auth_cred_username_t **cred_p,
 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 *
 242 svn_cmdline_auth_ssl_server_trust_prompt
 243   (svn_auth_cred_ssl_server_trust_t **cred_p,
 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 *
 263 svn_cmdline_auth_ssl_client_cert_prompt
 264   (svn_auth_cred_ssl_client_cert_t **cred_p,
 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 *
 279 svn_cmdline_auth_ssl_client_cert_pw_prompt
 280   (svn_auth_cred_ssl_client_cert_pw_t **cred_p,
 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 *
 294 svn_cmdline_auth_plaintext_prompt(svn_boolean_t *may_save_plaintext,
 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 *
 307 svn_cmdline_auth_plaintext_passphrase_prompt(svn_boolean_t *may_save_plaintext,
 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 *
 330 svn_cmdline_create_auth_baton(svn_auth_baton_t **ab,
 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  */
 354 SVN_DEPRECATED
 355 svn_error_t *
 356 svn_cmdline_setup_auth_baton(svn_auth_baton_t **ab,
 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 */