1.\" $OpenBSD: UI_get_string_type.3,v 1.4 2018/03/22 21:08:22 schwarze Exp $ 2.\" OpenSSL UI_STRING.pod e9c9971b Jul 1 18:28:50 2017 +0200 3.\" 4.\" This file was written by Richard Levitte <levitte@openssl.org> 5.\" Copyright (c) 2017 The OpenSSL Project. All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 11.\" 1. Redistributions of source code must retain the above copyright 12.\" notice, this list of conditions and the following disclaimer. 13.\" 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in 16.\" the documentation and/or other materials provided with the 17.\" distribution. 18.\" 19.\" 3. All advertising materials mentioning features or use of this 20.\" software must display the following acknowledgment: 21.\" "This product includes software developed by the OpenSSL Project 22.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 23.\" 24.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 25.\" endorse or promote products derived from this software without 26.\" prior written permission. For written permission, please contact 27.\" openssl-core@openssl.org. 28.\" 29.\" 5. Products derived from this software may not be called "OpenSSL" 30.\" nor may "OpenSSL" appear in their names without prior written 31.\" permission of the OpenSSL Project. 32.\" 33.\" 6. Redistributions of any form whatsoever must retain the following 34.\" acknowledgment: 35.\" "This product includes software developed by the OpenSSL Project 36.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 37.\" 38.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 39.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 40.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 41.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 42.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 43.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 44.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 45.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 46.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 47.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 48.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 49.\" OF THE POSSIBILITY OF SUCH DAMAGE. 50.\" 51.Dd $Mdocdate: March 22 2018 $ 52.Dt UI_GET_STRING_TYPE 3 53.Os 54.Sh NAME 55.Nm UI_get_string_type , 56.Nm UI_get_input_flags , 57.Nm UI_get0_output_string , 58.Nm UI_get0_action_string , 59.Nm UI_get0_result_string , 60.Nm UI_get0_test_string , 61.Nm UI_get_result_minsize , 62.Nm UI_get_result_maxsize , 63.Nm UI_set_result 64.Nd OpenSSL user interface string parsing 65.Sh SYNOPSIS 66.In openssl/ui.h 67.Bd -literal 68enum UI_string_types { 69 UIT_NONE = 0, 70 UIT_PROMPT, /* Prompt for a string */ 71 UIT_VERIFY, /* Prompt for a string and verify */ 72 UIT_BOOLEAN, /* Prompt for a yes/no response */ 73 UIT_INFO, /* Send info to the user */ 74 UIT_ERROR /* Send an error message to the user */ 75}; 76.Ed 77.Pp 78.Ft enum UI_string_types 79.Fo UI_get_string_type 80.Fa "UI_STRING *uis" 81.Fc 82.Ft int 83.Fo UI_get_input_flags 84.Fa "UI_STRING *uis" 85.Fc 86.Ft const char * 87.Fo UI_get0_output_string 88.Fa "UI_STRING *uis" 89.Fc 90.Ft const char * 91.Fo UI_get0_action_string 92.Fa "UI_STRING *uis" 93.Fc 94.Ft const char * 95.Fo UI_get0_result_string 96.Fa "UI_STRING *uis" 97.Fc 98.Ft const char * 99.Fo UI_get0_test_string 100.Fa "UI_STRING *uis" 101.Fc 102.Ft int 103.Fo UI_get_result_minsize 104.Fa "UI_STRING *uis" 105.Fc 106.Ft int 107.Fo UI_get_result_maxsize 108.Fa "UI_STRING *uis" 109.Fc 110.Ft int 111.Fo UI_set_result 112.Fa "UI *ui" 113.Fa "UI_STRING *uis" 114.Fa "const char *result" 115.Fc 116.Sh DESCRIPTION 117A 118.Vt UI_STRING 119gets created internally and added to a 120.Vt UI 121object whenever one of the functions 122.Xr UI_add_input_string 3 , 123.Xr UI_dup_input_string 3 , 124.Xr UI_add_verify_string 3 , 125.Xr UI_dup_verify_string 3 , 126.Xr UI_add_input_boolean 3 , 127.Xr UI_dup_input_boolean 3 , 128.Xr UI_add_info_string 3 , 129.Xr UI_dup_info_string 3 , 130.Xr UI_add_error_string 3 131or 132.Xr UI_dup_error_string 3 133is called. 134For a 135.Vt UI_METHOD 136user, there's no need to know more. 137For a 138.Vt UI_METHOD 139creator, it is of interest to fetch text from these 140.Vt UI_STRING 141objects as well as adding results to some of them. 142.Pp 143.Fn UI_get_string_type 144is used to retrieve the type of the given 145.Vt UI_STRING . 146.Pp 147.Fn UI_get_input_flags 148is used to retrieve the flags associated with the given 149.Vt UI_STRING . 150.Pp 151.Fn UI_get0_output_string 152is used to retrieve the actual string to output (prompt, info, error, ...). 153.Pp 154.Fn UI_get0_action_string 155is used to retrieve the action description associated with a 156.Dv UIT_BOOLEAN 157type 158.Vt UI_STRING . 159See 160.Xr UI_add_input_boolean 3 . 161.Pp 162.Fn UI_get0_result_string 163is used to retrieve the result of a prompt. 164This is only useful for 165.Dv UIT_PROMPT 166and 167.Dv UIT_VERIFY 168type strings. 169.Pp 170.Fn UI_get0_test_string 171is used to retrieve the string to compare the prompt result with. 172This is only useful for 173.Dv UIT_VERIFY 174type strings. 175.Pp 176.Fn UI_get_result_minsize 177and 178.Fn UI_get_result_maxsize 179are used to retrieve the minimum and maximum required size of the 180result. 181This is only useful for 182.Dv UIT_PROMPT 183and 184.Dv UIT_VERIFY 185type strings. 186.Pp 187.Fn UI_set_result 188is used to set the result value of a prompt. 189For 190.Sy UIT_PROMPT 191and 192.Sy UIT_VERIFY 193type UI strings, this sets the result retrievable with 194.Fn UI_get0_result_string 195by copying the contents of 196.Fa result 197if its length fits the minimum and maximum size requirements. 198For 199.Dv UIT_BOOLEAN 200type UI strings, this sets the first character of the result retrievable 201with 202.Fn UI_get0_result_string 203to the first of the 204.Fa ok_chars 205given with 206.Xr UI_add_input_boolean 3 207or 208.Xr UI_dup_input_boolean 3 209if the 210.Fa result 211matched any of them, or the first of the 212.Fa cancel_chars 213if the 214.Fa result 215matched any of them, otherwise it's set to the NUL char. 216See 217.Xr UI_add_input_boolean 3 218for more information on 219.Fa ok_chars 220and 221.Fa cancel_chars . 222.Sh RETURN VALUES 223.Fn UI_get_string_type 224returns the UI string type. 225.Pp 226.Fn UI_get_input_flags 227returns the UI string flags. 228.Pp 229.Fn UI_get0_output_string 230returns the UI string output string. 231.Pp 232.Fn UI_get0_action_string 233returns the UI string action description string for 234.Dv UIT_BOOLEAN 235type UI strings, or 236.Dv NULL 237for any other type. 238.Pp 239.Fn UI_get0_result_string 240returns the UI string result buffer for 241.Dv UIT_PROMPT 242and 243.Dv UIT_VERIFY 244type UI strings, or 245.Dv NULL 246for any other type. 247.Pp 248.Fn UI_get0_test_string 249returns the UI string action description string for 250.Dv UIT_VERIFY 251type UI strings, or 252.Dv NULL 253for any other type. 254.Pp 255.Fn UI_get_result_minsize 256returns the minimum allowed result size for the UI string for 257.Dv UIT_PROMPT 258and 259.Dv UIT_VERIFY 260type strings, or -1 for any other type. 261.Pp 262.Fn UI_get_result_maxsize 263returns the minimum allowed result size for the UI string for 264.Dv UIT_PROMPT 265and 266.Dv UIT_VERIFY 267type strings, or -1 for any other type. 268.Pp 269.Fn UI_set_result 270returns 0 on success or when the UI string is of any type other than 271.Dv UIT_PROMPT , 272.Dv UIT_VERIFY , 273or 274.Dv UIT_BOOLEAN , 275or -1 on error. 276.Sh SEE ALSO 277.Xr UI_new 3 278.Sh HISTORY 279These functions first appeared in OpenSSL 0.9.7 280and have been available since 281.Ox 3.2 . 282