From 86fc3e402aea49b88419b3fc079c1f28f4bf27a7 Mon Sep 17 00:00:00 2001 From: Werner Koch Date: Thu, 18 Dec 2003 16:01:22 +0000 Subject: Getting ready for a new release --- doc/ChangeLog | 8 ++++ doc/Makefile.am | 2 +- doc/assuan.texi | 123 ++++++++++++++++++++++++++++++++++++++++++++++---------- 3 files changed, 110 insertions(+), 23 deletions(-) (limited to 'doc') 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 + + * 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 * 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 [] @@ -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} @@ -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 -- cgit v1.2.1