284 lines
8.8 KiB
Groff
284 lines
8.8 KiB
Groff
.\" $OpenBSD: UI_create_method.3,v 1.6 2023/05/22 19:38:04 tb 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 22 2023 $
|
|
.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 .
|