UI_create_method.pod 7.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220
  1. =pod
  2. =head1 NAME
  3. UI_METHOD,
  4. UI_create_method, UI_destroy_method, UI_method_set_opener,
  5. UI_method_set_writer, UI_method_set_flusher, UI_method_set_reader,
  6. UI_method_set_closer, UI_method_set_data_duplicator,
  7. UI_method_set_prompt_constructor, UI_method_set_ex_data,
  8. UI_method_get_opener, UI_method_get_writer, UI_method_get_flusher,
  9. UI_method_get_reader, UI_method_get_closer,
  10. UI_method_get_data_duplicator, UI_method_get_data_destructor,
  11. UI_method_get_prompt_constructor, UI_method_get_ex_data - user
  12. interface method creation and destruction
  13. =head1 SYNOPSIS
  14. #include <openssl/ui.h>
  15. typedef struct ui_method_st UI_METHOD;
  16. UI_METHOD *UI_create_method(const char *name);
  17. void UI_destroy_method(UI_METHOD *ui_method);
  18. int UI_method_set_opener(UI_METHOD *method, int (*opener) (UI *ui));
  19. int UI_method_set_writer(UI_METHOD *method,
  20. int (*writer) (UI *ui, UI_STRING *uis));
  21. int UI_method_set_flusher(UI_METHOD *method, int (*flusher) (UI *ui));
  22. int UI_method_set_reader(UI_METHOD *method,
  23. int (*reader) (UI *ui, UI_STRING *uis));
  24. int UI_method_set_closer(UI_METHOD *method, int (*closer) (UI *ui));
  25. int UI_method_set_data_duplicator(UI_METHOD *method,
  26. void *(*duplicator) (UI *ui, void *ui_data),
  27. void (*destructor)(UI *ui, void *ui_data));
  28. int UI_method_set_prompt_constructor(UI_METHOD *method,
  29. char *(*prompt_constructor) (UI *ui,
  30. const char
  31. *object_desc,
  32. const char
  33. *object_name));
  34. int UI_method_set_ex_data(UI_METHOD *method, int idx, void *data);
  35. int (*UI_method_get_opener(const UI_METHOD *method)) (UI *);
  36. int (*UI_method_get_writer(const UI_METHOD *method)) (UI *, UI_STRING *);
  37. int (*UI_method_get_flusher(const UI_METHOD *method)) (UI *);
  38. int (*UI_method_get_reader(const UI_METHOD *method)) (UI *, UI_STRING *);
  39. int (*UI_method_get_closer(const UI_METHOD *method)) (UI *);
  40. char *(*UI_method_get_prompt_constructor(const UI_METHOD *method))
  41. (UI *, const char *, const char *);
  42. void *(*UI_method_get_data_duplicator(const UI_METHOD *method)) (UI *, void *);
  43. void (*UI_method_get_data_destructor(const UI_METHOD *method)) (UI *, void *);
  44. const void *UI_method_get_ex_data(const UI_METHOD *method, int idx);
  45. =head1 DESCRIPTION
  46. A method contains a few functions that implement the low-level of the
  47. User Interface.
  48. These functions are:
  49. =over 4
  50. =item an opener
  51. This function takes a reference to a UI and starts a session, for
  52. example by opening a channel to a tty, or by creating a dialog box.
  53. =item a writer
  54. This function takes a reference to a UI and a UI String, and writes
  55. the string where appropriate, maybe to the tty, maybe added as a field
  56. label in a dialog box.
  57. Note that this gets fed all strings associated with a UI, one after
  58. the other, so care must be taken which ones it actually uses.
  59. =item a flusher
  60. This function takes a reference to a UI, and flushes everything that
  61. has been output so far.
  62. For example, if the method builds up a dialog box, this can be used to
  63. actually display it and accepting input ended with a pressed button.
  64. =item a reader
  65. This function takes a reference to a UI and a UI string and reads off
  66. the given prompt, maybe from the tty, maybe from a field in a dialog
  67. box.
  68. Note that this gets fed all strings associated with a UI, one after
  69. the other, so care must be taken which ones it actually uses.
  70. =item a closer
  71. This function takes a reference to a UI, and closes the session, maybe
  72. by closing the channel to the tty, maybe by destroying a dialog box.
  73. =back
  74. All of these functions are expected to return 0 on error, 1 on
  75. success, or -1 on out-off-band events, for example if some prompting
  76. has been cancelled (by pressing Ctrl-C, for example).
  77. Only the flusher or the reader are expected to return -1.
  78. If returned by another of the functions, it's treated as if 0 was
  79. returned.
  80. Regarding the writer and the reader, don't assume the former should
  81. only write and don't assume the latter should only read.
  82. This depends on the needs of the method.
  83. For example, a typical tty reader wouldn't write the prompts in the
  84. write, but would rather do so in the reader, because of the sequential
  85. nature of prompting on a tty.
  86. This is how the UI_OpenSSL() method does it.
  87. In contrast, a method that builds up a dialog box would add all prompt
  88. text in the writer, have all input read in the flusher and store the
  89. results in some temporary buffer, and finally have the reader just
  90. fetch those results.
  91. The central function that uses these method functions is UI_process(),
  92. and it does it in five steps:
  93. =over 4
  94. =item 1.
  95. Open the session using the opener function if that one's defined.
  96. If an error occurs, jump to 5.
  97. =item 2.
  98. For every UI String associated with the UI, call the writer function
  99. if that one's defined.
  100. If an error occurs, jump to 5.
  101. =item 3.
  102. Flush everything using the flusher function if that one's defined.
  103. If an error occurs, jump to 5.
  104. =item 4.
  105. For every UI String associated with the UI, call the reader function
  106. if that one's defined.
  107. If an error occurs, jump to 5.
  108. =item 5.
  109. Close the session using the closer function if that one's defined.
  110. =back
  111. UI_create_method() creates a new UI method with a given B<name>.
  112. UI_destroy_method() destroys the given UI method B<ui_method>.
  113. UI_method_set_opener(), UI_method_set_writer(),
  114. UI_method_set_flusher(), UI_method_set_reader() and
  115. UI_method_set_closer() set the five main method function to the given
  116. function pointer.
  117. UI_method_set_data_duplicator() sets the user data duplicator and destructor.
  118. See L<UI_dup_user_data(3)>.
  119. UI_method_set_prompt_constructor() sets the prompt constructor.
  120. See L<UI_construct_prompt(3)>.
  121. UI_method_set_ex_data() sets application specific data with a given
  122. EX_DATA index.
  123. See L<CRYPTO_get_ex_new_index(3)> for general information on how to
  124. get that index.
  125. UI_method_get_opener(), UI_method_get_writer(),
  126. UI_method_get_flusher(), UI_method_get_reader(),
  127. UI_method_get_closer(), UI_method_get_data_duplicator(),
  128. UI_method_get_data_destructor() and UI_method_get_prompt_constructor()
  129. return the different method functions.
  130. UI_method_get_ex_data() returns the application data previously stored
  131. with UI_method_set_ex_data().
  132. =head1 RETURN VALUES
  133. UI_create_method() returns a UI_METHOD pointer on success, NULL on
  134. error.
  135. UI_method_set_opener(), UI_method_set_writer(),
  136. UI_method_set_flusher(), UI_method_set_reader(),
  137. UI_method_set_closer(), UI_method_set_data_duplicator() and
  138. UI_method_set_prompt_constructor()
  139. return 0 on success, -1 if the given B<method> is NULL.
  140. UI_method_set_ex_data() returns 1 on success and 0 on error (because
  141. CRYPTO_set_ex_data() does so).
  142. UI_method_get_opener(), UI_method_get_writer(),
  143. UI_method_get_flusher(), UI_method_get_reader(),
  144. UI_method_get_closer(), UI_method_get_data_duplicator(),
  145. UI_method_get_data_destructor() and UI_method_get_prompt_constructor()
  146. return the requested function pointer if it's set in the method,
  147. otherwise NULL.
  148. UI_method_get_ex_data() returns a pointer to the application specific
  149. data associated with the method.
  150. =head1 SEE ALSO
  151. L<UI(3)>, L<CRYPTO_get_ex_data(3)>, L<UI_STRING(3)>
  152. =head1 HISTORY
  153. The UI_method_set_data_duplicator(), UI_method_get_data_duplicator()
  154. and UI_method_get_data_destructor() functions were added in OpenSSL 1.1.1.
  155. =head1 COPYRIGHT
  156. Copyright 2001-2020 The OpenSSL Project Authors. All Rights Reserved.
  157. Licensed under the Apache License 2.0 (the "License"). You may not use
  158. this file except in compliance with the License. You can obtain a copy
  159. in the file LICENSE in the source distribution or at
  160. L<https://www.openssl.org/source/license.html>.
  161. =cut