secure/lib/libcrypto/man/man3/UI_create_method.3

   1 .\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 .    ds C`
  42 .    ds C'
  43 'br\}
  44 .\"
  45 .\" Escape single quotes in literal strings from groff's Unicode transform.
  46 .ie \n(.g .ds Aq \(aq
  47 .el       .ds Aq '
  48 .\"
  49 .\" If the F register is >0, we'll generate index entries on stderr for
  50 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  51 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  52 .\" output yourself in some meaningful fashion.
  53 .\"
  54 .\" Avoid warning from groff about undefined register 'F'.
  55 .de IX
  56 ..
  57 .nr rF 0
  58 .if \n(.g .if rF .nr rF 1
  59 .if (\n(rF:(\n(.g==0)) \{\
  60 .    if \nF \{\
  61 .        de IX
  62 .        tm Index:\\$1\t\\n%\t"\\$2"
  63 ..
  64 .        if !\nF==2 \{\
  65 .            nr % 0
  66 .            nr F 2
  67 .        \}
  68 .    \}
  69 .\}
  70 .rr rF
  71 .\"
  72 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  73 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  74 .    \" fudge factors for nroff and troff
  75 .if n \{\
  76 .    ds #H 0
  77 .    ds #V .8m
  78 .    ds #F .3m
  79 .    ds #[ \f1
  80 .    ds #] \fP
  81 .\}
  82 .if t \{\
  83 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  84 .    ds #V .6m
  85 .    ds #F 0
  86 .    ds #[ \&
  87 .    ds #] \&
  88 .\}
  89 .    \" simple accents for nroff and troff
  90 .if n \{\
  91 .    ds ' \&
  92 .    ds ` \&
  93 .    ds ^ \&
  94 .    ds , \&
  95 .    ds ~ ~
  96 .    ds /
  97 .\}
  98 .if t \{\
  99 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
 100 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
 101 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
 102 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
 103 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 104 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 105 .\}
 106 .    \" troff and (daisy-wheel) nroff accents
 107 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 108 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 109 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 110 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 111 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 112 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 113 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 114 .ds ae a\h'-(\w'a'u*4/10)'e
 115 .ds Ae A\h'-(\w'A'u*4/10)'E
 116 .    \" corrections for vroff
 117 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 118 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 119 .    \" for low resolution devices (crt and lpr)
 120 .if \n(.H>23 .if \n(.V>19 \
 121 \{\
 122 .    ds : e
 123 .    ds 8 ss
 124 .    ds o a
 125 .    ds d- d\h'-1'\(ga
 126 .    ds D- D\h'-1'\(hy
 127 .    ds th \o'bp'
 128 .    ds Th \o'LP'
 129 .    ds ae ae
 130 .    ds Ae AE
 131 .\}
 132 .rm #[ #] #H #V #F C
 133 .\" ========================================================================
 134 .\"
 135 .IX Title "UI_CREATE_METHOD 3"
 136 .TH UI_CREATE_METHOD 3 "2020-09-22" "1.1.1h" "OpenSSL"
 137 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 138 .\" way too many mistakes in technical documents.
 139 .if n .ad l
 140 .nh
 141 .SH "NAME"
 142 UI_METHOD, UI_create_method, UI_destroy_method, UI_method_set_opener, UI_method_set_writer, UI_method_set_flusher, UI_method_set_reader, UI_method_set_closer, UI_method_set_data_duplicator, UI_method_set_prompt_constructor, UI_method_set_ex_data, UI_method_get_opener, UI_method_get_writer, UI_method_get_flusher, UI_method_get_reader, UI_method_get_closer, UI_method_get_data_duplicator, UI_method_get_data_destructor, UI_method_get_prompt_constructor, UI_method_get_ex_data \- user interface method creation and destruction
 143 .SH "SYNOPSIS"
 144 .IX Header "SYNOPSIS"
 145 .Vb 1
 146 \& #include <openssl/ui.h>
 147 \&
 148 \& typedef struct ui_method_st UI_METHOD;
 149 \&
 150 \& UI_METHOD *UI_create_method(const char *name);
 151 \& void UI_destroy_method(UI_METHOD *ui_method);
 152 \& int UI_method_set_opener(UI_METHOD *method, int (*opener) (UI *ui));
 153 \& int UI_method_set_writer(UI_METHOD *method,
 154 \&                          int (*writer) (UI *ui, UI_STRING *uis));
 155 \& int UI_method_set_flusher(UI_METHOD *method, int (*flusher) (UI *ui));
 156 \& int UI_method_set_reader(UI_METHOD *method,
 157 \&                          int (*reader) (UI *ui, UI_STRING *uis));
 158 \& int UI_method_set_closer(UI_METHOD *method, int (*closer) (UI *ui));
 159 \& int UI_method_set_data_duplicator(UI_METHOD *method,
 160 \&                                   void *(*duplicator) (UI *ui, void *ui_data),
 161 \&                                   void (*destructor)(UI *ui, void *ui_data));
 162 \& int UI_method_set_prompt_constructor(UI_METHOD *method,
 163 \&                                      char *(*prompt_constructor) (UI *ui,
 164 \&                                                                   const char
 165 \&                                                                   *object_desc,
 166 \&                                                                   const char
 167 \&                                                                   *object_name));
 168 \& int UI_method_set_ex_data(UI_METHOD *method, int idx, void *data);
 169 \& int (*UI_method_get_opener(const UI_METHOD *method)) (UI *);
 170 \& int (*UI_method_get_writer(const UI_METHOD *method)) (UI *, UI_STRING *);
 171 \& int (*UI_method_get_flusher(const UI_METHOD *method)) (UI *);
 172 \& int (*UI_method_get_reader(const UI_METHOD *method)) (UI *, UI_STRING *);
 173 \& int (*UI_method_get_closer(const UI_METHOD *method)) (UI *);
 174 \& char *(*UI_method_get_prompt_constructor(const UI_METHOD *method))
 175 \&     (UI *, const char *, const char *);
 176 \& void *(*UI_method_get_data_duplicator(const UI_METHOD *method)) (UI *, void *);
 177 \& void (*UI_method_get_data_destructor(const UI_METHOD *method)) (UI *, void *);
 178 \& const void *UI_method_get_ex_data(const UI_METHOD *method, int idx);
 179 .Ve
 180 .SH "DESCRIPTION"
 181 .IX Header "DESCRIPTION"
 182 A method contains a few functions that implement the low-level of the
 183 User Interface.
 184 These functions are:
 185 .IP "an opener" 4
 186 .IX Item "an opener"
 187 This function takes a reference to a \s-1UI\s0 and starts a session, for
 188 example by opening a channel to a tty, or by creating a dialog box.
 189 .IP "a writer" 4
 190 .IX Item "a writer"
 191 This function takes a reference to a \s-1UI\s0 and a \s-1UI\s0 String, and writes
 192 the string where appropriate, maybe to the tty, maybe added as a field
 193 label in a dialog box.
 194 Note that this gets fed all strings associated with a \s-1UI,\s0 one after
 195 the other, so care must be taken which ones it actually uses.
 196 .IP "a flusher" 4
 197 .IX Item "a flusher"
 198 This function takes a reference to a \s-1UI,\s0 and flushes everything that
 199 has been output so far.
 200 For example, if the method builds up a dialog box, this can be used to
 201 actually display it and accepting input ended with a pressed button.
 202 .IP "a reader" 4
 203 .IX Item "a reader"
 204 This function takes a reference to a \s-1UI\s0 and a \s-1UI\s0 string and reads off
 205 the given prompt, maybe from the tty, maybe from a field in a dialog
 206 box.
 207 Note that this gets fed all strings associated with a \s-1UI,\s0 one after
 208 the other, so care must be taken which ones it actually uses.
 209 .IP "a closer" 4
 210 .IX Item "a closer"
 211 This function takes a reference to a \s-1UI,\s0 and closes the session, maybe
 212 by closing the channel to the tty, maybe by destroying a dialog box.
 213 .PP
 214 All of these functions are expected to return 0 on error, 1 on
 215 success, or \-1 on out-off-band events, for example if some prompting
 216 has been cancelled (by pressing Ctrl-C, for example).
 217 Only the flusher or the reader are expected to return \-1.
 218 If returned by another of the functions, it's treated as if 0 was
 219 returned.
 220 .PP
 221 Regarding the writer and the reader, don't assume the former should
 222 only write and don't assume the latter should only read.
 223 This depends on the needs of the method.
 224 .PP
 225 For example, a typical tty reader wouldn't write the prompts in the
 226 write, but would rather do so in the reader, because of the sequential
 227 nature of prompting on a tty.
 228 This is how the \fBUI_OpenSSL()\fR method does it.
 229 .PP
 230 In contrast, a method that builds up a dialog box would add all prompt
 231 text in the writer, have all input read in the flusher and store the
 232 results in some temporary buffer, and finally have the reader just
 233 fetch those results.
 234 .PP
 235 The central function that uses these method functions is \fBUI_process()\fR,
 236 and it does it in five steps:
 237 .IP "1." 4
 238 Open the session using the opener function if that one's defined.
 239 If an error occurs, jump to 5.
 240 .IP "2." 4
 241 For every \s-1UI\s0 String associated with the \s-1UI,\s0 call the writer function
 242 if that one's defined.
 243 If an error occurs, jump to 5.
 244 .IP "3." 4
 245 Flush everything using the flusher function if that one's defined.
 246 If an error occurs, jump to 5.
 247 .IP "4." 4
 248 For every \s-1UI\s0 String associated with the \s-1UI,\s0 call the reader function
 249 if that one's defined.
 250 If an error occurs, jump to 5.
 251 .IP "5." 4
 252 Close the session using the closer function if that one's defined.
 253 .PP
 254 \&\fBUI_create_method()\fR creates a new \s-1UI\s0 method with a given \fBname\fR.
 255 .PP
 256 \&\fBUI_destroy_method()\fR destroys the given \s-1UI\s0 method \fBui_method\fR.
 257 .PP
 258 \&\fBUI_method_set_opener()\fR, \fBUI_method_set_writer()\fR,
 259 \&\fBUI_method_set_flusher()\fR, \fBUI_method_set_reader()\fR and
 260 \&\fBUI_method_set_closer()\fR set the five main method function to the given
 261 function pointer.
 262 .PP
 263 \&\fBUI_method_set_data_duplicator()\fR sets the user data duplicator and destructor.
 264 See \fBUI_dup_user_data\fR\|(3).
 265 .PP
 266 \&\fBUI_method_set_prompt_constructor()\fR sets the prompt constructor.
 267 See \fBUI_construct_prompt\fR\|(3).
 268 .PP
 269 \&\fBUI_method_set_ex_data()\fR sets application specific data with a given
 270 \&\s-1EX_DATA\s0 index.
 271 See \fBCRYPTO_get_ex_new_index\fR\|(3) for general information on how to
 272 get that index.
 273 .PP
 274 \&\fBUI_method_get_opener()\fR, \fBUI_method_get_writer()\fR,
 275 \&\fBUI_method_get_flusher()\fR, \fBUI_method_get_reader()\fR,
 276 \&\fBUI_method_get_closer()\fR, \fBUI_method_get_data_duplicator()\fR,
 277 \&\fBUI_method_get_data_destructor()\fR and \fBUI_method_get_prompt_constructor()\fR
 278 return the different method functions.
 279 .PP
 280 \&\fBUI_method_get_ex_data()\fR returns the application data previously stored
 281 with \fBUI_method_set_ex_data()\fR.
 282 .SH "RETURN VALUES"
 283 .IX Header "RETURN VALUES"
 284 \&\fBUI_create_method()\fR returns a \s-1UI_METHOD\s0 pointer on success, \s-1NULL\s0 on
 285 error.
 286 .PP
 287 \&\fBUI_method_set_opener()\fR, \fBUI_method_set_writer()\fR,
 288 \&\fBUI_method_set_flusher()\fR, \fBUI_method_set_reader()\fR,
 289 \&\fBUI_method_set_closer()\fR, \fBUI_method_set_data_duplicator()\fR and
 290 \&\fBUI_method_set_prompt_constructor()\fR
 291 return 0 on success, \-1 if the given \fBmethod\fR is \s-1NULL.\s0
 292 .PP
 293 \&\fBUI_method_set_ex_data()\fR returns 1 on success and 0 on error (because
 294 \&\fBCRYPTO_set_ex_data()\fR does so).
 295 .PP
 296 \&\fBUI_method_get_opener()\fR, \fBUI_method_get_writer()\fR,
 297 \&\fBUI_method_get_flusher()\fR, \fBUI_method_get_reader()\fR,
 298 \&\fBUI_method_get_closer()\fR, \fBUI_method_get_data_duplicator()\fR,
 299 \&\fBUI_method_get_data_destructor()\fR and \fBUI_method_get_prompt_constructor()\fR
 300 return the requested function pointer if it's set in the method,
 301 otherwise \s-1NULL.\s0
 302 .PP
 303 \&\fBUI_method_get_ex_data()\fR returns a pointer to the application specific
 304 data associated with the method.
 305 .SH "SEE ALSO"
 306 .IX Header "SEE ALSO"
 307 \&\s-1\fBUI\s0\fR\|(3), \fBCRYPTO_get_ex_data\fR\|(3), \s-1\fBUI_STRING\s0\fR\|(3)
 308 .SH "HISTORY"
 309 .IX Header "HISTORY"
 310 The \fBUI_method_set_data_duplicator()\fR, \fBUI_method_get_data_duplicator()\fR
 311 and \fBUI_method_get_data_destructor()\fR functions were added in OpenSSL 1.1.1.
 312 .SH "COPYRIGHT"
 313 .IX Header "COPYRIGHT"
 314 Copyright 2001\-2020 The OpenSSL Project Authors. All Rights Reserved.
 315 .PP
 316 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 317 this file except in compliance with the License.  You can obtain a copy
 318 in the file \s-1LICENSE\s0 in the source distribution or at
 319 <https://www.openssl.org/source/license.html>.