Changes to make use of code taken from libassuan. This replaces the
[gnupg.git] / include / assuan.h
1 /* assuan.c - Definitions for the Assuan protocol
2  *      Copyright (C) 2001, 2002, 2003 Free Software Foundation, Inc.
3  *      Copyright (C) 2005 Free Software Foundation, Inc.
4  *
5  * This file is part of Assuan.
6  *
7  * Assuan is free software; you can redistribute it and/or modify it
8  * under the terms of the GNU Lesser General Public License as
9  * published by the Free Software Foundation; either version 2.1 of
10  * the License, or (at your option) any later version.
11  *
12  * Assuan is distributed in the hope that it will be useful, but
13  * WITHOUT ANY WARRANTY; without even the implied warranty of
14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
15  * Lesser General Public License for more details.
16  *
17  * You should have received a copy of the GNU Lesser General Public
18  * License along with this program; if not, write to the Free Software
19  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA 
20  */
21
22 /* Please note that this is a stripped down and modified version of
23    the orginal Assuan code from libassuan.  For the standalone version
24    of gnupg we only need the ability to connect to a server, so we
25    dropped everything else and maintain this separate copy. */
26
27 #ifndef ASSUAN_H
28 #define ASSUAN_H
29
30 #include <stdio.h>
31 #include <sys/types.h>
32 #include <unistd.h>
33
34 typedef enum
35 {
36   ASSUAN_No_Error = 0,
37   ASSUAN_General_Error = 1,
38   ASSUAN_Out_Of_Core = 2,
39   ASSUAN_Invalid_Value = 3,
40   ASSUAN_Timeout = 4,
41   ASSUAN_Read_Error = 5,
42   ASSUAN_Write_Error = 6,
43   ASSUAN_Problem_Starting_Server = 7,
44   ASSUAN_Not_A_Server = 8,
45   ASSUAN_Not_A_Client = 9,
46   ASSUAN_Nested_Commands = 10,
47   ASSUAN_Invalid_Response = 11,
48   ASSUAN_No_Data_Callback = 12,
49   ASSUAN_No_Inquire_Callback = 13,
50   ASSUAN_Connect_Failed = 14,
51   ASSUAN_Accept_Failed = 15,
52
53   /* Error codes above 99 are meant as status codes */
54   ASSUAN_Not_Implemented = 100,
55   ASSUAN_Server_Fault    = 101,
56   ASSUAN_Invalid_Command = 102,
57   ASSUAN_Unknown_Command = 103,
58   ASSUAN_Syntax_Error    = 104,
59   ASSUAN_Parameter_Error = 105,
60   ASSUAN_Parameter_Conflict = 106,
61   ASSUAN_Line_Too_Long = 107,
62   ASSUAN_Line_Not_Terminated = 108,
63   ASSUAN_No_Input = 109,
64   ASSUAN_No_Output = 110,
65   ASSUAN_Canceled = 111,
66   ASSUAN_Unsupported_Algorithm = 112,
67   ASSUAN_Server_Resource_Problem = 113,
68   ASSUAN_Server_IO_Error = 114,
69   ASSUAN_Server_Bug = 115,
70   ASSUAN_No_Data_Available = 116,
71   ASSUAN_Invalid_Data = 117,
72   ASSUAN_Unexpected_Command = 118,
73   ASSUAN_Too_Much_Data = 119,
74   ASSUAN_Inquire_Unknown = 120,
75   ASSUAN_Inquire_Error = 121,
76   ASSUAN_Invalid_Option = 122,
77   ASSUAN_Invalid_Index = 123,
78   ASSUAN_Unexpected_Status = 124,
79   ASSUAN_Unexpected_Data = 125,
80   ASSUAN_Invalid_Status = 126,
81   ASSUAN_Locale_Problem = 127,
82   ASSUAN_Not_Confirmed = 128,
83
84   /* Error codes in the range 1000 to 9999 may be used by applications
85      at their own discretion. */
86   ASSUAN_USER_ERROR_FIRST = 1000,
87   ASSUAN_USER_ERROR_LAST = 9999
88
89 } assuan_error_t;
90
91
92 #define ASSUAN_LINELENGTH 1002 /* 1000 + [CR,]LF */
93
94 struct assuan_context_s;
95 typedef struct assuan_context_s *assuan_context_t;
96
97 /*-- assuan-handler.c --*/
98 int assuan_register_command (assuan_context_t ctx,
99                              const char *cmd_string,
100                              int (*handler)(assuan_context_t, char *));
101 int assuan_register_bye_notify (assuan_context_t ctx,
102                                 void (*fnc)(assuan_context_t));
103 int assuan_register_reset_notify (assuan_context_t ctx,
104                                   void (*fnc)(assuan_context_t));
105 int assuan_register_cancel_notify (assuan_context_t ctx,
106                                    void (*fnc)(assuan_context_t));
107 int assuan_register_input_notify (assuan_context_t ctx,
108                                   void (*fnc)(assuan_context_t, const char *));
109 int assuan_register_output_notify (assuan_context_t ctx,
110                                   void (*fnc)(assuan_context_t, const char *));
111
112 int assuan_register_option_handler (assuan_context_t ctx,
113                                     int (*fnc)(assuan_context_t,
114                                                const char*, const char*));
115
116 int assuan_process (assuan_context_t ctx);
117 int assuan_process_next (assuan_context_t ctx);
118 int assuan_get_active_fds (assuan_context_t ctx, int what,
119                            int *fdarray, int fdarraysize);
120
121
122 FILE *assuan_get_data_fp (assuan_context_t ctx);
123 assuan_error_t assuan_set_okay_line (assuan_context_t ctx, const char *line);
124 assuan_error_t assuan_write_status (assuan_context_t ctx,
125                                     const char *keyword, const char *text);
126
127 /* Negotiate a file descriptor.  If LINE contains "FD=N", returns N
128    assuming a local file descriptor.  If LINE contains "FD" reads a
129    file descriptor via CTX and stores it in *RDF (the CTX must be
130    capable of passing file descriptors).  */
131 assuan_error_t assuan_command_parse_fd (assuan_context_t ctx, char *line,
132                                      int *rfd);
133
134 /*-- assuan-listen.c --*/
135 assuan_error_t assuan_set_hello_line (assuan_context_t ctx, const char *line);
136 assuan_error_t assuan_accept (assuan_context_t ctx);
137 int assuan_get_input_fd (assuan_context_t ctx);
138 int assuan_get_output_fd (assuan_context_t ctx);
139 assuan_error_t assuan_close_input_fd (assuan_context_t ctx);
140 assuan_error_t assuan_close_output_fd (assuan_context_t ctx);
141
142
143 /*-- assuan-pipe-server.c --*/
144 int assuan_init_pipe_server (assuan_context_t *r_ctx, int filedes[2]);
145 void assuan_deinit_server (assuan_context_t ctx);
146
147 /*-- assuan-socket-server.c --*/
148 int assuan_init_socket_server (assuan_context_t *r_ctx, int listen_fd);
149 int assuan_init_connected_socket_server (assuan_context_t *r_ctx, int fd);
150
151
152 /*-- assuan-pipe-connect.c --*/
153 assuan_error_t assuan_pipe_connect (assuan_context_t *ctx, const char *name,
154                                  char *const argv[], int *fd_child_list);
155 assuan_error_t assuan_pipe_connect2 (assuan_context_t *ctx, const char *name,
156                                      char *const argv[], int *fd_child_list,
157                                      void (*atfork) (void*, int),
158                                      void *atforkvalue);
159 /*-- assuan-socket-connect.c --*/
160 assuan_error_t assuan_socket_connect (assuan_context_t *ctx, const char *name,
161                                       pid_t server_pid);
162
163 /*-- assuan-domain-connect.c --*/
164
165 /* Connect to a Unix domain socket server.  RENDEZVOUSFD is
166    bidirectional file descriptor (normally returned via socketpair)
167    which the client can use to rendezvous with the server.  SERVER s
168    the server's pid.  */
169 assuan_error_t assuan_domain_connect (assuan_context_t *r_ctx,
170                                    int rendezvousfd,
171                                    pid_t server);
172
173 /*-- assuan-domain-server.c --*/
174
175 /* RENDEZVOUSFD is a bidirectional file descriptor (normally returned
176    via socketpair) that the domain server can use to rendezvous with
177    the client.  CLIENT is the client's pid.  */
178 assuan_error_t assuan_init_domain_server (assuan_context_t *r_ctx,
179                                        int rendezvousfd,
180                                        pid_t client);
181
182
183 /*-- assuan-connect.c --*/
184 void assuan_disconnect (assuan_context_t ctx);
185 pid_t assuan_get_pid (assuan_context_t ctx);
186
187 /*-- assuan-client.c --*/
188 assuan_error_t 
189 assuan_transact (assuan_context_t ctx,
190                  const char *command,
191                  assuan_error_t (*data_cb)(void *, const void *, size_t),
192                  void *data_cb_arg,
193                  assuan_error_t (*inquire_cb)(void*, const char *),
194                  void *inquire_cb_arg,
195                  assuan_error_t (*status_cb)(void*, const char *),
196                  void *status_cb_arg);
197 assuan_error_t 
198 assuan_transact2 (assuan_context_t ctx,
199                   const char *command,
200                   assuan_error_t (*data_cb)(void *, const void *, size_t),
201                   void *data_cb_arg,
202                   assuan_error_t (*inquire_cb)(void*, const char *),
203                   void *inquire_cb_arg,
204                   assuan_error_t (*status_cb)(void*, const char *),
205                   void *status_cb_arg,
206                   assuan_error_t (*okay_cb)(void*, const char *),
207                   void *okay_cb_arg);
208
209
210 /*-- assuan-inquire.c --*/
211 assuan_error_t assuan_inquire (assuan_context_t ctx, const char *keyword,
212                             unsigned char **r_buffer, size_t *r_length,
213                             size_t maxlen);
214
215 /*-- assuan-buffer.c --*/
216 assuan_error_t assuan_read_line (assuan_context_t ctx,
217                               char **line, size_t *linelen);
218 int assuan_pending_line (assuan_context_t ctx);
219 assuan_error_t assuan_write_line (assuan_context_t ctx, const char *line );
220 assuan_error_t assuan_send_data (assuan_context_t ctx,
221                               const void *buffer, size_t length);
222
223 /*-- assuan-util.c --*/
224 void assuan_set_malloc_hooks ( void *(*new_alloc_func)(size_t n),
225                                void *(*new_realloc_func)(void *p, size_t n),
226                                void (*new_free_func)(void*) );
227 void assuan_set_log_stream (assuan_context_t ctx, FILE *fp);
228 int assuan_set_error (assuan_context_t ctx, int err, const char *text);
229 void assuan_set_pointer (assuan_context_t ctx, void *pointer);
230 void *assuan_get_pointer (assuan_context_t ctx);
231
232 void assuan_begin_confidential (assuan_context_t ctx);
233 void assuan_end_confidential (assuan_context_t ctx);
234
235 /*-- assuan-errors.c (built) --*/
236 const char *assuan_strerror (assuan_error_t err);
237
238 /*-- assuan-logging.c --*/
239
240 /* Set the stream to which assuan should log message not associated
241    with a context.  By default, this is stderr.  The default value
242    will be changed when the first log stream is associated with a
243    context.  Note, that this function is not thread-safe and should
244    in general be used right at startup. */
245 extern void assuan_set_assuan_log_stream (FILE *fp);
246
247 /* Return the stream which is currently being using for global logging.  */
248 extern FILE *assuan_get_assuan_log_stream (void);
249
250 /* Set the prefix to be used at the start of a line emitted by assuan
251    on the log stream.  The default is the empty string.  Note, that
252    this function is not thread-safe and should in general be used
253    right at startup. */
254 void assuan_set_assuan_log_prefix (const char *text);
255
256 /* Return a prefix to be used at the start of a line emitted by assuan
257    on the log stream.  The default implementation returns the empty
258    string, i.e. ""  */
259 const char *assuan_get_assuan_log_prefix (void);
260
261 #endif /* ASSUAN_H */