2002-05-09 Marcus Brinkmann <marcus@g10code.de>
[pinentry.git] / pinentry / pinentry.h
1 /* pinentry.h - The interface for the PIN entry support library.
2    Copyright (C) 2002 g10 Code GmbH
3    
4    This file is part of PINENTRY.
5    
6    PINENTRY is free software; you can redistribute it and/or modify it
7    under the terms of the GNU General Public License as published by
8    the Free Software Foundation; either version 2 of the License, or
9    (at your option) any later version.
10  
11    PINENTRY is distributed in the hope that it will be useful, but
12    WITHOUT ANY WARRANTY; without even the implied warranty of
13    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
14    General Public License for more details.
15  
16    You should have received a copy of the GNU General Public License
17    along with this program; if not, write to the Free Software
18    Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA
19    02111-1307, USA  */
20
21 #ifndef PINENTRY_H
22 #define PINENTRY_H
23
24 struct pinentry
25 {
26   /* The description to display, or NULL.  */
27   char *description;
28   /* The error message to display, or NULL.  */
29   char *error;
30   /* The prompt to display, or NULL.  */
31   char *prompt;
32   /* The OK button text to display, or NULL.  */
33   char *ok;
34   /* The Cancel button text to display, or NULL.  */
35   char *cancel;
36   /* The buffer to store the secret into.  */
37   char *pin;
38   /* The length of the buffer.  */
39   int pin_len;
40
41   /* The name of the X display to use if X is available and supported.  */
42   char *display;
43   /* The name of the terminal node to open if X not available or supported.  */
44   char *ttyname;
45   /* The type of the terminal.  */
46   char *ttytype;
47   /* The LC_CTYPE value for the terminal.  */
48   char *lc_ctype;
49   /* The LC_MESSAGES value for the terminal.  */
50   char *lc_messages;
51
52   /* True if debug mode is requested.  */
53   int debug;
54   /* True if enhanced mode is requested.  */
55   int enhanced;
56   /* True if caller should grab the keyboard.  */
57   int grab;
58
59   /* The user should set this to -1 if the user canceled the request,
60      and to the length of the PIN stored in pin otherwise.  */
61   int result;
62 };
63 typedef struct pinentry *pinentry_t;
64
65 \f
66 /* The pinentry command handler type processes the pinentry request
67    PIN.  If PIN->pin is zero, request a confirmation, otherwise a PIN
68    entry.  On confirmation, the function should return TRUE if
69    confirmed, and FALSE otherwise.  On PIN entry, the function should
70    return -1 if cancelled and the length of the secret otherwise.  */
71 typedef int (*pinentry_cmd_handler_t) (pinentry_t pin);
72
73 /* Start the pinentry event loop.  The program will start to process
74    Assuan commands until it is finished or an error occurs.  If an
75    error occurs, -1 is returned and errno indicates the type of an
76    error.  Otherwise, 0 is returned.  */
77 int pinentry_loop (void);
78
79 /* Try to make room for at least LEN bytes for the pin in the pinentry
80    PIN.  Returns new buffer on success and 0 on failure.  */
81 char *pinentry_setbufferlen (pinentry_t pin, int len);
82
83 \f
84 /* The caller must define this variable to process assuan commands.  */
85 extern pinentry_cmd_handler_t pinentry_cmd_handler;
86
87 #endif  /* PINENTRY_H */