diff options
| -rw-r--r-- | NEWS | 4 | ||||
| -rw-r--r-- | TODO | 3 | ||||
| -rw-r--r-- | configure.ac | 2 | ||||
| -rw-r--r-- | doc/ChangeLog | 8 | ||||
| -rw-r--r-- | doc/Makefile.am | 2 | ||||
| -rw-r--r-- | doc/assuan.texi | 123 | ||||
| -rw-r--r-- | src/ChangeLog | 7 | ||||
| -rw-r--r-- | src/assuan.h | 53 |
8 files changed, 154 insertions, 48 deletions
@@ -1,4 +1,4 @@ -Noteworthy changes in version 0.6.2 (unreleased) +Noteworthy changes in version 0.6.2 (2003-12-18) ------------------------------------------------ * New function assuan_set_assuan_log_prefix to store a log prefix to @@ -6,6 +6,8 @@ Noteworthy changes in version 0.6.2 (unreleased) assuan_get_assuan_log_context is not anymore declared as user overridable. + * Documentation cleanups. + Noteworthy changes in version 0.6.1 (2003-11-17) ------------------------------------------------ @@ -1,4 +1,5 @@ * waitpid is used instead of pth_waitpid as well as some other functions. * When turning libassuan into a shared library, provide a general - version as well as aPTh-enabled one.
\ No newline at end of file + version as well as aPTh-enabled one. +* Need API documentation.
\ No newline at end of file diff --git a/configure.ac b/configure.ac index 1b2c672..79a8be4 100644 --- a/configure.ac +++ b/configure.ac @@ -23,7 +23,7 @@ min_automake_version="1.7.6" # Version number: Remember to change it immediately *after* a release. # Add a "-cvs" prefix for non-released code. -AC_INIT(libassuan, 0.6.2-cvs, gnupg-devel@gnupg.org) +AC_INIT(libassuan, 0.6.2, gnupg-devel@gnupg.org) # Note, that this is not yet available as a shared library. PACKAGE=$PACKAGE_NAME diff --git a/doc/ChangeLog b/doc/ChangeLog index d92b425..f39c5b1 100644 --- a/doc/ChangeLog +++ b/doc/ChangeLog @@ -1,3 +1,11 @@ +2003-12-18 Werner Koch <wk@gnupg.org> + + * assuan.texi: Changed copyright to GPL because this is not a book + but useful documentation in other software too. Reworked + sectioning, updated list of error codes. + * gpl.texi: Added. + * fdl.texi: Removed. + 2003-08-06 Werner Koch <wk@gnupg.org> * lgpl.texi: New. diff --git a/doc/Makefile.am b/doc/Makefile.am index 38a204a..039ef2f 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -21,5 +21,5 @@ info_TEXINFOS = assuan.texi -assuan_TEXINFOS = lgpl.texi fdl.texi +assuan_TEXINFOS = lgpl.texi gpl.texi diff --git a/doc/assuan.texi b/doc/assuan.texi index f8671f3..cfb2d4c 100644 --- a/doc/assuan.texi +++ b/doc/assuan.texi @@ -7,13 +7,13 @@ Copyright @copyright{} 2002, 2003 Free Software Foundation, Inc. @end macro @macro permissionnotice Permission is granted to copy, distribute and/or modify this document -under the terms of the GNU Free Documentation License, Version 1.1 or -any later version published by the Free Software Foundation; with no -Invariant Sections, with no Front-Cover texts, and with no Back-Cover -texts. A copy of the license is included in the section entitled -``GNU Free Documentation License''. +under the terms of the GNU General Public License as published by the +Free Software Foundation; either version 2 of the License, or (at your +option) any later version. The text of the license can be found in the +section entitled ``Copying''. @end macro +@include version.texi @settitle Developing with Assuan @@ -93,31 +93,34 @@ Boston, MA 02111-1307 USA @page +@ifnottex @node Top @top Introduction @cindex introduction This manual documents how to exploit the Assuan library, a simple interprocess communcation library. +@end ifnottex @menu * Introduction:: An introduction to and the motivation behind Assuan. * Assuan:: Description of the Assuan protocol. +* Implementation:: Overview of the implementation. Miscellaneous * Library Copying:: GNU Lesser General Public License says - how you can copy and share Assuan -* GNU Free Documentation License:: How you can copy and share this manual. + how you can copy and share Assuan. +* Copying:: How you can copy and share this manual. Indices * Option Index:: Index to command line options. * Index:: Index of concepts and symbol names. + @end menu -@include lgpl.texi -@include fdl.texi + @node Introduction @chapter Introduction to Assuan @@ -169,7 +172,7 @@ Goals: @itemize @bullet @item Common framework for module communication @item Easy debugging -@item Easy module testing +@item Easy module testing @item Extendible @item Optional authentication and encryption facility @item Usable by access external hardware @@ -190,7 +193,8 @@ Design criteria: @item Subliminal channels are not an issue @end itemize -Implementation: +@node Implementation +@chapter Implementation The implementation is line based with a maximum line size of 1000 octects. The default IPC mechanism are Unix Domain Sockets. @@ -211,7 +215,15 @@ state. All textual messages are assumed to be in UTF-8 unless otherwise noted. -Server responses: +@menu +* Server responses:: Description of server responses. +* Client requests:: Description of client requests. +* Error codes:: List of error and status codes. +@end menu + + +@node Server responses +@section Server responses @table @code @item OK [<arbitary debugging information>] @@ -252,11 +264,11 @@ treated as a communication error. (The rationale for having a line length limit is to allow for easier multiplexing of multiple channels). -Client requests: +@node Client requests +@section Client requests The server waits for client requests after he sent an Okay or Error. -The client should not issue a request in other cases with the -exception of the CANCEL command. +The client should not issue a request in other cases. @example @var{command} <parameters> @@ -303,9 +315,8 @@ all protocols and partly directly supported by the Assuan library: @table @code @item CANCEL -This is the one special command which aborts the current request. It can -be sent at any time and the server will stop its operation right before -it would send the next response line (of any type). +This command is used for future extenxions. It may today be used to +cancel outstanding requests in an asynchronous protocol. @item BYE Close the connect, the server will reply with an @code{OK}. @@ -322,23 +333,91 @@ should release all resources associated with the connection. @item END Used by a client to mark the end of raw data. The server may send END to indicate a partial end of data. + +@item HELP +Reserved for future extensions. + +@item QUIT +Reserved for future extensions. + @end table -Error Codes: +@node Error codes +@section Error codes Here we keep a list of error codes used in any Assuan based protocol. The format is the string @code{ERR}, white space, the error number, white space, a textual description of the error. -@table @code +General error codes pertaining to the actual Assuan operations: -@item 100 Unknown Command -@item 101 Not Implemented +@table @code +@item 0 Success +@item 1 General error +@item 2 Out of core +@item 3 Invalid value +@item 4 Timeout +@item 5 Read error +@item 6 Write error +@item 7 Problem starting server +@item 8 Not a server +@item 9 Not a client +@item 10 Nested commands +@item 11 Invalid response +@item 12 No data callback +@item 13 No inquire callback +@item 14 Connect failed +@item 15 Accept failed +@end table +Error codes used as status codes in the Assuan protocol: +@table @code +@item 100 Not implemented +@item 101 Server fault (catch all error code) +@item 102 Invalid command +@item 103 Unknown command +@item 104 Syntax error +@item 105 Parameter error +@item 106 Parameter conflict +@item 107 Line too long +@item 108 Line not terminated +@item 109 No input +@item 110 No output +@item 111 Canceled +@item 112 Unsupported algorithm +@item 113 Server resource problem +@item 114 Server I/O error +@item 115 Server bug +@item 116 No data available +@item 117 Invalid data +@item 118 Unexpected command +@item 119 Too much data +@item 120 Inquire unknown +@item 121 Inquire error +@item 122 Invalid option +@item 123 Invalid index +@item 124 Unexpected status +@item 125 Unexpected data +@item 126 Invalid status +@item 128 Not confirmed @end table +For historical reasons a few more error codes are defined in +@file{assuan.h}; they should not be used be new applications. + +Errror codes in the range @var{ASSUAN_USER_ERROR_FIRST} to +@var{ASSUAN_USER_ERROR_LAST} may be used at the applications own +discretion. Error codes greater than 65535 are not defined by Assuan +and may also be used by applications --- note that the GnuPG system +maps libgpg-error codes into this range. + + + +@include lgpl.texi +@include gpl.texi + @c --------------------------------------------------------------------- @c Indexes diff --git a/src/ChangeLog b/src/ChangeLog index bb61f3e..2b2f768 100644 --- a/src/ChangeLog +++ b/src/ChangeLog @@ -1,3 +1,10 @@ +2003-12-18 Werner Koch <wk@gnupg.org> + + * assuan.h (AssuanCommand): Clarified that these are now + deprecated and actually useless. + (assuan_error_t): Clarified and added ASSUAN_USER_ERROR_FIRST, + ASSUAN_USER_ERROR_LAST. + 2003-12-16 Werner Koch <wk@gnupg.org> * assuan-buffer.c: Changed formatting of the debug output prefix. diff --git a/src/assuan.h b/src/assuan.h index 261a752..c5598bc 100644 --- a/src/assuan.h +++ b/src/assuan.h @@ -52,7 +52,7 @@ typedef enum ASSUAN_Connect_Failed = 14, ASSUAN_Accept_Failed = 15, - /* error codes above 99 are meant as status codes */ + /* Error codes above 99 are meant as status codes */ ASSUAN_Not_Implemented = 100, ASSUAN_Server_Fault = 101, ASSUAN_Invalid_Command = 102, @@ -83,6 +83,7 @@ typedef enum ASSUAN_Not_Confirmed = 128, + /* Warning: Don't use the rror codes, below they are deprecated. */ ASSUAN_Bad_Certificate = 201, ASSUAN_Bad_Certificate_Chain = 202, ASSUAN_Missing_Certificate = 203, @@ -104,11 +105,18 @@ typedef enum ASSUAN_Card_Not_Present = 404, ASSUAN_Invalid_Id = 405 + /* Error codes in the range 1000 to 9999 may be used by applications + at their own discretion. */ + ASSUAN_USER_ERROR_FIRST = 1000, + ASSUAN_USER_ERROR_LAST = 9999 + } assuan_error_t; typedef assuan_error_t AssuanError; /* Deprecated. */ /* This is a list of pre-registered ASSUAN commands */ +/* NOTE, these command IDs are now deprectated and solely exists for + compatibility reasons. */ typedef enum { ASSUAN_CMD_NOP = 0, @@ -125,6 +133,7 @@ typedef enum ASSUAN_CMD_USER = 256 /* Other commands should be used with this offset*/ } AssuanCommand; + #define ASSUAN_LINELENGTH 1002 /* 1000 + [CR,]LF */ struct assuan_context_s; @@ -157,7 +166,7 @@ int assuan_get_active_fds (assuan_context_t ctx, int what, FILE *assuan_get_data_fp (assuan_context_t ctx); -AssuanError assuan_set_okay_line (assuan_context_t ctx, const char *line); +assuan_error_t assuan_set_okay_line (assuan_context_t ctx, const char *line); void assuan_write_status (assuan_context_t ctx, const char *keyword, const char *text); @@ -165,16 +174,16 @@ void assuan_write_status (assuan_context_t ctx, assuming a local file descriptor. If LINE contains "FD" reads a file descriptor via CTX and stores it in *RDF (the CTX must be capable of passing file descriptors). */ -AssuanError assuan_command_parse_fd (assuan_context_t ctx, char *line, +assuan_error_t assuan_command_parse_fd (assuan_context_t ctx, char *line, int *rfd); /*-- assuan-listen.c --*/ -AssuanError assuan_set_hello_line (assuan_context_t ctx, const char *line); -AssuanError assuan_accept (assuan_context_t ctx); +assuan_error_t assuan_set_hello_line (assuan_context_t ctx, const char *line); +assuan_error_t assuan_accept (assuan_context_t ctx); int assuan_get_input_fd (assuan_context_t ctx); int assuan_get_output_fd (assuan_context_t ctx); -AssuanError assuan_close_input_fd (assuan_context_t ctx); -AssuanError assuan_close_output_fd (assuan_context_t ctx); +assuan_error_t assuan_close_input_fd (assuan_context_t ctx); +assuan_error_t assuan_close_output_fd (assuan_context_t ctx); /*-- assuan-pipe-server.c --*/ @@ -187,10 +196,10 @@ int assuan_init_connected_socket_server (assuan_context_t *r_ctx, int fd); /*-- assuan-pipe-connect.c --*/ -AssuanError assuan_pipe_connect (assuan_context_t *ctx, const char *name, +assuan_error_t assuan_pipe_connect (assuan_context_t *ctx, const char *name, char *const argv[], int *fd_child_list); /*-- assuan-socket-connect.c --*/ -AssuanError assuan_socket_connect (assuan_context_t *ctx, const char *name, +assuan_error_t assuan_socket_connect (assuan_context_t *ctx, const char *name, pid_t server_pid); /*-- assuan-domain-connect.c --*/ @@ -199,7 +208,7 @@ AssuanError assuan_socket_connect (assuan_context_t *ctx, const char *name, bidirectional file descriptor (normally returned via socketpair) which the client can use to rendezvous with the server. SERVER s the server's pid. */ -AssuanError assuan_domain_connect (assuan_context_t *r_ctx, +assuan_error_t assuan_domain_connect (assuan_context_t *r_ctx, int rendezvousfd, pid_t server); @@ -208,7 +217,7 @@ AssuanError assuan_domain_connect (assuan_context_t *r_ctx, /* RENDEZVOUSFD is a bidirectional file descriptor (normally returned via socketpair) that the domain server can use to rendezvous with the client. CLIENT is the client's pid. */ -AssuanError assuan_init_domain_server (assuan_context_t *r_ctx, +assuan_error_t assuan_init_domain_server (assuan_context_t *r_ctx, int rendezvousfd, pid_t client); @@ -218,36 +227,36 @@ void assuan_disconnect (assuan_context_t ctx); pid_t assuan_get_pid (assuan_context_t ctx); /*-- assuan-client.c --*/ -AssuanError +assuan_error_t assuan_transact (assuan_context_t ctx, const char *command, - AssuanError (*data_cb)(void *, const void *, size_t), + assuan_error_t (*data_cb)(void *, const void *, size_t), void *data_cb_arg, - AssuanError (*inquire_cb)(void*, const char *), + assuan_error_t (*inquire_cb)(void*, const char *), void *inquire_cb_arg, - AssuanError (*status_cb)(void*, const char *), + assuan_error_t (*status_cb)(void*, const char *), void *status_cb_arg); /*-- assuan-inquire.c --*/ -AssuanError assuan_inquire (assuan_context_t ctx, const char *keyword, +assuan_error_t assuan_inquire (assuan_context_t ctx, const char *keyword, unsigned char **r_buffer, size_t *r_length, size_t maxlen); /*-- assuan-buffer.c --*/ -AssuanError assuan_read_line (assuan_context_t ctx, +assuan_error_t assuan_read_line (assuan_context_t ctx, char **line, size_t *linelen); int assuan_pending_line (assuan_context_t ctx); -AssuanError assuan_write_line (assuan_context_t ctx, const char *line ); -AssuanError assuan_send_data (assuan_context_t ctx, +assuan_error_t assuan_write_line (assuan_context_t ctx, const char *line ); +assuan_error_t assuan_send_data (assuan_context_t ctx, const void *buffer, size_t length); /* The file descriptor must be pending before assuan_receivefd is call. This means that assuan_sendfd should be called *before* the trigger is sent (normally via assuan_send_data ("I sent you a descriptor")). */ -AssuanError assuan_sendfd (assuan_context_t ctx, int fd); -AssuanError assuan_receivefd (assuan_context_t ctx, int *fd); +assuan_error_t assuan_sendfd (assuan_context_t ctx, int fd); +assuan_error_t assuan_receivefd (assuan_context_t ctx, int *fd); /*-- assuan-util.c --*/ void assuan_set_malloc_hooks ( void *(*new_alloc_func)(size_t n), @@ -262,7 +271,7 @@ void assuan_begin_confidential (assuan_context_t ctx); void assuan_end_confidential (assuan_context_t ctx); /*-- assuan-errors.c (built) --*/ -const char *assuan_strerror (AssuanError err); +const char *assuan_strerror (assuan_error_t err); /*-- assuan-logging.c --*/ |