doc/man3/UI_create_method.pod

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