1.\" $OpenBSD: UI_create_method.3,v 1.6 2023/05/22 19:38:04 tb Exp $ 2.\" OpenSSL UI_create_method.pod 8e3d46e5 Mar 11 10:51:04 2017 +0100 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: May 22 2023 $ 52.Dt UI_CREATE_METHOD 3 53.Os 54.Sh NAME 55.Nm UI_create_method , 56.Nm UI_destroy_method , 57.Nm UI_method_set_opener , 58.Nm UI_method_set_writer , 59.Nm UI_method_set_flusher , 60.Nm UI_method_set_reader , 61.Nm UI_method_set_closer , 62.Nm UI_method_set_prompt_constructor , 63.Nm UI_method_get_opener , 64.Nm UI_method_get_writer , 65.Nm UI_method_get_flusher , 66.Nm UI_method_get_reader , 67.Nm UI_method_get_closer , 68.Nm UI_method_get_prompt_constructor 69.Nd user interface method creation and destruction 70.Sh SYNOPSIS 71.In openssl/ui.h 72.Ft UI_METHOD * 73.Fo UI_create_method 74.Fa "const char *name" 75.Fc 76.Ft void 77.Fo UI_destroy_method 78.Fa "UI_METHOD *ui_method" 79.Fc 80.Ft int 81.Fo UI_method_set_opener 82.Fa "UI_METHOD *method" 83.Fa "int (*opener)(UI *ui)" 84.Fc 85.Ft int 86.Fo UI_method_set_writer 87.Fa "UI_METHOD *method" 88.Fa "int (*writer)(UI *ui, UI_STRING *uis)" 89.Fc 90.Ft int 91.Fo UI_method_set_flusher 92.Fa "UI_METHOD *method" 93.Fa "int (*flusher)(UI *ui)" 94.Fc 95.Ft int 96.Fo UI_method_set_reader 97.Fa "UI_METHOD *method" 98.Fa "int (*reader)(UI *ui, UI_STRING *uis)" 99.Fc 100.Ft int 101.Fo UI_method_set_closer 102.Fa "UI_METHOD *method" 103.Fa "int (*closer)(UI *ui)" 104.Fc 105.Ft int 106.Fo UI_method_set_prompt_constructor 107.Fa "UI_METHOD *method" 108.Fa "char *(*prompt_constructor)(UI *ui, const char *object_desc,\ 109 const char *object_name)" 110.Fc 111.Ft int 112.Fo "(*UI_method_get_opener(const UI_METHOD *method))" 113.Fa "UI *" 114.Fc 115.Ft int 116.Fo "(*UI_method_get_writer(const UI_METHOD *method))" 117.Fa "UI *" 118.Fa "UI_STRING *" 119.Fc 120.Ft int 121.Fo "(*UI_method_get_flusher(const UI_METHOD *method))" 122.Fa "UI *" 123.Fc 124.Ft int 125.Fo "(*UI_method_get_reader(const UI_METHOD *method))" 126.Fa "UI *" 127.Fa "UI_STRING *" 128.Fc 129.Ft int 130.Fo "(*UI_method_get_closer(const UI_METHOD *method))" 131.Fa "UI *" 132.Fc 133.Ft char * 134.Fo "(*UI_method_get_prompt_constructor(UI_METHOD *method))" 135.Fa "UI *" 136.Fa "const char *" 137.Fa "const char *" 138.Fc 139.Sh DESCRIPTION 140A method contains a few functions that implement the low level of the 141User Interface. 142These functions are: 143.Bl -tag -width Ds 144.It an opener 145This function takes a reference to a UI and starts a session, for 146example by opening a channel to a tty, or by creating a dialog box. 147.It a writer 148This function takes a reference to a UI and a UI String, and writes the 149string where appropriate, maybe to the tty, maybe added as a field label 150in a dialog box. 151Note that this gets fed all strings associated with a UI, one after the 152other, so care must be taken which ones it actually uses. 153.It a flusher 154This function takes a reference to a UI, and flushes everything that has 155been output so far. 156For example, if the method builds up a dialog box, this can be used to 157actually display it and accepting input ended with a pressed button. 158.It a reader 159This function takes a reference to a UI and a UI string and reads off 160the given prompt, maybe from the tty, maybe from a field in a dialog 161box. 162Note that this gets fed all strings associated with a UI, one after the 163other, so care must be taken which ones it actually uses. 164.It a closer 165This function takes a reference to a UI, and closes the session, maybe 166by closing the channel to the tty, maybe by destroying a dialog box. 167.El 168.Pp 169All of these functions are expected to return 0 on error, 1 on success, 170or -1 on out-off-band events, for example if some prompting has been 171cancelled (by pressing Ctrl-C, for example). 172Only the flusher or the reader are expected to return -1. 173If returned by another of the functions, it's treated as if 0 was returned. 174.Pp 175Regarding the writer and the reader, don't assume the former should only 176write and don't assume the latter should only read. 177This depends on the needs of the method. 178.Pp 179For example, a typical tty reader wouldn't write the prompts in the 180write, but would rather do so in the reader, because of the sequential 181nature of prompting on a tty. 182This is how the 183.Xr UI_OpenSSL 3 184method does it. 185.Pp 186In contrast, a method that builds up a dialog box would add all prompt 187text in the writer, have all input read in the flusher and store the 188results in some temporary buffer, and finally have the reader just fetch 189those results. 190.Pp 191The central function that uses these method functions is 192.Xr UI_process 3 , 193and it does it in five steps: 194.Bl -enum 195.It 196Open the session using the opener function if that one is defined. 197If an error occurs, jump to 5. 198.It 199For every UI String associated with the UI, call the writer function if 200that one is defined. 201If an error occurs, jump to 5. 202.It 203Flush everything using the flusher function if that one is defined. 204If an error occurs, jump to 5. 205.It 206For every UI String associated with the UI, call the reader function if 207that one is defined. 208If an error occurs, jump to 5. 209.It 210Close the session using the closer function if that one is defined. 211.El 212.Pp 213.Fn UI_create_method 214creates a new UI method with a given 215.Fa name . 216.Pp 217.Fn UI_destroy_method 218destroys the given 219.Fa ui_method . 220.Pp 221.Fn UI_method_set_opener , 222.Fn UI_method_set_writer , 223.Fn UI_method_set_flusher , 224.Fn UI_method_set_reader 225and 226.Fn UI_method_set_closer 227set one of the five main methods to the given function pointer. 228.Pp 229.Fn UI_method_set_prompt_constructor 230sets the prompt constructor, see 231.Xr UI_construct_prompt 3 . 232.Sh RETURN VALUES 233.Fn UI_create_method 234returns a 235.Vt UI_METHOD 236pointer on success or 237.Dv NULL 238on error. 239.Pp 240.Fn UI_method_set_opener , 241.Fn UI_method_set_writer , 242.Fn UI_method_set_flusher , 243.Fn UI_method_set_reader , 244.Fn UI_method_set_closer , 245and 246.Fn UI_method_set_prompt_constructor 247return 0 on success or -1 if the given method is 248.Dv NULL . 249.Pp 250.Fn UI_method_get_opener , 251.Fn UI_method_get_writer , 252.Fn UI_method_get_flusher , 253.Fn UI_method_get_reader , 254.Fn UI_method_get_closer , 255and 256.Fn UI_method_get_prompt_constructor 257return the requested function pointer if it is set in the method, 258or otherwise 259.Dv NULL . 260.Sh SEE ALSO 261.Xr UI_get_string_type 3 , 262.Xr UI_new 3 263.Sh HISTORY 264.Fn UI_create_method , 265.Fn UI_destroy_method , 266.Fn UI_method_set_opener , 267.Fn UI_method_set_writer , 268.Fn UI_method_set_flusher , 269.Fn UI_method_set_reader , 270.Fn UI_method_set_closer , 271.Fn UI_method_get_opener , 272.Fn UI_method_get_writer , 273.Fn UI_method_get_flusher , 274.Fn UI_method_get_reader , 275and 276.Fn UI_method_get_closer 277first appeared in OpenSSL 0.9.7 and have been available since 278.Ox 3.2 . 279.Pp 280.Fn UI_method_set_prompt_constructor 281and 282.Fn UI_method_get_prompt_constructor 283first appeared in OpenSSL 1.0.0 and have been available since 284.Ox 4.9 . 285