Document UI_METHOD and UI_STRING, both useful for UI_METHOD creators

=pod

=head1 NAMES

UI_STRING, UI_string_types,

=head1 SYNOPSIS

 #include <openssl/ui.h>

 typedef struct ui_string_st UI_STRING;

 enum UI_string_types {

     UIT_NONE = 0,

     UIT_PROMPT,                 /* Prompt for a string */

     UIT_VERIFY,                 /* Prompt for a string and verify */

     UIT_BOOLEAN,                /* Prompt for a yes/no response */

     UIT_INFO,                   /* Send info to the user */

     UIT_ERROR                   /* Send an error message to the user */

 };

 enum UI_string_types UI_get_string_type(UI_STRING *uis);

 int UI_get_input_flags(UI_STRING *uis);

 const char *UI_get0_output_string(UI_STRING *uis);

 const char *UI_get0_action_string(UI_STRING *uis);

 const char *UI_get0_result_string(UI_STRING *uis);

 const char *UI_get0_test_string(UI_STRING *uis);

 int UI_get_result_minsize(UI_STRING *uis);

 int UI_get_result_maxsize(UI_STRING *uis);

 int UI_set_result(UI *ui, UI_STRING *uis, const char *result);

=head1 DESCRIPTION

The B<UI_STRING> gets created internally and added to a B<UI> whenever

one of the functions UI_add_input_string(), UI_dup_input_string(),

UI_add_verify_string(), UI_dup_verify_string(),

UI_add_input_boolean(), UI_dup_input_boolean(), UI_add_info_string(),

UI_dup_info_string(), UI_add_error_string() or UI_dup_error_string()

is called.

For a B<UI_METHOD> user, there's no need to know more.

For a B<UI_METHOD> creator, it is of interest to fetch text from these

B<UI_STRING> objects as well as adding results to some of them.

UI_get_string_type() is used to retrieve the type of the given

B<UI_STRING>.

UI_get_input_flags() is used to retrieve the flags associated with the

given B<UI_STRING>.

UI_get0_output_string() is used to retrieve the actual string to

output (prompt, info, error, ...).

UI_get0_action_string() is used to retrieve the action description

associated with a B<UIT_BOOLEAN> type B<UI_STRING>.

For all other B<UI_STRING> types, NULL is returned.

See L<UI_Add_input_boolean(3)>.

UI_get0_result_string() is used to retrieve the result of a prompt.

This is only useful for B<UIT_PROMPT> and B<UIT_VERIFY> type strings.

For all other B<UI_STRING> types, NULL is returned.

UI_get0_test_string() is used to retrieve the string to compare the

prompt result with.

This is only useful for B<UIT_VERIFY> type strings.

For all other B<UI_STRING> types, NULL is returned.

UI_get_result_minsize() and UI_get_result_maxsize() are used to

retrieve the minimum and maximum required size of the result.

This is only useful for B<UIT_PROMPT> and B<UIT_VERIFY> type strings.

For all other B<UI_STRING> types, -1 is returned.

UI_set_result() is used to set the result value of a prompt.

For B<UIT_PROMPT> and B<UIT_VERIFY> type UI strings, this sets the

result retrievable with UI_get0_result_string() by copying the

contents of B<result> if its length fits the minimum and maximum size

requirements.

For B<UIT_BOOLEAN> type UI strings, this sets the first character of

the result retrievable with UI_get0_result_string() to the first

B<ok_char> given with UI_add_input_boolean() or UI_dup_input_boolean()

if the B<result> matched any of them, or the first of the

B<cancel_chars> if the B<result> matched any of them, otherwise it's

set to the NUL char C<\0>.

See L<UI_add_input_boolean(3)> for more information on B<ok_chars> and

B<cancel_chars>.

=head1 RETURN VALUES

UI_get_string_type() returns the UI string type.

UI_get_input_flags() returns the UI string flags.

UI_get0_output_string() returns the UI string output string.

UI_get0_action_string() returns the UI string action description

string for B<UIT_BOOLEAN> type UI strings, NULL for any other type.

UI_get0_result_string() returns the UI string action description

string for B<UIT_PROMPT> and B<UIT_VERIFY> type UI strings, NULL for

any other type.

UI_get0_test_string() returns the UI string action description

string for B<UIT_VERIFY> type UI strings, NULL for any other type.

UI_get_result_minsize() returns the minimum allowed result size for

the UI string for  for B<UIT_PROMPT> and B<UIT_VERIFY> type strings,

-1 for any other type.

UI_get_result_maxsize() returns the minimum allowed result size for

the UI string for  for B<UIT_PROMPT> and B<UIT_VERIFY> type strings,

-1 for any other type.

UI_set_result() returns 0 on success or when the UI string is of any

type other than B<UIT_PROMPT>, B<UIT_VERIFY> or B<UIT_BOOLEAN>, -1 on

