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