Document UI_METHOD and UI_STRING, both useful for UI_METHOD creators

Reviewed-by: NTim Hudson <tjh@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/2903)

doc/man3/UI_STRING.pod

+=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
+

doc/man3/UI_create_method.pod

+=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

doc/man3/UI_new.pod

@@ -2,7 +2,7 @@
 
 =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,
@@ -16,7 +16,6 @@ UI_set_method, UI_OpenSSL, UI_null - user interface
  #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);
@@ -65,7 +64,7 @@ UI_set_method, UI_OpenSSL, UI_null - user interface
 
 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.
 
@@ -159,7 +158,8 @@ UI_get0_result() returns a pointer to the result buffer associated with
 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()