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