libkdenetwork Library API Documentation

assuan.h

00001 /* assuan.c - Definitions for the Assuan protocol
00002  *  Copyright (C) 2001, 2002, 2003 Free Software Foundation, Inc.
00003  *
00004  * This file is part of Assuan.
00005  *
00006  * Assuan is free software; you can redistribute it and/or modify it
00007  * under the terms of the GNU Lesser General Public License as
00008  * published by the Free Software Foundation; either version 2.1 of
00009  * the License, or (at your option) any later version.
00010  *
00011  * Assuan is distributed in the hope that it will be useful, but
00012  * WITHOUT ANY WARRANTY; without even the implied warranty of
00013  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
00014  * Lesser General Public License for more details.
00015  *
00016  * You should have received a copy of the GNU Lesser General Public
00017  * License along with this program; if not, write to the Free Software
00018  * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA 
00019  */
00020 
00021 #ifndef ASSUAN_H
00022 #define ASSUAN_H
00023 
00024 #include <stdio.h>
00025 #include <sys/types.h>
00026 #include <unistd.h>
00027 
00028 #include <sys/socket.h>
00029 
00030 #define _ASSUAN_IN_GPGME
00031 #ifdef _ASSUAN_IN_GPGME
00032 #define _ASSUAN_EXT_SYM_PREFIX _gpgme_
00033 
00034 #ifdef _ASSUAN_IN_GPGME_BUILD_ASSUAN
00035 int _gpgme_io_read (int fd, void *buffer, size_t count);
00036 int _gpgme_io_write (int fd, const void *buffer, size_t count);
00037 ssize_t _gpgme_ath_select (int nfd, fd_set *rset, fd_set *wset, fd_set *eset,
00038                struct timeval *timeout);
00039 ssize_t _gpgme_ath_waitpid (pid_t pid, int *status, int options);
00040 int _gpgme_ath_accept (int s, struct sockaddr *addr, socklen_t *length_ptr);
00041 int _gpgme_ath_connect (int s, struct sockaddr *addr, socklen_t length);
00042 int _gpgme_ath_sendmsg (int s, const struct msghdr *msg, int flags);
00043 int _gpgme_ath_recvmsg (int s, struct msghdr *msg, int flags);
00044 
00045 #define read          _gpgme_io_read
00046 #define write         _gpgme_io_write
00047 #define waitpid       _gpgme_ath_waitpid
00048 #define select        _gpgme_ath_select
00049 #define accept        _gpgme_ath_accept
00050 #define connect       _gpgme_ath_connect
00051 #define sendmsg       _gpgme_ath_sendmsg
00052 #define recvmsg       _gpgme_ath_recvmsg
00053 #endif
00054 #endif
00055 
00056 #ifdef _ASSUAN_EXT_SYM_PREFIX
00057 #define _ASSUAN_PREFIX1(x,y) x ## y
00058 #define _ASSUAN_PREFIX2(x,y) _ASSUAN_PREFIX1(x,y)
00059 #define _ASSUAN_PREFIX(x) _ASSUAN_PREFIX2(_ASSUAN_EXT_SYM_PREFIX,x)
00060 #define assuan_ _ASSUAN_PREFIX(assuan_)
00061 #define assuan_register_command _ASSUAN_PREFIX(assuan_register_command)
00062 #define assuan_register_bye_notify _ASSUAN_PREFIX(assuan_register_bye_notify)
00063 #define assuan_register_reset_notify \
00064   _ASSUAN_PREFIX(assuan_register_reset_notify)
00065 #define assuan_register_cancel_notify \
00066   _ASSUAN_PREFIX(assuan_register_cancel_notify)
00067 #define assuan_register_input_notify \
00068   _ASSUAN_PREFIX(assuan_register_input_notify)
00069 #define assuan_register_output_notify \
00070   _ASSUAN_PREFIX(assuan_register_output_notify)
00071 #define assuan_register_option_handler \
00072   _ASSUAN_PREFIX(assuan_register_option_handler)
00073 #define assuan_process _ASSUAN_PREFIX(assuan_process)
00074 #define assuan_process_next _ASSUAN_PREFIX(assuan_process_next)
00075 #define assuan_get_active_fds _ASSUAN_PREFIX(assuan_get_active_fds)
00076 #define assuan_get_data_fp _ASSUAN_PREFIX(assuan_get_data_fp)
00077 #define assuan_set_okay_line _ASSUAN_PREFIX(assuan_set_okay_line)
00078 #define assuan_write_status _ASSUAN_PREFIX(assuan_write_status)
00079 #define assuan_command_parse_fd _ASSUAN_PREFIX(assuan_command_parse_fd)
00080 #define assuan_set_hello_line _ASSUAN_PREFIX(assuan_set_hello_line)
00081 #define assuan_accept _ASSUAN_PREFIX(assuan_accept)
00082 #define assuan_get_input_fd _ASSUAN_PREFIX(assuan_get_input_fd)
00083 #define assuan_get_output_fd _ASSUAN_PREFIX(assuan_get_output_fd)
00084 #define assuan_close_input_fd _ASSUAN_PREFIX(assuan_close_input_fd)
00085 #define assuan_close_output_fd _ASSUAN_PREFIX(assuan_close_output_fd)
00086 #define assuan_init_pipe_server _ASSUAN_PREFIX(assuan_init_pipe_server)
00087 #define assuan_deinit_server _ASSUAN_PREFIX(assuan_deinit_server)
00088 #define assuan_init_socket_server _ASSUAN_PREFIX(assuan_init_socket_server)
00089 #define assuan_init_connected_socket_server \
00090   _ASSUAN_PREFIX(assuan_init_connected_socket_server)
00091 #define assuan_pipe_connect _ASSUAN_PREFIX(assuan_pipe_connect)
00092 #define assuan_socket_connect _ASSUAN_PREFIX(assuan_socket_connect)
00093 #define assuan_domain_connect _ASSUAN_PREFIX(assuan_domain_connect)
00094 #define assuan_init_domain_server _ASSUAN_PREFIX(assuan_init_domain_server)
00095 #define assuan_disconnect _ASSUAN_PREFIX(assuan_disconnect)
00096 #define assuan_get_pid _ASSUAN_PREFIX(assuan_get_pid)
00097 #define assuan_transact _ASSUAN_PREFIX(assuan_transact)
00098 #define assuan_inquire _ASSUAN_PREFIX(assuan_inquire)
00099 #define assuan_read_line _ASSUAN_PREFIX(assuan_read_line)
00100 #define assuan_pending_line _ASSUAN_PREFIX(assuan_pending_line)
00101 #define assuan_write_line _ASSUAN_PREFIX(assuan_write_line)
00102 #define assuan_send_data _ASSUAN_PREFIX(assuan_send_data)
00103 #define assuan_sendfd _ASSUAN_PREFIX(assuan_sendfd)
00104 #define assuan_receivefd _ASSUAN_PREFIX(assuan_receivefd)
00105 #define assuan_set_malloc_hooks _ASSUAN_PREFIX(assuan_set_malloc_hooks)
00106 #define assuan_set_log_stream _ASSUAN_PREFIX(assuan_set_log_stream)
00107 #define assuan_set_error _ASSUAN_PREFIX(assuan_set_error)
00108 #define assuan_set_pointer _ASSUAN_PREFIX(assuan_set_pointer)
00109 #define assuan_get_pointer _ASSUAN_PREFIX(assuan_get_pointer)
00110 #define assuan_begin_confidential _ASSUAN_PREFIX(assuan_begin_confidential)
00111 #define assuan_end_confidential _ASSUAN_PREFIX(assuan_end_confidential)
00112 #define assuan_strerror _ASSUAN_PREFIX(assuan_strerror)
00113 #define assuan_set_assuan_log_stream \
00114   _ASSUAN_PREFIX(assuan_set_assuan_log_stream)
00115 #define assuan_get_assuan_log_stream \
00116   _ASSUAN_PREFIX(assuan_get_assuan_log_stream)
00117 #define assuan_get_assuan_log_prefix \
00118   _ASSUAN_PREFIX(assuan_get_assuan_log_prefix)
00119 
00120 /* And now the internal functions, argh...  */
00121 #define _assuan_read_line _ASSUAN_PREFIX(_assuan_read_line)
00122 #define _assuan_cookie_write_data _ASSUAN_PREFIX(_assuan_cookie_write_data)
00123 #define _assuan_cookie_write_flush _ASSUAN_PREFIX(_assuan_cookie_write_flush)
00124 #define _assuan_read_from_server _ASSUAN_PREFIX(_assuan_read_from_server)
00125 #define _assuan_domain_init _ASSUAN_PREFIX(_assuan_domain_init)
00126 #define _assuan_register_std_commands \
00127   _ASSUAN_PREFIX(_assuan_register_std_commands)
00128 #define _assuan_simple_read _ASSUAN_PREFIX(_assuan_simple_read)
00129 #define _assuan_simple_write _ASSUAN_PREFIX(_assuan_simple_write)
00130 #define _assuan_simple_read _ASSUAN_PREFIX(_assuan_simple_read)
00131 #define _assuan_simple_write _ASSUAN_PREFIX(_assuan_simple_write)
00132 #define _assuan_new_context _ASSUAN_PREFIX(_assuan_new_context)
00133 #define _assuan_release_context _ASSUAN_PREFIX(_assuan_release_context)
00134 #define _assuan_malloc _ASSUAN_PREFIX(_assuan_malloc)
00135 #define _assuan_realloc _ASSUAN_PREFIX(_assuan_realloc)
00136 #define _assuan_calloc _ASSUAN_PREFIX(_assuan_calloc)
00137 #define _assuan_free _ASSUAN_PREFIX(_assuan_free)
00138 #define _assuan_log_print_buffer _ASSUAN_PREFIX(_assuan_log_print_buffer)
00139 #define _assuan_log_sanitized_string \
00140   _ASSUAN_PREFIX(_assuan_log_sanitized_string)
00141 
00142 #endif
00143 
00144 #ifdef __cplusplus
00145 extern "C"
00146 {
00147 #endif
00148   
00149 
00150 typedef enum
00151 {
00152   ASSUAN_No_Error = 0,
00153   ASSUAN_General_Error = 1,
00154   ASSUAN_Out_Of_Core = 2,
00155   ASSUAN_Invalid_Value = 3,
00156   ASSUAN_Timeout = 4,
00157   ASSUAN_Read_Error = 5,
00158   ASSUAN_Write_Error = 6,
00159   ASSUAN_Problem_Starting_Server = 7,
00160   ASSUAN_Not_A_Server = 8,
00161   ASSUAN_Not_A_Client = 9,
00162   ASSUAN_Nested_Commands = 10,
00163   ASSUAN_Invalid_Response = 11,
00164   ASSUAN_No_Data_Callback = 12,
00165   ASSUAN_No_Inquire_Callback = 13,
00166   ASSUAN_Connect_Failed = 14,
00167   ASSUAN_Accept_Failed = 15,
00168 
00169   /* error codes above 99 are meant as status codes */
00170   ASSUAN_Not_Implemented = 100,
00171   ASSUAN_Server_Fault    = 101,
00172   ASSUAN_Invalid_Command = 102,
00173   ASSUAN_Unknown_Command = 103,
00174   ASSUAN_Syntax_Error    = 104,
00175   ASSUAN_Parameter_Error = 105,
00176   ASSUAN_Parameter_Conflict = 106,
00177   ASSUAN_Line_Too_Long = 107,
00178   ASSUAN_Line_Not_Terminated = 108,
00179   ASSUAN_No_Input = 109,
00180   ASSUAN_No_Output = 110,
00181   ASSUAN_Canceled = 111,
00182   ASSUAN_Unsupported_Algorithm = 112,
00183   ASSUAN_Server_Resource_Problem = 113,
00184   ASSUAN_Server_IO_Error = 114,
00185   ASSUAN_Server_Bug = 115,
00186   ASSUAN_No_Data_Available = 116,
00187   ASSUAN_Invalid_Data = 117,
00188   ASSUAN_Unexpected_Command = 118,
00189   ASSUAN_Too_Much_Data = 119,
00190   ASSUAN_Inquire_Unknown = 120,
00191   ASSUAN_Inquire_Error = 121,
00192   ASSUAN_Invalid_Option = 122,
00193   ASSUAN_Invalid_Index = 123,
00194   ASSUAN_Unexpected_Status = 124,
00195   ASSUAN_Unexpected_Data = 125,
00196   ASSUAN_Invalid_Status = 126,
00197 
00198   ASSUAN_Not_Confirmed = 128,
00199 
00200   ASSUAN_Bad_Certificate = 201,
00201   ASSUAN_Bad_Certificate_Chain = 202,
00202   ASSUAN_Missing_Certificate = 203,
00203   ASSUAN_Bad_Signature = 204,
00204   ASSUAN_No_Agent = 205,
00205   ASSUAN_Agent_Error = 206,
00206   ASSUAN_No_Public_Key = 207,
00207   ASSUAN_No_Secret_Key = 208,
00208   ASSUAN_Invalid_Name = 209,
00209 
00210   ASSUAN_Cert_Revoked = 301,
00211   ASSUAN_No_CRL_For_Cert = 302,
00212   ASSUAN_CRL_Too_Old = 303,
00213   ASSUAN_Not_Trusted = 304,
00214 
00215   ASSUAN_Card_Error = 401,
00216   ASSUAN_Invalid_Card = 402,
00217   ASSUAN_No_PKCS15_App = 403,
00218   ASSUAN_Card_Not_Present = 404,
00219   ASSUAN_Invalid_Id = 405
00220 
00221 } AssuanError;
00222 
00223 /* This is a list of pre-registered ASSUAN commands */
00224 typedef enum
00225 {
00226   ASSUAN_CMD_NOP = 0,
00227   ASSUAN_CMD_CANCEL,    /* cancel the current request */
00228   ASSUAN_CMD_BYE,
00229   ASSUAN_CMD_AUTH,
00230   ASSUAN_CMD_RESET,
00231   ASSUAN_CMD_OPTION,
00232   ASSUAN_CMD_DATA,
00233   ASSUAN_CMD_END,
00234   ASSUAN_CMD_INPUT,
00235   ASSUAN_CMD_OUTPUT,
00236 
00237   ASSUAN_CMD_USER = 256  /* Other commands should be used with this offset*/
00238 } AssuanCommand;
00239 
00240 #define ASSUAN_LINELENGTH 1002 /* 1000 + [CR,]LF */
00241 
00242 struct assuan_context_s;
00243 typedef struct assuan_context_s *ASSUAN_CONTEXT;
00244 
00245 /*-- assuan-handler.c --*/
00246 int assuan_register_command (ASSUAN_CONTEXT ctx,
00247                              const char *cmd_string,
00248                              int (*handler)(ASSUAN_CONTEXT, char *));
00249 int assuan_register_bye_notify (ASSUAN_CONTEXT ctx,
00250                                 void (*fnc)(ASSUAN_CONTEXT));
00251 int assuan_register_reset_notify (ASSUAN_CONTEXT ctx,
00252                                   void (*fnc)(ASSUAN_CONTEXT));
00253 int assuan_register_cancel_notify (ASSUAN_CONTEXT ctx,
00254                                    void (*fnc)(ASSUAN_CONTEXT));
00255 int assuan_register_input_notify (ASSUAN_CONTEXT ctx,
00256                                   void (*fnc)(ASSUAN_CONTEXT, const char *));
00257 int assuan_register_output_notify (ASSUAN_CONTEXT ctx,
00258                                   void (*fnc)(ASSUAN_CONTEXT, const char *));
00259 
00260 int assuan_register_option_handler (ASSUAN_CONTEXT ctx,
00261                                     int (*fnc)(ASSUAN_CONTEXT,
00262                                                const char*, const char*));
00263 
00264 int assuan_process (ASSUAN_CONTEXT ctx);
00265 int assuan_process_next (ASSUAN_CONTEXT ctx);
00266 int assuan_get_active_fds (ASSUAN_CONTEXT ctx, int what,
00267                            int *fdarray, int fdarraysize);
00268 
00269 
00270 FILE *assuan_get_data_fp (ASSUAN_CONTEXT ctx);
00271 AssuanError assuan_set_okay_line (ASSUAN_CONTEXT ctx, const char *line);
00272 void assuan_write_status (ASSUAN_CONTEXT ctx,
00273                           const char *keyword, const char *text);
00274 
00275 /* Negotiate a file descriptor.  If LINE contains "FD=N", returns N
00276    assuming a local file descriptor.  If LINE contains "FD" reads a
00277    file descriptor via CTX and stores it in *RDF (the CTX must be
00278    capable of passing file descriptors).  */
00279 AssuanError assuan_command_parse_fd (ASSUAN_CONTEXT ctx, char *line,
00280                      int *rfd);
00281 
00282 /*-- assuan-listen.c --*/
00283 AssuanError assuan_set_hello_line (ASSUAN_CONTEXT ctx, const char *line);
00284 AssuanError assuan_accept (ASSUAN_CONTEXT ctx);
00285 int assuan_get_input_fd (ASSUAN_CONTEXT ctx);
00286 int assuan_get_output_fd (ASSUAN_CONTEXT ctx);
00287 AssuanError assuan_close_input_fd (ASSUAN_CONTEXT ctx);
00288 AssuanError assuan_close_output_fd (ASSUAN_CONTEXT ctx);
00289 
00290 
00291 /*-- assuan-pipe-server.c --*/
00292 int assuan_init_pipe_server (ASSUAN_CONTEXT *r_ctx, int filedes[2]);
00293 void assuan_deinit_server (ASSUAN_CONTEXT ctx);
00294 
00295 /*-- assuan-socket-server.c --*/
00296 int assuan_init_socket_server (ASSUAN_CONTEXT *r_ctx, int listen_fd);
00297 int assuan_init_connected_socket_server (ASSUAN_CONTEXT *r_ctx, int fd);
00298 
00299 
00300 /*-- assuan-pipe-connect.c --*/
00301 AssuanError assuan_pipe_connect (ASSUAN_CONTEXT *ctx, const char *name,
00302                                  char *const argv[], int *fd_child_list);
00303 /*-- assuan-socket-connect.c --*/
00304 AssuanError assuan_socket_connect (ASSUAN_CONTEXT *ctx, const char *name,
00305                                    pid_t server_pid);
00306 
00307 /*-- assuan-domain-connect.c --*/
00308 
00309 /* Connect to a Unix domain socket server.  RENDEZVOUSFD is
00310    bidirectional file descriptor (normally returned via socketpair)
00311    which the client can use to rendezvous with the server.  SERVER s
00312    the server's pid.  */
00313 AssuanError assuan_domain_connect (ASSUAN_CONTEXT *r_ctx,
00314                    int rendezvousfd,
00315                    pid_t server);
00316 
00317 /*-- assuan-domain-server.c --*/
00318 
00319 /* RENDEZVOUSFD is a bidirectional file descriptor (normally returned
00320    via socketpair) that the domain server can use to rendezvous with
00321    the client.  CLIENT is the client's pid.  */
00322 AssuanError assuan_init_domain_server (ASSUAN_CONTEXT *r_ctx,
00323                        int rendezvousfd,
00324                        pid_t client);
00325 
00326 
00327 /*-- assuan-connect.c --*/
00328 void assuan_disconnect (ASSUAN_CONTEXT ctx);
00329 pid_t assuan_get_pid (ASSUAN_CONTEXT ctx);
00330 
00331 /*-- assuan-client.c --*/
00332 AssuanError 
00333 assuan_transact (ASSUAN_CONTEXT ctx,
00334                  const char *command,
00335                  AssuanError (*data_cb)(void *, const void *, size_t),
00336                  void *data_cb_arg,
00337                  AssuanError (*inquire_cb)(void*, const char *),
00338                  void *inquire_cb_arg,
00339                  AssuanError (*status_cb)(void*, const char *),
00340                  void *status_cb_arg);
00341 
00342 
00343 /*-- assuan-inquire.c --*/
00344 AssuanError assuan_inquire (ASSUAN_CONTEXT ctx, const char *keyword,
00345                             char **r_buffer, size_t *r_length, size_t maxlen);
00346 
00347 /*-- assuan-buffer.c --*/
00348 AssuanError assuan_read_line (ASSUAN_CONTEXT ctx,
00349                               char **line, size_t *linelen);
00350 int assuan_pending_line (ASSUAN_CONTEXT ctx);
00351 AssuanError assuan_write_line (ASSUAN_CONTEXT ctx, const char *line );
00352 AssuanError assuan_send_data (ASSUAN_CONTEXT ctx,
00353                               const void *buffer, size_t length);
00354 
00355 /* The file descriptor must be pending before assuan_receivefd is
00356    call.  This means that assuan_sendfd should be called *before* the
00357    trigger is sent (normally via assuan_send_data ("I sent you a
00358    descriptor")).  */
00359 AssuanError assuan_sendfd (ASSUAN_CONTEXT ctx, int fd);
00360 AssuanError assuan_receivefd (ASSUAN_CONTEXT ctx, int *fd);
00361 
00362 /*-- assuan-util.c --*/
00363 void assuan_set_malloc_hooks ( void *(*new_alloc_func)(size_t n),
00364                                void *(*new_realloc_func)(void *p, size_t n),
00365                                void (*new_free_func)(void*) );
00366 void assuan_set_log_stream (ASSUAN_CONTEXT ctx, FILE *fp);
00367 int assuan_set_error (ASSUAN_CONTEXT ctx, int err, const char *text);
00368 void assuan_set_pointer (ASSUAN_CONTEXT ctx, void *pointer);
00369 void *assuan_get_pointer (ASSUAN_CONTEXT ctx);
00370 
00371 void assuan_begin_confidential (ASSUAN_CONTEXT ctx);
00372 void assuan_end_confidential (ASSUAN_CONTEXT ctx);
00373 
00374 /*-- assuan-errors.c (built) --*/
00375 const char *assuan_strerror (AssuanError err);
00376 
00377 /*-- assuan-logging.c --*/
00378 
00379 /* Set the stream to which assuan should log.  By default, this is
00380    stderr.  */
00381 extern void assuan_set_assuan_log_stream (FILE *fp);
00382 
00383 /* Return the stream which is currently being using for logging.  */
00384 extern FILE *assuan_get_assuan_log_stream (void);
00385 
00386 /* User defined call back.  Return a prefix to be used at the start of
00387    a line emitted by assuan on the log stream.  The default
00388    implementation returns the empty string, i.e. ""  */
00389 extern const char *assuan_get_assuan_log_prefix (void);
00390 
00391 #ifdef __cplusplus
00392 }
00393 #endif
00394 #endif /* ASSUAN_H */
KDE Logo
This file is part of the documentation for libkdenetwork Library Version 3.3.2.
Documentation copyright © 1996-2004 the KDE developers.
Generated on Wed Oct 17 09:52:19 2007 by doxygen 1.4.2 written by Dimitri van Heesch, © 1997-2003