提交 5469600e 编写于 作者: R Richard Levitte

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)
上级 d61461a7
=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
......@@ -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()
......
Markdown is supported
0% .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑!
想要评论请 注册