1UI_CREATE_METHOD(3)                 OpenSSL                UI_CREATE_METHOD(3)
2
3
4

NAME

6       UI_METHOD, UI_create_method, UI_destroy_method, UI_method_set_opener,
7       UI_method_set_writer, UI_method_set_flusher, UI_method_set_reader,
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,
13       UI_method_get_prompt_constructor, UI_method_get_ex_data - user
14       interface method creation and destruction
15

SYNOPSIS

17        #include <openssl/ui.h>
18
19        typedef struct ui_method_st UI_METHOD;
20
21        UI_METHOD *UI_create_method(const char *name);
22        void UI_destroy_method(UI_METHOD *ui_method);
23        int UI_method_set_opener(UI_METHOD *method, int (*opener) (UI *ui));
24        int UI_method_set_writer(UI_METHOD *method,
25                                 int (*writer) (UI *ui, UI_STRING *uis));
26        int UI_method_set_flusher(UI_METHOD *method, int (*flusher) (UI *ui));
27        int UI_method_set_reader(UI_METHOD *method,
28                                 int (*reader) (UI *ui, UI_STRING *uis));
29        int UI_method_set_closer(UI_METHOD *method, int (*closer) (UI *ui));
30        int UI_method_set_data_duplicator(UI_METHOD *method,
31                                          void *(*duplicator) (UI *ui, void *ui_data),
32                                          void (*destructor)(UI *ui, void *ui_data));
33        int UI_method_set_prompt_constructor(UI_METHOD *method,
34                                             char *(*prompt_constructor) (UI *ui,
35                                                                          const char
36                                                                          *object_desc,
37                                                                          const char
38                                                                          *object_name));
39        int UI_method_set_ex_data(UI_METHOD *method, int idx, void *data);
40        int (*UI_method_get_opener(const UI_METHOD *method)) (UI *);
41        int (*UI_method_get_writer(const UI_METHOD *method)) (UI *, UI_STRING *);
42        int (*UI_method_get_flusher(const UI_METHOD *method)) (UI *);
43        int (*UI_method_get_reader(const UI_METHOD *method)) (UI *, UI_STRING *);
44        int (*UI_method_get_closer(const UI_METHOD *method)) (UI *);
45        char *(*UI_method_get_prompt_constructor(const UI_METHOD *method))
46            (UI *, const char *, const char *);
47        void *(*UI_method_get_data_duplicator(const UI_METHOD *method)) (UI *, void *);
48        void (*UI_method_get_data_destructor(const UI_METHOD *method)) (UI *, void *);
49        const void *UI_method_get_ex_data(const UI_METHOD *method, int idx);
50

DESCRIPTION

