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