xref: /netbsd-src/crypto/external/bsd/openssl.old/dist/doc/man3/UI_STRING.pod (revision 4724848cf0da353df257f730694b7882798e5daf)
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