contrib/subversion/subversion/include/svn_cmdline.h

   1 /**
   2  * @copyright
   3  * ====================================================================
   4  *    Licensed to the Apache Software Foundation (ASF) under one
   5  *    or more contributor license agreements.  See the NOTICE file
   6  *    distributed with this work for additional information
   7  *    regarding copyright ownership.  The ASF licenses this file
   8  *    to you under the Apache License, Version 2.0 (the
   9  *    "License"); you may not use this file except in compliance
  10  *    with the License.  You may obtain a copy of the License at
  11  *
  12  *      http://www.apache.org/licenses/LICENSE-2.0
  13  *
  14  *    Unless required by applicable law or agreed to in writing,
  15  *    software distributed under the License is distributed on an
  16  *    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
  17  *    KIND, either express or implied.  See the License for the
  18  *    specific language governing permissions and limitations
  19  *    under the License.
  20  * ====================================================================
  21  * @endcopyright
  22  *
  23  * @file svn_cmdline.h
  24  * @brief Support functions for command line programs
  25  */
  26
  27
  28 \f
  29
  30 #ifndef SVN_CMDLINE_H
  31 #define SVN_CMDLINE_H
  32
  33 #include <apr_pools.h>
  34 #include <apr_getopt.h>
  35
  36 #ifndef DOXYGEN_SHOULD_SKIP_THIS
  37 #define APR_WANT_STDIO
  38 #endif
  39 #include <apr_want.h>
  40
  41 #include "svn_types.h"
  42 #include "svn_auth.h"
  43 #include "svn_config.h"
  44
  45 #ifdef __cplusplus
  46 extern "C" {
  47 #endif /* __cplusplus */
  48
  49
  50 /** Set up the locale for character conversion, and initialize APR.
  51  * If @a error_stream is non-NULL, print error messages to the stream,
  52  * using @a progname as the program name.  Attempt to set @c stdout to
  53  * line-buffered mode, and @a error_stream to unbuffered mode.  Return
  54  * @c EXIT_SUCCESS if successful, otherwise @c EXIT_FAILURE.
  55  *
  56  * @note This function should be called exactly once at program startup,
  57  *       before calling any other APR or Subversion functions.
  58  */
  59 int
  60 svn_cmdline_init(const char *progname,
  61                  FILE *error_stream);
  62
  63
  64 /** Set @a *dest to an output-encoded C string from UTF-8 C string @a
  65  * src; allocate @a *dest in @a pool.
  66  */
  67 svn_error_t *
  68 svn_cmdline_cstring_from_utf8(const char **dest,
  69                               const char *src,
  70                               apr_pool_t *pool);
  71
  72 /** Like svn_utf_cstring_from_utf8_fuzzy(), but converts to an
  73  * output-encoded C string. */
  74 const char *
  75 svn_cmdline_cstring_from_utf8_fuzzy(const char *src,
  76                                     apr_pool_t *pool);
  77
  78 /** Set @a *dest to a UTF-8-encoded C string from input-encoded C
  79  * string @a src; allocate @a *dest in @a pool.
  80  */
  81 svn_error_t *
  82 svn_cmdline_cstring_to_utf8(const char **dest,
  83                             const char *src,
  84                             apr_pool_t *pool);
  85
  86 /** Set @a *dest to an output-encoded natively-formatted path string
  87  * from canonical path @a src; allocate @a *dest in @a pool.
  88  */
  89 svn_error_t *
  90 svn_cmdline_path_local_style_from_utf8(const char **dest,
  91                                        const char *src,
  92                                        apr_pool_t *pool);
  93
  94 /** Write to stdout, using a printf-like format string @a fmt, passed
  95  * through apr_pvsprintf().  All string arguments are in UTF-8; the output
  96  * is converted to the output encoding.  Use @a pool for temporary
  97  * allocation.
  98  *
  99  * @since New in 1.1.
 100  */
 101 svn_error_t *
 102 svn_cmdline_printf(apr_pool_t *pool,
 103                    const char *fmt,
 104                    ...)
 105        __attribute__((format(printf, 2, 3)));
 106
 107 /** Write to the stdio @a stream, using a printf-like format string @a fmt,
 108  * passed through apr_pvsprintf().  All string arguments are in UTF-8;
 109  * the output is converted to the output encoding.  Use @a pool for
 110  * temporary allocation.
 111  *
 112  * @since New in 1.1.
 113  */
 114 svn_error_t *
 115 svn_cmdline_fprintf(FILE *stream,
 116                     apr_pool_t *pool,
 117                     const char *fmt,
 118                     ...)
 119        __attribute__((format(printf, 3, 4)));
 120
 121 /** Output the @a string to the stdio @a stream, converting from UTF-8
 122  * to the output encoding.  Use @a pool for temporary allocation.
 123  *
 124  * @since New in 1.1.
 125  */
 126 svn_error_t *
 127 svn_cmdline_fputs(const char *string,
 128                   FILE *stream,
 129                   apr_pool_t *pool);
 130
 131 /** Flush output buffers of the stdio @a stream, returning an error if that
 132  * fails.  This is just a wrapper for the standard fflush() function for
 133  * consistent error handling.
 134  *
 135  * @since New in 1.1.
 136  */
 137 svn_error_t *
 138 svn_cmdline_fflush(FILE *stream);
 139
 140 /** Return the name of the output encoding allocated in @a pool, or @c
 141  * APR_LOCALE_CHARSET if the output encoding is the same as the locale
 142  * encoding.
 143  *
 144  * @since New in 1.3.
 145  */
 146 const char *
 147 svn_cmdline_output_encoding(apr_pool_t *pool);
 148
 149 /** Handle @a error in preparation for immediate exit from a
 150  * command-line client.  Specifically:
 151  *
 152  * Call svn_handle_error2(@a error, stderr, FALSE, @a prefix), clear
 153  * @a error, destroy @a pool iff it is non-NULL, and return EXIT_FAILURE.
 154  *
 155  * @since New in 1.3.
 156  */
 157 int
 158 svn_cmdline_handle_exit_error(svn_error_t *error,
 159                               apr_pool_t *pool,
 160                               const char *prefix);
 161
 162 /** A prompt function/baton pair, and the path to the configuration
 163  * directory. To be passed as the baton argument to the
 164  * @c svn_cmdline_*_prompt functions.
 165  *
 166  * @since New in 1.6.
 167  */
 168 typedef struct svn_cmdline_prompt_baton2_t {
 169   svn_cancel_func_t cancel_func;
 170   void *cancel_baton;
 171   const char *config_dir;
 172 } svn_cmdline_prompt_baton2_t;
 173
 174 /** Like svn_cmdline_prompt_baton2_t, but without the path to the
 175  * configuration directory.
 176  *
 177  * @since New in 1.4.
 178  * @deprecated Provided for backward compatibility with the 1.5 API.
 179  */
 180 typedef struct svn_cmdline_prompt_baton_t {
 181   svn_cancel_func_t cancel_func;
 182   void *cancel_baton;
 183 } svn_cmdline_prompt_baton_t;
 184
 185 /** Prompt the user for input, using @a prompt_str for the prompt and
 186  * @a baton (which may be @c NULL) for cancellation, and returning the
 187  * user's response in @a result, allocated in @a pool.
 188  *
 189  * @since New in 1.5.
 190  */
 191 svn_error_t *
 192 svn_cmdline_prompt_user2(const char **result,
 193                          const char *prompt_str,
 194                          svn_cmdline_prompt_baton_t *baton,
 195                          apr_pool_t *pool);
 196
 197 /** Similar to svn_cmdline_prompt_user2, but without cancellation
 198  * support.
 199  *
 200  * @deprecated Provided for backward compatibility with the 1.4 API.
 201  */
 202 SVN_DEPRECATED
 203 svn_error_t *
 204 svn_cmdline_prompt_user(const char **result,
 205                         const char *prompt_str,
 206                         apr_pool_t *pool);
 207
 208 /** An implementation of @c svn_auth_simple_prompt_func_t that prompts
 209  * the user for keyboard input on the command line.
 210  *
 211  * @since New in 1.4.
 212  *
 213  * Expects a @c svn_cmdline_prompt_baton_t to be passed as @a baton.
 214  */
 215 svn_error_t *
 216 svn_cmdline_auth_simple_prompt(svn_auth_cred_simple_t **cred_p,
 217                                void *baton,
 218                                const char *realm,
 219                                const char *username,
 220                                svn_boolean_t may_save,
 221                                apr_pool_t *pool);
 222
 223
 224 /** An implementation of @c svn_auth_username_prompt_func_t that prompts
 225  * the user for their username via the command line.
 226  *
 227  * @since New in 1.4.
 228  *
 229  * Expects a @c svn_cmdline_prompt_baton_t to be passed as @a baton.
 230  */
 231 svn_error_t *
 232 svn_cmdline_auth_username_prompt(svn_auth_cred_username_t **cred_p,
 233                                  void *baton,
 234                                  const char *realm,
 235                                  svn_boolean_t may_save,
 236                                  apr_pool_t *pool);
 237
 238
 239 /** An implementation of @c svn_auth_ssl_server_trust_prompt_func_t that
 240  * asks the user if they trust a specific ssl server via the command line.
 241  *
 242  * @since New in 1.4.
 243  *
 244  * Expects a @c svn_cmdline_prompt_baton_t to be passed as @a baton.
 245  */
 246 svn_error_t *
 247 svn_cmdline_auth_ssl_server_trust_prompt(
 248   svn_auth_cred_ssl_server_trust_t **cred_p,
 249   void *baton,
 250   const char *realm,
 251   apr_uint32_t failures,
 252   const svn_auth_ssl_server_cert_info_t *cert_info,
 253   svn_boolean_t may_save,
 254   apr_pool_t *pool);
 255
 256
 257 /** An implementation of @c svn_auth_ssl_client_cert_prompt_func_t that
 258  * prompts the user for the filename of their SSL client certificate via
 259  * the command line.
 260  *
 261  * Records absolute path of the SSL client certificate file.
 262  *
 263  * @since New in 1.4.
 264  *
 265  * Expects a @c svn_cmdline_prompt_baton_t to be passed as @a baton.
 266  */
 267 svn_error_t *
 268 svn_cmdline_auth_ssl_client_cert_prompt(
 269   svn_auth_cred_ssl_client_cert_t **cred_p,
 270   void *baton,
 271   const char *realm,
 272   svn_boolean_t may_save,
 273   apr_pool_t *pool);
 274
 275
 276 /** An implementation of @c svn_auth_ssl_client_cert_pw_prompt_func_t that
 277  * prompts the user for their SSL certificate password via the command line.
 278  *
 279  * @since New in 1.4.
 280  *
 281  * Expects a @c svn_cmdline_prompt_baton_t to be passed as @a baton.
 282  */
 283 svn_error_t *
 284 svn_cmdline_auth_ssl_client_cert_pw_prompt(
 285   svn_auth_cred_ssl_client_cert_pw_t **cred_p,
 286   void *baton,
 287   const char *realm,
 288   svn_boolean_t may_save,
 289   apr_pool_t *pool);
 290
 291 /** An implementation of @c svn_auth_plaintext_prompt_func_t that
 292  * prompts the user whether storing unencrypted passwords to disk is OK.
 293  *
 294  * Expects a @c svn_cmdline_prompt_baton2_t to be passed as @a baton.
 295  *
 296  * @since New in 1.6.
 297  */
 298 svn_error_t *
 299 svn_cmdline_auth_plaintext_prompt(svn_boolean_t *may_save_plaintext,
 300                                   const char *realmstring,
 301                                   void *baton,
 302                                   apr_pool_t *pool);
 303
 304 /** An implementation of @c svn_auth_plaintext_passphrase_prompt_func_t that
 305  * prompts the user whether storing unencrypted passphrase to disk is OK.
 306  *
 307  * Expects a @c svn_cmdline_prompt_baton2_t to be passed as @a baton.
 308  *
 309  * @since New in 1.6.
 310  */
 311 svn_error_t *
 312 svn_cmdline_auth_plaintext_passphrase_prompt(svn_boolean_t *may_save_plaintext,
 313                                              const char *realmstring,
 314                                              void *baton,
 315                                              apr_pool_t *pool);
 316
 317
 318 /** Set @a *ab to an authentication baton allocated from @a pool and
 319  * initialized with the standard set of authentication providers used
 320  * by the command line client.
 321  *
 322  * @a non_interactive, @a username, @a password, @a config_dir,
 323  * @a no_auth_cache, and @a trust_server_cert are the values of the
 324  * command line options of the corresponding names.
 325  *
 326  * @a cfg is the @c SVN_CONFIG_CATEGORY_CONFIG configuration, and
 327  * @a cancel_func and @a cancel_baton control the cancellation of the
 328  * prompting providers that are initialized.
 329  *
 330  * Use @a pool for all allocations.
 331  *
 332  * @since New in 1.6.
 333  */
 334 svn_error_t *
 335 svn_cmdline_create_auth_baton(svn_auth_baton_t **ab,
 336                               svn_boolean_t non_interactive,
 337                               const char *username,
 338                               const char *password,
 339                               const char *config_dir,
 340                               svn_boolean_t no_auth_cache,
 341                               svn_boolean_t trust_server_cert,
 342                               svn_config_t *cfg,
 343                               svn_cancel_func_t cancel_func,
 344                               void *cancel_baton,
 345                               apr_pool_t *pool);
 346
 347 /** Similar to svn_cmdline_create_auth_baton(), but with
 348  * @a trust_server_cert always set to false.
 349  *
 350  * @since New in 1.4.
 351  * @deprecated Provided for backward compatibility with the 1.5 API.
 352  * Use svn_cmdline_create_auth_baton() instead.
 353  *
 354  * @note This deprecation does not follow the usual pattern of putting
 355  * a new number on end of the function's name.  Instead, the new
 356  * function name is distinguished from the old by a grammatical
 357  * improvement: the verb "create" instead of the noun "setup".
 358  */
 359 SVN_DEPRECATED
 360 svn_error_t *
 361 svn_cmdline_setup_auth_baton(svn_auth_baton_t **ab,
 362                              svn_boolean_t non_interactive,
 363                              const char *username,
 364                              const char *password,
 365                              const char *config_dir,
 366                              svn_boolean_t no_auth_cache,
 367                              svn_config_t *cfg,
 368                              svn_cancel_func_t cancel_func,
 369                              void *cancel_baton,
 370                              apr_pool_t *pool);
 371
 372 #ifdef __cplusplus
 373 }
 374 #endif /* __cplusplus */
 375
 376 #endif /* SVN_CMDLINE_H */