From 5469600e367a1a4cf3dd929159b5bc8091db49de Mon Sep 17 00:00:00 2001 From: Richard Levitte Date: Sat, 11 Mar 2017 00:51:53 +0100 Subject: [PATCH] Document UI_METHOD and UI_STRING, both useful for UI_METHOD creators Reviewed-by: Tim Hudson (Merged from https://github.com/openssl/openssl/pull/2903) --- doc/man3/UI_STRING.pod | 130 ++++++++++++++++++++ doc/man3/UI_create_method.pod | 217 ++++++++++++++++++++++++++++++++++ doc/man3/UI_new.pod | 8 +- 3 files changed, 351 insertions(+), 4 deletions(-) create mode 100644 doc/man3/UI_STRING.pod create mode 100644 doc/man3/UI_create_method.pod diff --git a/doc/man3/UI_STRING.pod b/doc/man3/UI_STRING.pod new file mode 100644 index 0000000000..b0f937144c --- /dev/null +++ b/doc/man3/UI_STRING.pod @@ -0,0 +1,130 @@ +=pod + +=head1 NAMES + +UI_STRING, UI_string_types, + +=head1 SYNOPSIS + + #include + + 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 gets created internally and added to a B 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 user, there's no need to know more. +For a B creator, it is of interest to fetch text from these +B 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_get_input_flags() is used to retrieve the flags associated with the +given B. + +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 type B. +For all other B types, NULL is returned. +See L. + +UI_get0_result_string() is used to retrieve the result of a prompt. +This is only useful for B and B type strings. +For all other B 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 type strings. +For all other B 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 and B type strings. +For all other B types, -1 is returned. + +UI_set_result() is used to set the result value of a prompt. +For B and B type UI strings, this sets the +result retrievable with UI_get0_result_string() by copying the +contents of B if its length fits the minimum and maximum size +requirements. +For B type UI strings, this sets the first character of +the result retrievable with UI_get0_result_string() to the first +B given with UI_add_input_boolean() or UI_dup_input_boolean() +if the B matched any of them, or the first of the +B if the B matched any of them, otherwise it's +set to the NUL char C<\0>. +See L for more information on B and +B. + +=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 type UI strings, NULL for any other type. + +UI_get0_result_string() returns the UI string action description +string for B and B type UI strings, NULL for +any other type. + +UI_get0_test_string() returns the UI string action description +string for B 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 and B type strings, +-1 for any other type. + +UI_get_result_maxsize() returns the minimum allowed result size for +the UI string for for B and B 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, B or B, -1 on +error. + +=head1 SEE ALSO + +L + +=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. + +=cut + diff --git a/doc/man3/UI_create_method.pod b/doc/man3/UI_create_method.pod new file mode 100644 index 0000000000..c1d3088296 --- /dev/null +++ b/doc/man3/UI_create_method.pod @@ -0,0 +1,217 @@ +=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 + + 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. + +UI_destroy_method() destroys the given UI method B. + +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_method_set_ex_data() sets application specific data with a given +EX_DATA index. +See L 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 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, L, L + +=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. + +=cut diff --git a/doc/man3/UI_new.pod b/doc/man3/UI_new.pod index 08400d3492..8d4ae659a6 100644 --- a/doc/man3/UI_new.pod +++ b/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 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), prompting can be done in any way +(see L), 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. 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, which makes UI_process() -- 2.25.1