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