Added stuff to the manual. Minor prototype cleanups.

3 files changed, 262 insertions, 14 deletions

diff --git a/doc/assuan.texi b/doc/assuan.texi
index 7404709..0d804e6 100644
--- a/doc/assuan.texi
+++ b/doc/assuan.texi
@@ -3,7 +3,7 @@
 @setfilename assuan.info
 
 @macro copyrightnotice
-Copyright @copyright{} 2002, 2003 Free Software Foundation, Inc.
+Copyright @copyright{} 2002, 2003, 2006 Free Software Foundation, Inc.
 @end macro
 @macro permissionnotice
 Permission is granted to copy, distribute and/or modify this document
@@ -26,6 +26,11 @@ section entitled ``Copying''.
 @syncodeindex pg cp
 @syncodeindex tp cp
 
+@c A simple macro for optional variables.
+@macro ovar{varname}
+@r{[}@var{\varname\}@r{]}
+@end macro
+
 @c printing stuff taken from gcc.
 @macro gnupgtabopt{body}
 @code{\body\}
@@ -106,6 +111,11 @@ interprocess communcation library.
 * Introduction::        An introduction to and the motivation behind Assuan.
 * Assuan::              Description of the Assuan protocol.
 * Implementation::      Overview of the implementation.
+* Preparation::         What you should do before using the library.
+* Generalities::        Initialization code and data types used.
+* Client code::         How to develop an Assuan client.
+* Server code::         How to develop an Assuan server.
+* Utilities::           Utility functions.
 
 Miscellaneous
 
@@ -115,13 +125,14 @@ Miscellaneous
 
 Indices
 
-* Option Index::        Index to command line options.
 * Index::	        Index of concepts and symbol names.
 
 @end menu
 
 
-
+@c
+@c   I N T R O
+@c
 @node Introduction
 @chapter Introduction to Assuan
 
@@ -414,6 +425,248 @@ and may also be used by applications --- note that the GnuPG system
 maps libgpg-error codes into this range.
 
 
