00001 /** 00002 * @copyright 00003 * ==================================================================== 00004 * Copyright (c) 2000-2004 CollabNet. All rights reserved. 00005 * 00006 * This software is licensed as described in the file COPYING, which 00007 * you should have received as part of this distribution. The terms 00008 * are also available at http://subversion.tigris.org/license-1.html. 00009 * If newer versions of this license are posted there, you may use a 00010 * newer version instead, at your option. 00011 * 00012 * This software consists of voluntary contributions made by many 00013 * individuals. For exact contribution history, see the revision 00014 * history and logs, available at http://subversion.tigris.org/. 00015 * ==================================================================== 00016 * @endcopyright 00017 * 00018 * @file svn_cmdline.h 00019 * @brief Support functions for command line programs 00020 */ 00021 00022 00023 00024 00025 #ifndef SVN_CMDLINE_H 00026 #define SVN_CMDLINE_H 00027 00028 #ifndef DOXYGEN_SHOULD_SKIP_THIS 00029 #define APR_WANT_STDIO 00030 #endif 00031 #include <apr_want.h> 00032 #include <apr_getopt.h> 00033 00034 #include "svn_utf.h" 00035 #include "svn_auth.h" 00036 #include "svn_config.h" 00037 00038 #ifdef __cplusplus 00039 extern "C" { 00040 #endif /* __cplusplus */ 00041 00042 00043 /** Set up the locale for character conversion, and initialize APR. 00044 * If @a error_stream is non-NULL, print error messages to the stream, 00045 * using @a progname as the program name. Attempt to set @c stdout to 00046 * line-buffered mode, and @a error_stream to unbuffered mode. Return 00047 * @c EXIT_SUCCESS if successful, otherwise @c EXIT_FAILURE. 00048 * 00049 * @note This function should be called exactly once at program startup, 00050 * before calling any other APR or Subversion functions. 00051 */ 00052 int svn_cmdline_init(const char *progname, FILE *error_stream); 00053 00054 00055 /** Set @a *dest to an output-encoded C string from UTF-8 C string @a 00056 * src; allocate @a *dest in @a pool. 00057 */ 00058 svn_error_t *svn_cmdline_cstring_from_utf8(const char **dest, 00059 const char *src, 00060 apr_pool_t *pool); 00061 00062 /** Like svn_utf_cstring_from_utf8_fuzzy(), but converts to an 00063 * output-encoded C string. */ 00064 const char *svn_cmdline_cstring_from_utf8_fuzzy(const char *src, 00065 apr_pool_t *pool); 00066 00067 /** Set @a *dest to a UTF-8-encoded C string from input-encoded C 00068 * string @a src; allocate @a *dest in @a pool. 00069 */ 00070 svn_error_t * svn_cmdline_cstring_to_utf8(const char **dest, 00071 const char *src, 00072 apr_pool_t *pool); 00073 00074 /** Set @a *dest to an output-encoded natively-formatted path string 00075 * from canonical path @a src; allocate @a *dest in @a pool. 00076 */ 00077 svn_error_t *svn_cmdline_path_local_style_from_utf8(const char **dest, 00078 const char *src, 00079 apr_pool_t *pool); 00080 00081 /** Write to stdout, using a printf-like format string @a fmt, passed 00082 * through apr_pvsprintf(). All string arguments are in UTF-8; the output 00083 * is converted to the output encoding. Use @a pool for temporary 00084 * allocation. 00085 * 00086 * @since New in 1.1. 00087 */ 00088 svn_error_t *svn_cmdline_printf(apr_pool_t *pool, 00089 const char *fmt, 00090 ...) 00091 __attribute__((format(printf, 2, 3))); 00092 00093 /** Write to the stdio @a stream, using a printf-like format string @a fmt, 00094 * passed through apr_pvsprintf(). All string arguments are in UTF-8; 00095 * the output is converted to the output encoding. Use @a pool for 00096 * temporary allocation. 00097 * 00098 * @since New in 1.1. 00099 */ 00100 svn_error_t *svn_cmdline_fprintf(FILE *stream, 00101 apr_pool_t *pool, 00102 const char *fmt, 00103 ...) 00104 __attribute__((format(printf, 3, 4))); 00105 00106 /** Output the @a string to the stdio @a stream, converting from UTF-8 00107 * to the output encoding. Use @a pool for temporary allocation. 00108 * 00109 * @since New in 1.1. 00110 */ 00111 svn_error_t *svn_cmdline_fputs(const char *string, 00112 FILE *stream, 00113 apr_pool_t *pool); 00114 00115 /** Flush output buffers of the stdio @a stream, returning an error if that 00116 * fails. This is just a wrapper for the standard fflush() function for 00117 * consistent error handling. 00118 * 00119 * @since New in 1.1. 00120 */ 00121 svn_error_t *svn_cmdline_fflush(FILE *stream); 00122 00123 /** Return the name of the output encoding allocated in @a pool, or @c 00124 * APR_LOCALE_CHARSET if the output encoding is the same as the locale 00125 * encoding. 00126 * 00127 * @since New in 1.3. 00128 */ 00129 const char *svn_cmdline_output_encoding(apr_pool_t *pool); 00130 00131 /** Handle @a error in preparation for immediate exit from a 00132 * command-line client. Specifically: 00133 * 00134 * Call svn_handle_error2(@a error, stderr, FALSE, @a prefix), clear 00135 * @a error, destroy @a pool iff it is non-NULL, and return EXIT_FAILURE. 00136 * 00137 * @since New in 1.3. 00138 */ 00139 int svn_cmdline_handle_exit_error(svn_error_t *error, 00140 apr_pool_t *pool, 00141 const char *prefix); 00142 00143 /** A cancellation function/baton pair to be passed as the baton argument 00144 * to the @c svn_cmdline_*_prompt functions. 00145 * 00146 * @since New in 1.4. 00147 */ 00148 typedef struct svn_cmdline_prompt_baton_t { 00149 svn_cancel_func_t cancel_func; 00150 void *cancel_baton; 00151 } svn_cmdline_prompt_baton_t; 00152 00153 /** Prompt the user for input, using @a prompt_str for the prompt and 00154 * @a baton (which may be @c NULL) for cancellation, and returning the 00155 * user's response in @a result, allocated in @a pool. 00156 * 00157 * @since New in 1.5. 00158 */ 00159 svn_error_t * 00160 svn_cmdline_prompt_user2(const char **result, 00161 const char *prompt_str, 00162 svn_cmdline_prompt_baton_t *baton, 00163 apr_pool_t *pool); 00164 00165 /** Similar to svn_cmdline_prompt_user2, but without cancellation 00166 * support. 00167 * 00168 * @deprecated Provided for backward compatibility with the 1.4 API. 00169 */ 00170 svn_error_t * 00171 svn_cmdline_prompt_user(const char **result, 00172 const char *prompt_str, 00173 apr_pool_t *pool); 00174 00175 /** An implementation of @c svn_auth_simple_prompt_func_t that prompts 00176 * the user for keyboard input on the command line. 00177 * 00178 * @since New in 1.4. 00179 * 00180 * Expects a @c svn_cmdline_prompt_baton_t to be passed as @a baton. 00181 */ 00182 svn_error_t * 00183 svn_cmdline_auth_simple_prompt(svn_auth_cred_simple_t **cred_p, 00184 void *baton, 00185 const char *realm, 00186 const char *username, 00187 svn_boolean_t may_save, 00188 apr_pool_t *pool); 00189 00190 00191 /** An implementation of @c svn_auth_username_prompt_func_t that prompts 00192 * the user for their username via the command line. 00193 * 00194 * @since New in 1.4. 00195 * 00196 * Expects a @c svn_cmdline_prompt_baton_t to be passed as @a baton. 00197 */ 00198 svn_error_t * 00199 svn_cmdline_auth_username_prompt(svn_auth_cred_username_t **cred_p, 00200 void *baton, 00201 const char *realm, 00202 svn_boolean_t may_save, 00203 apr_pool_t *pool); 00204 00205 00206 /** An implementation of @c svn_auth_ssl_server_trust_prompt_func_t that 00207 * asks the user if they trust a specific ssl server via the command line. 00208 * 00209 * @since New in 1.4. 00210 * 00211 * Expects a @c svn_cmdline_prompt_baton_t to be passed as @a baton. 00212 */ 00213 svn_error_t * 00214 svn_cmdline_auth_ssl_server_trust_prompt 00215 (svn_auth_cred_ssl_server_trust_t **cred_p, 00216 void *baton, 00217 const char *realm, 00218 apr_uint32_t failures, 00219 const svn_auth_ssl_server_cert_info_t *cert_info, 00220 svn_boolean_t may_save, 00221 apr_pool_t *pool); 00222 00223 00224 /** An implementation of @c svn_auth_ssl_client_cert_prompt_func_t that 00225 * prompts the user for the filename of their SSL client certificate via 00226 * the command line. 00227 * 00228 * @since New in 1.4. 00229 * 00230 * Expects a @c svn_cmdline_prompt_baton_t to be passed as @a baton. 00231 */ 00232 svn_error_t * 00233 svn_cmdline_auth_ssl_client_cert_prompt 00234 (svn_auth_cred_ssl_client_cert_t **cred_p, 00235 void *baton, 00236 const char *realm, 00237 svn_boolean_t may_save, 00238 apr_pool_t *pool); 00239 00240 00241 /** An implementation of @c svn_auth_ssl_client_cert_pw_prompt_func_t that 00242 * prompts the user for their SSL certificate password via the command line. 00243 * 00244 * @since New in 1.4. 00245 * 00246 * Expects a @c svn_cmdline_prompt_baton_t to be passed as @a baton. 00247 */ 00248 svn_error_t * 00249 svn_cmdline_auth_ssl_client_cert_pw_prompt 00250 (svn_auth_cred_ssl_client_cert_pw_t **cred_p, 00251 void *baton, 00252 const char *realm, 00253 svn_boolean_t may_save, 00254 apr_pool_t *pool); 00255 00256 /** Initialize auth baton @a ab with the standard set of authentication 00257 * providers used by the command line client. @a non_interactive, 00258 * @a username, @a password, @a config_dir, and @a no_auth_cache are the 00259 * values of the command line options of the same names. @a cfg is the 00260 * @c SVN_CONFIG_CATEGORY_CONFIG configuration, and @a cancel_func and 00261 * @a cancel_baton control the cancellation of the prompting providers 00262 * that are initialized. @a pool is used for all allocations. 00263 * 00264 * @since New in 1.4. 00265 */ 00266 svn_error_t * 00267 svn_cmdline_setup_auth_baton(svn_auth_baton_t **ab, 00268 svn_boolean_t non_interactive, 00269 const char *username, 00270 const char *password, 00271 const char *config_dir, 00272 svn_boolean_t no_auth_cache, 00273 svn_config_t *cfg, 00274 svn_cancel_func_t cancel_func, 00275 void *cancel_baton, 00276 apr_pool_t *pool); 00277 00278 /** Wrapper for apr_getopt_init(), which see. 00279 * 00280 * @since New in 1.4. 00281 * 00282 * On OS400 V5R4, prior to calling apr_getopt_init(), converts each of the 00283 * @a argc strings in @a argv[] in place from EBCDIC to UTF-8, allocating 00284 * each new UTF-8 string in @a pool. 00285 * 00286 * This is a private API for Subversion's own use. 00287 */ 00288 svn_error_t * 00289 svn_cmdline__getopt_init(apr_getopt_t **os, 00290 int argc, 00291 const char *argv[], 00292 apr_pool_t *pool); 00293 00294 #ifdef __cplusplus 00295 } 00296 #endif /* __cplusplus */ 00297 00298 #endif /* SVN_CMDLINE_H */