[svn] assuan - r198 - in trunk: doc src
svn author wk
cvs at cvs.gnupg.org
Mon Sep 11 15:15:49 CEST 2006
Author: wk
Date: 2006-09-11 15:15:48 +0200 (Mon, 11 Sep 2006)
New Revision: 198
Modified:
trunk/doc/assuan.texi
trunk/src/assuan-client.c
trunk/src/assuan.h
Log:
Added stuff to the manual. Minor prototype cleanups.
Modified: trunk/doc/assuan.texi
===================================================================
--- trunk/doc/assuan.texi 2006-09-10 12:24:40 UTC (rev 197)
+++ trunk/doc/assuan.texi 2006-09-11 13:15:48 UTC (rev 198)
@@ -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 @@
@syncodeindex pg cp
@syncodeindex tp cp
+ at c A simple macro for optional variables.
+ at macro ovar{varname}
+ at r{[}@var{\varname\}@r{]}
+ at end macro
+
@c printing stuff taken from gcc.
@macro gnupgtabopt{body}
@code{\body\}
@@ -106,6 +111,11 @@
* 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 @@
Indices
-* Option Index:: Index to command line options.
* Index:: Index of concepts and symbol names.
@end menu
-
+ at c
+ at c I N T R O
+ at c
@node Introduction
@chapter Introduction to Assuan
@@ -414,7 +425,249 @@
maps libgpg-error codes into this range.
+ at c
+ at c P R E P A R A T I O N
+ at c
+ at node Preparation
+ at 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.
+
+
+ at 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.
+ at end menu
+
+ at node Header
+ at 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:
+
+ at example
+#include <assuan.h>
+ at 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.
+
+ at node Building sources
+ at 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
+ at option{--cflags} option to @command{libassuan-config}. The following
+example shows how it can be used at the command line:
+
+ at example
+gcc -c foo.c $(libassuan-config --cflags)
+ at 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
+ at 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
+ at command{foo}.
+
+ at example
+gcc -o foo foo.o $(libassuan-config --libs)
+ at end example
+
+Of course you can also combine both examples to a single command by
+specifying both options to @command{libassuan-config}:
+
+ at example
+gcc -o foo foo.c $(libassuan-config --cflags --libs)
+ at end example
+
+ at node Automake
+ at 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.
+
+ at 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
+ at 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
+ at file{assuan.h} header file, and @code{LIBASSUAN_LIBS} to the linker
+flags needed to link the program to the @sc{libassuan} library.
+ at end defmac
+
+You can use the defined Autoconf variables like this in your
+ at file{Makefile.am}:
+
+ at example
+AM_CPPFLAGS = $(LIBASSUAN_CFLAGS)
+LDADD = $(LIBASSUAN_LIBS)
+ at end example
+
+
+ at node Multi Threading
+ at section Multi Threading
+
+The @sc{libgcrypt} library is thread-safe if you adhere to the following
+requirements:
+
+ at itemize @bullet
+ at item Run the initialization functions before you actually start
+to use threads.
+ at item Only one thread at a time may access an @sc{libassuan} context.
+ at item Use @code{assuan_set_assuan_log_stream} to setup a default log stream.
+ at end itemize
+
+
+ at c
+ at c G E N E R A L I T I E S
+ at c
+ at node Generalities
+ at chapter Generalities
+
+ at menu
+* Data Types:: Data types used by @sc{libassuan}.
+* Initializing the library:: How to initialize the library.
+ at end menu
+
+
+
+ at node Data Types
+ at section Data Types used by the library
+
+ at sc{libassuan} uses a context approach to keep state. The following
+data type is used all over the palce:
+
+ at 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.
+ at end deftp
+
+For compatibility with older versions of @sc{libassuan} a data
+type for error return values exists:
+
+ at 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.
+ at end deftp
+
+
+ at node Initializing the library
+ at 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
+
+ at 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.
+ at end deftypefun
+
+To integrate assuan logging and diagnostics into your own logging
+system, you may use the following two functions:
+
+ at 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
+ at 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.
+ at end deftypefun
+
+ at 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.
+ at end deftypefun
+
+If you intend to use @sc{libassuan} along with the package
+ at 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
+
+ at 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
+ at smallexample
+assuan_set_assuan_err_source (GPG_ERR_SOURCE_DEFAULT);
+ at end smallexample
+ at end deftypefun
+
+ at c
+ at c C L I E N T C O D E
+ at c
+ at node Client code
+ at chapter How to develop an Assuan client
+
+foo
+
+
+ at c
+ at c S E R V E R C O D E
+ at c
+ at node Server code
+ at chapter How to develop an Assuan server
+
+bar
+
+ at c
+ at c U T I L I T I E S
+ at c
+ at node Utilities
+ at chapter Utility functions
+
+baz
+
+
+ at c ---------------------------------------------------------------------
+ at c Legal BS
+ at c ---------------------------------------------------------------------
+
@include lgpl.texi
@include gpl.texi
@@ -423,11 +676,6 @@
@c Indexes
@c ---------------------------------------------------------------------
- at node Option Index
- at unnumbered Option Index
-
- at printindex op
-
@node Index
@unnumbered Index
Modified: trunk/src/assuan-client.c
===================================================================
--- trunk/src/assuan-client.c 2006-09-10 12:24:40 UTC (rev 197)
+++ trunk/src/assuan-client.c 2006-09-11 13:15:48 UTC (rev 198)
@@ -132,11 +132,11 @@
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;
Modified: trunk/src/assuan.h
===================================================================
--- trunk/src/assuan.h 2006-09-10 12:24:40 UTC (rev 197)
+++ trunk/src/assuan.h 2006-09-11 13:15:48 UTC (rev 198)
@@ -408,11 +408,11 @@
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);
More information about the Gnupg-commits
mailing list