UI_CREATE_METHOD(3) | Library Functions Manual | UI_CREATE_METHOD(3) |
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_prompt_constructor
,
UI_method_get_opener
,
UI_method_get_writer
,
UI_method_get_flusher
,
UI_method_get_reader
,
UI_method_get_closer
,
UI_method_get_prompt_constructor
—
user interface method creation and destruction
#include
<openssl/ui.h>
UI_METHOD *
UI_create_method
(const char
*name);
void
UI_destroy_method
(UI_METHOD
*ui_method);
int
UI_method_set_opener
(UI_METHOD
*method, int (*opener)(UI *ui));
int
UI_method_set_writer
(UI_METHOD
*method, int (*writer)(UI *ui, UI_STRING
*uis));
int
UI_method_set_flusher
(UI_METHOD
*method, int (*flusher)(UI *ui));
int
UI_method_set_reader
(UI_METHOD
*method, int (*reader)(UI *ui, UI_STRING
*uis));
int
UI_method_set_closer
(UI_METHOD
*method, int (*closer)(UI *ui));
int
UI_method_set_prompt_constructor
(UI_METHOD
*method, char *(*prompt_constructor)(UI *ui, const
char *object_desc, const char *object_name));
int
(*UI_method_get_opener(const UI_METHOD
*method))
(UI *;);
int
(*UI_method_get_writer(const UI_METHOD
*method))
(UI *, UI_STRING
*);
int
(*UI_method_get_flusher(const UI_METHOD
*method))
(UI *);
int
(*UI_method_get_reader(const UI_METHOD
*method))
(UI *, UI_STRING
*);
int
(*UI_method_get_closer(const UI_METHOD
*method))
(UI *);
char *
(*UI_method_get_prompt_constructor(UI_METHOD
*method))
(UI *, const char
*, const char *);
A method contains a few functions that implement the low level of the User Interface. These functions are:
All of these functions are expected to return 0 on error, 1 on success, or -1 on out-off-band events, for example if some prompting has been cancelled (by pressing Ctrl-C, for example). Only the flusher or the reader are expected to return -1. If returned by another of the functions, it's treated as if 0 was returned.
Regarding the writer and the reader, don't assume the former should only write and don't assume the latter should only read. This depends on the needs of the method.
For example, a typical tty reader wouldn't write the prompts in the write, but would rather do so in the reader, because of the sequential nature of prompting on a tty. This is how the UI_OpenSSL(3) method does it.
In contrast, a method that builds up a dialog box would add all prompt text in the writer, have all input read in the flusher and store the results in some temporary buffer, and finally have the reader just fetch those results.
The central function that uses these method functions is UI_process(3), and it does it in five steps:
UI_create_method
()
creates a new UI method with a given name.
UI_destroy_method
()
destroys the given ui_method.
UI_method_set_opener
(),
UI_method_set_writer
(),
UI_method_set_flusher
(),
UI_method_set_reader
()
and
UI_method_set_closer
()
set one of the five main methods to the given function pointer.
UI_method_set_prompt_constructor
()
sets the prompt constructor, see
UI_construct_prompt(3).
UI_create_method
() returns a
UI_METHOD pointer on success or
NULL
on error.
UI_method_set_opener
(),
UI_method_set_writer
(),
UI_method_set_flusher
(),
UI_method_set_reader
(),
UI_method_set_closer
(), and
UI_method_set_prompt_constructor
() return 0 on
success or -1 if the given method is NULL
.
UI_method_get_opener
(),
UI_method_get_writer
(),
UI_method_get_flusher
(),
UI_method_get_reader
(),
UI_method_get_closer
(), and
UI_method_get_prompt_constructor
() return the
requested function pointer if it is set in the method, or otherwise
NULL
.
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_get_opener
(),
UI_method_get_writer
(),
UI_method_get_flusher
(),
UI_method_get_reader
(), and
UI_method_get_closer
() first appeared in OpenSSL
0.9.7 and have been available since OpenBSD 3.2.
UI_method_set_prompt_constructor
() and
UI_method_get_prompt_constructor
() first appeared in
OpenSSL 1.0.0 and have been available since OpenBSD
4.9.
May 19, 2018 | OpenBSD-current |