- Main Page
- Related Pages
- Modules
- Data Structures
- Files

- File List
- Globals

# 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