NOM¶
UI_new, UI_new_method, UI_free, UI_add_input_string, UI_dup_input_string,
UI_add_verify_string, UI_dup_verify_string, UI_add_input_boolean,
UI_dup_input_boolean, UI_add_info_string, UI_dup_info_string,
UI_add_error_string, UI_dup_error_string, UI_construct_prompt,
UI_add_user_data, UI_get0_user_data, UI_get0_result, UI_process, UI_ctrl,
UI_set_default_method, UI_get_default_method, UI_get_method, UI_set_method,
UI_OpenSSL, ERR_load_UI_strings - Nouvelle interface utilisateur.
SYNOPSIS¶
#include <openssl/ui.h>
typedef struct ui_st UI;
typedef struct ui_method_st UI_METHOD;
UI *UI_new(void);
UI *UI_new_method(const UI_METHOD *method);
void UI_free(UI *ui);
int UI_add_input_string(UI *ui, const char *prompt, int flags,
char *result_buf, int minsize, int maxsize);
int UI_dup_input_string(UI *ui, const char *prompt, int flags,
char *result_buf, int minsize, int maxsize);
int UI_add_verify_string(UI *ui, const char *prompt, int flags,
char *result_buf, int minsize, int maxsize, const char *test_buf);
int UI_dup_verify_string(UI *ui, const char *prompt, int flags,
char *result_buf, int minsize, int maxsize, const char *test_buf);
int UI_add_input_boolean(UI *ui, const char *prompt, const char *action_desc,
const char *ok_chars, const char *cancel_chars,
int flags, char *result_buf);
int UI_dup_input_boolean(UI *ui, const char *prompt, const char *action_desc,
const char *ok_chars, const char *cancel_chars,
int flags, char *result_buf);
int UI_add_info_string(UI *ui, const char *text);
int UI_dup_info_string(UI *ui, const char *text);
int UI_add_error_string(UI *ui, const char *text);
int UI_dup_error_string(UI *ui, const char *text);
/* Voici les drapeaux disponibles. Ils peuvent être ajoutés ensemble avec OR */
#define UI_INPUT_FLAG_ECHO 0x01
#define UI_INPUT_FLAG_DEFAULT_PWD 0x02
char *UI_construct_prompt(UI *ui_method,
const char *object_desc, const char *object_name);
void *UI_add_user_data(UI *ui, void *user_data);
void *UI_get0_user_data(UI *ui);
const char *UI_get0_result(UI *ui, int i);
int UI_process(UI *ui);
int UI_ctrl(UI *ui, int cmd, long i, void *p, void (*f)());
#define UI_CTRL_PRINT_ERRORS 1
#define UI_CTRL_IS_REDOABLE 2
void UI_set_default_method(const UI_METHOD *meth);
const UI_METHOD *UI_get_default_method(void);
const UI_METHOD *UI_get_method(UI *ui);
const UI_METHOD *UI_set_method(UI *ui, const UI_METHOD *meth);
UI_METHOD *UI_OpenSSL(void);
DESCRIPTION¶
UI signifie Interface utilisateur, et est un ensemble général de
routines qui demandent une saisie à l'utilisateur pour des informations
qui sont basées sur du texte. À travers des méthodes
écrites par l'utilisateur (voir
ui_create(3)), les demandes
peuvent être faites de n'importe quelle façon imaginable, en
texte brut, à travers des boites de dialogue ou sur un
téléphone portable.
Toutes les fonctions fonctionnent dans un contexte du type d'UI. Ce contexte
contient toutes les informations nécessaires pour faire une demande de
saisie de façon correcte, ainsi qu'une référence vers un
UI_METHOD qui est un vecteur de fonctions ordonné qui transporte les
demandes de saisies.
La première chose à faire est de créer une UI avec
UI_new() ou
UI_new_method(), puis d'ajouter des informations
avec les fonctions UI_add ou UI_dup. Les données définies comme
aléatoires par l'utilisateur peuvent aussi être passées
aux méthodes sous-jacentes à travers des appels à
UI_add_user_data. L'UI par défaut ne prend pas en compte ces
données, mais d'autres méthodes pourraient. Finalement, utilisez
UI_process() pour faire la demande d'entrée et
UI_get0_result() pour avoir le résultat de cette demande.
Une UI peut contenir plusieurs demandes de saisie qui sont effectuées
dans chaque séquence. Chaque demande reçoit un numéro
d'indexation, qui est renvoyé par les fonctions UI_add et UI_dup, et
qui doit être utilisé par
UI_get0_result() pour obtenir
le résultat correspondant.
Les fonctions sont comme suit :
UI_new() crée une nouvelle méthode d'UI. Quand
l'utilisation de cette UI est terminée, elle doit être
libérée avec
UI_free().
UI_new_method() crée une nouvelle UI en utilisant la
méthode UI donnée. Quand celle-ci a fini avec cette UI, elle
doit être libérée en utilisant
UI_free().
UI_OpenSSL() renvoie la méthode construite dans l'UI
(note : pas celle par défaut puisque celle-ci peut être
modifiée. Voir plus loin). Cette méthode est la plus
dépendante de la machine et de l'OS d'OpenSSL et génère
normalement le plus de problèmes de portabilité.
UI_free() supprime une UI de la mémoire, ainsi que tous morceaux
de mémoire qui sont connectés à celle-ci, comme des
copies de chaînes de caractères d'entrées, des
résultats et autres.
UI_add_input_string() et
UI_add_verify_string() ajoutent une
demande à l'UI, ainsi que des drapeaux, un tampon de résultat et
les tailles minimales et maximales désirées pour le
résultat. Les informations fournies sont utilisées pour demander
des informations, par exemple un mot de passe, et pour vérifier le mot
de passe (c'est-à-dire l'utilisateur rentre deux fois le mot de passe
et l'égalité est vérifiée).
UI_add_verify_string() prend un argument en plus, qui devrait
être un pointeur vers le tampon de retour de la chaîne de
caractères de sortie qu'il est supposé vérifier, ou la
vérification échouera.
UI_add_input_boolean() ajoute une demande d'entrée à l'UI
qui doit avoir une réponse sous forme d'un booléen, avec un seul
caractère pour oui et un caractère différent pour non. Un
ensemble de caractères qui peuvent être utilisés pour
annuler cette demande est aussi donné. La demande elle-même est
divisée en deux parties, la première étant la description
textuelle (donnée par l'argument
prompt) et la seconde
décrivant les réponses possibles (données par l'argument
action_desc).
UI_add_info_string() et
UI_add_error_string() ajoutent les
chaînes de caractères qui sont affichées au même
moment que la demande de saisie dans le cas de demande d'information
supplémentaire ou pour afficher un message d'erreur. La
différence entre les deux n'est que conceptuelle. Avec la
méthode interne, il n'y a pas de différence technique entres
elles. Mais il se peut que d'autres méthodes puissent produire une
différence.
Les drapeaux gérés actuellement sont UI_INPUT_FLAG_ECHO, qui est
applicable à
UI_add_input_string() et qui fera s'afficher les
réponses de l'utilisateur (quand un mot de passe est demandé, ce
drapeau ne doit évidemment pas être utilisé), et
UI_INPUT_FLAG_DEFAULT_PWD, qui indique qu'un mot de passe par défaut va
être utilisé (cela dépend entièrement de
l'application et de la méthode d'UI).
UI_dup_input_string(),
UI_dup_verify_string(),
UI_dup_input_boolean(),
UI_dup_info_string() et
UI_dup_error_string() sont identiques à leurs contreparties
UI_add, sauf qu'ils font leurs propres copies des chaînes.
UI_construct_prompt() est une fonction d'aide qui est utilisée
pour créer une demande d'entrée de texte pour deux morceaux
d'information : une description et un nom. Le constructeur par
défaut (s'il n'y en a aucun de fourni par la méthode
utilisée) crée une chaîne de caractères
« Enter
description for
name : ». Avec la description « pass
phrase » et le nom de fichier
« foo.key », qui devient « Enter
pass phrase for foo.key : ». D'autres méthodes
peuvent créer n'importe quelle chaîne de caractères et
peuvent inclure des encodages qui seront traités par d'autres fonctions
de méthodes.
UI_add_user_data() ajoute un morceau de mémoire pour la
méthode à utiliser à chaque instant. La méthode de
l'UI intégrée ne prend pas cette information en compte. Notez
que plusieurs appels à cette fonction n'ajoutent pas de données,
elle remplace le blob précédent par celui donné comme
argument.
UI_get0_user_data() récupère les données qui ont
été données à l'UI avec
UI_add_user_data().
UI_get0_result() renvoie un pointeur vers le résultat du tampon
associé à l'information indexée par
i.
UI_process() parcourt l'information donnée jusque-là, fait
tout les affichages et requêtes et renvoie.
UI_ctrl() ajoute un contrôle supplémentaire pour l'auteur
de l'application. Pour l'instant, elle comprend deux commandes :
UI_CTRL_PRINT_ERRORS, qui demande à
UI_process() d'afficher la
pile d'erreurs d'OpenSSL comme partie du traitement de l'UI, et
UI_CTRL_IS_REDOABLE qui renvoie un drapeau exprimant la
réutilisabilité de l'UI.
UI_set_default_method() change la méthode par défaut de
l'UI pour celle donnée.
UI_get_default_method() renvoie un pointeur vers la méthode par
défaut actuelle de l'UI.
UI_get_method() renvoie la méthode d'UI associée à
une UI donnée.
UI_set_method() change la méthode d'UI associée à
une UI donnée.
VOIR AUSSI¶
ui_create(3),
ui_compat(3)
HISTORIQUE¶
La partie UI a été introduite dans la version 0.9.7
d'OpenSSL.
AUTEUR¶
Richard Levitte <richard@levitte.org> pour le projet OpenSSL
<
http://www.openssl.org>.
TRADUCTION¶
La traduction de cette page de manuel est maintenue par les membres de la liste
<debian-l10n-french AT lists DOT debian DOT org>. Veuillez signaler
toute erreur de traduction par un rapport de bogue sur le paquet
manpages-fr-extra.