+@c 
+@c           P R E P A R A T I O N
+@c
+@node Preparation
+@chapter Preparation
+
+To use `@sc{libassuan}', you have to perform some changes to your
+sources and the build system.  The necessary changes are small and
+explained in the following sections. 
+
+
+@menu
+* Header::                 What header file you need to include.
+* Building sources::       How to build sources using the library.
+* Automake::               How to build sources with the help of Automake.
+* Multi Threading::        How @sc{libassuan} can be used in a MT environment.
+@end menu
+
+@node Header
+@section Header
+
+All interfaces (data types and functions) of @sc{libassuan} are defined
+in the header file @file{assuan.h}.  You must include this in all source
+files using the library, either directly or through some other header
+file, like this:
+
+@example
+#include <assuan.h>
+@end example
+
+The name space of `@sc{assuan}' is @code{assuan_*} for function
+and type names and @code{ASSUAN*} for other symbols.  In addition the
+same name prefixes with one prepended underscore are reserved for
+internal use and should never be used by an application. 
+
+@node Building sources
+@section Building sources
+
+If you want to compile a source file including the @file{assuan.h}
+header file, you must make sure that the compiler can find it in the
+directory hierarchy.  This is accomplished by adding the path to the
+directory in which the header file is located to the compilers include
+file search path (via the @option{-I} option).
+
+However, the path to the include file is determined at the time the
+source is configured.  To solve this problem, @sc{libgcrypt} ships with
+a small helper program @command{libassuan-config} that knows the path to
+the include file and other configuration options.  The options that need
+to be added to the compiler invocation at compile time are output by the
+@option{--cflags} option to @command{libassuan-config}.  The following
+example shows how it can be used at the command line:
+
+@example
+gcc -c foo.c $(libassuan-config --cflags)
+@end example
+
+Adding the output of @samp{libassuan-config --cflags} to the compiler's
+command line will ensure that the compiler can find the @file{assuan.h}
+header file.
+
+A similar problem occurs when linking the program with the library.
+Again, the compiler/linker has to find the library files.  For this to
+work, the path to the library files has to be added to the library
+search path (via the @option{-L} option).  For this, the option
+@option{--libs} to @command{libassuan-config} can be used.  For
+convenience, this option also outputs all other options that are
+required to link the program with the @sc{libassuan} libraries (in
+particular, the @option{-lassuan} option).  The example shows how to
+link @file{foo.o} with the @sc{libassuan} library to a program
+@command{foo}.
+
+@example
+gcc -o foo foo.o $(libassuan-config --libs)
+@end example
+
+Of course you can also combine both examples to a single command by
+specifying both options to @command{libassuan-config}:
+
+@example
+gcc -o foo foo.c $(libassuan-config --cflags --libs)
+@end example
+
+@node Automake
+@section Building sources using Automake
+
+It is much easier if you use GNU Automake instead of writing your own
+Makefiles.  If you do that you do not have to worry about finding and
+invoking the @command{libassuan-config} script at all.  @sc{libassuan}
+provides an Automake macro that does all the work for you.
+
+@defmac AM_PATH_LIBASSUAN (@ovar{minimum-version}, @ovar{action-if-found}, @ovar{action-if-not-found})
+Check whether @sc{libassuan} (at least version @var{minimum-version}, if
+given) exists on the host system.  If it is found, execute
+@var{action-if-found}, otherwise do @var{action-if-not-found}, if given.
+
+Additionally, the function defines @code{LIBASSUAN_CFLAGS} to the
+flags needed for compilation of the program to find the
+@file{assuan.h} header file, and @code{LIBASSUAN_LIBS} to the linker
+flags needed to link the program to the @sc{libassuan} library.
+@end defmac
+
+You can use the defined Autoconf variables like this in your
+@file{Makefile.am}:
+
+@example
+AM_CPPFLAGS = $(LIBASSUAN_CFLAGS)
+LDADD = $(LIBASSUAN_LIBS)
+@end example
+
+
+@node Multi Threading
+@section Multi Threading
+
+The @sc{libgcrypt} library is thread-safe if you adhere to the following
+requirements:
+
+@itemize @bullet
+@item Run the initialization functions before you actually start
+to use threads.
+@item Only one thread at a time may access an @sc{libassuan} context.
+@item Use @code{assuan_set_assuan_log_stream} to setup a default log stream.
+@end itemize
+
+
+@c 
+@c     G E N E R A L I T I E S
+@c
+@node Generalities
+@chapter Generalities
+
+@menu
+* Data Types::                  Data types used by @sc{libassuan}.
+* Initializing the library::    How to initialize the library.
+@end menu
+
+
+
+@node Data Types
+@section Data Types used by the library
+
+@sc{libassuan} uses a context approach to keep state.  The following
+data type is used all over the palce:
+
+@deftp {Data type} assuan_context_t
+The @code{assuan_context_t} type is a pointer to an object mainted
+internally by the library.  Certain assuan fucntions allocate such a
+context and return it to the caller using this data type. Other
+functions take this data type to access the state created by these
+functions.
+@end deftp
+
+For compatibility with older versions of @sc{libassuan} a data
+type for error return values exists:
+
+@deftp {Data type} assuan_error_t
+This has orginally been an @code{enum} but applications should either
+view it as an @code{int} or if possible use the @code{gpg_error_t} data
+type as defined by the @sc{libgpg-error} package.
+@end deftp
+
+
+@node Initializing the library
+@section Initializing the library
+
+In general the library requires no initialization.  There are however
+some initialization hooks provided which aren often useful.  These
+should be called as early as possible and in a multi-threaded
+application before a second thread is created. 
+
+If your application uses its own memory allocation functions or wrappers
+it is good idea to tell @sc{libassuan} about it so it can make use of the
+same functions or wrappers.  You do this with
+
+@deftypefun void assuan_set_malloc_hooks (@w{void *(*@var{malloc_func})(size_t)}, @w{void *(*@var{realloc_func})(void *, size_t)}, @w{void (*@var{free_func})(void*)})
+You need to provide all three functions.  Those functions need to behave
+exactly as their standard counterparts (@code{malloc}, @code{realloc}
+and @code{free}).  If you write your own functions please take care to
+set @code{errno} whenever an error has occured.
+@end deftypefun
+
+To integrate assuan logging and diagnostics into your own logging
+system, you may use the following two functions:
+
+@deftypefun void assuan_set_assuan_log_stream (FILE *@var{fp})
+This sets the stream to which @sc{libassuan} should log messages not
+associated with a specific context to @var{fp}.  The default is to log
+to @code{stderr}.  This default value is also changed by using
+@code{assuan_set_log_stream} (to set a logging stream for a specific
+context) unless this function has been used.  Obviously this is not
+thread-asfe and thus it is highly recommended to use this function to
+setup a proper default.
+@end deftypefun
+
+@deftypefun void assuan_set_assuan_log_prefix (const char *@var{text})
+Set the prefix to be used at the start of a line emitted by assuan
+on the log stream to @var{text}.  The default is the empty string. 
+@end deftypefun
+
+If you intend to use @sc{libassuan} along with the package
+@sc{libgpg-error} it is recommended to switch @sc{libassuan} into a mode
+which directly makes use of error codes provided by @sc{libgpg-error}.
+Because the Assuan error codes and those of gpg-error overlap, it is
+required to explictly request this.  You do this by calling the function
+
+@deftypefun void assuan_set_assuan_err_source (int @var{errsource})
+Enable gpg-error style error codes.  @var{errsource} is one of the
+gpg-error sources.  Switching back to the old style mode is not
+possible.  The usual way to call this function is
+@smallexample
+assuan_set_assuan_err_source (GPG_ERR_SOURCE_DEFAULT);
+@end smallexample
+@end deftypefun
+
+@c 
+@c     C L I E N T   C O D E
+@c
+@node Client code
+@chapter How to develop an Assuan client
+
+foo
+
+
+@c 
+@c     S E R V E R   C O D E
+@c
+@node Server code
+@chapter How to develop an Assuan server
+
+bar
+
+@c
+@c     U T I L I T I E S
+@c
+@node Utilities
+@chapter Utility functions
+
+baz
+
+
+@c ---------------------------------------------------------------------
+@c Legal BS
+@c ---------------------------------------------------------------------
 
 @include lgpl.texi
 @include gpl.texi
