path: root/lib/libcrypto/man/UI_create_method.3

.\"	$OpenBSD: UI_create_method.3,v 1.5 2018/05/19 23:06:33 schwarze Exp $
.\"	OpenSSL UI_create_method.pod 8e3d46e5 Mar 11 10:51:04 2017 +0100
.\"
.\" This file was written by Richard Levitte <levitte@openssl.org>.
.\" Copyright (c) 2017 The OpenSSL Project.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\"
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\"
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in
.\"    the documentation and/or other materials provided with the
.\"    distribution.
.\"
.\" 3. All advertising materials mentioning features or use of this
.\"    software must display the following acknowledgment:
.\"    "This product includes software developed by the OpenSSL Project
.\"    for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
.\"
.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
.\"    endorse or promote products derived from this software without
.\"    prior written permission. For written permission, please contact
.\"    openssl-core@openssl.org.
.\"
.\" 5. Products derived from this software may not be called "OpenSSL"
.\"    nor may "OpenSSL" appear in their names without prior written
.\"    permission of the OpenSSL Project.
.\"
.\" 6. Redistributions of any form whatsoever must retain the following
.\"    acknowledgment:
.\"    "This product includes software developed by the OpenSSL Project
.\"    for use in the OpenSSL Toolkit (http://www.openssl.org/)"
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OpenSSL PROJECT OR
.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
.\" OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd $Mdocdate: May 19 2018 $
.Dt UI_CREATE_METHOD 3
.Os
.Sh NAME
.Nm UI_create_method ,
.Nm UI_destroy_method ,
.Nm UI_method_set_opener ,
.Nm UI_method_set_writer ,
.Nm UI_method_set_flusher ,
.Nm UI_method_set_reader ,
.Nm UI_method_set_closer ,
.Nm UI_method_set_prompt_constructor ,
.Nm UI_method_get_opener ,
.Nm UI_method_get_writer ,
.Nm UI_method_get_flusher ,
.Nm UI_method_get_reader ,
.Nm UI_method_get_closer ,
.Nm UI_method_get_prompt_constructor
.Nd user interface method creation and destruction
.Sh SYNOPSIS
.In openssl/ui.h
.Ft UI_METHOD *
.Fo UI_create_method
.Fa "const char *name"
.Fc
.Ft void
.Fo UI_destroy_method
.Fa "UI_METHOD *ui_method"
.Fc
.Ft int
.Fo UI_method_set_opener
.Fa "UI_METHOD *method"
.Fa "int (*opener)(UI *ui)"
.Fc
.Ft int
.Fo UI_method_set_writer
.Fa "UI_METHOD *method"
.Fa "int (*writer)(UI *ui, UI_STRING *uis)"
.Fc
.Ft int
.Fo UI_method_set_flusher
.Fa "UI_METHOD *method"
.Fa "int (*flusher)(UI *ui)"
.Fc
.Ft int
.Fo UI_method_set_reader
.Fa "UI_METHOD *method"
.Fa "int (*reader)(UI *ui, UI_STRING *uis)"
.Fc
.Ft int
.Fo UI_method_set_closer
.Fa "UI_METHOD *method"
.Fa "int (*closer)(UI *ui)"
.Fc
.Ft int
.Fo UI_method_set_prompt_constructor
.Fa "UI_METHOD *method"
.Fa "char *(*prompt_constructor)(UI *ui, const char *object_desc,\
 const char *object_name)"
