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_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
  13
  14 =head1 SYNOPSIS
  15
  16  #include <openssl/ui.h>
  17
  18  typedef struct ui_method_st UI_METHOD;
  19
  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,
  31                                                                    const char
  32                                                                    *object_desc,
  33                                                                    const char
  34                                                                    *object_name));
  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);
  44
  45 =head1 DESCRIPTION
  46
  47 A method contains a few functions that implement the low level of the
  48 User Interface.
  49 These functions are:
  50
  51 =over 4
  52
  53 =item an opener
  54
  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.
  57
  58 =item a writer
  59
  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.
  65
  66 =item a flusher
  67
  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.
  72
  73 =item a reader
  74
  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
  77 box.
  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.
  80
  81 =item a closer
  82
  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.
  85
  86 =back
  87
  88 All of these functions are expected to return one of these values:
  89
  90 =over 4
  91
  92 =item 0
  93
  94 on error.
  95
  96 =item 1
  97
  98 on success.
  99
 100 =item -1
 101
 102 on out-off-band events, for example if some prompting has been
 103 cancelled (by pressing Ctrl-C, for example).
 104 This is only expected to be returned by the flusher or the reader.
 105 If returned by another of the functions, it's treated as if 0 was
 106 returned.
 107
 108 =back
 109
 110 Regarding the writer and the reader, don't assume the former should
 111 only write and don't assume the latter should only read.
 112 This depends on the needs of the method.
 113
 114 For example, a typical tty reader wouldn't write the prompts in the
 115 write, but would rather do so in the reader, because of the sequential
 116 nature of prompting on a tty.
 117 This is how the UI_OpenSSL() method does it.
 118
 119 In contrast, a method that builds up a dialog box would add all prompt
 120 text in the writer, have all input read in the flusher and store the
 121 results in some temporary buffer, and finally have the reader just
 122 fetch those results.
 123
 124 The central function that uses these method functions is UI_process(),
 125 and it does it in five steps:
 126
 127 =over 4
 128
 129 =item 1.
 130
 131 Open the session using the opener function if that one's defined.
 132 If an error occurs, jump to 5.
 133
 134 =item 2.
 135
 136 For every UI String associated with the UI, call the writer function
 137 if that one's defined.
 138 If an error occurs, jump to 5.
 139
 140 =item 3.
 141
 142 Flush everything using the flusher function if that one's defined.
 143 If an error occurs, jump to 5.
 144
 145 =item 4.
 146
 147 For every UI String associated with the UI, call the reader function
 148 if that one's defined.
 149 If an error occurs, jump to 5.
 150
 151 =item 5.
 152
 153 Close the session using the closer function if that one's defined.
 154
 155 =back
 156
 157 UI_create_method() creates a new UI method with a given B<name>.
 158
 159 UI_destroy_method() destroys the given UI method B<ui_method>.
 160
 161 UI_method_set_opener(), UI_method_set_writer(),
 162 UI_method_set_flusher(), UI_method_set_reader() and
 163 UI_method_set_closer() set the five main method function to the given
 164 function pointer.
 165
 166 UI_method_set_prompt_constructor() sets the prompt constructor.
 167 See L<UI_construct_prompt(3)>.
 168
 169 UI_method_set_ex_data() sets application specific data with a given
 170 EX_DATA index.
 171 See L<CRYPTO_get_ex_new_index(3)> for general information on how to
 172 get that index.
 173
 174 UI_method_get_opener(), UI_method_get_writer(),
 175 UI_method_get_flusher(), UI_method_get_reader(),
 176 UI_method_get_closer() and UI_method_get_prompt_constructor() return
 177 the different method functions.
 178
 179 UI_method_get_ex_data() returns the application data previously stored
 180 with UI_method_set_ex_data().
 181
 182 =head1 RETURN VALUES
 183
 184 UI_create_method() returns a UI_METHOD pointer on success, NULL on
 185 error.
 186
 187 UI_method_set_opener(), UI_method_set_writer(),
 188 UI_method_set_flusher(), UI_method_set_reader(),
 189 UI_method_set_closer() and UI_method_set_prompt_constructor() return
 190 0 on success, -1 if the given B<method> is NULL.
 191
 192 UI_method_set_ex_data() returns 1 on success and 0 on error (because
 193 CRYPTO_set_ex_data() does so).
 194
 195 UI_method_get_opener(), UI_method_get_writer(),
 196 UI_method_get_flusher(), UI_method_get_reader(),
 197 UI_method_get_closer() and UI_method_get_prompt_constructor() return
 198 the requested function pointer if it's set in the method, otherwise
 199 NULL.
 200
 201 UI_method_get_ex_data() returns a pointer to the application specific
 202 data associated with the method.
 203
 204 =head1 SEE ALSO
 205
 206 L<UI(3)>, L<CRYPTO_get_ex_data(3)>, L<UI_STRING(3)>
 207
 208 =head1 COPYRIGHT
 209
 210 Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.
 211
 212 Licensed under the OpenSSL license (the "License").  You may not use
 213 this file except in compliance with the License.  You can obtain a copy
 214 in the file LICENSE in the source distribution or at
 215 L<https://www.openssl.org/source/license.html>.
 216
 217 =cut