@@ -423,11 +676,6 @@ maps libgpg-error codes into this range.
 @c Indexes
 @c ---------------------------------------------------------------------
 
-@node Option Index
-@unnumbered Option Index
-
-@printindex op
-
 @node Index
 @unnumbered Index
 
diff --git a/src/assuan-client.c b/src/assuan-client.c
index d8f1cee..cf85ddf 100644
--- a/src/assuan-client.c
+++ b/src/assuan-client.c
@@ -132,11 +132,11 @@ _assuan_read_from_server (ASSUAN_CONTEXT ctx, int *okay, int *off)
 assuan_error_t
 assuan_transact (ASSUAN_CONTEXT ctx,
                  const char *command,
-                 assuan_error_t (*data_cb)(void *, const void *, size_t),
+                 int (*data_cb)(void *, const void *, size_t),
                  void *data_cb_arg,
-                 assuan_error_t (*inquire_cb)(void*, const char *),
+                 int (*inquire_cb)(void*, const char *),
                  void *inquire_cb_arg,
-                 assuan_error_t (*status_cb)(void*, const char *),
+                 int (*status_cb)(void*, const char *),
                  void *status_cb_arg)
 {
   int rc, okay, off;
diff --git a/src/assuan.h b/src/assuan.h
index 8553ab0..b85e642 100644
--- a/src/assuan.h
+++ b/src/assuan.h
@@ -408,11 +408,11 @@ pid_t assuan_get_pid (assuan_context_t ctx);
 assuan_error_t 
 assuan_transact (assuan_context_t ctx,
                  const char *command,
-                 assuan_error_t (*data_cb)(void *, const void *, size_t),
+                 int (*data_cb)(void *, const void *, size_t),
                  void *data_cb_arg,
-                 assuan_error_t (*inquire_cb)(void*, const char *),
+                 int (*inquire_cb)(void*, const char *),
                  void *inquire_cb_arg,
-                 assuan_error_t (*status_cb)(void*, const char *),
+                 int (*status_cb)(void*, const char *),
                  void *status_cb_arg);