huschi.net

UI_STRING(3)                        OpenSSL                       UI_STRING(3)
NAME
       UI_STRING, UI_string_types, UI_get_string_type, UI_get_input_flags,
       UI_get0_output_string, UI_get0_action_string, UI_get0_result_string,
       UI_get_result_string_length, UI_get0_test_string,
       UI_get_result_minsize, UI_get_result_maxsize, UI_set_result,
       UI_set_result_ex - User interface string parsing
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);
        int UI_get_result_string_length(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);
        int UI_set_result_ex(UI *ui, UI_STRING *uis, const char *result, int len);
DESCRIPTION
       The UI_STRING gets created internally and added to a 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
       UI_METHOD user, there's no need to know more.  For a UI_METHOD creator,
       it is of interest to fetch text from these 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
       UI_STRING.
       UI_get_input_flags() is used to retrieve the flags associated with the
       given 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 UIT_BOOLEAN type UI_STRING.  For all other UI_STRING
       types, NULL is returned.  See UI_add_input_boolean(3).
       UI_get0_result_string() and UI_get_result_string_length() are used to
       retrieve the result of a prompt and its length.  This is only useful
       for UIT_PROMPT and UIT_VERIFY type strings.  For all other UI_STRING
       types, UI_get0_result_string() returns NULL and
       UI_get_result_string_length() returns -1.
       UI_get0_test_string() is used to retrieve the string to compare the
       prompt result with.  This is only useful for UIT_VERIFY type strings.
       For all other 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 UIT_PROMPT and UIT_VERIFY type strings.  For all other
       UI_STRING types, -1 is returned.
       UI_set_result_ex() is used to set the result value of a prompt and its
       length.  For UIT_PROMPT and UIT_VERIFY type UI strings, this sets the
       result retrievable with UI_get0_result_string() by copying the contents
       of result if its length fits the minimum and maximum size requirements.
       For UIT_BOOLEAN type UI strings, this sets the first character of the
       result retrievable with UI_get0_result_string() to the first ok_char
       given with UI_add_input_boolean() or UI_dup_input_boolean() if the
       result matched any of them, or the first of the cancel_chars if the
       result matched any of them, otherwise it's set to the NUL char "\0".
       See UI_add_input_boolean(3) for more information on ok_chars and
       cancel_chars.
       UI_set_result() does the same thing as UI_set_result_ex(), but
       calculates its length internally.  It expects the string to be
       terminated with a NUL byte, and is therefore only useful with normal C
       strings.
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 UIT_BOOLEAN type UI strings, NULL for any other type.
       UI_get0_result_string() returns the UI string result buffer for
       UIT_PROMPT and UIT_VERIFY type UI strings, NULL for any other type.
       UI_get_result_string_length() returns the UI string result buffer's
       content length for UIT_PROMPT and UIT_VERIFY type UI strings, -1 for
       any other type.
       UI_get0_test_string() returns the UI string action description string
       for 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 UIT_PROMPT and UIT_VERIFY type strings, -1 for any other
       type.
       UI_get_result_maxsize() returns the minimum allowed result size for the
       UI string for UIT_PROMPT and 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 UIT_PROMPT, UIT_VERIFY or UIT_BOOLEAN, -1 on error.
SEE ALSO
       UI(3)
COPYRIGHT
       Copyright 2001-2018 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
       <https://www.openssl.org/source/license.html>;.
1.1.1k                            2021-03-25                      UI_STRING(3)