.\" $OpenBSD: UI_get_string_type.3,v 1.4 2018/03/22 21:08:22 schwarze Exp $ .\" OpenSSL UI_STRING.pod e9c9971b Jul 1 18:28:50 2017 +0200 .\" .\" This file was written by Richard Levitte .\" Copyright (c) 2017 The OpenSSL Project. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in .\" the documentation and/or other materials provided with the .\" distribution. .\" .\" 3. All advertising materials mentioning features or use of this .\" software must display the following acknowledgment: .\" "This product includes software developed by the OpenSSL Project .\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" .\" .\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to .\" endorse or promote products derived from this software without .\" prior written permission. For written permission, please contact .\" openssl-core@openssl.org. .\" .\" 5. Products derived from this software may not be called "OpenSSL" .\" nor may "OpenSSL" appear in their names without prior written .\" permission of the OpenSSL Project. .\" .\" 6. Redistributions of any form whatsoever must retain the following .\" acknowledgment: .\" "This product includes software developed by the OpenSSL Project .\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" .\" .\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY .\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR .\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" .Dd $Mdocdate: March 22 2018 $ .Dt UI_GET_STRING_TYPE 3 .Os .Sh NAME .Nm UI_get_string_type , .Nm UI_get_input_flags , .Nm UI_get0_output_string , .Nm UI_get0_action_string , .Nm UI_get0_result_string , .Nm UI_get0_test_string , .Nm UI_get_result_minsize , .Nm UI_get_result_maxsize , .Nm UI_set_result .Nd OpenSSL user interface string parsing .Sh SYNOPSIS .In openssl/ui.h .Bd -literal 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 */ }; .Ed .Pp .Ft enum UI_string_types .Fo UI_get_string_type .Fa "UI_STRING *uis" .Fc .Ft int .Fo UI_get_input_flags .Fa "UI_STRING *uis" .Fc .Ft const char * .Fo UI_get0_output_string .Fa "UI_STRING *uis" .Fc .Ft const char * .Fo UI_get0_action_string .Fa "UI_STRING *uis" .Fc .Ft const char * .Fo UI_get0_result_string .Fa "UI_STRING *uis" .Fc .Ft const char * .Fo UI_get0_test_string .Fa "UI_STRING *uis" .Fc .Ft int .Fo UI_get_result_minsize .Fa "UI_STRING *uis" .Fc .Ft int .Fo UI_get_result_maxsize .Fa "UI_STRING *uis" .Fc .Ft int .Fo UI_set_result .Fa "UI *ui" .Fa "UI_STRING *uis" .Fa "const char *result" .Fc .Sh DESCRIPTION A .Vt UI_STRING gets created internally and added to a .Vt UI object whenever one of the functions .Xr UI_add_input_string 3 , .Xr UI_dup_input_string 3 , .Xr UI_add_verify_string 3 , .Xr UI_dup_verify_string 3 , .Xr UI_add_input_boolean 3 , .Xr UI_dup_input_boolean 3 , .Xr UI_add_info_string 3 , .Xr UI_dup_info_string 3 , .Xr UI_add_error_string 3 or .Xr UI_dup_error_string 3 is called. For a .Vt UI_METHOD user, there's no need to know more. For a .Vt UI_METHOD creator, it is of interest to fetch text from these .Vt UI_STRING objects as well as adding results to some of them. .Pp .Fn UI_get_string_type is used to retrieve the type of the given .Vt UI_STRING . .Pp .Fn UI_get_input_flags is used to retrieve the flags associated with the given .Vt UI_STRING . .Pp .Fn UI_get0_output_string is used to retrieve the actual string to output (prompt, info, error, ...). .Pp .Fn UI_get0_action_string is used to retrieve the action description associated with a .Dv UIT_BOOLEAN type .Vt UI_STRING . See .Xr UI_add_input_boolean 3 . .Pp .Fn UI_get0_result_string is used to retrieve the result of a prompt. This is only useful for .Dv UIT_PROMPT and .Dv UIT_VERIFY type strings. .Pp .Fn UI_get0_test_string is used to retrieve the string to compare the prompt result with. This is only useful for .Dv UIT_VERIFY type strings. .Pp .Fn UI_get_result_minsize and .Fn UI_get_result_maxsize are used to retrieve the minimum and maximum required size of the result. This is only useful for .Dv UIT_PROMPT and .Dv UIT_VERIFY type strings. .Pp .Fn UI_set_result is used to set the result value of a prompt. For .Sy UIT_PROMPT and .Sy UIT_VERIFY type UI strings, this sets the result retrievable with .Fn UI_get0_result_string by copying the contents of .Fa result if its length fits the minimum and maximum size requirements. For .Dv UIT_BOOLEAN type UI strings, this sets the first character of the result retrievable with .Fn UI_get0_result_string to the first of the .Fa ok_chars given with .Xr UI_add_input_boolean 3 or .Xr UI_dup_input_boolean 3 if the .Fa result matched any of them, or the first of the .Fa cancel_chars if the .Fa result matched any of them, otherwise it's set to the NUL char. See .Xr UI_add_input_boolean 3 for more information on .Fa ok_chars and .Fa cancel_chars . .Sh RETURN VALUES .Fn UI_get_string_type returns the UI string type. .Pp .Fn UI_get_input_flags returns the UI string flags. .Pp .Fn UI_get0_output_string returns the UI string output string. .Pp .Fn UI_get0_action_string returns the UI string action description string for .Dv UIT_BOOLEAN type UI strings, or .Dv NULL for any other type. .Pp .Fn UI_get0_result_string returns the UI string result buffer for .Dv UIT_PROMPT and .Dv UIT_VERIFY type UI strings, or .Dv NULL for any other type. .Pp .Fn UI_get0_test_string returns the UI string action description string for .Dv UIT_VERIFY type UI strings, or .Dv NULL for any other type. .Pp .Fn UI_get_result_minsize returns the minimum allowed result size for the UI string for .Dv UIT_PROMPT and .Dv UIT_VERIFY type strings, or -1 for any other type. .Pp .Fn UI_get_result_maxsize returns the minimum allowed result size for the UI string for .Dv UIT_PROMPT and .Dv UIT_VERIFY type strings, or -1 for any other type. .Pp .Fn UI_set_result returns 0 on success or when the UI string is of any type other than .Dv UIT_PROMPT , .Dv UIT_VERIFY , or .Dv UIT_BOOLEAN , or -1 on error. .Sh SEE ALSO .Xr UI_new 3 .Sh HISTORY These functions first appeared in OpenSSL 0.9.7 and have been available since .Ox 3.2 .