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.