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