]>
Commit | Line | Data |
---|---|---|
5469600e RL |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
5 | UI_METHOD, | |
6 | UI_create_method, UI_destroy_method, UI_method_set_opener, | |
7 | UI_method_set_writer, UI_method_set_flusher, UI_method_set_reader, | |
545360c4 RL |
8 | UI_method_set_closer, UI_method_set_data_duplicator, |
9 | UI_method_set_prompt_constructor, UI_method_set_ex_data, | |
10 | UI_method_get_opener, UI_method_get_writer, UI_method_get_flusher, | |
11 | UI_method_get_reader, UI_method_get_closer, | |
12 | UI_method_get_data_duplicator, UI_method_get_data_destructor, | |
5469600e RL |
13 | UI_method_get_prompt_constructor, UI_method_get_ex_data - user |
14 | interface method creation and destruction | |
15 | ||
16 | =head1 SYNOPSIS | |
17 | ||
18 | #include <openssl/ui.h> | |
19 | ||
20 | typedef struct ui_method_st UI_METHOD; | |
21 | ||
22 | UI_METHOD *UI_create_method(const char *name); | |
23 | void UI_destroy_method(UI_METHOD *ui_method); | |
24 | int UI_method_set_opener(UI_METHOD *method, int (*opener) (UI *ui)); | |
25 | int UI_method_set_writer(UI_METHOD *method, | |
26 | int (*writer) (UI *ui, UI_STRING *uis)); | |
27 | int UI_method_set_flusher(UI_METHOD *method, int (*flusher) (UI *ui)); | |
28 | int UI_method_set_reader(UI_METHOD *method, | |
29 | int (*reader) (UI *ui, UI_STRING *uis)); | |
30 | int UI_method_set_closer(UI_METHOD *method, int (*closer) (UI *ui)); | |
545360c4 RL |
31 | int UI_method_set_data_duplicator(UI_METHOD *method, |
32 | void *(*duplicator) (UI *ui, void *ui_data), | |
33 | void (*destructor)(UI *ui, void *ui_data)); | |
5469600e RL |
34 | int UI_method_set_prompt_constructor(UI_METHOD *method, |
35 | char *(*prompt_constructor) (UI *ui, | |
36 | const char | |
37 | *object_desc, | |
38 | const char | |
39 | *object_name)); | |
40 | int UI_method_set_ex_data(UI_METHOD *method, int idx, void *data); | |
41 | int (*UI_method_get_opener(const UI_METHOD *method)) (UI *); | |
42 | int (*UI_method_get_writer(const UI_METHOD *method)) (UI *, UI_STRING *); | |
43 | int (*UI_method_get_flusher(const UI_METHOD *method)) (UI *); | |
44 | int (*UI_method_get_reader(const UI_METHOD *method)) (UI *, UI_STRING *); | |
45 | int (*UI_method_get_closer(const UI_METHOD *method)) (UI *); | |
46 | char *(*UI_method_get_prompt_constructor(const UI_METHOD *method)) | |
47 | (UI *, const char *, const char *); | |
545360c4 RL |
48 | void *(*UI_method_get_data_duplicator(const UI_METHOD *method)) (UI *, void *); |
49 | void (*UI_method_get_data_destructor(const UI_METHOD *method)) (UI *, void *); | |
5469600e RL |
50 | const void *UI_method_get_ex_data(const UI_METHOD *method, int idx); |
51 | ||
52 | =head1 DESCRIPTION | |
53 | ||
54 | A method contains a few functions that implement the low level of the | |
55 | User Interface. | |
56 | These functions are: | |
57 | ||
58 | =over 4 | |
59 | ||
60 | =item an opener | |
61 | ||
62 | This function takes a reference to a UI and starts a session, for | |
63 | example by opening a channel to a tty, or by creating a dialog box. | |
64 | ||
65 | =item a writer | |
66 | ||
67 | This function takes a reference to a UI and a UI String, and writes | |
68 | the string where appropriate, maybe to the tty, maybe added as a field | |
69 | label in a dialog box. | |
70 | Note that this gets fed all strings associated with a UI, one after | |
71 | the other, so care must be taken which ones it actually uses. | |
72 | ||
73 | =item a flusher | |
74 | ||
75 | This function takes a reference to a UI, and flushes everything that | |
76 | has been output so far. | |
77 | For example, if the method builds up a dialog box, this can be used to | |
78 | actually display it and accepting input ended with a pressed button. | |
79 | ||
80 | =item a reader | |
81 | ||
82 | This function takes a reference to a UI and a UI string and reads off | |
83 | the given prompt, maybe from the tty, maybe from a field in a dialog | |
84 | box. | |
85 | Note that this gets fed all strings associated with a UI, one after | |
86 | the other, so care must be taken which ones it actually uses. | |
87 | ||
88 | =item a closer | |
89 | ||
90 | This function takes a reference to a UI, and closes the session, maybe | |
91 | by closing the channel to the tty, maybe by destroying a dialog box. | |
92 | ||
93 | =back | |
94 | ||
8e3d46e5 RL |
95 | All of these functions are expected to return 0 on error, 1 on |
96 | success, or -1 on out-off-band events, for example if some prompting | |
97 | has been cancelled (by pressing Ctrl-C, for example). | |
98 | Only the flusher or the reader are expected to return -1. | |
5469600e RL |
99 | If returned by another of the functions, it's treated as if 0 was |
100 | returned. | |
101 | ||
5469600e RL |
102 | Regarding the writer and the reader, don't assume the former should |
103 | only write and don't assume the latter should only read. | |
104 | This depends on the needs of the method. | |
105 | ||
106 | For example, a typical tty reader wouldn't write the prompts in the | |
107 | write, but would rather do so in the reader, because of the sequential | |
108 | nature of prompting on a tty. | |
109 | This is how the UI_OpenSSL() method does it. | |
110 | ||
111 | In contrast, a method that builds up a dialog box would add all prompt | |
112 | text in the writer, have all input read in the flusher and store the | |
113 | results in some temporary buffer, and finally have the reader just | |
114 | fetch those results. | |
115 | ||
116 | The central function that uses these method functions is UI_process(), | |
117 | and it does it in five steps: | |
118 | ||
119 | =over 4 | |
120 | ||
121 | =item 1. | |
122 | ||
123 | Open the session using the opener function if that one's defined. | |
124 | If an error occurs, jump to 5. | |
125 | ||
126 | =item 2. | |
127 | ||
128 | For every UI String associated with the UI, call the writer function | |
129 | if that one's defined. | |
130 | If an error occurs, jump to 5. | |
131 | ||
132 | =item 3. | |
133 | ||
134 | Flush everything using the flusher function if that one's defined. | |
135 | If an error occurs, jump to 5. | |
136 | ||
137 | =item 4. | |
138 | ||
139 | For every UI String associated with the UI, call the reader function | |
140 | if that one's defined. | |
141 | If an error occurs, jump to 5. | |
142 | ||
143 | =item 5. | |
144 | ||
145 | Close the session using the closer function if that one's defined. | |
146 | ||
147 | =back | |
148 | ||
149 | UI_create_method() creates a new UI method with a given B<name>. | |
150 | ||
151 | UI_destroy_method() destroys the given UI method B<ui_method>. | |
152 | ||
153 | UI_method_set_opener(), UI_method_set_writer(), | |
154 | UI_method_set_flusher(), UI_method_set_reader() and | |
155 | UI_method_set_closer() set the five main method function to the given | |
156 | function pointer. | |
157 | ||
545360c4 RL |
158 | UI_method_set_data_duplicator() sets the user data duplicator and destructor. |
159 | See L<UI_dup_user_data(3)>. | |
160 | ||
5469600e RL |
161 | UI_method_set_prompt_constructor() sets the prompt constructor. |
162 | See L<UI_construct_prompt(3)>. | |
163 | ||
164 | UI_method_set_ex_data() sets application specific data with a given | |
165 | EX_DATA index. | |
166 | See L<CRYPTO_get_ex_new_index(3)> for general information on how to | |
167 | get that index. | |
168 | ||
169 | UI_method_get_opener(), UI_method_get_writer(), | |
170 | UI_method_get_flusher(), UI_method_get_reader(), | |
545360c4 RL |
171 | UI_method_get_closer(), UI_method_get_data_duplicator(), |
172 | UI_method_get_data_destructor() and UI_method_get_prompt_constructor() | |
173 | return the different method functions. | |
5469600e RL |
174 | |
175 | UI_method_get_ex_data() returns the application data previously stored | |
176 | with UI_method_set_ex_data(). | |
177 | ||
178 | =head1 RETURN VALUES | |
179 | ||
180 | UI_create_method() returns a UI_METHOD pointer on success, NULL on | |
181 | error. | |
182 | ||
183 | UI_method_set_opener(), UI_method_set_writer(), | |
184 | UI_method_set_flusher(), UI_method_set_reader(), | |
545360c4 RL |
185 | UI_method_set_closer(), UI_method_set_data_duplicator() and |
186 | UI_method_set_prompt_constructor() | |
187 | return 0 on success, -1 if the given B<method> is NULL. | |
5469600e RL |
188 | |
189 | UI_method_set_ex_data() returns 1 on success and 0 on error (because | |
190 | CRYPTO_set_ex_data() does so). | |
191 | ||
192 | UI_method_get_opener(), UI_method_get_writer(), | |
193 | UI_method_get_flusher(), UI_method_get_reader(), | |
545360c4 RL |
194 | UI_method_get_closer(), UI_method_get_data_duplicator(), |
195 | UI_method_get_data_destructor() and UI_method_get_prompt_constructor() | |
196 | return the requested function pointer if it's set in the method, | |
197 | otherwise NULL. | |
5469600e RL |
198 | |
199 | UI_method_get_ex_data() returns a pointer to the application specific | |
200 | data associated with the method. | |
201 | ||
202 | =head1 SEE ALSO | |
203 | ||
204 | L<UI(3)>, L<CRYPTO_get_ex_data(3)>, L<UI_STRING(3)> | |
205 | ||
545360c4 RL |
206 | =head1 HISTORY |
207 | ||
fc5ecadd DMSP |
208 | The UI_method_set_data_duplicator(), UI_method_get_data_duplicator() |
209 | and UI_method_get_data_destructor() functions were added in OpenSSL 1.1.1. | |
545360c4 | 210 | |
5469600e RL |
211 | =head1 COPYRIGHT |
212 | ||
213 | Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved. | |
214 | ||
4746f25a | 215 | Licensed under the Apache License 2.0 (the "License"). You may not use |
5469600e RL |
216 | this file except in compliance with the License. You can obtain a copy |
217 | in the file LICENSE in the source distribution or at | |
218 | L<https://www.openssl.org/source/license.html>. | |
219 | ||
220 | =cut |