1*4724848cSchristos=pod 2*4724848cSchristos 3*4724848cSchristos=head1 NAME 4*4724848cSchristos 5*4724848cSchristosUI_STRING, UI_string_types, UI_get_string_type, 6*4724848cSchristosUI_get_input_flags, UI_get0_output_string, 7*4724848cSchristosUI_get0_action_string, UI_get0_result_string, UI_get_result_string_length, 8*4724848cSchristosUI_get0_test_string, UI_get_result_minsize, 9*4724848cSchristosUI_get_result_maxsize, UI_set_result, UI_set_result_ex 10*4724848cSchristos- User interface string parsing 11*4724848cSchristos 12*4724848cSchristos=head1 SYNOPSIS 13*4724848cSchristos 14*4724848cSchristos #include <openssl/ui.h> 15*4724848cSchristos 16*4724848cSchristos typedef struct ui_string_st UI_STRING; 17*4724848cSchristos 18*4724848cSchristos enum UI_string_types { 19*4724848cSchristos UIT_NONE = 0, 20*4724848cSchristos UIT_PROMPT, /* Prompt for a string */ 21*4724848cSchristos UIT_VERIFY, /* Prompt for a string and verify */ 22*4724848cSchristos UIT_BOOLEAN, /* Prompt for a yes/no response */ 23*4724848cSchristos UIT_INFO, /* Send info to the user */ 24*4724848cSchristos UIT_ERROR /* Send an error message to the user */ 25*4724848cSchristos }; 26*4724848cSchristos 27*4724848cSchristos enum UI_string_types UI_get_string_type(UI_STRING *uis); 28*4724848cSchristos int UI_get_input_flags(UI_STRING *uis); 29*4724848cSchristos const char *UI_get0_output_string(UI_STRING *uis); 30*4724848cSchristos const char *UI_get0_action_string(UI_STRING *uis); 31*4724848cSchristos const char *UI_get0_result_string(UI_STRING *uis); 32*4724848cSchristos int UI_get_result_string_length(UI_STRING *uis); 33*4724848cSchristos const char *UI_get0_test_string(UI_STRING *uis); 34*4724848cSchristos int UI_get_result_minsize(UI_STRING *uis); 35*4724848cSchristos int UI_get_result_maxsize(UI_STRING *uis); 36*4724848cSchristos int UI_set_result(UI *ui, UI_STRING *uis, const char *result); 37*4724848cSchristos int UI_set_result_ex(UI *ui, UI_STRING *uis, const char *result, int len); 38*4724848cSchristos 39*4724848cSchristos=head1 DESCRIPTION 40*4724848cSchristos 41*4724848cSchristosThe B<UI_STRING> gets created internally and added to a B<UI> whenever 42*4724848cSchristosone of the functions UI_add_input_string(), UI_dup_input_string(), 43*4724848cSchristosUI_add_verify_string(), UI_dup_verify_string(), 44*4724848cSchristosUI_add_input_boolean(), UI_dup_input_boolean(), UI_add_info_string(), 45*4724848cSchristosUI_dup_info_string(), UI_add_error_string() or UI_dup_error_string() 46*4724848cSchristosis called. 47*4724848cSchristosFor a B<UI_METHOD> user, there's no need to know more. 48*4724848cSchristosFor a B<UI_METHOD> creator, it is of interest to fetch text from these 49*4724848cSchristosB<UI_STRING> objects as well as adding results to some of them. 50*4724848cSchristos 51*4724848cSchristosUI_get_string_type() is used to retrieve the type of the given 52*4724848cSchristosB<UI_STRING>. 53*4724848cSchristos 54*4724848cSchristosUI_get_input_flags() is used to retrieve the flags associated with the 55*4724848cSchristosgiven B<UI_STRING>. 56*4724848cSchristos 57*4724848cSchristosUI_get0_output_string() is used to retrieve the actual string to 58*4724848cSchristosoutput (prompt, info, error, ...). 59*4724848cSchristos 60*4724848cSchristosUI_get0_action_string() is used to retrieve the action description 61*4724848cSchristosassociated with a B<UIT_BOOLEAN> type B<UI_STRING>. 62*4724848cSchristosFor all other B<UI_STRING> types, NULL is returned. 63*4724848cSchristosSee L<UI_add_input_boolean(3)>. 64*4724848cSchristos 65*4724848cSchristosUI_get0_result_string() and UI_get_result_string_length() are used to 66*4724848cSchristosretrieve the result of a prompt and its length. 67*4724848cSchristosThis is only useful for B<UIT_PROMPT> and B<UIT_VERIFY> type strings. 68*4724848cSchristosFor all other B<UI_STRING> types, UI_get0_result_string() returns NULL 69*4724848cSchristosand UI_get_result_string_length() returns -1. 70*4724848cSchristos 71*4724848cSchristosUI_get0_test_string() is used to retrieve the string to compare the 72*4724848cSchristosprompt result with. 73*4724848cSchristosThis is only useful for B<UIT_VERIFY> type strings. 74*4724848cSchristosFor all other B<UI_STRING> types, NULL is returned. 75*4724848cSchristos 76*4724848cSchristosUI_get_result_minsize() and UI_get_result_maxsize() are used to 77*4724848cSchristosretrieve the minimum and maximum required size of the result. 78*4724848cSchristosThis is only useful for B<UIT_PROMPT> and B<UIT_VERIFY> type strings. 79*4724848cSchristosFor all other B<UI_STRING> types, -1 is returned. 80*4724848cSchristos 81*4724848cSchristosUI_set_result_ex() is used to set the result value of a prompt and its length. 82*4724848cSchristosFor B<UIT_PROMPT> and B<UIT_VERIFY> type UI strings, this sets the 83*4724848cSchristosresult retrievable with UI_get0_result_string() by copying the 84*4724848cSchristoscontents of B<result> if its length fits the minimum and maximum size 85*4724848cSchristosrequirements. 86*4724848cSchristosFor B<UIT_BOOLEAN> type UI strings, this sets the first character of 87*4724848cSchristosthe result retrievable with UI_get0_result_string() to the first 88*4724848cSchristosB<ok_char> given with UI_add_input_boolean() or UI_dup_input_boolean() 89*4724848cSchristosif the B<result> matched any of them, or the first of the 90*4724848cSchristosB<cancel_chars> if the B<result> matched any of them, otherwise it's 91*4724848cSchristosset to the NUL char C<\0>. 92*4724848cSchristosSee L<UI_add_input_boolean(3)> for more information on B<ok_chars> and 93*4724848cSchristosB<cancel_chars>. 94*4724848cSchristos 95*4724848cSchristosUI_set_result() does the same thing as UI_set_result_ex(), but calculates 96*4724848cSchristosits length internally. 97*4724848cSchristosIt expects the string to be terminated with a NUL byte, and is therefore 98*4724848cSchristosonly useful with normal C strings. 99*4724848cSchristos 100*4724848cSchristos=head1 RETURN VALUES 101*4724848cSchristos 102*4724848cSchristosUI_get_string_type() returns the UI string type. 103*4724848cSchristos 104*4724848cSchristosUI_get_input_flags() returns the UI string flags. 105*4724848cSchristos 106*4724848cSchristosUI_get0_output_string() returns the UI string output string. 107*4724848cSchristos 108*4724848cSchristosUI_get0_action_string() returns the UI string action description 109*4724848cSchristosstring for B<UIT_BOOLEAN> type UI strings, NULL for any other type. 110*4724848cSchristos 111*4724848cSchristosUI_get0_result_string() returns the UI string result buffer for 112*4724848cSchristosB<UIT_PROMPT> and B<UIT_VERIFY> type UI strings, NULL for any other 113*4724848cSchristostype. 114*4724848cSchristos 115*4724848cSchristosUI_get_result_string_length() returns the UI string result buffer's 116*4724848cSchristoscontent length for B<UIT_PROMPT> and B<UIT_VERIFY> type UI strings, 117*4724848cSchristos-1 for any other type. 118*4724848cSchristos 119*4724848cSchristosUI_get0_test_string() returns the UI string action description 120*4724848cSchristosstring for B<UIT_VERIFY> type UI strings, NULL for any other type. 121*4724848cSchristos 122*4724848cSchristosUI_get_result_minsize() returns the minimum allowed result size for 123*4724848cSchristosthe UI string for B<UIT_PROMPT> and B<UIT_VERIFY> type strings, 124*4724848cSchristos-1 for any other type. 125*4724848cSchristos 126*4724848cSchristosUI_get_result_maxsize() returns the minimum allowed result size for 127*4724848cSchristosthe UI string for B<UIT_PROMPT> and B<UIT_VERIFY> type strings, 128*4724848cSchristos-1 for any other type. 129*4724848cSchristos 130*4724848cSchristosUI_set_result() returns 0 on success or when the UI string is of any 131*4724848cSchristostype other than B<UIT_PROMPT>, B<UIT_VERIFY> or B<UIT_BOOLEAN>, -1 on 132*4724848cSchristoserror. 133*4724848cSchristos 134*4724848cSchristos=head1 SEE ALSO 135*4724848cSchristos 136*4724848cSchristosL<UI(3)> 137*4724848cSchristos 138*4724848cSchristos=head1 COPYRIGHT 139*4724848cSchristos 140*4724848cSchristosCopyright 2001-2018 The OpenSSL Project Authors. All Rights Reserved. 141*4724848cSchristos 142*4724848cSchristosLicensed under the OpenSSL license (the "License"). You may not use 143*4724848cSchristosthis file except in compliance with the License. You can obtain a copy 144*4724848cSchristosin the file LICENSE in the source distribution or at 145*4724848cSchristosL<https://www.openssl.org/source/license.html>. 146*4724848cSchristos 147*4724848cSchristos=cut 148*4724848cSchristos 149