6 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_prompt_constructor,
9 UI_method_set_ex_data, UI_method_get_opener, UI_method_get_writer,
10 UI_method_get_flusher, UI_method_get_reader, UI_method_get_closer,
11 UI_method_get_prompt_constructor, UI_method_get_ex_data - user
12 interface method creation and destruction
16 #include <openssl/ui.h>
18 typedef struct ui_method_st UI_METHOD;
20 UI_METHOD *UI_create_method(const char *name);
21 void UI_destroy_method(UI_METHOD *ui_method);
22 int UI_method_set_opener(UI_METHOD *method, int (*opener) (UI *ui));
23 int UI_method_set_writer(UI_METHOD *method,
24 int (*writer) (UI *ui, UI_STRING *uis));
25 int UI_method_set_flusher(UI_METHOD *method, int (*flusher) (UI *ui));
26 int UI_method_set_reader(UI_METHOD *method,
27 int (*reader) (UI *ui, UI_STRING *uis));
28 int UI_method_set_closer(UI_METHOD *method, int (*closer) (UI *ui));
29 int UI_method_set_prompt_constructor(UI_METHOD *method,
30 char *(*prompt_constructor) (UI *ui,
35 int UI_method_set_ex_data(UI_METHOD *method, int idx, void *data);
36 int (*UI_method_get_opener(const UI_METHOD *method)) (UI *);
37 int (*UI_method_get_writer(const UI_METHOD *method)) (UI *, UI_STRING *);
38 int (*UI_method_get_flusher(const UI_METHOD *method)) (UI *);
39 int (*UI_method_get_reader(const UI_METHOD *method)) (UI *, UI_STRING *);
40 int (*UI_method_get_closer(const UI_METHOD *method)) (UI *);
41 char *(*UI_method_get_prompt_constructor(const UI_METHOD *method))
42 (UI *, const char *, const char *);
43 const void *UI_method_get_ex_data(const UI_METHOD *method, int idx);
47 A method contains a few functions that implement the low level of the
55 This function takes a reference to a UI and starts a session, for
56 example by opening a channel to a tty, or by creating a dialog box.
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 field
62 label in a dialog box.
63 Note that this gets fed all strings associated with a UI, one after
64 the other, so care must be taken which ones it actually uses.
68 This function takes a reference to a UI, and flushes everything that
69 has been output so far.
70 For example, if the method builds up a dialog box, this can be used to
71 actually display it and accepting input ended with a pressed button.
75 This function takes a reference to a UI and a UI string and reads off
76 the given prompt, maybe from the tty, maybe from a field in a dialog
78 Note that this gets fed all strings associated with a UI, one after
79 the other, so care must be taken which ones it actually uses.
83 This function takes a reference to a UI, and closes the session, maybe
84 by closing the channel to the tty, maybe by destroying a dialog box.
88 All of these functions are expected to return 0 on error, 1 on
89 success, or -1 on out-off-band events, for example if some prompting
90 has been cancelled (by pressing Ctrl-C, for example).
91 Only the flusher or the reader are expected to return -1.
92 If returned by another of the functions, it's treated as if 0 was
95 Regarding the writer and the reader, don't assume the former should
96 only write and don't assume the latter should only read.
97 This depends on the needs of the method.
99 For example, a typical tty reader wouldn't write the prompts in the
100 write, but would rather do so in the reader, because of the sequential
101 nature of prompting on a tty.
102 This is how the UI_OpenSSL() method does it.
104 In contrast, a method that builds up a dialog box would add all prompt
105 text in the writer, have all input read in the flusher and store the
106 results in some temporary buffer, and finally have the reader just
109 The central function that uses these method functions is UI_process(),
110 and it does it in five steps:
116 Open the session using the opener function if that one's defined.
117 If an error occurs, jump to 5.
121 For every UI String associated with the UI, call the writer function
122 if that one's defined.
123 If an error occurs, jump to 5.
127 Flush everything using the flusher function if that one's defined.
128 If an error occurs, jump to 5.
132 For every UI String associated with the UI, call the reader function
133 if that one's defined.
134 If an error occurs, jump to 5.
138 Close the session using the closer function if that one's defined.
142 UI_create_method() creates a new UI method with a given B<name>.
144 UI_destroy_method() destroys the given UI method B<ui_method>.
146 UI_method_set_opener(), UI_method_set_writer(),
147 UI_method_set_flusher(), UI_method_set_reader() and
148 UI_method_set_closer() set the five main method function to the given
151 UI_method_set_prompt_constructor() sets the prompt constructor.
152 See L<UI_construct_prompt(3)>.
154 UI_method_set_ex_data() sets application specific data with a given
156 See L<CRYPTO_get_ex_new_index(3)> for general information on how to
159 UI_method_get_opener(), UI_method_get_writer(),
160 UI_method_get_flusher(), UI_method_get_reader(),
161 UI_method_get_closer() and UI_method_get_prompt_constructor() return
162 the different method functions.
164 UI_method_get_ex_data() returns the application data previously stored
165 with UI_method_set_ex_data().
169 UI_create_method() returns a UI_METHOD pointer on success, NULL on
172 UI_method_set_opener(), UI_method_set_writer(),
173 UI_method_set_flusher(), UI_method_set_reader(),
174 UI_method_set_closer() and UI_method_set_prompt_constructor() return
175 0 on success, -1 if the given B<method> is NULL.
177 UI_method_set_ex_data() returns 1 on success and 0 on error (because
178 CRYPTO_set_ex_data() does so).
180 UI_method_get_opener(), UI_method_get_writer(),
181 UI_method_get_flusher(), UI_method_get_reader(),
182 UI_method_get_closer() and UI_method_get_prompt_constructor() return
183 the requested function pointer if it's set in the method, otherwise
186 UI_method_get_ex_data() returns a pointer to the application specific
187 data associated with the method.
191 L<UI(3)>, L<CRYPTO_get_ex_data(3)>, L<UI_STRING(3)>
195 Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
197 Licensed under the OpenSSL license (the "License"). You may not use
198 this file except in compliance with the License. You can obtain a copy
199 in the file LICENSE in the source distribution or at
200 L<https://www.openssl.org/source/license.html>.