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