1251881Speter/** 2251881Speter * @copyright 3251881Speter * ==================================================================== 4251881Speter * Licensed to the Apache Software Foundation (ASF) under one 5251881Speter * or more contributor license agreements. See the NOTICE file 6251881Speter * distributed with this work for additional information 7251881Speter * regarding copyright ownership. The ASF licenses this file 8251881Speter * to you under the Apache License, Version 2.0 (the 9251881Speter * "License"); you may not use this file except in compliance 10251881Speter * with the License. You may obtain a copy of the License at 11251881Speter * 12251881Speter * http://www.apache.org/licenses/LICENSE-2.0 13251881Speter * 14251881Speter * Unless required by applicable law or agreed to in writing, 15251881Speter * software distributed under the License is distributed on an 16251881Speter * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 17251881Speter * KIND, either express or implied. See the License for the 18251881Speter * specific language governing permissions and limitations 19251881Speter * under the License. 20251881Speter * ==================================================================== 21251881Speter * @endcopyright 22251881Speter * 23251881Speter * @file svn_cmdline.h 24251881Speter * @brief Support functions for command line programs 25251881Speter */ 26251881Speter 27251881Speter 28251881Speter 29251881Speter 30251881Speter#ifndef SVN_CMDLINE_H 31251881Speter#define SVN_CMDLINE_H 32251881Speter 33251881Speter#include <apr_pools.h> 34251881Speter#include <apr_getopt.h> 35251881Speter 36251881Speter#ifndef DOXYGEN_SHOULD_SKIP_THIS 37251881Speter#define APR_WANT_STDIO 38251881Speter#endif 39251881Speter#include <apr_want.h> 40251881Speter 41251881Speter#include "svn_types.h" 42251881Speter#include "svn_auth.h" 43251881Speter#include "svn_config.h" 44251881Speter 45251881Speter#ifdef __cplusplus 46251881Speterextern "C" { 47251881Speter#endif /* __cplusplus */ 48251881Speter 49251881Speter 50251881Speter/** Set up the locale for character conversion, and initialize APR. 51251881Speter * If @a error_stream is non-NULL, print error messages to the stream, 52251881Speter * using @a progname as the program name. Attempt to set @c stdout to 53251881Speter * line-buffered mode, and @a error_stream to unbuffered mode. Return 54251881Speter * @c EXIT_SUCCESS if successful, otherwise @c EXIT_FAILURE. 55251881Speter * 56251881Speter * @note This function should be called exactly once at program startup, 57251881Speter * before calling any other APR or Subversion functions. 58251881Speter */ 59251881Speterint 60251881Spetersvn_cmdline_init(const char *progname, 61251881Speter FILE *error_stream); 62251881Speter 63251881Speter 64251881Speter/** Set @a *dest to an output-encoded C string from UTF-8 C string @a 65251881Speter * src; allocate @a *dest in @a pool. 66251881Speter */ 67251881Spetersvn_error_t * 68251881Spetersvn_cmdline_cstring_from_utf8(const char **dest, 69251881Speter const char *src, 70251881Speter apr_pool_t *pool); 71251881Speter 72251881Speter/** Like svn_utf_cstring_from_utf8_fuzzy(), but converts to an 73251881Speter * output-encoded C string. */ 74251881Speterconst char * 75251881Spetersvn_cmdline_cstring_from_utf8_fuzzy(const char *src, 76251881Speter apr_pool_t *pool); 77251881Speter 78251881Speter/** Set @a *dest to a UTF-8-encoded C string from input-encoded C 79251881Speter * string @a src; allocate @a *dest in @a pool. 80251881Speter */ 81251881Spetersvn_error_t * 82251881Spetersvn_cmdline_cstring_to_utf8(const char **dest, 83251881Speter const char *src, 84251881Speter apr_pool_t *pool); 85251881Speter 86251881Speter/** Set @a *dest to an output-encoded natively-formatted path string 87251881Speter * from canonical path @a src; allocate @a *dest in @a pool. 88251881Speter */ 89251881Spetersvn_error_t * 90251881Spetersvn_cmdline_path_local_style_from_utf8(const char **dest, 91251881Speter const char *src, 92251881Speter apr_pool_t *pool); 93251881Speter 94251881Speter/** Write to stdout, using a printf-like format string @a fmt, passed 95251881Speter * through apr_pvsprintf(). All string arguments are in UTF-8; the output 96251881Speter * is converted to the output encoding. Use @a pool for temporary 97251881Speter * allocation. 98251881Speter * 99251881Speter * @since New in 1.1. 100251881Speter */ 101251881Spetersvn_error_t * 102251881Spetersvn_cmdline_printf(apr_pool_t *pool, 103251881Speter const char *fmt, 104251881Speter ...) 105251881Speter __attribute__((format(printf, 2, 3))); 106251881Speter 107251881Speter/** Write to the stdio @a stream, using a printf-like format string @a fmt, 108251881Speter * passed through apr_pvsprintf(). All string arguments are in UTF-8; 109251881Speter * the output is converted to the output encoding. Use @a pool for 110251881Speter * temporary allocation. 111251881Speter * 112251881Speter * @since New in 1.1. 113251881Speter */ 114251881Spetersvn_error_t * 115251881Spetersvn_cmdline_fprintf(FILE *stream, 116251881Speter apr_pool_t *pool, 117251881Speter const char *fmt, 118251881Speter ...) 119251881Speter __attribute__((format(printf, 3, 4))); 120251881Speter 121251881Speter/** Output the @a string to the stdio @a stream, converting from UTF-8 122251881Speter * to the output encoding. Use @a pool for temporary allocation. 123251881Speter * 124251881Speter * @since New in 1.1. 125251881Speter */ 126251881Spetersvn_error_t * 127251881Spetersvn_cmdline_fputs(const char *string, 128251881Speter FILE *stream, 129251881Speter apr_pool_t *pool); 130251881Speter 131251881Speter/** Flush output buffers of the stdio @a stream, returning an error if that 132251881Speter * fails. This is just a wrapper for the standard fflush() function for 133251881Speter * consistent error handling. 134251881Speter * 135251881Speter * @since New in 1.1. 136251881Speter */ 137251881Spetersvn_error_t * 138251881Spetersvn_cmdline_fflush(FILE *stream); 139251881Speter 140251881Speter/** Return the name of the output encoding allocated in @a pool, or @c 141251881Speter * APR_LOCALE_CHARSET if the output encoding is the same as the locale 142251881Speter * encoding. 143251881Speter * 144251881Speter * @since New in 1.3. 145251881Speter */ 146251881Speterconst char * 147251881Spetersvn_cmdline_output_encoding(apr_pool_t *pool); 148251881Speter 149251881Speter/** Handle @a error in preparation for immediate exit from a 150251881Speter * command-line client. Specifically: 151251881Speter * 152251881Speter * Call svn_handle_error2(@a error, stderr, FALSE, @a prefix), clear 153251881Speter * @a error, destroy @a pool iff it is non-NULL, and return EXIT_FAILURE. 154251881Speter * 155251881Speter * @since New in 1.3. 156251881Speter */ 157251881Speterint 158251881Spetersvn_cmdline_handle_exit_error(svn_error_t *error, 159251881Speter apr_pool_t *pool, 160251881Speter const char *prefix); 161251881Speter 162251881Speter/** A prompt function/baton pair, and the path to the configuration 163251881Speter * directory. To be passed as the baton argument to the 164251881Speter * @c svn_cmdline_*_prompt functions. 165251881Speter * 166251881Speter * @since New in 1.6. 167251881Speter */ 168251881Spetertypedef struct svn_cmdline_prompt_baton2_t { 169251881Speter svn_cancel_func_t cancel_func; 170251881Speter void *cancel_baton; 171251881Speter const char *config_dir; 172251881Speter} svn_cmdline_prompt_baton2_t; 173251881Speter 174251881Speter/** Like svn_cmdline_prompt_baton2_t, but without the path to the 175251881Speter * configuration directory. 176251881Speter * 177251881Speter * @since New in 1.4. 178251881Speter * @deprecated Provided for backward compatibility with the 1.5 API. 179251881Speter */ 180251881Spetertypedef struct svn_cmdline_prompt_baton_t { 181251881Speter svn_cancel_func_t cancel_func; 182251881Speter void *cancel_baton; 183251881Speter} svn_cmdline_prompt_baton_t; 184251881Speter 185251881Speter/** Prompt the user for input, using @a prompt_str for the prompt and 186251881Speter * @a baton (which may be @c NULL) for cancellation, and returning the 187251881Speter * user's response in @a result, allocated in @a pool. 188251881Speter * 189251881Speter * @since New in 1.5. 190251881Speter */ 191251881Spetersvn_error_t * 192251881Spetersvn_cmdline_prompt_user2(const char **result, 193251881Speter const char *prompt_str, 194251881Speter svn_cmdline_prompt_baton_t *baton, 195251881Speter apr_pool_t *pool); 196251881Speter 197251881Speter/** Similar to svn_cmdline_prompt_user2, but without cancellation 198251881Speter * support. 199251881Speter * 200251881Speter * @deprecated Provided for backward compatibility with the 1.4 API. 201251881Speter */ 202251881SpeterSVN_DEPRECATED 203251881Spetersvn_error_t * 204251881Spetersvn_cmdline_prompt_user(const char **result, 205251881Speter const char *prompt_str, 206251881Speter apr_pool_t *pool); 207251881Speter 208251881Speter/** An implementation of @c svn_auth_simple_prompt_func_t that prompts 209251881Speter * the user for keyboard input on the command line. 210251881Speter * 211251881Speter * @since New in 1.4. 212251881Speter * 213251881Speter * Expects a @c svn_cmdline_prompt_baton_t to be passed as @a baton. 214251881Speter */ 215251881Spetersvn_error_t * 216251881Spetersvn_cmdline_auth_simple_prompt(svn_auth_cred_simple_t **cred_p, 217251881Speter void *baton, 218251881Speter const char *realm, 219251881Speter const char *username, 220251881Speter svn_boolean_t may_save, 221251881Speter apr_pool_t *pool); 222251881Speter 223251881Speter 224251881Speter/** An implementation of @c svn_auth_username_prompt_func_t that prompts 225251881Speter * the user for their username via the command line. 226251881Speter * 227251881Speter * @since New in 1.4. 228251881Speter * 229251881Speter * Expects a @c svn_cmdline_prompt_baton_t to be passed as @a baton. 230251881Speter */ 231251881Spetersvn_error_t * 232251881Spetersvn_cmdline_auth_username_prompt(svn_auth_cred_username_t **cred_p, 233251881Speter void *baton, 234251881Speter const char *realm, 235251881Speter svn_boolean_t may_save, 236251881Speter apr_pool_t *pool); 237251881Speter 238251881Speter 239251881Speter/** An implementation of @c svn_auth_ssl_server_trust_prompt_func_t that 240251881Speter * asks the user if they trust a specific ssl server via the command line. 241251881Speter * 242251881Speter * @since New in 1.4. 243251881Speter * 244251881Speter * Expects a @c svn_cmdline_prompt_baton_t to be passed as @a baton. 245251881Speter */ 246251881Spetersvn_error_t * 247251881Spetersvn_cmdline_auth_ssl_server_trust_prompt( 248251881Speter svn_auth_cred_ssl_server_trust_t **cred_p, 249251881Speter void *baton, 250251881Speter const char *realm, 251251881Speter apr_uint32_t failures, 252251881Speter const svn_auth_ssl_server_cert_info_t *cert_info, 253251881Speter svn_boolean_t may_save, 254251881Speter apr_pool_t *pool); 255251881Speter 256251881Speter 257251881Speter/** An implementation of @c svn_auth_ssl_client_cert_prompt_func_t that 258251881Speter * prompts the user for the filename of their SSL client certificate via 259251881Speter * the command line. 260251881Speter * 261251881Speter * Records absolute path of the SSL client certificate file. 262251881Speter * 263251881Speter * @since New in 1.4. 264251881Speter * 265251881Speter * Expects a @c svn_cmdline_prompt_baton_t to be passed as @a baton. 266251881Speter */ 267251881Spetersvn_error_t * 268251881Spetersvn_cmdline_auth_ssl_client_cert_prompt( 269251881Speter svn_auth_cred_ssl_client_cert_t **cred_p, 270251881Speter void *baton, 271251881Speter const char *realm, 272251881Speter svn_boolean_t may_save, 273251881Speter apr_pool_t *pool); 274251881Speter 275251881Speter 276251881Speter/** An implementation of @c svn_auth_ssl_client_cert_pw_prompt_func_t that 277251881Speter * prompts the user for their SSL certificate password via the command line. 278251881Speter * 279251881Speter * @since New in 1.4. 280251881Speter * 281251881Speter * Expects a @c svn_cmdline_prompt_baton_t to be passed as @a baton. 282251881Speter */ 283251881Spetersvn_error_t * 284251881Spetersvn_cmdline_auth_ssl_client_cert_pw_prompt( 285251881Speter svn_auth_cred_ssl_client_cert_pw_t **cred_p, 286251881Speter void *baton, 287251881Speter const char *realm, 288251881Speter svn_boolean_t may_save, 289251881Speter apr_pool_t *pool); 290251881Speter 291251881Speter/** An implementation of @c svn_auth_plaintext_prompt_func_t that 292251881Speter * prompts the user whether storing unencrypted passwords to disk is OK. 293251881Speter * 294251881Speter * Expects a @c svn_cmdline_prompt_baton2_t to be passed as @a baton. 295251881Speter * 296251881Speter * @since New in 1.6. 297251881Speter */ 298251881Spetersvn_error_t * 299251881Spetersvn_cmdline_auth_plaintext_prompt(svn_boolean_t *may_save_plaintext, 300251881Speter const char *realmstring, 301251881Speter void *baton, 302251881Speter apr_pool_t *pool); 303251881Speter 304251881Speter/** An implementation of @c svn_auth_plaintext_passphrase_prompt_func_t that 305251881Speter * prompts the user whether storing unencrypted passphrase to disk is OK. 306251881Speter * 307251881Speter * Expects a @c svn_cmdline_prompt_baton2_t to be passed as @a baton. 308251881Speter * 309251881Speter * @since New in 1.6. 310251881Speter */ 311251881Spetersvn_error_t * 312251881Spetersvn_cmdline_auth_plaintext_passphrase_prompt(svn_boolean_t *may_save_plaintext, 313251881Speter const char *realmstring, 314251881Speter void *baton, 315251881Speter apr_pool_t *pool); 316251881Speter 317251881Speter 318251881Speter/** Set @a *ab to an authentication baton allocated from @a pool and 319251881Speter * initialized with the standard set of authentication providers used 320251881Speter * by the command line client. 321251881Speter * 322251881Speter * @a non_interactive, @a username, @a password, @a config_dir, 323289180Speter * and @a no_auth_cache are the values of the command line options 324289180Speter * of the corresponding names. 325251881Speter * 326289180Speter * If @a non_interactive is @c TRUE, then the following parameters 327289180Speter * control whether an invalid SSL certificate will be accepted 328289180Speter * regardless of a specific verification failure: 329289180Speter * 330289180Speter * @a trust_server_cert_unknown_ca: If @c TRUE, accept certificates 331289180Speter * from unknown certificate authorities. 332289180Speter * 333289180Speter * @a trust_server_cert_cn_mismatch: If @c TRUE, accept certificates 334289180Speter * even if the Common Name attribute of the certificate differs from 335289180Speter * the hostname of the server. 336289180Speter * 337289180Speter * @a trust_server_cert_expired: If @c TRUE, accept certificates even 338289180Speter * if they are expired. 339289180Speter * 340289180Speter * @a trust_server_cert_not_yet_valid: If @c TRUE, accept certificates 341289180Speter * from the future. 342289180Speter * 343289180Speter * @a trust_server_cert_other_failure: If @c TRUE, accept certificates 344289180Speter * even if any other verification failure than the above occured. 345289180Speter * 346251881Speter * @a cfg is the @c SVN_CONFIG_CATEGORY_CONFIG configuration, and 347251881Speter * @a cancel_func and @a cancel_baton control the cancellation of the 348251881Speter * prompting providers that are initialized. 349251881Speter * 350251881Speter * Use @a pool for all allocations. 351251881Speter * 352289180Speter * @since New in 1.9. 353289180Speter */ 354289180Spetersvn_error_t * 355289180Spetersvn_cmdline_create_auth_baton2(svn_auth_baton_t **ab, 356289180Speter svn_boolean_t non_interactive, 357289180Speter const char *username, 358289180Speter const char *password, 359289180Speter const char *config_dir, 360289180Speter svn_boolean_t no_auth_cache, 361289180Speter svn_boolean_t trust_server_cert_unknown_ca, 362289180Speter svn_boolean_t trust_server_cert_cn_mismatch, 363289180Speter svn_boolean_t trust_server_cert_expired, 364289180Speter svn_boolean_t trust_server_cert_not_yet_valid, 365289180Speter svn_boolean_t trust_server_cert_other_failure, 366289180Speter svn_config_t *cfg, 367289180Speter svn_cancel_func_t cancel_func, 368289180Speter void *cancel_baton, 369289180Speter apr_pool_t *pool); 370289180Speter 371289180Speter/* Like svn_cmdline_create_auth_baton2, but with only one trust_server_cert 372289180Speter * option which corresponds to trust_server_cert_unknown_ca. 373289180Speter * 374289180Speter * @deprecated Provided for backward compatibility with the 1.8 API. 375251881Speter * @since New in 1.6. 376251881Speter */ 377362181SdimSVN_DEPRECATED 378251881Spetersvn_error_t * 379251881Spetersvn_cmdline_create_auth_baton(svn_auth_baton_t **ab, 380251881Speter svn_boolean_t non_interactive, 381251881Speter const char *username, 382251881Speter const char *password, 383251881Speter const char *config_dir, 384251881Speter svn_boolean_t no_auth_cache, 385251881Speter svn_boolean_t trust_server_cert, 386251881Speter svn_config_t *cfg, 387251881Speter svn_cancel_func_t cancel_func, 388251881Speter void *cancel_baton, 389251881Speter apr_pool_t *pool); 390251881Speter 391251881Speter/** Similar to svn_cmdline_create_auth_baton(), but with 392251881Speter * @a trust_server_cert always set to false. 393251881Speter * 394251881Speter * @since New in 1.4. 395251881Speter * @deprecated Provided for backward compatibility with the 1.5 API. 396251881Speter * Use svn_cmdline_create_auth_baton() instead. 397251881Speter * 398251881Speter * @note This deprecation does not follow the usual pattern of putting 399251881Speter * a new number on end of the function's name. Instead, the new 400251881Speter * function name is distinguished from the old by a grammatical 401251881Speter * improvement: the verb "create" instead of the noun "setup". 402251881Speter */ 403251881SpeterSVN_DEPRECATED 404251881Spetersvn_error_t * 405251881Spetersvn_cmdline_setup_auth_baton(svn_auth_baton_t **ab, 406251881Speter svn_boolean_t non_interactive, 407251881Speter const char *username, 408251881Speter const char *password, 409251881Speter const char *config_dir, 410251881Speter svn_boolean_t no_auth_cache, 411251881Speter svn_config_t *cfg, 412251881Speter svn_cancel_func_t cancel_func, 413251881Speter void *cancel_baton, 414251881Speter apr_pool_t *pool); 415251881Speter 416251881Speter#ifdef __cplusplus 417251881Speter} 418251881Speter#endif /* __cplusplus */ 419251881Speter 420251881Speter#endif /* SVN_CMDLINE_H */ 421