52       A method contains a few functions that implement the low-level of the
53       User Interface.  These functions are:
54
55       an opener
56           This function takes a reference to a UI and starts a session, for
57           example by opening a channel to a tty, or by creating a dialog box.
58
59       a writer
60           This function takes a reference to a UI and a UI String, and writes
61           the string where appropriate, maybe to the tty, maybe added as a
62           field label in a dialog box.  Note that this gets fed all strings
63           associated with a UI, one after the other, so care must be taken
64           which ones it actually uses.
65
66       a flusher
67           This function takes a reference to a UI, and flushes everything
68           that has been output so far.  For example, if the method builds up
69           a dialog box, this can be used to actually display it and accepting
70           input ended with a pressed button.
71
72       a reader
73           This function takes a reference to a UI and a UI string and reads
74           off the given prompt, maybe from the tty, maybe from a field in a
75           dialog box.  Note that this gets fed all strings associated with a
76           UI, one after the other, so care must be taken which ones it
77           actually uses.
78
79       a closer
80           This function takes a reference to a UI, and closes the session,
81           maybe by closing the channel to the tty, maybe by destroying a
82           dialog box.
83
84       All of these functions are expected to return 0 on error, 1 on success,
85       or -1 on out-off-band events, for example if some prompting has been
86       cancelled (by pressing Ctrl-C, for example).  Only the flusher or the
87       reader are expected to return -1.  If returned by another of the
88       functions, it's treated as if 0 was returned.
89
90       Regarding the writer and the reader, don't assume the former should
91       only write and don't assume the latter should only read.  This depends
92       on the needs of the method.
93
94       For example, a typical tty reader wouldn't write the prompts in the
95       write, but would rather do so in the reader, because of the sequential
96       nature of prompting on a tty.  This is how the UI_OpenSSL() method does
97       it.
98
99       In contrast, a method that builds up a dialog box would add all prompt
100       text in the writer, have all input read in the flusher and store the
101       results in some temporary buffer, and finally have the reader just
102       fetch those results.
103
104       The central function that uses these method functions is UI_process(),
105       and it does it in five steps:
106
107       1.  Open the session using the opener function if that one's defined.
108           If an error occurs, jump to 5.
109
110       2.  For every UI String associated with the UI, call the writer
111           function if that one's defined.  If an error occurs, jump to 5.
112
113       3.  Flush everything using the flusher function if that one's defined.
114           If an error occurs, jump to 5.
115
116       4.  For every UI String associated with the UI, call the reader
117           function if that one's defined.  If an error occurs, jump to 5.
118
119       5.  Close the session using the closer function if that one's defined.
120
121       UI_create_method() creates a new UI method with a given name.
122
123       UI_destroy_method() destroys the given UI method ui_method.
124
125       UI_method_set_opener(), UI_method_set_writer(),
126       UI_method_set_flusher(), UI_method_set_reader() and
127       UI_method_set_closer() set the five main method function to the given
128       function pointer.
129
130       UI_method_set_data_duplicator() sets the user data duplicator and
131       destructor.  See UI_dup_user_data(3).
132
133       UI_method_set_prompt_constructor() sets the prompt constructor.  See
134       UI_construct_prompt(3).
135
136       UI_method_set_ex_data() sets application specific data with a given
137       EX_DATA index.  See CRYPTO_get_ex_new_index(3) for general information
138       on how to get that index.
139
140       UI_method_get_opener(), UI_method_get_writer(),
141       UI_method_get_flusher(), UI_method_get_reader(),
142       UI_method_get_closer(), UI_method_get_data_duplicator(),
143       UI_method_get_data_destructor() and UI_method_get_prompt_constructor()
144       return the different method functions.
145
146       UI_method_get_ex_data() returns the application data previously stored
147       with UI_method_set_ex_data().
148

RETURN VALUES

150       UI_create_method() returns a UI_METHOD pointer on success, NULL on
151       error.
152
153       UI_method_set_opener(), UI_method_set_writer(),
154       UI_method_set_flusher(), UI_method_set_reader(),
155       UI_method_set_closer(), UI_method_set_data_duplicator() and
156       UI_method_set_prompt_constructor() return 0 on success, -1 if the given
157       method is NULL.
158
159       UI_method_set_ex_data() returns 1 on success and 0 on error (because
160       CRYPTO_set_ex_data() does so).
161
162       UI_method_get_opener(), UI_method_get_writer(),
163       UI_method_get_flusher(), UI_method_get_reader(),
164       UI_method_get_closer(), UI_method_get_data_duplicator(),
165       UI_method_get_data_destructor() and UI_method_get_prompt_constructor()
166       return the requested function pointer if it's set in the method,
167       otherwise NULL.
168
169       UI_method_get_ex_data() returns a pointer to the application specific
170       data associated with the method.
171

SEE ALSO

173       UI(3), CRYPTO_get_ex_data(3), UI_STRING(3)
174

HISTORY

176       The UI_method_set_data_duplicator(), UI_method_get_data_duplicator()
177       and UI_method_get_data_destructor() functions were added in OpenSSL
178       1.1.1.
179
181       Copyright 2001-2020 The OpenSSL Project Authors. All Rights Reserved.
182
183       Licensed under the OpenSSL license (the "License").  You may not use
184       this file except in compliance with the License.  You can obtain a copy
185       in the file LICENSE in the source distribution or at
186       <https://www.openssl.org/source/license.html>.
187
188
189
1901.1.1q                            2023-07-20               UI_CREATE_METHOD(3)
Impressum