error.

=head1 SEE ALSO

L<UI(3)>

=head1 COPYRIGHT

Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the OpenSSL license (the "License").  You may not use

this file except in compliance with the License.  You can obtain a copy

in the file LICENSE in the source distribution or at

L<https://www.openssl.org/source/license.html>.

=cut

=pod

=head1 NAME

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_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_prompt_constructor, UI_method_get_ex_data - user

interface method creation and destruction

=head1 SYNOPSIS

 #include <openssl/ui.h>

 typedef struct ui_method_st UI_METHOD;

 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_set_ex_data(UI_METHOD *method, int idx, void *data);

 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(const UI_METHOD *method))

     (UI *, const char *, const char *);

 const void *UI_method_get_ex_data(const UI_METHOD *method, int idx);

=head1 DESCRIPTION

A method contains a few functions that implement the low level of the

User Interface.

These functions are:

=over 4

=item 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.

=item 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.

=item 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.

=item 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.

=item 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.

=back

All of these functions are expected to return one of these values:

=over 4

=item 0

on error.

=item 1

on success.

=item -1

on out-off-band events, for example if some prompting has been

cancelled (by pressing Ctrl-C, for example).

This is only expected to be returned by the flusher or the reader.

If returned by another of the functions, it's treated as if 0 was

returned.

=back

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() 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(),

and it does it in five steps:

=over 4

=item 1.

Open the session using the opener function if that one's defined.

If an error occurs, jump to 5.

=item 2.

For every UI String associated with the UI, call the writer function

if that one's defined.

If an error occurs, jump to 5.

=item 3.

Flush everything using the flusher function if that one's defined.

If an error occurs, jump to 5.

=item 4.

For every UI String associated with the UI, call the reader function

if that one's defined.

If an error occurs, jump to 5.

=item 5.

Close the session using the closer function if that one's defined.

=back

UI_create_method() creates a new UI method with a given B<name>.

UI_destroy_method() destroys the given UI method B<ui_method>.

UI_method_set_opener(), UI_method_set_writer(),

UI_method_set_flusher(), UI_method_set_reader() and

UI_method_set_closer() set the five main method function to the given

function pointer.

UI_method_set_prompt_constructor() sets the prompt constructor.

See L<UI_construct_prompt(3)>.

UI_method_set_ex_data() sets application specific data with a given

EX_DATA index.

See L<CRYPTO_get_ex_new_index(3)> for general information on how to

get that index.

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 different method functions.

UI_method_get_ex_data() returns the application data previously stored

with UI_method_set_ex_data().

=head1 RETURN VALUES

UI_create_method() returns a UI_METHOD pointer on success, 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, -1 if the given B<method> is NULL.

UI_method_set_ex_data() returns 1 on success and 0 on error (because

CRYPTO_set_ex_data() does so).

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's set in the method, otherwise

NULL.

UI_method_get_ex_data() returns a pointer to the application specific

data associated with the method.

=head1 SEE ALSO

L<UI(3)>, L<CRYPTO_get_ex_data(3)>, L<UI_STRING(3)>

=head1 COPYRIGHT

Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the OpenSSL license (the "License").  You may not use

this file except in compliance with the License.  You can obtain a copy

in the file LICENSE in the source distribution or at

L<https://www.openssl.org/source/license.html>.

=cut

=head1 NAME

UI, UI_METHOD,

UI,

UI_new, UI_new_method, UI_free, UI_add_input_string, UI_dup_input_string,

UI_add_verify_string, UI_dup_verify_string, UI_add_input_boolean,

UI_dup_input_boolean, UI_add_info_string, UI_dup_info_string,

 #include <openssl/ui.h>

 typedef struct ui_st UI;

 typedef struct ui_method_st UI_METHOD;

 UI *UI_new(void);

 UI *UI_new_method(const UI_METHOD *method);

UI stands for User Interface, and is general purpose set of routines to

prompt the user for text-based information.  Through user-written methods

(see L<ui_create(3)>), prompting can be done in any way

(see L<UI_create_method(3)>), prompting can be done in any way

imaginable, be it plain text prompting, through dialog boxes or from a

cell phone.

the information indexed by I<i>.

UI_process() goes through the information given so far, does all the printing

and prompting and returns.

and prompting and returns the final status, which is -2 on out-of-band events

(Interrupt, Cancel, ...), -1 on error and 0 on success.

UI_ctrl() adds extra control for the application author.  For now, it

understands two commands: B<UI_CTRL_PRINT_ERRORS>, which makes UI_process()

UI_set_method() changes the UI method associated with a given UI.

UI_OpenSSL() is the default OpenSSL UI method for prompting

passphrases on the command line.

=head1 COPYRIGHT

Copyright 2001-2016 The OpenSSL Project Authors. All Rights Reserved.