.Fc
.Ft int
.Fo "(*UI_method_get_opener(const UI_METHOD *method))"
.Fa "UI *";
.Fc
.Ft int
.Fo "(*UI_method_get_writer(const UI_METHOD *method))"
.Fa "UI *"
.Fa "UI_STRING *"
.Fc
.Ft int
.Fo "(*UI_method_get_flusher(const UI_METHOD *method))"
.Fa "UI *"
.Fc
.Ft int
.Fo "(*UI_method_get_reader(const UI_METHOD *method))"
.Fa "UI *"
.Fa "UI_STRING *"
.Fc
.Ft int
.Fo "(*UI_method_get_closer(const UI_METHOD *method))"
.Fa "UI *"
.Fc
.Ft char *
.Fo "(*UI_method_get_prompt_constructor(UI_METHOD *method))"
.Fa "UI *"
.Fa "const char *"
.Fa "const char *"
.Fc
.Sh DESCRIPTION
A method contains a few functions that implement the low level of the
User Interface.
These functions are:
.Bl -tag -width Ds
.It an opener
This function takes a reference to a UI and starts a session, for
example by opening a channel to a tty, or by creating a dialog box.
.It a writer
This function takes a reference to a UI and a UI String, and writes the
string where appropriate, maybe to the tty, maybe added as a field label
in a dialog box.
Note that this gets fed all strings associated with a UI, one after the
other, so care must be taken which ones it actually uses.
.It a flusher
This function takes a reference to a UI, and flushes everything that has
been output so far.
For example, if the method builds up a dialog box, this can be used to
actually display it and accepting input ended with a pressed button.
.It a reader
This function takes a reference to a UI and a UI string and reads off
the given prompt, maybe from the tty, maybe from a field in a dialog
box.
Note that this gets fed all strings associated with a UI, one after the
other, so care must be taken which ones it actually uses.
.It a closer
This function takes a reference to a UI, and closes the session, maybe
by closing the channel to the tty, maybe by destroying a dialog box.
.El
.Pp
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.
.Pp
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.
.Pp
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
.Xr UI_OpenSSL 3
method does it.
.Pp
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.
.Pp
The central function that uses these method functions is
.Xr UI_process 3 ,
and it does it in five steps:
.Bl -enum
.It
Open the session using the opener function if that one is defined.
If an error occurs, jump to 5.
.It
For every UI String associated with the UI, call the writer function if
that one is defined.
If an error occurs, jump to 5.
.It
Flush everything using the flusher function if that one is defined.
If an error occurs, jump to 5.
.It
For every UI String associated with the UI, call the reader function if
that one is defined.
If an error occurs, jump to 5.
.It
Close the session using the closer function if that one is defined.
.El
.Pp
.Fn UI_create_method
creates a new UI method with a given
.Fa name .
.Pp
.Fn UI_destroy_method
destroys the given
.Fa ui_method .
.Pp
.Fn UI_method_set_opener ,
.Fn UI_method_set_writer ,
.Fn UI_method_set_flusher ,
.Fn UI_method_set_reader
and
.Fn UI_method_set_closer
set one of the five main methods to the given function pointer.
.Pp
.Fn UI_method_set_prompt_constructor
sets the prompt constructor, see
.Xr UI_construct_prompt 3 .
.Sh RETURN VALUES
.Fn UI_create_method
returns a
.Vt UI_METHOD
pointer on success or
.Dv NULL
on error.
.Pp
.Fn UI_method_set_opener ,
.Fn UI_method_set_writer ,
.Fn UI_method_set_flusher ,
.Fn UI_method_set_reader ,
.Fn UI_method_set_closer ,
and
.Fn UI_method_set_prompt_constructor
return 0 on success or -1 if the given method is
.Dv NULL .
.Pp
.Fn UI_method_get_opener ,
.Fn UI_method_get_writer ,
.Fn UI_method_get_flusher ,
.Fn UI_method_get_reader ,
.Fn UI_method_get_closer ,
and
.Fn UI_method_get_prompt_constructor
return the requested function pointer if it is set in the method,
or otherwise
.Dv NULL .
.Sh SEE ALSO
.Xr UI_get_string_type 3 ,
.Xr UI_new 3
.Sh HISTORY
.Fn UI_create_method ,
.Fn UI_destroy_method ,
.Fn UI_method_set_opener ,
.Fn UI_method_set_writer ,
.Fn UI_method_set_flusher ,
.Fn UI_method_set_reader ,
.Fn UI_method_set_closer ,
.Fn UI_method_get_opener ,
.Fn UI_method_get_writer ,
.Fn UI_method_get_flusher ,
.Fn UI_method_get_reader ,
and
.Fn UI_method_get_closer
first appeared in OpenSSL 0.9.7 and have been available since
.Ox 3.2 .
.Pp
.Fn UI_method_set_prompt_constructor
and
.Fn UI_method_get_prompt_constructor
first appeared in OpenSSL 1.0.0 and have been available since
.Ox 4.9 .