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