Subversion
svn_cmdline.h
Go to the documentation of this file.
00001 /**
00002  * @copyright
00003  * ====================================================================
00004  *    Licensed to the Apache Software Foundation (ASF) under one
00005  *    or more contributor license agreements.  See the NOTICE file
00006  *    distributed with this work for additional information
00007  *    regarding copyright ownership.  The ASF licenses this file
00008  *    to you under the Apache License, Version 2.0 (the
00009  *    "License"); you may not use this file except in compliance
00010  *    with the License.  You may obtain a copy of the License at
00011  *
00012  *      http://www.apache.org/licenses/LICENSE-2.0
00013  *
00014  *    Unless required by applicable law or agreed to in writing,
00015  *    software distributed under the License is distributed on an
00016  *    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
00017  *    KIND, either express or implied.  See the License for the
00018  *    specific language governing permissions and limitations
00019  *    under the License.
00020  * ====================================================================
00021  * @endcopyright
00022  *
00023  * @file svn_cmdline.h
00024  * @brief Support functions for command line programs
00025  */
00026 
00027 
00028 
00029 
00030 #ifndef SVN_CMDLINE_H
00031 #define SVN_CMDLINE_H
00032 
00033 #include <apr_pools.h>
00034 #include <apr_getopt.h>
00035 
00036 #ifndef DOXYGEN_SHOULD_SKIP_THIS
00037 #define APR_WANT_STDIO
00038 #endif
00039 #include <apr_want.h>
00040 
00041 #include "svn_types.h"
00042 #include "svn_auth.h"
00043 #include "svn_config.h"
00044 
00045 #ifdef __cplusplus
00046 extern "C" {
00047 #endif /* __cplusplus */
00048 
00049 
00050 /** Set up the locale for character conversion, and initialize APR.
00051  * If @a error_stream is non-NULL, print error messages to the stream,
00052  * using @a progname as the program name.  Attempt to set @c stdout to
00053  * line-buffered mode, and @a error_stream to unbuffered mode.  Return
00054  * @c EXIT_SUCCESS if successful, otherwise @c EXIT_FAILURE.
00055  *
00056  * @note This function should be called exactly once at program startup,
00057  *       before calling any other APR or Subversion functions.
00058  */
00059 int
00060 svn_cmdline_init(const char *progname,
00061                  FILE *error_stream);
00062 
00063 
00064 /** Set @a *dest to an output-encoded C string from UTF-8 C string @a
00065  * src; allocate @a *dest in @a pool.
00066  */
00067 svn_error_t *
00068 svn_cmdline_cstring_from_utf8(const char **dest,
00069                               const char *src,
00070                               apr_pool_t *pool);
00071 
00072 /** Like svn_utf_cstring_from_utf8_fuzzy(), but converts to an
00073  * output-encoded C string. */
00074 const char *
00075 svn_cmdline_cstring_from_utf8_fuzzy(const char *src,
00076                                     apr_pool_t *pool);
00077 
00078 /** Set @a *dest to a UTF-8-encoded C string from input-encoded C
00079  * string @a src; allocate @a *dest in @a pool.
00080  */
00081 svn_error_t *
00082 svn_cmdline_cstring_to_utf8(const char **dest,
00083                             const char *src,
00084                             apr_pool_t *pool);
00085 
00086 /** Set @a *dest to an output-encoded natively-formatted path string
00087  * from canonical path @a src; allocate @a *dest in @a pool.
00088  */
00089 svn_error_t *
00090 svn_cmdline_path_local_style_from_utf8(const char **dest,
00091                                        const char *src,
00092                                        apr_pool_t *pool);
00093 
00094 /** Write to stdout, using a printf-like format string @a fmt, passed
00095  * through apr_pvsprintf().  All string arguments are in UTF-8; the output
00096  * is converted to the output encoding.  Use @a pool for temporary
00097  * allocation.
00098  *
00099  * @since New in 1.1.
00100  */
00101 svn_error_t *
00102 svn_cmdline_printf(apr_pool_t *pool,
00103                    const char *fmt,
00104                    ...)
00105        __attribute__((format(printf, 2, 3)));
00106 
00107 /** Write to the stdio @a stream, using a printf-like format string @a fmt,
00108  * passed through apr_pvsprintf().  All string arguments are in UTF-8;
00109  * the output is converted to the output encoding.  Use @a pool for
00110  * temporary allocation.
00111  *
00112  * @since New in 1.1.
00113  */
00114 svn_error_t *
00115 svn_cmdline_fprintf(FILE *stream,
00116                     apr_pool_t *pool,
00117                     const char *fmt,
00118                     ...)
00119        __attribute__((format(printf, 3, 4)));
00120 
00121 /** Output the @a string to the stdio @a stream, converting from UTF-8
00122  * to the output encoding.  Use @a pool for temporary allocation.
00123  *
00124  * @since New in 1.1.
00125  */
00126 svn_error_t *
00127 svn_cmdline_fputs(const char *string,
00128                   FILE *stream,
00129                   apr_pool_t *pool);
00130 
00131 /** Flush output buffers of the stdio @a stream, returning an error if that
00132  * fails.  This is just a wrapper for the standard fflush() function for
00133  * consistent error handling.
00134  *
00135  * @since New in 1.1.
00136  */
00137 svn_error_t *
00138 svn_cmdline_fflush(FILE *stream);
00139 
00140 /** Return the name of the output encoding allocated in @a pool, or @c
00141  * APR_LOCALE_CHARSET if the output encoding is the same as the locale
00142  * encoding.
00143  *
00144  * @since New in 1.3.
00145  */
00146 const char *
00147 svn_cmdline_output_encoding(apr_pool_t *pool);
00148 
00149 /** Handle @a error in preparation for immediate exit from a
00150  * command-line client.  Specifically:
00151  *
00152  * Call svn_handle_error2(@a error, stderr, FALSE, @a prefix), clear
00153  * @a error, destroy @a pool iff it is non-NULL, and return EXIT_FAILURE.
00154  *
00155  * @since New in 1.3.
00156  */
00157 int
00158 svn_cmdline_handle_exit_error(svn_error_t *error,
00159                               apr_pool_t *pool,
00160                               const char *prefix);
00161 
00162 /** A cancellation function/baton pair, and the path to the configuration
00163  * directory. To be passed as the baton argument to the
00164  * @c svn_cmdline_*_prompt functions.
00165  *
00166  * @since New in 1.6.
00167  */
00168 typedef struct svn_cmdline_prompt_baton2_t {
00169   svn_cancel_func_t cancel_func;
00170   void *cancel_baton;
00171   const char *config_dir;
00172 } svn_cmdline_prompt_baton2_t;
00173 
00174 /** Like svn_cmdline_prompt_baton2_t, but without the path to the
00175  * configuration directory.
00176  *
00177  * @since New in 1.4.
00178  * @deprecated Provided for backward compatibility with the 1.5 API.
00179  */
00180 typedef struct svn_cmdline_prompt_baton_t {
00181   svn_cancel_func_t cancel_func;
00182   void *cancel_baton;
00183 } svn_cmdline_prompt_baton_t;
00184 
00185 /** Prompt the user for input, using @a prompt_str for the prompt and
00186  * @a baton (which may be @c NULL) for cancellation, and returning the
00187  * user's response in @a result, allocated in @a pool.
00188  *
00189  * @since New in 1.5.
00190  */
00191 svn_error_t *
00192 svn_cmdline_prompt_user2(const char **result,
00193                          const char *prompt_str,
00194                          svn_cmdline_prompt_baton_t *baton,
00195                          apr_pool_t *pool);
00196 
00197 /** Similar to svn_cmdline_prompt_user2, but without cancellation
00198  * support.
00199  *
00200  * @deprecated Provided for backward compatibility with the 1.4 API.
00201  */
00202 SVN_DEPRECATED
00203 svn_error_t *
00204 svn_cmdline_prompt_user(const char **result,
00205                         const char *prompt_str,
00206                         apr_pool_t *pool);
00207 
00208 /** An implementation of @c svn_auth_simple_prompt_func_t that prompts
00209  * the user for keyboard input on the command line.
00210  *
00211  * @since New in 1.4.
00212  *
00213  * Expects a @c svn_cmdline_prompt_baton_t to be passed as @a baton.
00214  */
00215 svn_error_t *
00216 svn_cmdline_auth_simple_prompt(svn_auth_cred_simple_t **cred_p,
00217                                void *baton,
00218                                const char *realm,
00219                                const char *username,
00220                                svn_boolean_t may_save,
00221                                apr_pool_t *pool);
00222 
00223 
00224 /** An implementation of @c svn_auth_username_prompt_func_t that prompts
00225  * the user for their username via the command line.
00226  *
00227  * @since New in 1.4.
00228  *
00229  * Expects a @c svn_cmdline_prompt_baton_t to be passed as @a baton.
00230  */
00231 svn_error_t *
00232 svn_cmdline_auth_username_prompt(svn_auth_cred_username_t **cred_p,
00233                                  void *baton,
00234                                  const char *realm,
00235                                  svn_boolean_t may_save,
00236                                  apr_pool_t *pool);
00237 
00238 
00239 /** An implementation of @c svn_auth_ssl_server_trust_prompt_func_t that
00240  * asks the user if they trust a specific ssl server via the command line.
00241  *
00242  * @since New in 1.4.
00243  *
00244  * Expects a @c svn_cmdline_prompt_baton_t to be passed as @a baton.
00245  */
00246 svn_error_t *
00247 svn_cmdline_auth_ssl_server_trust_prompt(
00248   svn_auth_cred_ssl_server_trust_t **cred_p,
00249   void *baton,
00250   const char *realm,
00251   apr_uint32_t failures,
00252   const svn_auth_ssl_server_cert_info_t *cert_info,
00253   svn_boolean_t may_save,
00254   apr_pool_t *pool);
00255 
00256 
00257 /** An implementation of @c svn_auth_ssl_client_cert_prompt_func_t that
00258  * prompts the user for the filename of their SSL client certificate via
00259  * the command line.
00260  *
00261  * Records absolute path of the SSL client certificate file.
00262  *
00263  * @since New in 1.4.
00264  *
00265  * Expects a @c svn_cmdline_prompt_baton_t to be passed as @a baton.
00266  */
00267 svn_error_t *
00268 svn_cmdline_auth_ssl_client_cert_prompt(
00269   svn_auth_cred_ssl_client_cert_t **cred_p,
00270   void *baton,
00271   const char *realm,
00272   svn_boolean_t may_save,
00273   apr_pool_t *pool);
00274 
00275 
00276 /** An implementation of @c svn_auth_ssl_client_cert_pw_prompt_func_t that
00277  * prompts the user for their SSL certificate password via the command line.
00278  *
00279  * @since New in 1.4.
00280  *
00281  * Expects a @c svn_cmdline_prompt_baton_t to be passed as @a baton.
00282  */
00283 svn_error_t *
00284 svn_cmdline_auth_ssl_client_cert_pw_prompt(
00285   svn_auth_cred_ssl_client_cert_pw_t **cred_p,
00286   void *baton,
00287   const char *realm,
00288   svn_boolean_t may_save,
00289   apr_pool_t *pool);
00290 
00291 /** An implementation of @c svn_auth_plaintext_prompt_func_t that
00292  * prompts the user whether storing unencrypted passwords to disk is OK.
00293  *
00294  * Expects a @c svn_cmdline_prompt_baton2_t to be passed as @a baton.
00295  *
00296  * @since New in 1.6.
00297  */
00298 svn_error_t *
00299 svn_cmdline_auth_plaintext_prompt(svn_boolean_t *may_save_plaintext,
00300                                   const char *realmstring,
00301                                   void *baton,
00302                                   apr_pool_t *pool);
00303 
00304 /** An implementation of @c svn_auth_plaintext_passphrase_prompt_func_t that
00305  * prompts the user whether storing unencrypted passphrase to disk is OK.
00306  *
00307  * Expects a @c svn_cmdline_prompt_baton2_t to be passed as @a baton.
00308  *
00309  * @since New in 1.6.
00310  */
00311 svn_error_t *
00312 svn_cmdline_auth_plaintext_passphrase_prompt(svn_boolean_t *may_save_plaintext,
00313                                              const char *realmstring,
00314                                              void *baton,
00315                                              apr_pool_t *pool);
00316 
00317 
00318 /** Set @a *ab to an authentication baton allocated from @a pool and
00319  * initialized with the standard set of authentication providers used
00320  * by the command line client.
00321  *
00322  * @a non_interactive, @a username, @a password, @a config_dir,
00323  * @a no_auth_cache, and @a trust_server_cert are the values of the
00324  * command line options of the corresponding names.
00325  *
00326  * @a cfg is the @c SVN_CONFIG_CATEGORY_CONFIG configuration, and
00327  * @a cancel_func and @a cancel_baton control the cancellation of the
00328  * prompting providers that are initialized.
00329  *
00330  * Use @a pool for all allocations.
00331  *
00332  * @since New in 1.6.
00333  */
00334 svn_error_t *
00335 svn_cmdline_create_auth_baton(svn_auth_baton_t **ab,
00336                               svn_boolean_t non_interactive,
00337                               const char *username,
00338                               const char *password,
00339                               const char *config_dir,
00340                               svn_boolean_t no_auth_cache,
00341                               svn_boolean_t trust_server_cert,
00342                               svn_config_t *cfg,
00343                               svn_cancel_func_t cancel_func,
00344                               void *cancel_baton,
00345                               apr_pool_t *pool);
00346 
00347 /** Similar to svn_cmdline_create_auth_baton(), but with
00348  * @a trust_server_cert always set to false.
00349  *
00350  * @since New in 1.4.
00351  * @deprecated Provided for backward compatibility with the 1.5 API.
00352  * Use svn_cmdline_create_auth_baton() instead.
00353  *
00354  * @note This deprecation does not follow the usual pattern of putting
00355  * a new number on end of the function's name.  Instead, the new
00356  * function name is distinguished from the old by a grammatical
00357  * improvement: the verb "create" instead of the noun "setup".
00358  */
00359 SVN_DEPRECATED
00360 svn_error_t *
00361 svn_cmdline_setup_auth_baton(svn_auth_baton_t **ab,
00362                              svn_boolean_t non_interactive,
00363                              const char *username,
00364                              const char *password,
00365                              const char *config_dir,
00366                              svn_boolean_t no_auth_cache,
00367                              svn_config_t *cfg,
00368                              svn_cancel_func_t cancel_func,
00369                              void *cancel_baton,
00370                              apr_pool_t *pool);
00371 
00372 /** Wrapper for apr_getopt_init(), which see.
00373  *
00374  * @since New in 1.4.
00375  *
00376  * This is a private API for Subversion's own use.
00377  */
00378 svn_error_t *
00379 svn_cmdline__getopt_init(apr_getopt_t **os,
00380                          int argc,
00381                          const char *argv[],
00382                          apr_pool_t *pool);
00383 
00384 #ifdef __cplusplus
00385 }
00386 #endif /* __cplusplus */
00387 
00388 #endif /* SVN_CMDLINE_H */
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines