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 OpenSSL license (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