Add support for gpg --fetch-keys.
[gpgme.git] / doc / gpgme.texi
index ef4896c..a0bc20e 100644 (file)
@@ -1,4 +1,5 @@
-\input texinfo                  @c -*- Texinfo -*-
+\input texinfo                   @c -*- mode: texinfo; coding: latin-1; -*-
+@documentencoding ISO-8859-1
 @setfilename gpgme.info
 @settitle The `GnuPG Made Easy' Reference Manual
 
@@ -7,12 +8,41 @@
 * @acronym{GPGME}: (gpgme).          Adding support for cryptography to your program.
 @end direntry
 
-@include version.texi
-
 @c Unify some of the indices.
 @syncodeindex tp fn
 @syncodeindex pg fn
 
+@copying
+Copyright @copyright{} 2002, 2003, 2004, 2005, 2006, 2007, 2008 g10 Code GmbH.
+
+@quotation
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU General Public License as published by the
+Free Software Foundation; either version 3 of the License, or (at your
+option) any later version. The text of the license can be found in the
+section entitled ``Copying''.
+@end quotation
+
+This document is distributed in the hope that it will be useful, but
+WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+General Public License for more details.
+@end copying
+
+@include version.texi
+
+@c Macros used by the description of the UI server protocol
+@macro clnt
+  @sc{c:} @c
+@end macro
+@macro srvr
+  @sc{s:} @c
+@end macro
+
+
+@c 
+@c  T I T L E  P A G E
+@c
 @ifinfo
 This file documents the @acronym{GPGME} library.
 
@@ -20,22 +50,15 @@ This is Edition @value{EDITION}, last updated @value{UPDATED}, of
 @cite{The `GnuPG Made Easy' Reference Manual}, for Version
 @value{VERSION}.
 
-Copyright @copyright{} 2002 g10 Code GmbH.
-
-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 the
-Invariant Sections being ``Free Software Needs Free Documentation'' and
-``GNU Lesser General Public License'', the Front-Cover texts being (a)
-(see below), and with the Back-Cover Texts being (b) (see below).  A
-copy of the license is included in the section entitled ``GNU Free
-Documentation License''.
+@c NOTE: Don't forget to update the year for the TeX version, too.
+@insertcopying
 
 @end ifinfo
 
-@iftex
-@shorttitlepage The `GnuPG Made Easy' Reference Manual
-@end iftex
+@c We do not want that bastard short titlepage.
+@c @iftex
+@c @shorttitlepage The `GnuPG Made Easy' Reference Manual
+@c @end iftex
 @titlepage
 @center @titlefont{The `GnuPG Made Easy'}
 @sp 1
@@ -48,19 +71,15 @@ Documentation License''.
 @center for version @value{VERSION}
 @page
 @vskip 0pt plus 1filll
-Copyright @copyright{} 2002 g10 Code GmbH.
+Published by g10 Code GmbH@* Hüttenstr. 61@* 40699 Erkrath, Germany
 
-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 the
-Invariant Sections being ``Free Software Needs Free Documentation'' and
-``GNU Lesser General Public License'', the Front-Cover texts being (a)
-(see below), and with the Back-Cover Texts being (b) (see below).  A
-copy of the license is included in the section entitled ``GNU Free
-Documentation License''.
+@insertcopying
 @end titlepage
 @page
 
+@summarycontents
+@contents
+
 @ifnottex
 @node Top
 @top Main Menu
@@ -80,10 +99,12 @@ This is Edition @value{EDITION}, last updated @value{UPDATED}, of
 
 Appendices
 
+* UI Server Protocol::            The GnuPG UI Server Protocol.
+
+* Library Copying::               The GNU Lesser General Public License says
+                                  how you can copy and share `GnuPG Made Easy'.
 * Copying::                       The GNU General Public License says how you
-                                  can copy and share `GnuPG Made Easy'.
-* Free Documentation License::    This manual is under the GNU Free
-                                  Documentation License.
+                                  can copy and share this manual.
 
 Indices
 
@@ -104,14 +125,18 @@ Preparation
 
 * Header::                        What header file you need to include.
 * Building the Source::           Compiler options to be used.
+* Largefile Support (LFS)::       How to use @acronym{GPGME} with LFS.
 * Using Automake::                Compiler options to be used the easy way.
+* Using Libtool::                 Avoiding compiler options entirely.
 * Library Version Check::         Getting and verifying the library version.
+* Signal Handling::               How @acronym{GPGME} affects signal handling.
 * Multi Threading::               How @acronym{GPGME} can be used in an MT environment.
 
 Protocols and Engines
 
 * Engine Version Check::          Verifying the engine version.
 * Engine Information::            Obtaining more information about the engines.
+* Engine Configuration::          Changing the engine configuration.
 * OpenPGP::                       Support for the OpenPGP protocol.
 * Cryptographic Message Syntax::  Support for the CMS.
 
@@ -122,7 +147,9 @@ Algorithms
 
 Error Handling
 
-* Error Values::                  A list of all error values used.
+* Error Values::                  The error value and what it means.
+* Error Codes::                   A list of important error codes.
+* Error Sources::                 A list of important error sources.
 * Error Strings::                 How to get a descriptive string from a value.
 
 Exchanging Data 
@@ -137,10 +164,16 @@ Creating Data Buffers
 * File Based Data Buffers::       Creating file based data buffers.
 * Callback Based Data Buffers::   Creating callback based data buffers.
 
+Manipulating Data Buffers
+
+* Data Buffer I/O Operations::    I/O operations on data buffers.
+* Data Buffer Meta-Data::         Meta-data manipulation of data buffers.
+
 Contexts
 
 * Creating Contexts::             Creating new @acronym{GPGME} contexts.
 * Destroying Contexts::           Releasing @acronym{GPGME} contexts.
+* Result Management::             Managing the result of crypto operations.
 * Context Attributes::            Setting properties of a context.
 * Key Management::                Managing keys with @acronym{GPGME}.
 * Trust Item Management::         Managing trust items with @acronym{GPGME}.
@@ -150,12 +183,14 @@ Contexts
 Context Attributes
 
 * Protocol Selection::            Selecting the protocol used by a context.
-* @acronym{ASCII} Armor::                   Requesting @acronym{ASCII} armored output.
+* Crypto Engine::                 Configuring the crypto engine.
+* ASCII Armor::                   Requesting @acronym{ASCII} armored output.
 * Text Mode::                     Choosing canonical text mode.
 * Included Certificates::         Including a number of certificates.
 * Key Listing Mode::              Selecting key listing mode.
 * Passphrase Callback::           Getting the passphrase from the user.
 * Progress Meter Callback::       Being informed about the progress.
+* Locale::                        Setting the locale of a context.
 
 Key Management
 
@@ -167,6 +202,7 @@ Key Management
 * Exporting Keys::                Retrieving key data from the key ring.
 * Importing Keys::                Adding keys to the key ring.
 * Deleting Keys::                 Removing keys from the key ring.
+* Advanced Key Editing::          Advanced key edit operation.
 
 Trust Item Management
 
@@ -186,16 +222,17 @@ Sign
 
 * Selecting Signers::             How to choose the keys to sign with.
 * Creating a Signature::          How to create a signature.
+* Signature Notation Data::       How to add notation data to a signature.
 
 Encrypt
 
-* Selecting Recipients::          How to choose the recipients.
 * Encrypting a Plaintext::        How to encrypt a plaintext.
 
 Run Control
 
 * Waiting For Completion::        Waiting until an operation is completed.
 * Using External Event Loops::    Advanced control over what happens when.
+* Cancellation::                  How to end pending operations prematurely.
 
 Using External Event Loops
 
@@ -204,6 +241,7 @@ Using External Event Loops
 * I/O Callback Example::          An example how to use I/O callbacks.
 * I/O Callback Example GTK+::     How to integrate @acronym{GPGME} in GTK+.
 * I/O Callback Example GDK::      How to integrate @acronym{GPGME} in GDK.
+* I/O Callback Example Qt::       How to integrate @acronym{GPGME} in Qt.
 
 @end detailmenu
 @end menu
@@ -213,9 +251,9 @@ Using External Event Loops
 
 `GnuPG Made Easy' (@acronym{GPGME}) is a C language library that
 allows to add support for cryptography to a program.  It is designed
-to make access to crypto engines like GnuPG or GpgSM easier for
-applications.  @acronym{GPGME} provides a high-level crypto API for
-encryption, decryption, signing, signature verification and key
+to make access to public key crypto engines like GnuPG or GpgSM easier
+for applications.  @acronym{GPGME} provides a high-level crypto API
+for encryption, decryption, signing, signature verification and key
 management.
 
 @acronym{GPGME} uses GnuPG and GpgSM as its backends to support
@@ -261,7 +299,7 @@ engines into your application directly.
 @table @asis
 @item it's free software
 Anybody can use, modify, and redistribute it under the terms of the GNU
-General Public License (@pxref{Copying}).
+Lesser General Public License (@pxref{Library Copying}).
 
 @item it's flexible
 @acronym{GPGME} provides transparent support for several cryptographic
@@ -316,8 +354,11 @@ of the library are verified.
 @menu
 * Header::                        What header file you need to include.
 * Building the Source::           Compiler options to be used.
+* Largefile Support (LFS)::       How to use @acronym{GPGME} with LFS.
 * Using Automake::                Compiler options to be used the easy way.
+* Using Libtool::                 Avoiding compiler options entirely.
 * Library Version Check::         Getting and verifying the library version.
+* Signal Handling::               How @acronym{GPGME} affects signal handling.
 * Multi Threading::               How @acronym{GPGME} can be used in an MT environment.
 @end menu
 
@@ -340,9 +381,10 @@ The name space of @acronym{GPGME} is @code{gpgme_*} for function names
 and data types and @code{GPGME_*} for other symbols.  Symbols internal
 to @acronym{GPGME} take the form @code{_gpgme_*} and @code{_GPGME_*}.
 
-Because @acronym{GPGME} links to the Assuan library, linking to
-@acronym{GPGME} will also use the @code{assuan_*} and @code{_assuan_*}
-name space indirectly.
+Because @acronym{GPGME} makes use of the GPG Error library, using
+@acronym{GPGME} will also use the @code{GPG_ERR_*} name space
+directly, and the @code{gpg_err*} and @code{gpg_str*} name space
+indirectly.
 
 
 @node Building the Source
@@ -368,9 +410,9 @@ example shows how it can be used at the command line:
 gcc -c foo.c `gpgme-config --cflags`
 @end example
 
-Adding the output of @samp{gpgme-config --cflags} to the compilers
-command line will ensure that the compiler can find the @acronym{GPGME} header
-file.
+Adding the output of @samp{gpgme-config --cflags} to the compiler
+command line will ensure that the compiler can find the
+@acronym{GPGME} header file.
 
 A similar problem occurs when linking the program with the library.
 Again, the compiler has to find the library files.  For this to work,
@@ -393,14 +435,96 @@ specifying both options to @command{gpgme-config}:
 gcc -o foo foo.c `gpgme-config --cflags --libs`
 @end example
 
+If you want to link to one of the thread-safe versions of
+@acronym{GPGME}, you must specify the @option{--thread} option before
+any other option to select the thread package you want to link with.
+Supported thread packages are @option{--thread=pth} and
+@option{--thread=pthread}.
+
+
+@node Largefile Support (LFS)
+@section Largefile Support (LFS)
+@cindex largefile support
+@cindex LFS
+
+@acronym{GPGME} is compiled with largefile support by default, if it
+is available on the system.  This means that GPGME supports files
+larger than two gigabyte in size, if the underlying operating system
+can.  On some systems, largefile support is already the default.  On
+such systems, nothing special is required.  However, some systems
+provide only support for files up to two gigabyte in size by default.
+Support for larger file sizes has to be specifically enabled.
+
+To make a difficult situation even more complex, such systems provide
+two different types of largefile support.  You can either get all
+relevant functions replaced with alternatives that are largefile
+capable, or you can get new functions and data types for largefile
+support added.  Those new functions have the same name as their
+smallfile counterparts, but with a suffix of 64.
+
+An example: The data type @code{off_t} is 32 bit wide on GNU/Linux PC
+systems.  To address offsets in large files, you can either enable
+largefile support add-on.  Then a new data type @code{off64_t} is
+provided, which is 64 bit wide.  Or you can replace the existing
+@code{off_t} data type with its 64 bit wide counterpart.  All
+occurences of @code{off_t} are then automagically replaced.
+
+As if matters were not complex enough, there are also two different
+types of file descriptors in such systems.  This is important because
+if file descriptors are exchanged between programs that use a
+different maximum file size, certain errors must be produced on some
+file descriptors to prevent subtle overflow bugs from occuring.
+
+As you can see, supporting two different maximum file sizes at the
+same time is not at all an easy task.  However, the maximum file size
+does matter for @acronym{GPGME}, because some data types it uses in
+its interfaces are affected by that.  For example, the @code{off_t}
+data type is used in the @code{gpgme_data_seek} function, to match its
+@acronym{POSIX} counterpart.  This affects the call-frame of the
+function, and thus the ABI of the library.  Furthermore, file
+descriptors can be exchanged between GPGME and the application.
+
+For you as the user of the library, this means that your program must
+be compiled in the same file size mode as the library.  Luckily, there
+is absolutely no valid reason for new programs to not enable largefile
+support by default and just use that.  The compatibility modes (small
+file sizes or dual mode) can be considered an historic artefact, only
+useful to allow for a transitional period.
+
+@acronym{GPGME} is compiled using largefile support by default.  This
+means that your application must do the same, at least as far as it is
+relevant for using the @file{gpgme.h} header file.  All types in this
+header files refer to their largefile counterparts, if they are
+different from any default types on the system.
+
+You can enable largefile support, if it is different from the default
+on the system the application is compiled on, by using the Autoconf
+macro @code{AC_SYS_LARGEFILE}.  If you do this, then you don't need to
+worry about anything else: It will just work.  In this case you might
+also want to use @code{AC_FUNC_FSEEKO} to take advantage of some new
+interfaces, and @code{AC_TYPE_OFF_T} (just in case).
+
+If you do not use Autoconf, you can define the preprocessor symbol
+@code{_FILE_OFFSET_BITS} to 64 @emph{before} including any header
+files, for example by specifying the option
+@code{-D_FILE_OFFSET_BITS=64} on the compiler command line.  You will
+also want to define the preprocessor symbol @code{LARGEFILE_SOURCE} to
+1 in this case, to take advantage of some new interfaces.
+
+If you do not want to do either of the above, you probably know enough
+about the issue to invent your own solution.  Just keep in mind that
+the @acronym{GPGME} header file expects that largefile support is
+enabled, if it is available.  In particular, we do not support dual
+mode (@code{_LARGEFILE64_SOURCE}).
+
 
 @node Using Automake
 @section Using Automake
 @cindex automake
 @cindex autoconf
 
-It is much easier if you use GNU Automake instead writing your own
-Makefiles.  If you do that you don't have to worry about finding and
+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{gpgme-config} script at all.  @acronym{GPGME}
 provides an extension to Automake that does all the work for you.
 
@@ -409,6 +533,8 @@ provides an extension to Automake that does all the work for you.
 @r{[}@var{\varname\}@r{]}
 @end macro
 @defmac AM_PATH_GPGME (@ovar{minimum-version}, @ovar{action-if-found}, @ovar{action-if-not-found})
+@defmacx AM_PATH_GPGME_PTH (@ovar{minimum-version}, @ovar{action-if-found}, @ovar{action-if-not-found})
+@defmacx AM_PATH_GPGME_PTHREAD (@ovar{minimum-version}, @ovar{action-if-found}, @ovar{action-if-not-found})
 Check whether @acronym{GPGME} (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
@@ -418,6 +544,14 @@ Additionally, the function defines @code{GPGME_CFLAGS} to the flags
 needed for compilation of the program to find the @file{gpgme.h}
 header file, and @code{GPGME_LIBS} to the linker flags needed to link
 the program to the @acronym{GPGME} library.
+
+@code{AM_PATH_GPGME_PTH} checks for the version of @acronym{GPGME}
+that can be used with GNU Pth, and defines @code{GPGME_PTH_CFLAGS} and
+@code{GPGME_PTH_LIBS}.
+
+@code{AM_PATH_GPGME_PTHREAD} checks for the version of @acronym{GPGME}
+that can be used with the native pthread implementation, and defines
+@code{GPGME_PTHREAD_CFLAGS} and @code{GPGME_PTHREAD_LIBS}.
 @end defmac
 
 You can use the defined Autoconf variables like this in your
@@ -429,18 +563,32 @@ LDADD = $(GPGME_LIBS)
 @end example
 
 
+@node Using Libtool
+@section Using Libtool
+@cindex libtool
+
+The easiest way is to just use GNU Libtool.  If you use libtool, and
+link to @code{libgpgme.la}, @code{libgpgme-pth.la} or
+@code{libgpgme-pthread.la} respectively, everything will be done
+automatically by Libtool.
+
+
 @node Library Version Check
 @section Library Version Check
 @cindex version check, of the library
 
 @deftypefun {const char *} gpgme_check_version (@w{const char *@var{required_version}})
-The function @code{gpgme_check_version} has three purposes.  It can be
+The function @code{gpgme_check_version} has four purposes.  It can be
 used to retrieve the version number of the library.  In addition it
 can verify that the version number is higher than a certain required
 version number.  In either case, the function initializes some
 sub-systems, and for this reason alone it must be invoked early in
 your program, before you make use of the other functions in
-@acronym{GPGME}.
+@acronym{GPGME}.  The last purpose is to run selftests.
+
+As a side effect for W32 based systems, the socket layer will get
+initialized.
+
 
 If @var{required_version} is @code{NULL}, the function returns a
 pointer to a statically allocated string containing the version number
@@ -459,9 +607,70 @@ If you use a version of a library that is backwards compatible with
 older releases, but contains additional interfaces which your program
 uses, this function provides a run-time check if the necessary
 features are provided by the installed version of the library.
+
+If a selftest fails, the function may still succeed.  Selftest errors
+are returned later when invoking @code{gpgme_new}, so that a detailed
+error code can be returned (historically, @code{gpgme_check_version}
+does not return a detailed error code).
 @end deftypefun
 
 
+After initializing @acronym{GPGME}, you should set the locale
+information to the locale required for your output terminal.  This
+locale information is needed for example for the curses and Gtk
+pinentry.  Here is an example of a complete initialization:
+
+@example
+#include <locale.h>
+#include <gpgme.h>
+
+void
+init_gpgme (void)
+@{
+  /* Initialize the locale environment.  */
+  setlocale (LC_ALL, "");
+  gpgme_check_version (NULL);
+  gpgme_set_locale (NULL, LC_CTYPE, setlocale (LC_CTYPE, NULL));
+#ifdef LC_MESSAGES
+  gpgme_set_locale (NULL, LC_MESSAGES, setlocale (LC_MESSAGES, NULL));
+#endif
+@}
+@end example
+
+Note that you are highly recommended to initialize the locale settings
+like this.  @acronym{GPGME} can not do this for you because it would
+not be thread safe.  The conditional on LC_MESSAGES is only necessary
+for portability to W32 systems.
+
+
+@node Signal Handling
+@section Signal Handling
+@cindex signals
+@cindex signal handling
+
+The @acronym{GPGME} library communicates with child processes (the
+crypto engines).  If a child process dies unexpectedly, for example
+due to a bug, or system problem, a @code{SIGPIPE} signal will be
+delivered to the application.  The default action is to abort the
+program.  To protect against this, @code{gpgme_check_version} sets the
+@code{SIGPIPE} signal action to @code{SIG_IGN}, which means that the
+signal will be ignored.
+
+@acronym{GPGME} will only do that if the signal action for
+@code{SIGPIPE} is @code{SIG_DEF} at the time
+@code{gpgme_check_version} is called.  If it is something different,
+@code{GPGME} will take no action.
+
+This means that if your application does not install any signal
+handler for @code{SIGPIPE}, you don't need to take any precautions.
+If you do install a signal handler for @code{SIGPIPE}, you must be
+prepared to handle any @code{SIGPIPE} events that occur due to
+@acronym{GPGME} writing to a defunct pipe.  Furthermore, if your
+application is multi-threaded, and you install a signal action for
+@code{SIGPIPE}, you must make sure you do this either before
+@code{gpgme_check_version} is called or afterwards.
+
+
 @node Multi Threading
 @section Multi Threading
 @cindex thread-safeness
@@ -477,80 +686,51 @@ conditions to worry about:
 @acronym{GPGME} supports the thread libraries pthread and GNU Pth.
 The support for this has to be enabled at compile time.
 @acronym{GPGME} will automatically detect the location in which the
-thread libraries are installed and activate the support for them.
+thread libraries are installed and activate the support for them at
+build time.
 
 Support for other thread libraries is very easy to add.  Please
 contact us if you have the need.
 
 @item
-If you link your program dynamically to @acronym{GPGME} and your
-supported thread library, @acronym{GPGME} will automatically detect
-the presence of this library and activate its use.  You must link to
-the thread library before linking to @acronym{GPGME}.  If you link to
-both pthread and GNU Pth, @acronym{GPGME} will use the pthread
-support.  This feature requires weak symbol support.
+If you want to use @acronym{GPGME} with threads, you must link to the
+right version of the library.  The name of the right library is
+@code{libgpgme-} followed by the name of the thread package you use.
+For example, if you use GNU Pth, the right name is
+@code{libgpgme-pth}.  Use the Automake macros or
+@command{gpgme-config} program for simplicity.
 
-@item
-If you link your program statically to @acronym{GPGME}, there is
-currently no easy way to make sure that @acronym{GPGME} detects the
-presence of the thread library.  This will be solved in a future
-version.
 
 @item
 The function @code{gpgme_check_version} must be called before any
 other function in the library, because it initializes the thread
-support subsystem in @acronym{GPGME}.  To achieve this in all
-generality, it is necessary to synchronize the call to this function
-with all other calls to functions in the library, using the
-synchronization mechanisms available in your thread library.
-Otherwise, specific compiler or CPU memory cache optimizations could
-lead to the situation where a thread is started and uses
-@acronym{GPGME} before the effects of the initialization are visible
-for this thread.  It doesn't even suffice to call
-@code{gpgme_check_version} before creating this other
-thread@footnote{In SMP systems the new thread could be started on
-another CPU before the effects of the initialization are seen by that
-CPU's memory cache.  Not doing proper synchronization here leads to
-the same problems the double-checked locking idiom has.  You might
-find that if you don't do proper synchronization, it still works in
-most configurations.  Don't let this fool you.  Someday it might lead
-to subtle bugs when someone tries it on a DEC Alpha or an SMP
-machine.}.
-
-For example, if you are using POSIX threads, each thread that wants to
-call functions in @acronym{GPGME} could call the following function
-before any function in the library:
-
-@example
-#include <pthread.h>
-
-void
-initialize_gpgme (void)
-@{
-  static int gpgme_init;
-  static pthread_mutext_t gpgme_init_lock = PTHREAD_MUTEX_INITIALIZER;
-
-  pthread_mutex_lock (&gpgme_init_lock);
-  if (!gpgme_init)
-    @{
-      gpgme_check_version ();
-      gpgme_init = 1;
-    @}
-  pthread_mutex_unlock (&gpgme_init_lock);
-@}
-@end example
+support subsystem in @acronym{GPGME}.  To achieve this in
+multi-threaded programs, you must synchronize the memory with respect
+to other threads that also want to use @acronym{GPGME}.  For this, it
+is sufficient to call @code{gpgme_check_version} before creating the
+other threads using @acronym{GPGME}@footnote{At least this is true for
+POSIX threads, as @code{pthread_create} is a function that
+synchronizes memory with respects to other threads.  There are many
+functions which have this property, a complete list can be found in
+POSIX, IEEE Std 1003.1-2003, Base Definitions, Issue 6, in the
+definition of the term ``Memory Synchronization''.  For other thread
+packages other, more relaxed or more strict rules may apply.}.
 
 @item
-Any @code{gpgme_data_t}, @code{gpgme_ctx_t} and @code{gpgme_recipients_t}
-object must only be accessed by one thread at a time.  If multiple
-threads want to deal with the same object, the caller has to make sure
-that operations on that object are fully synchronized.
+Any @code{gpgme_data_t} and @code{gpgme_ctx_t} object must only be
+accessed by one thread at a time.  If multiple threads want to deal
+with the same object, the caller has to make sure that operations on
+that object are fully synchronized.
 
 @item
 Only one thread at any time is allowed to call @code{gpgme_wait}.  If
 multiple threads call this function, the caller must make sure that
 all invocations are fully synchronized.  It is safe to start
 asynchronous operations while a thread is running in gpgme_wait.
+
+@item
+The function @code{gpgme_strerror} is not thread safe.  You have to
+use @code{gpgme_strerror_r} instead.
 @end itemize
 
 
@@ -567,7 +747,7 @@ does not implement them.  Rather it uses backends (also called
 engines) which implement the protocol.  @acronym{GPGME} uses
 inter-process communication to pass data back and forth between the
 application and the backend, but the details of the communication
-protocol and invocation of the backends is completely hidden by the
+protocol and invocation of the backend is completely hidden by the
 interface.  All complexity is handled by @acronym{GPGME}.  Where an
 exchange of information between the application and the backend is
 necessary, @acronym{GPGME} provides the necessary callback function
@@ -582,13 +762,20 @@ are supported:
 @table @code
 @item GPGME_PROTOCOL_OpenPGP
 This specifies the OpenPGP protocol.
+
 @item GPGME_PROTOCOL_CMS
 This specifies the Cryptographic Message Syntax.
+
+@item GPGME_PROTOCOL_UNKNOWN
+Reserved for future extension.  You may use this to indicate that the
+used protocol is not known to the application.  Currently,
+@acronym{GPGME} does not accept this value in any operation, though,
+except for @code{gpgme_get_protocol_name}.
 @end table
 @end deftp
 
 
-@deftypefun const char *gpgme_get_protocol_name (@w{gpgme_protocol_t @var{protocol}})
+@deftypefun {const char *} gpgme_get_protocol_name (@w{gpgme_protocol_t @var{protocol}})
 The function @code{gpgme_get_protocol_name} returns a statically
 allocated string describing the protocol @var{protocol}, or
 @code{NULL} if the protocol number is not valid.
@@ -597,6 +784,7 @@ allocated string describing the protocol @var{protocol}, or
 @menu
 * Engine Version Check::          Verifying the engine version.
 * Engine Information::            Obtaining more information about the engines.
+* Engine Configuration::          Changing the engine configuration.
 * OpenPGP::                       Support for the OpenPGP protocol.
 * Cryptographic Message Syntax::  Support for the CMS.
 @end menu
@@ -611,8 +799,8 @@ The function @code{gpgme_engine_check_version} verifies that the
 engine implementing the protocol @var{PROTOCOL} is installed in the
 expected path and meets the version requirement of @acronym{GPGME}.
 
-This function returns @code{GPGME_No_Error} if the engine is available
-and @code{GPGME_Invalid_Engine} if it is not.
+This function returns the error code @code{GPG_ERR_NO_ERROR} if the
+engine is available and @code{GPG_ERR_INV_ENGINE} if it is not.
 @end deftypefun
 
 
@@ -623,8 +811,8 @@ and @code{GPGME_Invalid_Engine} if it is not.
 @deftp {Data type} {gpgme_engine_info_t}
 @tindex gpgme_protocol_t
 The @code{gpgme_engine_info_t} type specifies a pointer to a structure
-describing a crypto backend engine.  The structure contains the
-following elements:
+describing a crypto engine.  The structure contains the following
+elements:
 
 @table @code
 @item gpgme_engine_info_t next
@@ -632,7 +820,7 @@ This is a pointer to the next engine info structure in the linked
 list, or @code{NULL} if this is the last element.
 
 @item gpgme_protocol_t protocol
-This is the protocol for which the crypo engine is used.  You can
+This is the protocol for which the crypto engine is used.  You can
 convert this to a string with @code{gpgme_get_protocol_name} for
 printing.
 
@@ -641,6 +829,11 @@ This is a string holding the file name of the executable of the crypto
 engine.  Currently, it is never @code{NULL}, but using @code{NULL} is
 reserved for future use, so always check before you use it.
 
+@item const char *home_dir
+This is a string holding the directory name of the crypto engine's
+configuration directory.  If it is @code{NULL}, then the default
+directory is used.
+
 @item const char *version
 This is a string containing the version number of the crypto engine.
 It might be @code{NULL} if the version number can not be determined,
@@ -655,22 +848,20 @@ reserved for future use, so always check before you use it.
 @end table
 @end deftp
 
-@deftypefun gpgme_error_t gpgme_get_engine_info (gpgme_engine_info_t *info)
+@deftypefun gpgme_error_t gpgme_get_engine_info (@w{gpgme_engine_info_t *@var{info}})
 The function @code{gpgme_get_engine_info} returns a linked list of
 engine info structures in @var{info}.  Each info structure describes
-one configured crypto backend engine.
+the defaults of one configured backend.
 
 The memory for the info structures is allocated the first time this
 function is invoked, and must not be freed by the caller.
 
-This function returns @code{GPGME_No_Error} if successful, and
-@code{GPGME_Out_Of_Core} if not enough memory is available for the
-operation.
+This function returns the error code @code{GPG_ERR_NO_ERROR} if
+successful, and a system error if the memory could not be allocated.
 @end deftypefun
 
-Here is the example how you can provide more diagnostics if you
-receive an error message which indicates that the crypto engine is
-invalid.
+Here is an example how you can provide more diagnostics if you receive
+an error message which indicates that the crypto engine is invalid.
 
 @example
 gpgme_ctx_t ctx;
@@ -678,7 +869,7 @@ gpgme_error_t err;
 
 [...]
 
-if (err == GPGME_Invalid_Engine)
+if (gpgme_err_code (err) == GPG_ERR_INV_ENGINE)
   @{
     gpgme_engine_info_t info;
     err = gpgme_get_engine_info (&info);
@@ -689,12 +880,12 @@ if (err == GPGME_Invalid_Engine)
         if (!info)
           fprintf (stderr, "GPGME compiled without support for protocol %s",
                    gpgme_get_protocol_name (info->protocol));
-        else if (info->path && !info->version)
+        else if (info->file_name && !info->version)
           fprintf (stderr, "Engine %s not installed properly",
-                   info->path);
-        else if (info->path && info->version && info->req_version)
+                   info->file_name);
+        else if (info->file_name && info->version && info->req_version)
           fprintf (stderr, "Engine %s version %s installed, "
-                   "but at least version %s required", info->path,
+                   "but at least version %s required", info->file_name,
                    info->version, info->req_version);
         else
           fprintf (stderr, "Unknown problem with engine for protocol %s",
@@ -704,6 +895,37 @@ if (err == GPGME_Invalid_Engine)
 @end example
 
 
+@node Engine Configuration
+@section Engine Configuration
+@cindex engine, configuration of
+@cindex configuration of crypto backend
+
+You can change the configuration of a backend engine, and thus change
+the executable program and configuration directory to be used.  You
+can make these changes the default or set them for some contexts
+individually.
+
+@deftypefun gpgme_error_t gpgme_set_engine_info (@w{gpgme_protocol_t @var{proto}}, @w{const char *@var{file_name}}, @w{const char *@var{home_dir}})
+The function @code{gpgme_set_engine_info} changes the default
+configuration of the crypto engine implementing the protocol
+@var{proto}.
+
+@var{file_name} is the file name of the executable program
+implementing this protocol, and @var{home_dir} is the directory name
+of the configuration directory for this crypto engine.  If
+@var{home_dir} is @code{NULL}, the engine's default will be used.
+
+The new defaults are not applied to already created GPGME contexts.
+
+This function returns the error code @code{GPG_ERR_NO_ERROR} if
+successful, or an eror code on failure.
+@end deftypefun
+
+The functions @code{gpgme_ctx_get_engine_info} and
+@code{gpgme_ctx_set_engine_info} can be used to change the engine
+configuration per context.  @xref{Crypto Engine}.
+
+
 @node OpenPGP
 @section OpenPGP
 @cindex OpenPGP
@@ -738,8 +960,10 @@ The @acronym{CMS} protocol is specified by @code{GPGME_PROTOCOL_CMS}.
 @cindex algorithms
 
 The crypto backends support a variety of algorithms used in public key
-cryptography.  The following sections list the identifiers used to
-denote such an algorithm.
+cryptography.@footnote{Some engines also provide symmetric only
+encryption; see the description of the encryption function on how to use
+this.}  The following sections list the identifiers used to denote such
+an algorithm.
 
 @menu
 * Public Key Algorithms::         A list of all public key algorithms.
@@ -852,173 +1076,381 @@ operation, but the result of an operation that failed properly.  For
 example, if you try to decrypt a tempered message, the decryption will
 fail.  Another error value actually means that the end of a data
 buffer or list has been reached.  The following descriptions explain
-what each error message means in general.  Some error values have
-specific meanings if returned by a specific function.  Such cases are
+for many error codes what they mean usually.  Some error values have
+specific meanings if returned by a certain functions.  Such cases are
 described in the documentation of those functions.
 
+@acronym{GPGME} uses the @code{libgpg-error} library.  This allows to
+share the error codes with other components of the GnuPG system, and
+thus pass error values transparently from the crypto engine, or some
+helper application of the crypto engine, to the user.  This way no
+information is lost.  As a consequence, @acronym{GPGME} does not use
+its own identifiers for error codes, but uses those provided by
+@code{libgpg-error}.  They usually start with @code{GPG_ERR_}.
+
+However, @acronym{GPGME} does provide aliases for the functions
+defined in libgpg-error, which might be preferred for name space
+consistency.
+
 @menu
-* Error Values::                  A list of all error values used.
+* Error Values::                  The error value and what it means.
+* Error Sources::                 A list of important error sources.
+* Error Codes::                   A list of important error codes.
 * Error Strings::                 How to get a descriptive string from a value.
 @end menu
 
 
 @node Error Values
 @section Error Values
-@cindex error values, list of
+@cindex error values
+@cindex error codes
+@cindex error sources
+
+@deftp {Data type} {gpgme_err_code_t}
+The @code{gpgme_err_code_t} type is an alias for the @code{libgpg-error}
+type @code{gpg_err_code_t}.  The error code indicates the type of an
+error, or the reason why an operation failed.
+
+A list of important error codes can be found in the next section.
+@end deftp
+
+@deftp {Data type} {gpgme_err_source_t}
+The @code{gpgme_err_source_t} type is an alias for the
+@code{libgpg-error} type @code{gpg_err_source_t}.  The error source
+has not a precisely defined meaning.  Sometimes it is the place where
+the error happened, sometimes it is the place where an error was
+encoded into an error value.  Usually the error source will give an
+indication to where to look for the problem.  This is not always true,
+but it is attempted to achieve this goal.
+
+A list of important error sources can be found in the next section.
+@end deftp
+
+@deftp {Data type} {gpgme_error_t}
+The @code{gpgme_error_t} type is an alias for the @code{libgpg-error}
+type @code{gpg_error_t}.  An error value like this has always two
+components, an error code and an error source.  Both together form the
+error value.
+
+Thus, the error value can not be directly compared against an error
+code, but the accessor functions described below must be used.
+However, it is guaranteed that only 0 is used to indicate success
+(@code{GPG_ERR_NO_ERROR}), and that in this case all other parts of
+the error value are set to 0, too.
+
+Note that in @acronym{GPGME}, the error source is used purely for
+diagnostical purposes.  Only the error code should be checked to test
+for a certain outcome of a function.  The manual only documents the
+error code part of an error value.  The error source is left
+unspecified and might be anything.
+@end deftp
+
+@deftypefun {static inline gpgme_err_code_t} gpgme_err_code (@w{gpgme_error_t @var{err}})
+The static inline function @code{gpgme_err_code} returns the
+@code{gpgme_err_code_t} component of the error value @var{err}.  This
+function must be used to extract the error code from an error value in
+order to compare it with the @code{GPG_ERR_*} error code macros.
+@end deftypefun
+
+@deftypefun {static inline gpgme_err_source_t} gpgme_err_source (@w{gpgme_error_t @var{err}})
+The static inline function @code{gpgme_err_source} returns the
+@code{gpgme_err_source_t} component of the error value @var{err}.  This
+function must be used to extract the error source from an error value in
+order to compare it with the @code{GPG_ERR_SOURCE_*} error source macros.
+@end deftypefun
+
+@deftypefun {static inline gpgme_error_t} gpgme_err_make (@w{gpgme_err_source_t @var{source}}, @w{gpgme_err_code_t @var{code}})
+The static inline function @code{gpgme_err_make} returns the error
+value consisting of the error source @var{source} and the error code
+@var{code}.
+
+This function can be used in callback functions to construct an error
+value to return it to the library.
+@end deftypefun
+
+@deftypefun {static inline gpgme_error_t} gpgme_error (@w{gpgme_err_code_t @var{code}})
+The static inline function @code{gpgme_error} returns the error value
+consisting of the default error source and the error code @var{code}.
+
+For @acronym{GPGME} applications, the default error source is
+@code{GPG_ERR_SOURCE_USER_1}.  You can define
+@code{GPGME_ERR_SOURCE_DEFAULT} before including @file{gpgme.h} to
+change this default.
+
+This function can be used in callback functions to construct an error
+value to return it to the library.
+@end deftypefun
+
+The @code{libgpg-error} library provides error codes for all system
+error numbers it knows about.  If @var{err} is an unknown error
+number, the error code @code{GPG_ERR_UNKNOWN_ERRNO} is used.  The
+following functions can be used to construct error values from system
+errnor numbers.
+
+@deftypefun {gpgme_error_t} gpgme_err_make_from_errno (@w{gpgme_err_source_t @var{source}}, @w{int @var{err}})
+The function @code{gpgme_err_make_from_errno} is like
+@code{gpgme_err_make}, but it takes a system error like @code{errno}
+instead of a @code{gpgme_err_code_t} error code.
+@end deftypefun
+
+@deftypefun {gpgme_error_t} gpgme_error_from_errno (@w{int @var{err}})
+The function @code{gpgme_error_from_errno} is like @code{gpgme_error},
+but it takes a system error like @code{errno} instead of a
+@code{gpgme_err_code_t} error code.
+@end deftypefun
+
+Sometimes you might want to map system error numbers to error codes
+directly, or map an error code representing a system error back to the
+system error number.  The following functions can be used to do that.
+
+@deftypefun {gpgme_err_code_t} gpgme_err_code_from_errno (@w{int @var{err}})
+The function @code{gpgme_err_code_from_errno} returns the error code
+for the system error @var{err}.  If @var{err} is not a known system
+error, the function returns @code{GPG_ERR_UNKNOWN_ERRNO}.
+@end deftypefun
+
+@deftypefun {int} gpgme_err_code_to_errno (@w{gpgme_err_code_t @var{err}})
+The function @code{gpgme_err_code_to_errno} returns the system error
+for the error code @var{err}.  If @var{err} is not an error code
+representing a system error, or if this system error is not defined on
+this system, the function returns @code{0}.
+@end deftypefun
+
+
+@node Error Sources
+@section Error Sources
+@cindex error codes, list of
+
+The library @code{libgpg-error} defines an error source for every
+component of the GnuPG system.  The error source part of an error
+value is not well defined.  As such it is mainly useful to improve the
+diagnostic error message for the user.
+
+If the error code part of an error value is @code{0}, the whole error
+value will be @code{0}.  In this case the error source part is of
+course @code{GPG_ERR_SOURCE_UNKNOWN}.
 
-@deftp {Data type} {enum gpgme_error_t}
-@tindex gpgme_error_t
-The @code{gpgme_error_t} type specifies the set of all error values that
-are used by @acronym{GPGME}.  Possible values are:
+The list of error sources that might occur in applications using
+@acronym{GPGME} is:
 
 @table @code
-@item GPGME_EOF
+@item GPG_ERR_SOURCE_UNKNOWN
+The error source is not known.  The value of this error source is
+@code{0}.
+
+@item GPG_ERR_SOURCE_GPGME
+The error source is @acronym{GPGME} itself.  This is the default for
+errors that occur in the @acronym{GPGME} library.
+
+@item GPG_ERR_SOURCE_GPG
+The error source is GnuPG, which is the crypto engine used for the
+OpenPGP protocol.
+
+@item GPG_ERR_SOURCE_GPGSM
+The error source is GPGSM, which is the crypto engine used for the
+CMS protocol.
+
+@item GPG_ERR_SOURCE_GCRYPT
+The error source is @code{libgcrypt}, which is used by crypto engines
+to perform cryptographic operations.
+
+@item GPG_ERR_SOURCE_GPGAGENT
+The error source is @command{gpg-agent}, which is used by crypto
+engines to perform operations with the secret key.
+
+@item GPG_ERR_SOURCE_PINENTRY
+The error source is @command{pinentry}, which is used by
+@command{gpg-agent} to query the passphrase to unlock a secret key.
+
+@item GPG_ERR_SOURCE_SCD
+The error source is the SmartCard Daemon, which is used by
+@command{gpg-agent} to delegate operations with the secret key to a
+SmartCard.
+
+@item GPG_ERR_SOURCE_KEYBOX
+The error source is @code{libkbx}, a library used by the crypto
+engines to manage local keyrings.
+
+@item GPG_ERR_SOURCE_USER_1
+@item GPG_ERR_SOURCE_USER_2
+@item GPG_ERR_SOURCE_USER_3
+@item GPG_ERR_SOURCE_USER_4
+These error sources are not used by any GnuPG component and can be
+used by other software.  For example, applications using
+@acronym{GPGME} can use them to mark error values coming from callback
+handlers.  Thus @code{GPG_ERR_SOURCE_USER_1} is the default for errors
+created with @code{gpgme_error} and @code{gpgme_error_from_errno},
+unless you define @code{GPGME_ERR_SOURCE_DEFAULT} before including
+@file{gpgme.h}.
+@end table
+
+
+@node Error Codes
+@section Error Codes
+@cindex error codes, list of
+
+The library @code{libgpg-error} defines many error values.  Most of
+them are not used by @code{GPGME} directly, but might be returned by
+@acronym{GPGME} because it received them from the crypto engine.  The
+below list only includes such error codes that have a specific meaning
+in @code{GPGME}, or which are so common that you should know about
+them.
+
+@table @code
+@item GPG_ERR_EOF
 This value indicates the end of a list, buffer or file.
 
-@item GPGME_No_Error
-This value indicates success.  The value of this error is @code{0}.
+@item GPG_ERR_NO_ERROR
+This value indicates success.  The value of this error code is
+@code{0}.  Also, it is guaranteed that an error value made from the
+error code @code{0} will be @code{0} itself (as a whole).  This means
+that the error source information is lost for this error code,
+however, as this error code indicates that no error occured, this is
+generally not a problem.
 
-@item GPGME_General_Error
+@item GPG_ERR_GENERAL
 This value means that something went wrong, but either there is not
 enough information about the problem to return a more useful error
 value, or there is no separate error value for this type of problem.
 
-@item GPGME_Out_Of_Core
+@item GPG_ERR_ENOMEM
 This value means that an out-of-memory condition occurred.
 
-@item GPGME_Invalid_Value
-This value means that some user provided data was out of range.  This
-can also refer to objects.  For example, if an empty @code{gpgme_data_t}
-object was expected, but one containing data was provided, this error
-value is returned.
-
-@item GPGME_Exec_Error
-This value means that an error occurred when trying to spawn a child
-process.
-
-@item GPGME_Too_Many_Procs
-This value means that there are too many active backend processes.
+@item GPG_ERR_E...
+System errors are mapped to GPG_ERR_FOO where FOO is the symbol for
+the system error.
 
-@item GPGME_Pipe_Error
-This value means that the creation of a pipe failed.
+@item GPG_ERR_INV_VALUE
+This value means that some user provided data was out of range.  This
+can also refer to objects.  For example, if an empty
+@code{gpgme_data_t} object was expected, but one containing data was
+provided, this error value is returned.
 
-@item GPGME_No_UserID 
-This value means that no valid recipients for a message have been set.
+@item GPG_ERR_UNUSABLE_PUBKEY
+This value means that some recipients for a message were invalid.
 
-@item GPGME_Invalid_UserID
-This value means that some, but not all, recipients for a message have
-been invalid.
+@item GPG_ERR_UNUSABLE_SECKEY
+This value means that some signers were invalid.
 
-@item GPGME_No_Data
-This value means that a @code{gpgme_data_t} object which was expected to
-have content was found empty.
+@item GPG_ERR_NO_DATA
+This value means that a @code{gpgme_data_t} object which was expected
+to have content was found empty.
 
-@item GPGME_Conflict
+@item GPG_ERR_CONFLICT
 This value means that a conflict of some sort occurred.
 
-@item GPGME_Not_Implemented
+@item GPG_ERR_NOT_IMPLEMENTED
 This value indicates that the specific function (or operation) is not
 implemented.  This error should never happen.  It can only occur if
 you use certain values or configuration options which do not work,
 but for which we think that they should work at some later time.
 
-@item GPGME_Read_Error
-This value means that an I/O read operation failed.
-
-@item GPGME_Write_Error
-This value means that an I/O write operation failed.
-
-@item GPGME_File_Error
-This value means that a file I/O operation failed.  The value of
-@var{errno} contains the system error value.
-
-@item GPGME_Decryption_Failed
+@item GPG_ERR_DECRYPT_FAILED
 This value indicates that a decryption operation was unsuccessful.
 
-@item GPGME_Bad_Passphrase
+@item GPG_ERR_BAD_PASSPHRASE
 This value means that the user did not provide a correct passphrase
 when requested.
 
-@item GPGME_Canceled
+@item GPG_ERR_CANCELED
 This value means that the operation was canceled.
 
-@item GPGME_Invalid_Key
-This value means that a key was invalid.
-
-@item GPGME_Invalid_Engine
+@item GPG_ERR_INV_ENGINE
 This value means that the engine that implements the desired protocol
 is currently not available.  This can either be because the sources
 were configured to exclude support for this engine, or because the
 engine is not installed properly.
 
-@item GPGME_Unknown_Reason
-This value indicates that a user ID was invalid but the exact reason
-is not specified.
+@item GPG_ERR_AMBIGUOUS_NAME
+This value indicates that a user ID or other specifier did not specify
+a unique key.
 
-@item GPGME_Not_Found
-This value indicates that a user ID was not found.
-
-@item GPGME_Ambiguous_Specification
-This value indicates that a user ID did not specify a unique key.
-
-@item GPGME_Wrong_Key_Usage
+@item GPG_ERR_WRONG_KEY_USAGE
 This value indicates that a key is not used appropriately.
 
-@item GPGME_Key_Revoked
-This value indicates that a key was revoced.
+@item GPG_ERR_CERT_REVOKED
+This value indicates that a key signature was revoced.
 
-@item GPGME_Key_Expired
-This value indicates that a key was expired.
+@item GPG_ERR_CERT_EXPIRED
+This value indicates that a key signature expired.
 
-@item GPGME_No_CRL_Known
+@item GPG_ERR_NO_CRL_KNOWN
 This value indicates that no certificate revocation list is known for
 the certificate.
 
-@item GPGME_Policy_Mismatch
+@item GPG_ERR_NO_POLICY_MATCH
 This value indicates that a policy issue occured.
 
-@item GPGME_No_Secret_Key
+@item GPG_ERR_NO_SECKEY
 This value indicates that no secret key for the user ID is available.
 
-@item GPGME_Key_Not_Trusted
-This value indicates that the key with the user ID is not trusted.
+@item GPG_ERR_MISSING_CERT
+This value indicates that a key could not be imported because the
+issuer certificate is missing.
 
-@item GPGME_Issuer_Missing
-This value indicates that a key could not be imported because there is
-no issuer
-
-@item GPGME_Chain_Too_Long
+@item GPG_ERR_BAD_CERT_CHAIN
 This value indicates that a key could not be imported because its
-certificate chain is too long.
+certificate chain is not good, for example it could be too long.
 
-@item GPGME_Unsupported_Algorithm
+@item GPG_ERR_UNSUPPORTED_ALGORITHM
 This value means a verification failed because the cryptographic
 algorithm is not supported by the crypto backend.
 
-@item GPGME_Sig_Expired
-This value means a verification failed because the signature expired.
-
-@item GPGME_Bad_Signature
+@item GPG_ERR_BAD_SIGNATURE
 This value means a verification failed because the signature is bad.
 
-@item GPGME_No_Public_Key
+@item GPG_ERR_NO_PUBKEY
 This value means a verification failed because the public key is not
 available.
 
+@item GPG_ERR_USER_1
+@item GPG_ERR_USER_2
+@item ...
+@item GPG_ERR_USER_16
+These error codes are not used by any GnuPG component and can be
+freely used by other software.  Applications using @acronym{GPGME}
+might use them to mark specific errors returned by callback handlers
+if no suitable error codes (including the system errors) for
+these errors exist already.
 @end table
-@end deftp
 
 
 @node Error Strings
 @section Error Strings
 @cindex error values, printing of
+@cindex error codes, printing of
+@cindex error sources, printing of
 @cindex error strings
 
 @deftypefun {const char *} gpgme_strerror (@w{gpgme_error_t @var{err}})
 The function @code{gpgme_strerror} returns a pointer to a statically
-allocated string containing a description of the error with the error
-value @var{err}.  This string can be used to output a diagnostic
-message to the user.
+allocated string containing a description of the error code contained
+in the error value @var{err}.  This string can be used to output a
+diagnostic message to the user.
+
+This function is not thread safe.  Use @code{gpgme_strerror_r} in
+multi-threaded programs.
+@end deftypefun
+
+
+@deftypefun {int} gpgme_strerror_r (@w{gpgme_error_t @var{err}}, @w{char *@var{buf}}, @w{size_t @var{buflen}})
+The function @code{gpgme_strerror_r} returns the error string for
+@var{err} in the user-supplied buffer @var{buf} of size @var{buflen}.
+This function is, in contrast to @code{gpgme_strerror}, thread-safe if
+a thread-safe @code{strerror_r} function is provided by the system.
+If the function succeeds, 0 is returned and @var{buf} contains the
+string describing the error.  If the buffer was not large enough,
+ERANGE is returned and @var{buf} contains as much of the beginning of
+the error string as fits into the buffer.
+@end deftypefun
+
+
+@deftypefun {const char *} gpgme_strsource (@w{gpgme_error_t @var{err}})
+The function @code{gpgme_strerror} returns a pointer to a statically
+allocated string containing a description of the error source
+contained in the error value @var{err}.  This string can be used to
+output a diagnostic message to the user.
+@end deftypefun
 
 The following example illustrates the use of @code{gpgme_strerror}:
 
@@ -1027,12 +1459,11 @@ gpgme_ctx_t ctx;
 gpgme_error_t err = gpgme_new (&ctx);
 if (err)
   @{
-    fprintf (stderr, "%s: creating GpgME context failed: %s\n",
-             argv[0], gpgme_strerror (err));
+    fprintf (stderr, "%s: creating GpgME context failed: %s: %s\n",
+             argv[0], gpgme_strsource (err), gpgme_strerror (err));
     exit (1);
   @}
 @end example
-@end deftypefun
 
 
 @node Exchanging Data
@@ -1052,6 +1483,14 @@ The @code{gpgme_data_t} type is a handle for a container for generic
 data, which is used by @acronym{GPGME} to exchange data with the user.
 @end deftp
 
+@code{gpgme_data_t} objects do not provide notifications on events.
+It is assumed that read and write operations are blocking until data
+is available.  If this is undesirable, the application must ensure
+that all GPGME data operations always have data available, for example
+by using memory buffers or files rather than pipes or sockets.  This
+might be relevant, for example, if the external event loop mechanism
+is used.
+
 @menu
 * Creating Data Buffers::         Creating new data buffers.
 * Destroying Data Buffers::       Releasing data buffers.
@@ -1089,10 +1528,10 @@ The function @code{gpgme_data_new} creates a new @code{gpgme_data_t}
 object and returns a handle for it in @var{dh}.  The data object is
 memory based and initially empty.
 
-The function returns @code{GPGME_No_Error} if the data object was
-successfully created, @code{GPGME_Invalid_Value} if @var{dh} is not a
-valid pointer, and @code{GPGME_Out_Of_Core} if not enough memory is
-available.
+The function returns the error code @code{GPG_ERR_NO_ERROR} if the
+data object was successfully created, @code{GPG_ERR_INV_VALUE} if
+@var{dh} is not a valid pointer, and @code{GPG_ERR_ENOMEM} if not
+enough memory is available.
 @end deftypefun
 
 @deftypefun gpgme_error_t gpgme_data_new_from_mem (@w{gpgme_data_t *@var{dh}}, @w{const char *@var{buffer}}, @w{size_t @var{size}}, @w{int @var{copy}})
@@ -1105,10 +1544,10 @@ If @var{copy} is not zero, a private copy of the data is made.  If
 needed, and the user has to ensure that the buffer remains valid for
 the whole life span of the data object.
 
-The function returns @code{GPGME_No_Error} if the data object was
-successfully created, @code{GPGME_Invalid_Value} if @var{dh} or
-@var{buffer} is not a valid pointer, and @code{GPGME_Out_Of_Core} if
-not enough memory is available.
+The function returns the error code @code{GPG_ERR_NO_ERROR} if the
+data object was successfully created, @code{GPG_ERR_INV_VALUE} if
+@var{dh} or @var{buffer} is not a valid pointer, and
+@code{GPG_ERR_ENOMEM} if not enough memory is available.
 @end deftypefun
 
 @deftypefun gpgme_error_t gpgme_data_new_from_file (@w{gpgme_data_t *@var{dh}}, @w{const char *@var{filename}}, @w{int @var{copy}})
@@ -1122,11 +1561,11 @@ mode supported currently.  Later, a value of zero for @var{copy} might
 cause all reads to be delayed until the data is needed, but this is
 not yet implemented.
 
-The function returns @code{GPGME_No_Error} if the data object was
-successfully created, @code{GPGME_Invalid_Value} if @var{dh} or
-@var{filename} is not a valid pointer, @code{GPGME_File_Error} if an
-I/O operation fails, @code{GPGME_Not_Implemented} if @var{code} is
-zero, and @code{GPGME_Out_Of_Core} if not enough memory is available.
+The function returns the error code @code{GPG_ERR_NO_ERROR} if the
+data object was successfully created, @code{GPG_ERR_INV_VALUE} if
+@var{dh} or @var{filename} is not a valid pointer,
+@code{GPG_ERR_NOT_IMPLEMENTED} if @var{code} is zero, and
+@code{GPG_ERR_ENOMEM} if not enough memory is available.
 @end deftypefun
 
 @deftypefun gpgme_error_t gpgme_data_new_from_filepart (@w{gpgme_data_t *@var{dh}}, @w{const char *@var{filename}}, @w{FILE *@var{fp}}, @w{off_t @var{offset}}, @w{size_t @var{length}})
@@ -1139,11 +1578,10 @@ must be zero.  The argument that is not zero specifies the file from
 which @var{length} bytes are read into the data object, starting from
 @var{offset}.
 
-The function returns @code{GPGME_No_Error} if the data object was
-successfully created, @code{GPGME_Invalid_Value} if @var{dh} and
-exactly one of @var{filename} and @var{fp} is not a valid pointer,
-@code{GPGME_File_Error} if an I/O operation fails, and
-@code{GPGME_Out_Of_Core} if not enough memory is available.
+The function returns the error code @code{GPG_ERR_NO_ERROR} if the
+data object was successfully created, @code{GPG_ERR_INV_VALUE} if
+@var{dh} and exactly one of @var{filename} and @var{fp} is not a valid
+pointer, and @code{GPG_ERR_ENOMEM} if not enough memory is available.
 @end deftypefun
 
 
@@ -1164,9 +1602,13 @@ When using the data object as an input buffer, the function might read
 a bit more from the file descriptor than is actually needed by the
 crypto engine in the desired operation because of internal buffering.
 
-The function returns @code{GPGME_No_Error} if the data object was
-successfully created, and @code{GPGME_Out_Of_Core} if not enough
-memory is available.
+Note that GPGME assumes that the file descriptor is set to blocking
+mode.  Errors during I/O operations, except for EINTR, are usually
+fatal for crypto operations.
+
+The function returns the error code @code{GPG_ERR_NO_ERROR} if the
+data object was successfully created, and @code{GPG_ERR_ENOMEM} if not
+enough memory is available.
 @end deftypefun
 
 @deftypefun gpgme_error_t gpgme_data_new_from_stream (@w{gpgme_data_t *@var{dh}}, @w{FILE *@var{stream}})
@@ -1179,9 +1621,13 @@ When using the data object as an input buffer, the function might read
 a bit more from the stream than is actually needed by the crypto
 engine in the desired operation because of internal buffering.
 
-The function returns @code{GPGME_No_Error} if the data object was
-successfully created, and @code{GPGME_Out_Of_Core} if not enough
-memory is available.
+Note that GPGME assumes that the stream is in blocking mode.  Errors
+during I/O operations, except for EINTR, are usually fatal for crypto
+operations.
+
+The function returns the error code @code{GPG_ERR_NO_ERROR} if the
+data object was successfully created, and @code{GPG_ERR_ENOMEM} if not
+enough memory is available.
 @end deftypefun
 
 
@@ -1200,6 +1646,10 @@ data object.  The function should read up to @var{size} bytes from the
 current read position into the space starting at @var{buffer}.  The
 @var{handle} is provided by the user at data object creation time.
 
+Note that GPGME assumes that the read blocks until data is available.
+Errors during I/O operations, except for EINTR, are usually fatal for
+crypto operations.
+
 The function should return the number of bytes read, 0 on EOF, and -1
 on error.  If an error occurs, @var{errno} should be set to describe
 the type of the error.
@@ -1213,6 +1663,10 @@ data object.  The function should write up to @var{size} bytes to the
 current write position from the space starting at @var{buffer}.  The
 @var{handle} is provided by the user at data object creation time.
 
+Note that GPGME assumes that the write blocks until data is available.
+Errors during I/O operations, except for EINTR, are usually fatal for
+crypto operations.
+
 The function should return the number of bytes written, and -1 on
 error.  If an error occurs, @var{errno} should be set to describe the
 type of the error.
@@ -1269,9 +1723,9 @@ to operate on the data object.
 The handle @var{handle} is passed as first argument to the callback
 functions.  This can be used to identify this data object.
 
-The function returns @code{GPGME_No_Error} if the data object was
-successfully created, and @code{GPGME_Out_Of_Core} if not enough
-memory is available.
+The function returns the error code @code{GPG_ERR_NO_ERROR} if the
+data object was successfully created, and @code{GPG_ERR_ENOMEM} if not
+enough memory is available.
 @end deftypefun
 
 The following interface is deprecated and only provided for backward
@@ -1295,10 +1749,10 @@ return with an error code of @code{-1} and set @var{nread} to
 read pointer if it is invoked with @var{buffer} and @var{nread} being
 @code{NULL} and @var{count} being @code{0}.
 
-The function returns @code{GPGME_No_Error} if the data object was
-successfully created, @code{GPGME_Invalid_Value} if @var{dh} or
-@var{readfunc} is not a valid pointer, and @code{GPGME_Out_Of_Core} if
-not enough memory is available.
+The function returns the error code @code{GPG_ERR_NO_ERROR} if the
+data object was successfully created, @code{GPG_ERR_INV_VALUE} if
+@var{dh} or @var{readfunc} is not a valid pointer, and
+@code{GPG_ERR_ENOMEM} if not enough memory is available.
 @end deftypefun
 
 
@@ -1317,18 +1771,44 @@ The function @code{gpgme_data_release_and_get_mem} is like
 @code{gpgme_data_release}, except that it returns the data buffer and
 its length that was provided by the object.
 
-The user has to release the buffer with @code{free}.  In case the user
-provided the data buffer in non-copy mode, a copy will be made for
-this purpose.
+The user has to release the buffer with @code{gpgme_free}.  In case
+the user provided the data buffer in non-copy mode, a copy will be
+made for this purpose.
 
 In case an error returns, or there is no suitable data buffer that can
-be returned to the user, the function will return @code{NULL}.
+be returned to the user, the function will return @code{NULL}.  In any
+case, the data object @var{dh} is destroyed.
+@end deftypefun
+
+
+@deftypefun void gpgme_free (@w{void *@var{buffer}})
+The function @code{gpgme_free} releases the memory returned by
+@code{gpgme_data_release_and_get_mem}.  It should be used instead of
+the system libraries @code{free} function in case different allocators
+are used in a single program.
 @end deftypefun
 
 
 @node Manipulating Data Buffers
 @section Manipulating Data Buffers
-@cindex data buffere, manipulation
+@cindex data buffer, manipulation
+
+Data buffers contain data and meta-data.  The following operations can
+be used to manipulate both.
+
+
+@menu
+* Data Buffer I/O Operations::    I/O operations on data buffers.
+* Data Buffer Meta-Data::         Meta-data manipulation of data buffers.
+@end menu
+
+
+@node Data Buffer I/O Operations
+@subsection Data Buffer I/O Operations
+@cindex data buffer, I/O operations
+@cindex data buffer, read
+@cindex data buffer, write
+@cindex data buffer, seek
 
 @deftypefun ssize_t gpgme_data_read (@w{gpgme_data_t @var{dh}}, @w{void *@var{buffer}}, @w{size_t @var{length}})
 The function @code{gpgme_data_read} reads up to @var{length} bytes
@@ -1336,8 +1816,7 @@ from the data object with the handle @var{dh} into the space starting
 at @var{buffer}.
 
 If no error occurs, the actual amount read is returned.  If the end of
-the data object is reached, the function returns @code{GPGME_EOF} and
-sets @var{nread} to zero.
+the data object is reached, the function returns 0.
 
 In all other cases, the function returns -1 and sets @var{errno}.
 @end deftypefun
@@ -1351,12 +1830,7 @@ The function returns the number of bytes actually written, or -1 if an
 error occurs.  If an error occurs, @var{errno} is set.
 @end deftypefun
 
-/* Set the current position from where the next read or write starts
-   in the data object with the handle DH to OFFSET, relativ to
-   WHENCE.  */
-off_t gpgme_data_seek (gpgme_data_t dh, off_t offset, int whence);
-
-@deftypefun off_t gpgme_data_seek (@w{gpgme_data_t @var{dh}}, @w{off_t *@var{offset}}, @w{int @var{whence}})
+@deftypefun off_t gpgme_data_seek (@w{gpgme_data_t @var{dh}}, @w{off_t @var{offset}}, @w{int @var{whence}})
 The function @code{gpgme_data_seek} changes the current read/write
 position.
 
@@ -1365,15 +1839,15 @@ interpreted.  It must be one of the following symbolic constants:
 
 @table @code
 @item SEEK_SET
-Specifies that @var{whence} is a count of characters from the
+Specifies that @var{offset} is a count of characters from the
 beginning of the data object.
 
 @item SEEK_CUR
-Specifies that @var{whence} is a count of characters from the current
+Specifies that @var{offset} is a count of characters from the current
 file position.  This count may be positive or negative.
 
 @item SEEK_END
-Specifies that @var{whence} is a count of characters from the end of
+Specifies that @var{offset} is a count of characters from the end of
 the data object.  A negative count specifies a position within the
 current extent of the data object; a positive count specifies a
 position past the current end.  If you set the position past the
@@ -1397,18 +1871,51 @@ The function @code{gpgme_data_rewind} is equivalent to:
 
 @example
   return (gpgme_data_seek (dh, 0, SEEK_SET) == -1)
-    ? mk_error (File_Error) : 0;
+    ? gpgme_error_from_errno (errno) : 0;
 @end example
 @end deftypefun
 
-@c
-@c  gpgme_data_encoding_t
-@c
+
+
+
+@node Data Buffer Meta-Data
+@subsection Data Buffer Meta-Data
+@cindex data buffer, meta-data
+@cindex data buffer, file name
+@cindex data buffer, encoding
+
+@deftypefun {char *} gpgme_data_get_file_name (@w{gpgme_data_t @var{dh}})
+The function @code{gpgme_data_get_file_name} returns a pointer to a
+string containing the file name associated with the data object.  The
+file name will be stored in the output when encrypting or signing the
+data and will be returned to the user when decrypting or verifying the
+output data.
+
+If no error occurs, the string containing the file name is returned.
+Otherwise, @code{NULL} will be returned.
+@end deftypefun
+
+
+@deftypefun gpgme_error_t gpgme_data_set_file_name (@w{gpgme_data_t @var{dh}}, @w{const char *@var{file_name}})
+The function @code{gpgme_data_set_file_name} sets the file name
+associated with the data object.  The file name will be stored in the
+output when encrypting or signing the data and will be returned to the
+user when decrypting or verifying the output data.
+
+The function returns the error code @code{GPG_ERR_INV_VALUE} if
+@var{dh} is not a valid pointer and @code{GPG_ERR_ENOMEM} if not
+enough memory is available.
+@end deftypefun
+
+
 @deftp {Data type} {enum gpgme_data_encoding_t}
 @tindex gpgme_data_encoding_t
 The @code{gpgme_data_encoding_t} type specifies the encoding of a
-@code{gpgme_data_t} object.  This encoding is useful to give the backend
-a hint on the type of data.  The following data types are available:
+@code{gpgme_data_t} object.  For input data objects, the encoding is
+useful to give the backend a hint on the type of data.  For output
+data objects, the encoding can specify the output data format on
+certain operations.  Please note that not all backends support all
+encodings on all operations.  The following data types are available:
 
 @table @code
 @item GPGME_DATA_ENCODING_NONE
@@ -1427,6 +1934,19 @@ scheme as used by @acronym{MIME} and other protocols.
 @item GPGME_DATA_ENCODING_ARMOR
 This specifies that the data is encoded in an armored form as used by
 OpenPGP and PEM.
+
+@item GPGME_DATA_ENCODING_URL
+The data is a list of linefeed delimited URLs.  This is only useful with
+@code{gpgme_op_import}.
+
+@item GPGME_DATA_ENCODING_URL0
+The data is a list of binary zero delimited URLs.  This is only useful
+with @code{gpgme_op_import}.
+
+@item GPGME_DATA_ENCODING_URLESC
+The data is a list of linefeed delimited URLs with all control and space
+characters percent escaped.  This mode is is not yet implemented.
+
 @end table
 @end deftp
 
@@ -1465,6 +1985,7 @@ cryptographic operations.
 @menu
 * Creating Contexts::             Creating new @acronym{GPGME} contexts.
 * Destroying Contexts::           Releasing @acronym{GPGME} contexts.
+* Result Management::             Managing the result of crypto operations.
 * Context Attributes::            Setting properties of a context.
 * Key Management::                Managing keys with @acronym{GPGME}.
 * Trust Item Management::         Managing trust items with @acronym{GPGME}.
@@ -1478,13 +1999,17 @@ cryptographic operations.
 @cindex context, creation
 
 @deftypefun gpgme_error_t gpgme_new (@w{gpgme_ctx_t *@var{ctx}})
-The function @code{gpgme_data_new} creates a new @code{gpgme_ctx_t}
-object and returns a handle for it in @var{ctx}.
-
-The function returns @code{GPGME_No_Error} if the context was
-successfully created, @code{GPGME_Invalid_Value} if @var{ctx} is not a
-valid pointer, and @code{GPGME_Out_Of_Core} if not enough memory is
-available.
+The function @code{gpgme_new} creates a new @code{gpgme_ctx_t} object
+and returns a handle for it in @var{ctx}.
+
+The function returns the error code @code{GPG_ERR_NO_ERROR} if the
+context was successfully created, @code{GPG_ERR_INV_VALUE} if
+@var{ctx} is not a valid pointer, and @code{GPG_ERR_ENOMEM} if not
+enough memory is available.  Also, it returns
+@code{GPG_ERR_NOT_OPERATIONAL} if @code{gpgme_check_version} was not
+called to initialize GPGME, and @code{GPG_ERR_SELFTEST_FAILED} if a
+selftest failed.  Currently, the only selftest is for Windows MingW32
+targets to see if @code{-mms-bitfields} was used (as required).
 @end deftypefun
 
 
@@ -1498,18 +2023,52 @@ The function @code{gpgme_release} destroys the context with the handle
 @end deftypefun
 
 
+@node Result Management
+@section Result Management
+@cindex context, result of operation
+
+The detailed result of an operation is returned in operation-specific
+structures such as @code{gpgme_decrypt_result_t}.  The corresponding
+retrieval functions such as @code{gpgme_op_decrypt_result} provide
+static access to the results after an operation completes.  The
+following interfaces make it possible to detach a result structure
+from its associated context and give it a lifetime beyond that of the
+current operation or context.
+
+@deftypefun void gpgme_result_ref (@w{void *@var{result}})
+The function @code{gpgme_result_ref} acquires an additional reference
+for the result @var{result}, which may be of any type
+@code{gpgme_*_result_t}.  As long as the user holds a reference, the
+result structure is guaranteed to be valid and unmodified.
+@end deftypefun
+
+@deftypefun void gpgme_result_unref (@w{void *@var{result}})
+The function @code{gpgme_result_unref} releases a reference for the
+result @var{result}.  If this was the last reference, the result
+structure will be destroyed and all resources associated to it will be
+released.
+@end deftypefun
+
+Note that a context may hold its own references to result structures,
+typically until the context is destroyed or the next operation is
+started.  In fact, these references are accessed through the
+@code{gpgme_op_*_result} functions.
+
+
 @node Context Attributes
 @section Context Attributes
 @cindex context, attributes
 
 @menu
 * Protocol Selection::            Selecting the protocol used by a context.
-* @acronym{ASCII} Armor::                   Requesting @acronym{ASCII} armored output.
+* Crypto Engine::                 Configuring the crypto engine.
+* ASCII Armor::                   Requesting @acronym{ASCII} armored output.
 * Text Mode::                     Choosing canonical text mode.
 * Included Certificates::       Including a number of certificates.
 * Key Listing Mode::              Selecting key listing mode.
 * Passphrase Callback::           Getting the passphrase from the user.
 * Progress Meter Callback::       Being informed about the progress.
+* Locale::                        Setting the locale of a context.
 @end menu
 
 
@@ -1528,9 +2087,9 @@ Setting the protocol with @code{gpgme_set_protocol} does not check if
 the crypto engine for that protocol is available and installed
 correctly.  @xref{Engine Version Check}.
 
-The function returns @code{GPGME_No_Error} if the protocol could be
-set successfully, and @code{GPGME_Invalid_Value} if @var{protocol} is
-not a valid protocol.
+The function returns the error code @code{GPG_ERR_NO_ERROR} if the
+protocol could be set successfully, and @code{GPG_ERR_INV_VALUE} if
+@var{protocol} is not a valid protocol.
 @end deftypefun
 
 @deftypefun gpgme_protocol_t gpgme_get_protocol (@w{gpgme_ctx_t @var{ctx}})
@@ -1538,7 +2097,52 @@ The function @code{gpgme_get_protocol} retrieves the protocol currently
 use with the context @var{ctx}.
 @end deftypefun
 
-@node @acronym{ASCII} Armor
+
+@node Crypto Engine
+@subsection Crypto Engine
+@cindex context, configuring engine
+@cindex engine, configuration per context
+
+The following functions can be used to set and retrieve the
+configuration of the crypto engines of a specific context.  The
+default can also be retrieved without any particular context.
+@xref{Engine Information}.  The default can also be changed globally.
+@xref{Engine Configuration}.
+
+@deftypefun gpgme_engine_info_t gpgme_ctx_get_engine_info (@w{gpgme_ctx_t @var{ctx}})
+The function @code{gpgme_ctx_get_engine_info} returns a linked list of
+engine info structures.  Each info structure describes the
+configuration of one configured backend, as used by the context
+@var{ctx}.
+
+The result is valid until the next invocation of
+@code{gpgme_ctx_set_engine_info} for this particular context.
+
+This function can not fail.
+@end deftypefun
+
+@deftypefun gpgme_error_t gpgme_ctx_set_engine_info (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_protocol_t @var{proto}}, @w{const char *@var{file_name}}, @w{const char *@var{home_dir}})
+The function @code{gpgme_ctx_set_engine_info} changes the
+configuration of the crypto engine implementing the protocol
+@var{proto} for the context @var{ctx}.
+
+@var{file_name} is the file name of the executable program
+implementing this protocol, and @var{home_dir} is the directory name
+of the configuration directory for this crypto engine.  If
+@var{home_dir} is @code{NULL}, the engine's default will be used.
+
+Currently this function must be used before starting the first crypto
+operation.  It is unspecified if and when the changes will take effect
+if the function is called after starting the first operation on the
+context @var{ctx}.
+
+This function returns the error code @code{GPG_ERR_NO_ERROR} if
+successful, or an eror code on failure.
+@end deftypefun
+
+
+@c FIXME: Unfortunately, using @acronym here breaks texi2dvi.
+@node ASCII Armor
 @subsection @acronym{ASCII} Armor
 @cindex context, armor mode
 @cindex @acronym{ASCII} armor
@@ -1599,6 +2203,9 @@ default, only the sender's certificate is included.  The possible
 values of @var{nr_of_certs} are:
 
 @table @code
+@item GPGME_INCLUDE_CERTS_DEFAULT
+Fall back to the default of the crypto backend.  This is the default
+for GPGME.
 @item -2
 Include all certificates except the root certificate.
 @item -1
@@ -1614,8 +2221,8 @@ from the sender's certificate.  The number @code{n} must be positive.
 
 Values of @var{nr_of_certs} smaller than -2 are undefined.
 
-This option is only relevant to the CMS crypto engine, and ignored
-by all other engines.
+This option is only relevant to the CMS crypto engine, and ignored by
+all other engines.
 @end deftypefun
 
 @deftypefun int gpgme_get_include_certs (@w{gpgme_ctx_t @var{ctx}})
@@ -1629,7 +2236,7 @@ certificates to include into an S/MIME signed message.
 @cindex key listing mode
 @cindex key listing, mode of
 
-@deftypefun void gpgme_set_keylist_mode (@w{gpgme_ctx_t @var{ctx}}, @w{int @var{mode}})
+@deftypefun gpgme_error_t gpgme_set_keylist_mode (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_keylist_mode_t @var{mode}})
 The function @code{gpgme_set_keylist_mode} changes the default
 behaviour of the key listing functions.  The value in @var{mode} is a
 bitwise-or combination of one or multiple of the following bit values:
@@ -1642,32 +2249,50 @@ is the default.
 
 @item GPGME_KEYLIST_MODE_EXTERN
 The @code{GPGME_KEYLIST_MODE_EXTERN} symbol specifies that an external
-source should be should be searched for keys in the keylisting
-operation.  The type of external source is dependant on the crypto
-engine used.  For example, it can be a remote keyserver or LDAP
-certificate server.
+source should be searched for keys in the keylisting operation.  The
+type of external source is dependant on the crypto engine used and
+whether it is combined with @code{GPGME_KEYLIST_MODE_LOCAL}.  For
+example, it can be a remote keyserver or LDAP certificate server.
 
 @item GPGME_KEYLIST_MODE_SIGS
 The @code{GPGME_KEYLIST_MODE_SIGS} symbol specifies that the key
 signatures should be included in the listed keys.
+
+@item GPGME_KEYLIST_MODE_SIG_NOTATIONS
+The @code{GPGME_KEYLIST_MODE_SIG_NOTATIONS} symbol specifies that the
+signature notations on key signatures should be included in the listed
+keys.  This only works if @code{GPGME_KEYLIST_MODE_SIGS} is also
+enabled.
+
+@item GPGME_KEYLIST_MODE_EPHEMERAL
+The @code{GPGME_KEYLIST_MODE_EPHEMERAL} symbol specifies that keys
+flagged as ephemeral are included in the listing.
+
+@item GPGME_KEYLIST_MODE_VALIDATE
+The @code{GPGME_KEYLIST_MODE_VALIDATE} symbol specifies that the
+backend should do key or certificate validation and not just get the
+validity information from an internal cache.  This might be an
+expensive operation and is in general not useful.  Currently only
+implemented for the S/MIME backend and ignored for other backends.
+
 @end table
 
 At least one of @code{GPGME_KEYLIST_MODE_LOCAL} and
 @code{GPGME_KEYLIST_MODE_EXTERN} must be specified.  For future binary
 compatibility, you should get the current mode with
 @code{gpgme_get_keylist_mode} and modify it by setting or clearing the
-appropriate bits, and then using that calulcated value in the
+appropriate bits, and then using that calculated value in the
 @code{gpgme_set_keylisting_mode} operation.  This will leave all other
 bits in the mode value intact (in particular those that are not used
 in the current version of the library).
 
-The function returns @code{GPGME_No_Error} if the mode could be set
-correctly, and @code{GPGME_Invalid_Value} if @var{ctx} is not a valid
-pointer or @var{mode} is not a valid mode.
+The function returns the error code @code{GPG_ERR_NO_ERROR} if the
+mode could be set correctly, and @code{GPG_ERR_INV_VALUE} if @var{ctx}
+is not a valid pointer or @var{mode} is not a valid mode.
 @end deftypefun
 
 
-@deftypefun int gpgme_get_keylist_mode (@w{gpgme_ctx_t @var{ctx}})
+@deftypefun gpgme_keylist_mode_t gpgme_get_keylist_mode (@w{gpgme_ctx_t @var{ctx}})
 The function @code{gpgme_get_keylist_mode} returns the current key
 listing mode of the context @var{ctx}.  This value can then be
 modified and used in a subsequent @code{gpgme_set_keylist_mode}
@@ -1703,13 +2328,13 @@ previous attempts failed, then @var{prev_was_bad} is 1, otherwise it
 will be 0.
 
 The user must write the passphrase, followed by a newline character,
-to the file descriptor @var{fd}.  If the user does not return 0
-indicating success, the user must at least write a newline character
-before returning from the callback.
+to the file descriptor @var{fd}.  If the user returns 0 indicating
+success, the user must at least write a newline character before
+returning from the callback.
 
-If an error occurs, return the corresponding @code{gpgme_error_t} value.
-You can use @code{GPGME_Canceled} to abort the operation.  Otherwise,
-return @code{0}.
+If an error occurs, return the corresponding @code{gpgme_error_t}
+value.  You can use the error code @code{GPG_ERR_CANCELED} to abort
+the operation.  Otherwise, return @code{0}.
 @end deftp
 
 @deftypefun void gpgme_set_passphrase_cb (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_passphrase_cb_t @var{passfunc}}, @w{void *@var{hook_value}})
@@ -1723,7 +2348,9 @@ function is set.
 Not all crypto engines require this callback to retrieve the
 passphrase.  It is better if the engine retrieves the passphrase from
 a trusted agent (a daemon process), rather than having each user to
-implement their own passphrase query.
+implement their own passphrase query.  Some engines do not even
+support an external passphrase callback at all, in this case the error
+code @code{GPG_ERR_NOT_SUPPORTED} is returned.
 
 The user can disable the use of a passphrase callback function by
 calling @code{gpgme_set_passphrase_cb} with @var{passfunc} being
@@ -1747,7 +2374,7 @@ the corresponding value will not be returned.
 @cindex callback, progress meter
 @cindex progress meter callback
 
-@deftp {Data type} {const char *(*gpgme_progress_cb_t)(void *@var{hook}, const char *@var{what}, int @var{type}, int @var{current}, int @var{total})}
+@deftp {Data type} {void (*gpgme_progress_cb_t)(void *@var{hook}, const char *@var{what}, int @var{type}, int @var{current}, int @var{total})}
 @tindex gpgme_progress_cb_t
 The @code{gpgme_progress_cb_t} type is the type of functions usable as
 progress callback function.
@@ -1786,6 +2413,43 @@ the corresponding value will not be returned.
 @end deftypefun
 
 
+@node Locale
+@subsection Locale
+@cindex locale, default
+@cindex locale, of a context
+
+A locale setting can be associated with a context.  This locale is
+passed to the crypto engine, and used for applications like the PIN
+entry, which is displayed to the user when entering a passphrase is
+required.
+
+The default locale is used to initialize the locale setting of all
+contexts created afterwards.
+
+@deftypefun gpgme_error_t gpgme_set_locale (@w{gpgme_ctx_t @var{ctx}}, @w{int @var{category}}, @w{const char *@var{value}})
+The function @code{gpgme_set_locale} sets the locale of the context
+@var{ctx}, or the default locale if @var{ctx} is a null pointer.
+
+The locale settings that should be changed are specified by
+@var{category}.  Supported categories are @code{LC_CTYPE},
+@code{LC_MESSAGES}, and @code{LC_ALL}, which is a wildcard you can use
+if you want to change all the categories at once.
+
+The value to be used for the locale setting is @var{value}, which will
+be copied to @acronym{GPGME}'s internal data structures.  @var{value}
+can be a null pointer, which disables setting the locale, and will
+make PIN entry and other applications use their default setting, which
+is usually not what you want.
+
+Note that the settings are only used if the application runs on a text
+terminal, and that the settings should fit the configuration of the
+output terminal.  Normally, it is sufficient to initialize the default
+value at startup.
+
+The function returns an error if not enough memory is available.
+@end deftypefun
+
+
 @node Key Management
 @section Key Management
 @cindex key management
@@ -1796,12 +2460,12 @@ respective keys that should be used for the operation.  The following
 section describes how such keys can be selected and manipulated.
 
 @deftp {Data type} gpgme_sub_key_t
-The @code{gpgme_sub_key_t} type is a pointer to a subkey structure.  Sub
-keys are one component of a @code{gpgme_key_t} object.  In fact, subkeys
-are those parts that contains the real information about the
+The @code{gpgme_sub_key_t} type is a pointer to a subkey structure.
+Sub keys are one component of a @code{gpgme_key_t} object.  In fact,
+subkeys are those parts that contains the real information about the
 individual cryptographic keys that belong to the same key object.  One
-@code{gpgme_key_t} can contain several subkeys.  The first subkey in the
-linked list is also called the primary key.
+@code{gpgme_key_t} can contain several subkeys.  The first subkey in
+the linked list is also called the primary key.
 
 The subkey structure has the following members:
 
@@ -1826,13 +2490,22 @@ This is true if the subkey is invalid.
 This is true if the subkey can be used for encryption.
 
 @item unsigned int can_sign : 1
-This is true if the subkey can be used for signing.
+This is true if the subkey can be used to create data signatures.
 
 @item unsigned int can_certify : 1
-This is true if the subkey can be used for certification.
+This is true if the subkey can be used to create key certificates.
+
+@item unsigned int can_authenticate : 1
+This is true if the subkey can be used for authentication.
+
+@item unsigned int is_qualified : 1
+This is true if the subkey can be used for qualified signatures
+according to local government regulations.
 
 @item unsigned int secret : 1
-This is true if the subkey is a secret key.
+This is true if the subkey is a secret key.  Note that it will be false
+if the key is actually a stub key; i.e. a secret key operation is
+currently not possible (offline-key).
 
 @item gpgme_pubkey_algo_t pubkey_algo
 This is the public key algorithm supported by this subkey.
@@ -1845,7 +2518,7 @@ This is the key ID of the subkey in hexadecimal digits.
 
 @item char *fpr
 This is the fingerprint of the subkey in hexadecimal digits, if
-available.  This is usually only available for the primary key.
+available.
 
 @item long int timestamp
 This is the creation timestamp of the subkey.  This is -1 if the
@@ -1864,7 +2537,13 @@ validate user IDs on the key.
 
 The signatures on a key are only available if the key was retrieved
 via a listing operation with the @code{GPGME_KEYLIST_MODE_SIGS} mode
-enabled, because it is expensive to retrieve all signatures of a key.
+enabled, because it can be expensive to retrieve all signatures of a
+key.
+
+The signature notations on a key signature are only available if the
+key was retrieved via a listing operation with the
+@code{GPGME_KEYLIST_MODE_SIG_NOTATIONS} mode enabled, because it can
+be expensive to retrieve all signature notations.
 
 The key signature structure has the following members:
 
@@ -1882,7 +2561,7 @@ This is true if the key signature is expired.
 @item unsigned int invalid : 1
 This is true if the key signature is invalid.
 
-@item unsigned int disabled : 1
+@item unsigned int exportable : 1
 This is true if the key signature is exportable.
 
 @item gpgme_pubkey_algo_t pubkey_algo
@@ -1904,7 +2583,7 @@ signature does not expire.
 This is the status of the signature and has the same meaning as the
 member of the same name in a @code{gpgme_signature_t} object.
 
-@item unsigned int class
+@item unsigned int sig_class
 This specifies the signature class of the key signature.  The meaning
 is specific to the crypto engine.
 
@@ -1919,6 +2598,9 @@ This is the comment component of @code{uid}, if available.
 
 @item char *email
 This is the email component of @code{uid}, if available.
+
+@item gpgme_sig_notation_t notations
+This is a linked list with the notation data and policy URLs.
 @end table
 @end deftp
 
@@ -1965,6 +2647,9 @@ The @code{gpgme_key_t} type is a pointer to a key object.  It has the
 following members:
 
 @table @code
+@item gpgme_keylist_mode_t keylist_mode
+The keylist mode that was active when the key was retrieved.
+
 @item unsigned int revoked : 1
 This is true if the key is revoked.
 
@@ -1975,22 +2660,35 @@ This is true if the key is expired.
 This is true if the key is disabled.
 
 @item unsigned int invalid : 1
-This is true if the key is invalid.
+This is true if the key is invalid. This might have several reasons,
+for a example for the S/MIME backend, it will be set in during key
+listsing if the key could not be validated due to a missing
+certificates or unmatched policies.
 
 @item unsigned int can_encrypt : 1
 This is true if the key (ie one of its subkeys) can be used for
 encryption.
 
 @item unsigned int can_sign : 1
-This is true if the key (ie one of its subkeys) can be used for
-signing.
+This is true if the key (ie one of its subkeys) can be used to create
+data signatures.
 
 @item unsigned int can_certify : 1
+This is true if the key (ie one of its subkeys) can be used to create
+key certificates.
+
+@item unsigned int can_authenticate : 1
 This is true if the key (ie one of its subkeys) can be used for
-certification.
+authentication.
+
+@item unsigned int is_qualified : 1
+This is true if the key can be used for qualified signatures according
+to local government regulations.
 
 @item unsigned int secret : 1
-This is true if the key is a secret key.
+This is true if the key is a secret key.  Note, that this will always be
+true even if the corresponding subkey flag may be false (offline/stub
+keys).
 
 @item gpgme_protocol_t protocol
 This is the protocol supported by this key.
@@ -2030,6 +2728,7 @@ in the list is the main (or primary) user ID.
 * Exporting Keys::                Retrieving key data from the key ring.
 * Importing Keys::                Adding keys to the key ring.
 * Deleting Keys::                 Removing keys from the key ring.
+* Advanced Key Editing::          Advanced key edit operation.
 @end menu
 
 
@@ -2049,18 +2748,23 @@ in the list.
 
 If @var{pattern} is @code{NULL}, all available keys are returned.
 Otherwise, @var{pattern} contains an engine specific expression that
-is used to limit the list to all keys matching the pattern.
+is used to limit the list to all keys matching the pattern.  Note that
+the total length of the pattern is restricted to an engine-specific
+maximum (a couple of hundred characters are usually accepted).  The
+pattern should be used to restrict the search to a certain common name
+or user, not to list many specific keys at once by listing their
+fingerprints or key IDs.
 
 If @var{secret_only} is not @code{0}, the list is restricted to secret
 keys only.
 
 The context will be busy until either all keys are received (and
-@code{gpgme_op_keylist_next} returns @code{GPGME_EOF}), or
+@code{gpgme_op_keylist_next} returns @code{GPG_ERR_EOF}), or
 @code{gpgme_op_keylist_end} is called to finish the operation.
 
-The function returns @code{GPGME_Invalid_Value} if @var{ctx} is not a
-valid pointer, and passes through any errors that are reported by the
-crypto engine support routines.
+The function returns the error code @code{GPG_ERR_INV_VALUE} if
+@var{ctx} is not a valid pointer, and passes through any errors that
+are reported by the crypto engine support routines.
 @end deftypefun
 
 @deftypefun gpgme_error_t gpgme_op_keylist_ext_start (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{pattern}[]}, @w{int @var{secret_only}}, @w{int @var{reserved}})
@@ -2072,7 +2776,13 @@ everything up so that subsequent invocations of
 If @var{pattern} or @var{*pattern} is @code{NULL}, all available keys
 are returned.  Otherwise, @var{pattern} is a @code{NULL} terminated
 array of strings that are used to limit the list to all keys matching
-at least one of the patterns verbatim.
+at least one of the patterns verbatim.  Note that the total length of
+all patterns is restricted to an engine-specific maximum (the exact
+limit also depends on the number of patterns and amount of quoting
+required, but a couple of hundred characters are usually accepted).
+Patterns should be used to restrict the search to a certain common
+name or user, not to list many specific keys at once by listing their
+fingerprints or key IDs.
 
 If @var{secret_only} is not @code{0}, the list is restricted to secret
 keys only.
@@ -2080,12 +2790,12 @@ keys only.
 The value of @var{reserved} must be @code{0}.
 
 The context will be busy until either all keys are received (and
-@code{gpgme_op_keylist_next} returns @code{GPGME_EOF}), or
+@code{gpgme_op_keylist_next} returns @code{GPG_ERR_EOF}), or
 @code{gpgme_op_keylist_end} is called to finish the operation.
 
-The function returns @code{GPGME_Invalid_Value} if @var{ctx} is not a
-valid pointer, and passes through any errors that are reported by the
-crypto engine support routines.
+The function returns the error code @code{GPG_ERR_INV_VALUE} if
+@var{ctx} is not a valid pointer, and passes through any errors that
+are reported by the crypto engine support routines.
 @end deftypefun
 
 @deftypefun gpgme_error_t gpgme_op_keylist_next (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t *@var{r_key}})
@@ -2098,11 +2808,11 @@ This is the only way to get at @code{gpgme_key_t} objects in
 @acronym{GPGME}.
 
 If the last key in the list has already been returned,
-@code{gpgme_op_keylist_next} returns @code{GPGME_EOF}.
+@code{gpgme_op_keylist_next} returns @code{GPG_ERR_EOF}.
 
-The function returns @code{GPGME_Invalid_Value} if @var{ctx} or
-@var{r_key} is not a valid pointer, and @code{GPGME_Out_Of_Core} if
-there is not enough memory for the operation.
+The function returns the error code @code{GPG_ERR_INV_VALUE} if
+@var{ctx} or @var{r_key} is not a valid pointer, and
+@code{GPG_ERR_ENOMEM} if there is not enough memory for the operation.
 @end deftypefun
 
 @deftypefun gpgme_error_t gpgme_op_keylist_end (@w{gpgme_ctx_t @var{ctx}})
@@ -2113,9 +2823,9 @@ After the operation completed successfully, the result of the key
 listing operation can be retrieved with
 @code{gpgme_op_keylist_result}.
 
-The function returns @code{GPGME_Invalid_Value} if @var{ctx} is not a
-valid pointer, and @code{GPGME_Out_Of_Core} if at some time during the
-operation there was not enough memory available.
+The function returns the error code @code{GPG_ERR_INV_VALUE} if
+@var{ctx} is not a valid pointer, and @code{GPG_ERR_ENOMEM} if at some
+time during the operation there was not enough memory available.
 @end deftypefun
 
 The following example illustrates how all keys containing a certain
@@ -2124,25 +2834,30 @@ and e-mail address of the main user ID:
 
 @example
 gpgme_ctx_t ctx;
+gpgme_key_t key;
 gpgme_error_t err = gpgme_new (&ctx);
 
 if (!err)
   @{
     err = gpgme_op_keylist_start (ctx, "g10code", 0);
-    while (!err && (err = gpgme_op_keylist_next (ctx, &key)) != GPGME_EOF)
+    while (!err)
       @{
-        printf ("%s: %s <%s>\n",
-                gpgme_key_get_string_attr (key, GPGME_ATTR_KEYID, 0, 0),
-               gpgme_key_get_string_attr (key, GPGME_ATTR_NAME, 0, 0),
-               gpgme_key_get_string_attr (key, GPGME_ATTR_EMAIL, 0, 0));
+        err = gpgme_op_keylist_next (ctx, &key);
+        if (err)
+          break;
+        printf ("%s:", key->subkeys->keyid);
+        if (key->uids && key->uids->name)
+          printf (" %s", key->uids->name);
+        if (key->uids && key->uids->email)
+          printf (" <%s>", key->uids->email);
+        putchar ('\n');
         gpgme_key_release (key);
       @}
     gpgme_release (ctx);
   @}
-if (err)
+if (gpg_err_code (err) != GPG_ERR_EOF)
   @{
-    fprintf (stderr, "%s: can not list keys: %s\n",
-             argv[0], gpgme_strerror (err));
+    fprintf (stderr, "can not list keys: %s\n", gpgme_strerror (err));
     exit (1);
   @}
 @end example
@@ -2163,11 +2878,12 @@ less than the desired keys could be listed.
 
 @deftypefun gpgme_keylist_result_t gpgme_op_keylist_result (@w{gpgme_ctx_t @var{ctx}})
 The function @code{gpgme_op_keylist_result} returns a
-@code{gpgme_keylist_result_t} pointer to a structure holding the result of
-a @code{gpgme_op_keylist_*} operation.  The pointer is only valid if
-the last operation on the context was a key listing operation, and if
-this operation finished successfully.  The returned pointer is only
-valid until the next operation is started on the context.
+@code{gpgme_keylist_result_t} pointer to a structure holding the
+result of a @code{gpgme_op_keylist_*} operation.  The pointer is only
+valid if the last operation on the context was a key listing
+operation, and if this operation finished successfully.  The returned
+pointer is only valid until the next operation is started on the
+context.
 @end deftypefun
 
 In a simple program, for which a blocking operation is acceptable, the
@@ -2176,19 +2892,19 @@ following function can be used to retrieve a single key.
 @deftypefun gpgme_error_t gpgme_get_key (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{fpr}}, @w{gpgme_key_t *@var{r_key}}, @w{int @var{secret}})
 The function @code{gpgme_get_key} gets the key with the fingerprint
 (or key ID) @var{fpr} from the crypto backend and return it in
-@var{r_key}.  If @var{force_update} is true, force a refresh of the
-key from the crypto backend and replace the key in the cache, if any.
-If @var{secret} is true, get the secret key.  The currently active
-keylist mode is used to retrieve the key.
+@var{r_key}.  If @var{secret} is true, get the secret key.  The
+currently active keylist mode is used to retrieve the key.  The key
+will have one reference for the user.
 
 If the key is not found in the keyring, @code{gpgme_get_key} returns
-@code{GPGME_No_Error} and *@var{r_key} will be set to @code{NULL}.
+the error code @code{GPG_ERR_EOF} and *@var{r_key} will be set to
+@code{NULL}.
 
-The function returns @code{GPGME_Invalid_Value} if @var{ctx} or
-@var{r_key} is not a valid pointer, @code{GPGME_Invalid_Key} if
-@var{fpr} is not a fingerprint or key ID, @code{GPGME_Out_Of_Core} if
-at some time during the operation there was not enough memory
-available.
+The function returns the error code @code{GPG_ERR_INV_VALUE} if
+@var{ctx} or @var{r_key} is not a valid pointer or @var{fpr} is not a
+fingerprint or key ID, @code{GPG_ERR_AMBIGUOUS_NAME} if the key ID was
+not a unique specifier for a key, and @code{GPG_ERR_ENOMEM} if at some
+time during the operation there was not enough memory available.
 @end deftypefun
 
 
@@ -2346,14 +3062,14 @@ representable as a number, and is @code{1} if the sub key can be used
 for encryption, and @code{0} otherwise.
 
 @item GPGME_ATTR_CAN_SIGN
-This specifies if a sub key can be used for signatures.  It is
-representable as a number, and is @code{1} if the sub key can be used
-for signatures, and @code{0} otherwise.
+This specifies if a sub key can be used to create data signatures.  It
+is representable as a number, and is @code{1} if the sub key can be
+used for signatures, and @code{0} otherwise.
 
 @item GPGME_ATTR_CAN_CERTIFY
-This specifies if a sub key can be used for certifications.  It is
-representable as a number, and is @code{1} if the sub key can be used
-for certifications, and @code{0} otherwise.
+This specifies if a sub key can be used to create key certificates.
+It is representable as a number, and is @code{1} if the sub key can be
+used for certifications, and @code{0} otherwise.
 
 @item GPGME_ATTR_SERIAL
 The X.509 issuer serial attribute of the key.  It is representable as
@@ -2393,8 +3109,8 @@ returned.  The argument @var{reserved} is reserved for later use and
 should be @code{NULL}.
 
 The function returns @code{0} if the attribute can't be returned as a
-number, @var{key} is not a valid pointer, @var{idx} out of range,
-or @var{reserved} not @code{NULL}.
+number, @var{key} is not a valid pointer, @var{idx} out of range, or
+@var{reserved} not @code{NULL}.
 @end deftypefun
 
 
@@ -2590,11 +3306,11 @@ statements are not allowed.
 After the operation completed successfully, the result can be
 retrieved with @code{gpgme_op_genkey_result}.
 
-The function returns @code{GPGME_No_Error} if the operation could be
-started successfully, @code{GPGME_Invalid_Value} if @var{parms} is not
-a valid XML string, @code{GPGME_Not_Supported} if @var{public} or
-@var{secret} is not valid, and @code{GPGME_General_Error} if no key
-was created by the backend.
+The function returns the error code @code{GPG_ERR_NO_ERROR} if the
+operation could be started successfully, @code{GPG_ERR_INV_VALUE} if
+@var{parms} is not a valid XML string, @code{GPG_ERR_NOT_SUPPORTED} if
+@var{public} or @var{secret} is not valid, and @code{GPG_ERR_GENERAL}
+if no key was created by the backend.
 @end deftypefun
 
 @deftypefun gpgme_error_t gpgme_op_genkey_start (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{parms}}, @w{gpgme_data_t @var{public}}, @w{gpgme_data_t @var{secret}})
@@ -2602,10 +3318,11 @@ The function @code{gpgme_op_genkey_start} initiates a
 @code{gpgme_op_genkey} operation.  It can be completed by calling
 @code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
 
-The function returns @code{GPGME_No_Error} if the operation could be
-started successfully, @code{GPGME_Invalid_Value} if @var{parms} is not
-a valid XML string, and @code{GPGME_Not_Supported} if @var{public} or
-@var{secret} is not @code{NULL}.
+The function returns the error code @code{GPG_ERR_NO_ERROR} if the
+operation could be started successfully, @code{GPG_ERR_INV_VALUE} if
+@var{parms} is not a valid XML string, and
+@code{GPG_ERR_NOT_SUPPORTED} if @var{public} or @var{secret} is not
+@code{NULL}.
 @end deftypefun
 
 @deftp {Data type} {gpgme_genkey_result_t}
@@ -2648,28 +3365,116 @@ operation is started on the context.
 @cindex key, export
 @cindex key ring, export from
 
-@deftypefun gpgme_error_t gpgme_op_export (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_recipients_t @var{recipients}}, @w{gpgme_data_t @var{keydata}})
-The function @code{gpgme_op_export} extracts the public keys of the
-user IDs in @var{recipients} and returns them in the data buffer
-@var{keydata}.  The type of the public keys returned is determined by
-the @acronym{ASCII} armor attribute set for the context @var{ctx}.
+Exporting keys means the same as running @command{gpg} with the command
+@option{--export}.  However, a mode flag can be used to change the way
+the export works.  The available mode flags are described below, they
+may be or-ed together.
 
-The function returns @code{GPGME_No_Error} if the operation completed
-successfully, @code{GPGME_Invalid_Value} if @var{recipients} is
-@code{NULL} or @var{keydata} is not a valid empty data buffer, and
-passes through any errors that are reported by the crypto engine
-support routines.
+@table @code
+
+@item GPGME_EXPORT_MODE_EXTERN
+If this bit is set, the output is send directly to the default
+keyserver. This is currently only allowed for OpenPGP keys.  It is good
+practise to not send more than a few dozens key to a keyserver at one
+time.  Using this flag requires that the @var{keydata} argument of the
+export function is set to @code{NULL}.
+
+@end table
+
+
+
+@deftypefun gpgme_error_t gpgme_op_export (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{pattern}}, @w{gpgme_export_mode_t @var{mode}}, @w{gpgme_data_t @var{keydata}})
+The function @code{gpgme_op_export} extracts public keys and returns
+them in the data buffer @var{keydata}.  The output format of the key
+data returned is determined by the @acronym{ASCII} armor attribute set
+for the context @var{ctx}, or, if that is not set, by the encoding
+specified for @var{keydata}.
+
+If @var{pattern} is @code{NULL}, all available keys are returned.
+Otherwise, @var{pattern} contains an engine specific expression that
+is used to limit the list to all keys matching the pattern.
+
+@var{mode} is usually 0; other values are described above.
+
+The function returns the error code @code{GPG_ERR_NO_ERROR} if the
+operation completed successfully, @code{GPG_ERR_INV_VALUE} if
+@var{keydata} is not a valid empty data buffer, and passes through any
+errors that are reported by the crypto engine support routines.
 @end deftypefun
 
-@deftypefun gpgme_error_t gpgme_op_export_start (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_recipients_t @var{recipients}}, @w{gpgme_data_t @var{keydata}})
+@deftypefun gpgme_error_t gpgme_op_export_start (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{pattern}}, @w{gpgme_export_mode_t @var{mode}}, @w{gpgme_data_t @var{keydata}})
 The function @code{gpgme_op_export_start} initiates a
 @code{gpgme_op_export} operation.  It can be completed by calling
 @code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
 
-The function returns @code{GPGME_No_Error} if the operation could be
-started successfully, and @code{GPGME_Invalid_Value} if
-@var{recipients} is @code{NULL} or @var{keydata} is not a valid empty
-data buffer.
+The function returns the error code @code{GPG_ERR_NO_ERROR} if the
+operation could be started successfully, and @code{GPG_ERR_INV_VALUE}
+if @var{keydata} is not a valid empty data buffer.
+@end deftypefun
+
+@deftypefun gpgme_error_t gpgme_op_export_ext (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{pattern}[]}, @w{gpgme_export_mode_t @var{mode}}, @w{gpgme_data_t @var{keydata}})
+The function @code{gpgme_op_export} extracts public keys and returns
+them in the data buffer @var{keydata}.  The output format of the key
+data returned is determined by the @acronym{ASCII} armor attribute set
+for the context @var{ctx}, or, if that is not set, by the encoding
+specified for @var{keydata}.
+
+If @var{pattern} or @var{*pattern} is @code{NULL}, all available keys
+are returned.  Otherwise, @var{pattern} is a @code{NULL} terminated
+array of strings that are used to limit the list to all keys matching
+at least one of the patterns verbatim.
+
+@var{mode} is usually 0; other values are described above.
+
+The function returns the error code @code{GPG_ERR_NO_ERROR} if the
+operation completed successfully, @code{GPG_ERR_INV_VALUE} if
+@var{keydata} is not a valid empty data buffer, and passes through any
+errors that are reported by the crypto engine support routines.
+@end deftypefun
+
+@deftypefun gpgme_error_t gpgme_op_export_ext_start (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{pattern}[]}, @w{gpgme_export_mode_t @var{mode}}, @w{gpgme_data_t @var{keydata}})
+The function @code{gpgme_op_export_ext_start} initiates a
+@code{gpgme_op_export_ext} operation.  It can be completed by calling
+@code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
+
+The function returns the error code @code{GPG_ERR_NO_ERROR} if the
+operation could be started successfully, and @code{GPG_ERR_INV_VALUE}
+if @var{keydata} is not a valid empty data buffer.
+@end deftypefun
+
+
+@deftypefun gpgme_error_t gpgme_op_export_keys (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t keys[]}, @w{gpgme_export_mode_t @var{mode}}, @w{gpgme_data_t @var{keydata}})
+The function @code{gpgme_op_export_keys} extracts public keys and returns
+them in the data buffer @var{keydata}.  The output format of the key
+data returned is determined by the @acronym{ASCII} armor attribute set
+for the context @var{ctx}, or, if that is not set, by the encoding
+specified for @var{keydata}.
+
+The keys to export are taken form the @code{NULL} terminated array
+@var{keys}.  Only keys of the the currently selected protocol of
+@var{ctx} which do have a fingerprint set are considered for export.
+Other keys specified by the @var{keys} are ignored.  In particular
+OpenPGP keys retrieved via an external key listing are not included.
+
+@var{mode} is usually 0; other values are described above.
+
+The function returns the error code @code{GPG_ERR_NO_ERROR} if the
+operation completed successfully, @code{GPG_ERR_INV_VALUE} if
+@var{keydata} is not a valid empty data buffer, @code{GPG_ERR_NO_DATA}
+if no useful keys are in @var{keys} and passes through any errors that
+are reported by the crypto engine support routines.
+@end deftypefun
+
+@deftypefun gpgme_error_t gpgme_op_export_keys_start (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t @var{keys}[]}, @w{gpgme_export_mode_t @var{mode}}, @w{gpgme_data_t @var{keydata}})
+The function @code{gpgme_op_export_keys_start} initiates a
+@code{gpgme_op_export_ext} operation.  It can be completed by calling
+@code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
+
+The function returns the error code @code{GPG_ERR_NO_ERROR} if the
+operation could be started successfully, and @code{GPG_ERR_INV_VALUE}
+if @var{keydata} is not a valid empty data buffer, @code{GPG_ERR_NO_DATA}
+if no useful keys are in @var{keys} and passes through any errors that
+are reported by the crypto engine support routines.
 @end deftypefun
 
 
@@ -2678,19 +3483,23 @@ data buffer.
 @cindex key, import
 @cindex key ring, import to
 
+Importing keys means the same as running @command{gpg} with the command
+@option{--import}. 
+
+
 @deftypefun gpgme_error_t gpgme_op_import (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{keydata}})
 The function @code{gpgme_op_import} adds the keys in the data buffer
 @var{keydata} to the key ring of the crypto engine used by @var{ctx}.
-The format of @var{keydata} can be @var{ASCII} armored, for example,
+The format of @var{keydata} can be @acronym{ASCII} armored, for example,
 but the details are specific to the crypto engine.
 
 After the operation completed successfully, the result can be
 retrieved with @code{gpgme_op_import_result}.
 
-The function returns @code{GPGME_No_Error} if the import was completed
-successfully, @code{GPGME_Invalid_Value} if @var{keydata} if @var{ctx}
-or @var{keydata} is not a valid pointer, and @code{GPGME_No_Data} if
-@var{keydata} is an empty data buffer.
+The function returns the error code @code{GPG_ERR_NO_ERROR} if the
+import was completed successfully, @code{GPG_ERR_INV_VALUE} if
+@var{keydata} if @var{ctx} or @var{keydata} is not a valid pointer,
+and @code{GPG_ERR_NO_DATA} if @var{keydata} is an empty data buffer.
 @end deftypefun
 
 @deftypefun gpgme_error_t gpgme_op_import_start (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{keydata}})
@@ -2698,10 +3507,48 @@ The function @code{gpgme_op_import_start} initiates a
 @code{gpgme_op_import} operation.  It can be completed by calling
 @code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
 
-The function returns @code{GPGME_No_Error} if the import could be
-started successfully, @code{GPGME_Invalid_Value} if @var{keydata} if
-@var{ctx} or @var{keydata} is not a valid pointer, and
-@code{GPGME_No_Data} if @var{keydata} is an empty data buffer.
+The function returns the error code @code{GPG_ERR_NO_ERROR} if the
+import could be started successfully, @code{GPG_ERR_INV_VALUE} if
+@var{keydata} if @var{ctx} or @var{keydata} is not a valid pointer,
+and @code{GPG_ERR_NO_DATA} if @var{keydata} is an empty data buffer.
+@end deftypefun
+
+@deftypefun gpgme_error_t gpgme_op_import_keys (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t *@var{keys}})
+The function @code{gpgme_op_import_keys} adds the keys described by the
+@code{NULL} terminated array @var{keys} to the key ring of the crypto
+engine used by @var{ctx}.  This function is the general interface to
+move a key from one crypto engine to another as long as they are
+compatible.  In particular it is used to actually import and make keys
+permanent which have been retrieved from an external source (i.e. using
+@code{GPGME_KEYLIST_MODE_EXTERN}).  @footnote{Thus it is a replacement
+for the usual workaround of exporting and then importing a key to make
+an X.509 key permanent.}
+
+Only keys of the the currently selected protocol of @var{ctx} are
+considered for import.  Other keys specified by the @var{keys} are
+ignored.  As of now all considered keys must have been retrieved using
+the same method, that is the used key listing mode must be identical.
+
+After the operation completed successfully, the result can be
+retrieved with @code{gpgme_op_import_result}.
+
+The function returns the error code @code{GPG_ERR_NO_ERROR} if the
+import was completed successfully, @code{GPG_ERR_INV_VALUE} if
+@var{keydata} if @var{ctx} or @var{keydata} is not a valid pointer,
+@code{GPG_ERR_CONFLICT} if the key listing mode does not match, and
+@code{GPG_ERR_NO_DATA} if no keys are considered for export.
+@end deftypefun
+
+@deftypefun gpgme_error_t gpgme_op_import_keys_start (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t *@var{keys}})
+The function @code{gpgme_op_import_keys_start} initiates a
+@code{gpgme_op_import_keys} operation.  It can be completed by calling
+@code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
+
+The function returns the error code @code{GPG_ERR_NO_ERROR} if the
+import was completed successfully, @code{GPG_ERR_INV_VALUE} if
+@var{keydata} if @var{ctx} or @var{keydata} is not a valid pointer,
+@code{GPG_ERR_CONFLICT} if the key listing mode does not match, and
+@code{GPG_ERR_NO_DATA} if no keys are considered for export.
 @end deftypefun
 
 @deftp {Data type} {gpgme_import_status_t}
@@ -2720,7 +3567,8 @@ This is the fingerprint of the key that was considered.
 
 @item gpgme_error_t result
 If the import was not successful, this is the error value that caused
-the import to fail.  Otherwise it is @code{GPGME_No_Error}.
+the import to fail.  Otherwise the error code is
+@code{GPG_ERR_NO_ERROR}.
 
 @item unsigned int status
 This is a bit-wise OR of the following flags that give more
@@ -2801,9 +3649,9 @@ about the keys for which an import was attempted.
 
 @deftypefun gpgme_import_result_t gpgme_op_import_result (@w{gpgme_ctx_t @var{ctx}})
 The function @code{gpgme_op_import_result} returns a
-@code{gpgme_import_result_t} pointer to a structure holding the result of
-a @code{gpgme_op_import} operation.  The pointer is only valid if the
-last operation on the context was a @code{gpgme_op_import} or
+@code{gpgme_import_result_t} pointer to a structure holding the result
+of a @code{gpgme_op_import} operation.  The pointer is only valid if
+the last operation on the context was a @code{gpgme_op_import} or
 @code{gpgme_op_import_start} operation, and if this operation finished
 successfully.  The returned pointer is only valid until the next
 operation is started on the context.
@@ -2838,12 +3686,13 @@ key ring of the crypto engine used by @var{ctx}.  If
 @var{allow_secret} is @code{0}, only public keys are deleted,
 otherwise secret keys are deleted as well, if that is supported.
 
-The function returns @code{GPGME_No_Error} if the key was deleted
-successfully, @code{GPGME_Invalid_Value} if @var{ctx} or @var{key} is
-not a valid pointer, @code{GPGME_Invalid_Key} if @var{key} could not
-be found in the keyring, @code{GPGME_Ambiguous_Specification} if the
-key was not specified unambiguously, and @code{GPGME_Conflict} if the
-secret key for @var{key} is available, but @var{allow_secret} is zero.
+The function returns the error code @code{GPG_ERR_NO_ERROR} if the key
+was deleted successfully, @code{GPG_ERR_INV_VALUE} if @var{ctx} or
+@var{key} is not a valid pointer, @code{GPG_ERR_NO_PUBKEY} if
+@var{key} could not be found in the keyring,
+@code{GPG_ERR_AMBIGUOUS_NAME} if the key was not specified
+unambiguously, and @code{GPG_ERR_CONFLICT} if the secret key for
+@var{key} is available, but @var{allow_secret} is zero.
 @end deftypefun
 
 @deftypefun gpgme_error_t gpgme_op_delete_start (@w{gpgme_ctx_t @var{ctx}}, @w{const gpgme_key_t @var{key}}, @w{int @var{allow_secret}})
@@ -2851,9 +3700,71 @@ The function @code{gpgme_op_delete_start} initiates a
 @code{gpgme_op_delete} operation.  It can be completed by calling
 @code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
 
-The function returns @code{GPGME_No_Error} if the operation was
-started successfully, and @code{GPGME_Invalid_Value} if @var{ctx} or
-@var{key} is not a valid pointer.
+The function returns the error code @code{GPG_ERR_NO_ERROR} if the
+operation was started successfully, and @code{GPG_ERR_INV_VALUE} if
+@var{ctx} or @var{key} is not a valid pointer.
+@end deftypefun
+
+
+@node Advanced Key Editing
+@subsection Advanced Key Editing
+@cindex key, edit
+
+@deftp {Data type} {gpgme_error_t (*gpgme_edit_cb_t) (@w{void *@var{handle}}, @w{gpgme_status_code_t @var{status}}, @w{const char *@var{args}}, @w{int @var{fd}})}
+@tindex gpgme_edit_cb_t
+The @code{gpgme_edit_cb_t} type is the type of functions which
+@acronym{GPGME} calls if it a key edit operation is on-going.  The
+status code @var{status} and the argument line @var{args} are passed
+through by @acronym{GPGME} from the crypto engine.  The file
+descriptor @var{fd} is -1 for normal status messages.  If @var{status}
+indicates a command rather than a status message, the response to the
+command should be written to @var{fd}.  The @var{handle} is provided
+by the user at start of operation.
+
+The function should return @code{GPG_ERR_NO_ERROR} or an error value.
+@end deftp
+
+@deftypefun gpgme_error_t gpgme_op_edit (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t @var{key}}, @w{gpgme_edit_cb_t @var{fnc}}, @w{void *@var{handle}}, @w{gpgme_data_t @var{out}})
+The function @code{gpgme_op_edit} processes the key @var{KEY}
+interactively, using the edit callback function @var{FNC} with the
+handle @var{HANDLE}.  The callback is invoked for every status and
+command request from the crypto engine.  The output of the crypto
+engine is written to the data object @var{out}.
+
+Note that the protocol between the callback function and the crypto
+engine is specific to the crypto engine and no further support in
+implementing this protocol correctly is provided by @acronym{GPGME}.
+
+The function returns the error code @code{GPG_ERR_NO_ERROR} if the
+edit operation completes successfully, @code{GPG_ERR_INV_VALUE} if
+@var{ctx} or @var{key} is not a valid pointer, and any error returned
+by the crypto engine or the edit callback handler.
+@end deftypefun
+
+@deftypefun gpgme_error_t gpgme_op_edit_start (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t @var{key}}, @w{gpgme_edit_cb_t @var{fnc}}, @w{void *@var{handle}}, @w{gpgme_data_t @var{out}})
+The function @code{gpgme_op_edit_start} initiates a
+@code{gpgme_op_edit} operation.  It can be completed by calling
+@code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
+
+The function returns the error code @code{GPG_ERR_NO_ERROR} if the
+operation was started successfully, and @code{GPG_ERR_INV_VALUE} if
+@var{ctx} or @var{key} is not a valid pointer.
+@end deftypefun
+
+
+@deftypefun gpgme_error_t gpgme_op_card_edit (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t @var{key}}, @w{gpgme_edit_cb_t @var{fnc}}, @w{void *@var{handle}}, @w{gpgme_data_t @var{out}})
+The function @code{gpgme_op_card_edit} is analogous to
+@code{gpgme_op_edit}, but should be used to process the smart card corresponding to the key @var{key}.
+@end deftypefun
+
+@deftypefun gpgme_error_t gpgme_op_card_edit_start (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t @var{key}}, @w{gpgme_edit_cb_t @var{fnc}}, @w{void *@var{handle}}, @w{gpgme_data_t @var{out}})
+The function @code{gpgme_op_card_edit_start} initiates a
+@code{gpgme_op_card_edit} operation.  It can be completed by calling
+@code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
+
+The function returns the error code @code{GPG_ERR_NO_ERROR} if the
+operation was started successfully, and @code{GPG_ERR_INV_VALUE} if
+@var{ctx} or @var{key} is not a valid pointer.
 @end deftypefun
 
 
@@ -2913,12 +3824,12 @@ can not be the empty string.
 The argument @var{max_level} is currently ignored.
 
 The context will be busy until either all trust items are received
-(and @code{gpgme_op_trustlist_next} returns @code{GPGME_EOF}), or
+(and @code{gpgme_op_trustlist_next} returns @code{GPG_ERR_EOF}), or
 @code{gpgme_op_trustlist_end} is called to finish the operation.
 
-The function returns @code{GPGME_Invalid_Value} if @var{ctx} is not a
-valid pointer, and passes through any errors that are reported by the
-crypto engine support routines.
+The function returns the error code @code{GPG_ERR_INV_VALUE} if
+@var{ctx} is not a valid pointer, and passes through any errors that
+are reported by the crypto engine support routines.
 @end deftypefun
 
 @deftypefun gpgme_error_t gpgme_op_trustlist_next (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_trust_item_t *@var{r_item}})
@@ -2931,10 +3842,10 @@ This is the only way to get at @code{gpgme_trust_item_t} objects in
 @acronym{GPGME}.
 
 If the last trust item in the list has already been returned,
-@code{gpgme_op_trustlist_next} returns @code{GPGME_EOF}.
+@code{gpgme_op_trustlist_next} returns @code{GPG_ERR_EOF}.
 
-The function returns @code{GPGME_Invalid_Value} if @var{ctx} or
-@var{r_item} is not a valid pointer, and @code{GPGME_Out_Of_Core} if
+The function returns the error code @code{GPG_ERR_INV_VALUE} if @var{ctx} or
+@var{r_item} is not a valid pointer, and @code{GPG_ERR_ENOMEM} if
 there is not enough memory for the operation.
 @end deftypefun
 
@@ -2942,9 +3853,9 @@ there is not enough memory for the operation.
 The function @code{gpgme_op_trustlist_next} ends a pending key list
 operation in the context @var{ctx}.
 
-The function returns @code{GPGME_Invalid_Value} if @var{ctx} is not a
-valid pointer, and @code{GPGME_Out_Of_Core} if at some time during the
-operation there was not enough memory available.
+The function returns the error code @code{GPG_ERR_INV_VALUE} if
+@var{ctx} is not a valid pointer, and @code{GPG_ERR_ENOMEM} if at some
+time during the operation there was not enough memory available.
 @end deftypefun
 
 
@@ -3021,24 +3932,24 @@ The function @code{gpgme_trust_item_release} is an alias for
 @cindex cryptographic operation
 
 Sometimes, the result of a crypto operation returns a list of invalid
-user IDs encountered in processing the request.  The following
-structure is used to hold information about such an user ID.
+keys encountered in processing the request.  The following structure
+is used to hold information about such a key.
 
-@deftp {Data type} {gpgme_invalid_user_id_t}
+@deftp {Data type} {gpgme_invalid_key_t}
 This is a pointer to a structure used to store a part of the result of
 a crypto operation which takes user IDs as one input parameter.  The
 structure contains the following members:
 
 @table @code
-@item gpgme_invalid_user_id_t next
-This is a pointer to the next invalid user ID structure in the linked
+@item gpgme_invalid_key_t next
+This is a pointer to the next invalid key structure in the linked
 list, or @code{NULL} if this is the last element.
 
-@item char *id
-The invalid user ID encountered.
+@item char *fpr
+The fingerprint or key ID of the invalid key encountered.
 
 @item gpgme_error_t reason
-An error code describing the reason why the user ID was found invalid.
+An error code describing the reason why the key was found invalid.
 @end table
 @end deftp
 
@@ -3062,12 +3973,12 @@ The function @code{gpgme_op_decrypt} decrypts the ciphertext in the
 data object @var{cipher} and stores it into the data object
 @var{plain}.
 
-The function returns @code{GPGME_No_Error} if the ciphertext could be
-decrypted successfully, @code{GPGME_Invalid_Value} if @var{ctx},
-@var{cipher} or @var{plain} is not a valid pointer,
-@code{GPGME_No_Data} if @var{cipher} does not contain any data to
-decrypt, @code{GPGME_Decryption_Failed} if @var{cipher} is not a valid
-cipher text, @code{GPGME_Bad_Passphrase} if the passphrase for the
+The function returns the error code @code{GPG_ERR_NO_ERROR} if the
+ciphertext could be decrypted successfully, @code{GPG_ERR_INV_VALUE}
+if @var{ctx}, @var{cipher} or @var{plain} is not a valid pointer,
+@code{GPG_ERR_NO_DATA} if @var{cipher} does not contain any data to
+decrypt, @code{GPG_ERR_DECRYPT_FAILED} if @var{cipher} is not a valid
+cipher text, @code{GPG_ERR_BAD_PASSPHRASE} if the passphrase for the
 secret key could not be retrieved, and passes through any errors that
 are reported by the crypto engine support routines.
 @end deftypefun
@@ -3077,14 +3988,43 @@ The function @code{gpgme_op_decrypt_start} initiates a
 @code{gpgme_op_decrypt} operation.  It can be completed by calling
 @code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
 
-The function returns @code{GPGME_No_Error} if the operation could be
-started successfully, and @code{GPGME_Invalid_Value} if @var{cipher}
-or @var{plain} is not a valid pointer.
+The function returns the error code @code{GPG_ERR_NO_ERROR} if the
+operation could be started successfully, and @code{GPG_ERR_INV_VALUE}
+if @var{cipher} or @var{plain} is not a valid pointer.
 @end deftypefun
 
+@deftp {Data type} {gpgme_recipient_t}
+This is a pointer to a structure used to store information about the
+recipient of an encrypted text which is decrypted in a
+@code{gpgme_op_decrypt} operation.  This information (except for the
+status field) is even available before the operation finished
+successfully, for example in a passphrase callback.  The structure
+contains the following members:
+
+@table @code
+@item gpgme_recipient_t next
+This is a pointer to the next recipient structure in the linked list,
+or @code{NULL} if this is the last element.
+
+@item gpgme_pubkey_algo_t
+The public key algorithm used in the encryption.
+
+@item unsigned int wrong_key_usage : 1
+This is true if the key was not used according to its policy.
+
+@item char *keyid
+This is the key ID of the key (in hexadecimal digits) used as
+recipient.
+
+@item gpgme_error_t status
+This is an error number with the error code GPG_ERR_NO_SECKEY if the
+secret key for this recipient is not available, and 0 otherwise.
+@end table
+@end deftp
+
 @deftp {Data type} {gpgme_decrypt_result_t}
 This is a pointer to a structure used to store the result of a
-@code{gpgme_op_decrypt} operation.  After successfully encrypting
+@code{gpgme_op_decrypt} operation.  After successfully decrypting
 data, you can retrieve the pointer to the result with
 @code{gpgme_op_decrypt_result}.  The structure contains the following
 members:
@@ -3093,17 +4033,28 @@ members:
 @item char *unsupported_algorithm
 If an unsupported algorithm was encountered, this string describes the
 algorithm that is not supported.
+
+@item unsigned int wrong_key_usage : 1
+This is true if the key was not used according to its policy.
+
+@item gpgme_recipient_t recipient
+This is a linked list of recipients to which this message was encrypted.
+
+@item char *file_name
+This is the filename of the original plaintext message file if it is
+known, otherwise this is a null pointer.
 @end table
 @end deftp
 
 @deftypefun gpgme_decrypt_result_t gpgme_op_decrypt_result (@w{gpgme_ctx_t @var{ctx}})
 The function @code{gpgme_op_decrypt_result} returns a
-@code{gpgme_decrypt_result_t} pointer to a structure holding the result of
-a @code{gpgme_op_decrypt} operation.  The pointer is only valid if the
-last operation on the context was a @code{gpgme_op_decrypt} or
-@code{gpgme_op_decrypt_start} operation, and if this operation
-finished successfully.  The returned pointer is only valid until the
-next operation is started on the context.
+@code{gpgme_decrypt_result_t} pointer to a structure holding the
+result of a @code{gpgme_op_decrypt} operation.  The pointer is only
+valid if the last operation on the context was a
+@code{gpgme_op_decrypt} or @code{gpgme_op_decrypt_start} operation.
+If the operation failed this might be a @code{NULL} pointer.  The
+returned pointer is only valid until the next operation is started on
+the context.
 @end deftypefun
 
 
@@ -3113,6 +4064,8 @@ next operation is started on the context.
 @cindex signature, verification
 @cindex cryptographic operation, verification
 @cindex cryptographic operation, signature check
+@cindex signature notation data
+@cindex notation data
 
 @deftypefun gpgme_error_t gpgme_op_verify (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{sig}}, @w{gpgme_data_t @var{signed_text}}, @w{gpgme_data_t @var{plain}})
 The function @code{gpgme_op_verify} verifies that the signature in the
@@ -3127,12 +4080,12 @@ verification.
 The results of the individual signature verifications can be retrieved
 with @code{gpgme_op_verify_result}.
 
-The function returns @code{GPGME_No_Error} if the operation could be
-completed successfully, @code{GPGME_Invalid_Value} if @var{ctx},
-@var{sig}, @var{plain} or @var{r_stat} is not a valid pointer,
-@code{GPGME_No_Data} if @var{sig} does not contain any data to verify,
-and passes through any errors that are reported by the crypto engine
-support routines.
+The function returns the error code @code{GPG_ERR_NO_ERROR} if the
+operation could be completed successfully, @code{GPG_ERR_INV_VALUE} if
+@var{ctx}, @var{sig} or @var{plain} is not a valid pointer,
+@code{GPG_ERR_NO_DATA} if @var{sig} does not contain any data to
+verify, and passes through any errors that are reported by the crypto
+engine support routines.
 @end deftypefun
 
 @deftypefun gpgme_error_t gpgme_op_verify_start (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{sig}}, @w{gpgme_data_t @var{signed_text}}, @w{gpgme_data_t @var{plain}})
@@ -3140,11 +4093,11 @@ The function @code{gpgme_op_verify_start} initiates a
 @code{gpgme_op_verify} operation.  It can be completed by calling
 @code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
 
-The function returns @code{GPGME_No_Error} if the operation could be
-started successfully, @code{GPGME_Invalid_Value} if @var{ctx},
-@var{sig}, @var{plain} or @var{r_stat} is not a valid pointer, and
-@code{GPGME_No_Data} if @var{sig} or @var{plain} does not contain any
-data to verify.
+The function returns the error code @code{GPG_ERR_NO_ERROR} if the
+operation could be started successfully, @code{GPG_ERR_INV_VALUE} if
+@var{ctx}, @var{sig} or @var{plain} is not a valid pointer, and
+@code{GPG_ERR_NO_DATA} if @var{sig} or @var{plain} does not contain
+any data to verify.
 @end deftypefun
 
 @deftp {Data type} {gpgme_sig_notation_t}
@@ -3161,9 +4114,45 @@ linked list, or @code{NULL} if this is the last element.
 The name of the notation field.  If this is @code{NULL}, then the
 member @code{value} will contain a policy URL.
 
+@item int name_len
+The length of the @code{name} field.  For strings the length is
+counted without the trailing binary zero.
+
 @item char *value
 The value of the notation field.  If @code{name} is @code{NULL}, then
 this is a policy URL.
+
+@item int value_len
+The length of the @code{value} field.  For strings the length is
+counted without the trailing binary zero.
+
+@item gpgme_sig_notation_flags_t flags
+The accumulated flags field.  This field contains the flags associated
+with the notation data in an accumulated form which can be used as an
+argument to the function @code{gpgme_sig_notation_add}.  The value
+@code{flags} is a bitwise-or combination of one or multiple of the
+following bit values:
+
+@table @code
+@item GPGME_SIG_NOTATION_HUMAN_READABLE
+The @code{GPGME_SIG_NOTATION_HUMAN_READABLE} symbol specifies that the
+notation data is in human readable form
+
+@item GPGME_SIG_NOTATION_CRITICAL
+The @code{GPGME_SIG_NOTATION_CRITICAL} symbol specifies that the
+notation data is critical.
+
+@end table
+
+@item unsigned int human_readable : 1
+This is true if the @code{GPGME_SIG_NOTATION_HUMAN_READABLE} flag is
+set and false otherwise.  This flag is only valid for notation data,
+not for policy URLs.
+
+@item unsigned int critical : 1
+This is true if the @code{GPGME_SIG_NOTATION_CRITICAL} flag is set and
+false otherwise.  This flag is valid for notation data and policy URLs.
+
 @end table
 @end deftp
 
@@ -3177,7 +4166,7 @@ following members:
 This is a pointer to the next new signature structure in the linked
 list, or @code{NULL} if this is the last element.
 
-@item unsigned int summary;
+@item gpgme_sigsum_t summary
 This is a bit vector giving a summary of the signature status.  It
 provides an easy interface to a defined semantic of the signature
 status.  Checking just one bit is sufficient to see whether a
@@ -3193,8 +4182,8 @@ The defined bits are:
   information.  Check the other bits.
 
   @item GPGME_SIGSUM_RED
-  The signature is bad. It might be useful to checkother bits and
-  display moe information, i.e. a revoked certificate might not render a
+  The signature is bad. It might be useful to check other bits and
+  display more information, i.e. a revoked certificate might not render a
   signature invalid when the message was received prior to the cause for
   the revocation.
 
@@ -3209,7 +4198,7 @@ The defined bits are:
   The signature has expired.
 
   @item GPGME_SIGSUM_KEY_MISSING
-  Can't verifydue to a missing key o certificate.
+  Can't verify due to a missing key or certificate.
 
   @item GPGME_SIGSUM_CRL_MISSING
   The CRL (or an equivalent mechanism) is not available. 
@@ -3232,30 +4221,36 @@ This is the status of the signature.  In particular, the following
 status codes are of interest:
 
   @table @code
-  @item GPGME_No_Error
+  @item GPG_ERR_NO_ERROR
   This status indicates that the signature is valid.  For the combined
   result this status means that all signatures are valid.
 
-  @item GPGME_Sig_Expired
+  @item GPG_ERR_SIG_EXPIRED
   This status indicates that the signature is valid but expired.  For
   the combined result this status means that all signatures are valid
   and expired.
 
-  @item GPGME_Key_Expired
+  @item GPG_ERR_KEY_EXPIRED
   This status indicates that the signature is valid but the key used to
   verify the signature has expired.  For the combined result this status
   means that all signatures are valid and all keys are expired.
 
-  @item GPGME_Bad_Signature
+  @item GPG_ERR_CERT_REVOKED
+  This status indicates that the signature is valid but the key used
+  to verify the signature has been revoked.  For the combined result
+  this status means that all signatures are valid and all keys are
+  revoked.
+
+  @item GPG_ERR_BAD_SIGNATURE
   This status indicates that the signature is invalid.  For the combined
   result this status means that all signatures are invalid.
 
-  @item GPGME_No_Public_Key
+  @item GPG_ERR_NO_PUBKEY
   This status indicates that the signature could not be verified due to
   a missing key.  For the combined result this status means that all
   signatures could not be checked due to missing keys.
 
-  @item GPGME_General_Error
+  @item GPG_ERR_GENERAL
   This status indicates that there was some other error which prevented
   the signature verification.
   @end table
@@ -3270,36 +4265,79 @@ The creation timestamp of this signature.
 The expiration timestamp of this signature, or 0 if the signature does
 not expire.
 
-@item int wrong_key_usage : 1;
+@item unsigned int wrong_key_usage : 1
+This is true if the key was not used according to its policy.
+
+@item unsigned int pka_trust : 2
+This is set to the trust information gained by means of the PKA system.
+Values are:
+  @table @code
+  @item 0
+        No PKA information available or verification not possible.
+  @item 1
+        PKA verification failed. 
+  @item 2
+        PKA verification succeeded.
+  @item 3
+        Reserved for future use.
+  @end table
+Depending on the configuration of the engine, this metric may also be
+reflected by the validity of the signature.
+
+@item unsigned int chain_model : 1
+This is true if the validity of the signature has been checked using the
+chain model.  In the chain model the time the signature has been created
+must be within the validity period of the certificate and the time the
+certificate itself has been created must be within the validity period
+of the issuing certificate.  In contrast the default validation model
+checks the validity of signature as well at the entire certificate chain
+at the current time.
+
 
 @item gpgme_validity_t validity
+The validity of the signature.
 
 @item gpgme_error_t validity_reason
+If a signature is not valid, this provides a reason why.
+
+@item gpgme_pubkey_algo_t
+The public key algorithm used to create this signature.
+
+@item gpgme_hash_algo_t
+The hash algorithm used to create this signature.
 @end table
 @end deftp
 
 @deftp {Data type} {gpgme_verify_result_t}
 This is a pointer to a structure used to store the result of a
-@code{gpgme_op_verify} operation.  After successfully verifying a
-signature, you can retrieve the pointer to the result with
-@code{gpgme_op_verify_result}.  The structure contains the following
-member:
+@code{gpgme_op_verify} operation.  After verifying a signature, you
+can retrieve the pointer to the result with
+@code{gpgme_op_verify_result}.  If the operation failed this might be
+a @code{NULL} pointer.  The structure contains the following member:
 
 @table @code
 @item gpgme_signature_t signatures
 A linked list with information about all signatures for which a
 verification was attempted.
+
+@item char *file_name
+This is the filename of the original plaintext message file if it is
+known, otherwise this is a null pointer.
 @end table
 @end deftp
 
-@deftypefun gpgme_sign_result_t gpgme_op_verify_result (@w{gpgme_ctx_t @var{ctx}})
+@deftypefun gpgme_verify_result_t gpgme_op_verify_result (@w{gpgme_ctx_t @var{ctx}})
 The function @code{gpgme_op_verify_result} returns a
-@code{gpgme_verify_result_t} pointer to a structure holding the result of
-a @code{gpgme_op_verify} operation.  The pointer is only valid if the
-last operation on the context was a @code{gpgme_op_verify} or
-@code{gpgme_op_verify_start} operation, and if this operation finished
-successfully.  The returned pointer is only valid until the next
-operation is started on the context.
+@code{gpgme_verify_result_t} pointer to a structure holding the result
+of a @code{gpgme_op_verify} operation.  The pointer is only valid if
+the last operation on the context was a @code{gpgme_op_verify},
+@code{gpgme_op_verify_start}, @code{gpgme_op_decrypt_verify} or
+@code{gpgme_op_decrypt_verify_start} operation, and if this operation
+finished successfully (for @code{gpgme_op_decrypt_verify} and
+@code{gpgme_op_decrypt_verify_start}, the error code
+@code{GPG_ERR_NO_DATA} counts as successful in this context).  The
+returned pointer is only valid until the next operation is started on
+the context.
 @end deftypefun
 
 
@@ -3375,29 +4413,29 @@ The function @code{gpgme_get_sig_status} is equivalent to:
 
   if (r_stat)
     @{
-      switch (sig->status)
+      switch (gpg_err_code (sig->status))
        @{
-       case GPGME_No_Error:
+       case GPG_ERR_NO_ERROR:
          *r_stat = GPGME_SIG_STAT_GOOD;
          break;
          
-       case GPGME_Bad_Signature:
+       case GPG_ERR_BAD_SIGNATURE:
          *r_stat = GPGME_SIG_STAT_BAD;
          break;
          
-       case GPGME_No_Public_Key:
+       case GPG_ERR_NO_PUBKEY:
          *r_stat = GPGME_SIG_STAT_NOKEY;
          break;
          
-       case GPGME_No_Data:
+       case GPG_ERR_NO_DATA:
          *r_stat = GPGME_SIG_STAT_NOSIG;
          break;
          
-       case GPGME_Sig_Expired:
+       case GPG_ERR_SIG_EXPIRED:
          *r_stat = GPGME_SIG_STAT_GOOD_EXP;
          break;
          
-       case GPGME_Key_Expired:
+       case GPG_ERR_KEY_EXPIRED:
          *r_stat = GPGME_SIG_STAT_GOOD_EXPKEY;
          break;
          
@@ -3480,22 +4518,22 @@ The function @code{gpgme_get_sig_ulong_attr} is equivalent to:
     case GPGME_ATTR_SIG_STATUS:
       switch (sig->status)
        @{
-       case GPGME_No_Error:
+       case GPG_ERR_NO_ERROR:
          return GPGME_SIG_STAT_GOOD;
          
-       case GPGME_Bad_Signature:
+       case GPG_ERR_BAD_SIGNATURE:
          return GPGME_SIG_STAT_BAD;
          
-       case GPGME_No_Public_Key:
+       case GPG_ERR_NO_PUBKEY:
          return GPGME_SIG_STAT_NOKEY;
          
-       case GPGME_No_Data:
+       case GPG_ERR_NO_DATA:
          return GPGME_SIG_STAT_NOSIG;
          
-       case GPGME_Sig_Expired:
+       case GPG_ERR_SIG_EXPIRED:
          return GPGME_SIG_STAT_GOOD_EXP;
          
-       case GPGME_Key_Expired:
+       case GPG_ERR_KEY_EXPIRED:
          return GPGME_SIG_STAT_GOOD_EXPKEY;
          
        default:
@@ -3528,9 +4566,9 @@ The function @code{gpgme_get_sig_key} is equivalent to:
       idx--;
     @}
   if (!sig || idx)
-    return GPGME_EOF;
+    return gpg_error (GPG_ERR_EOF);
 
-  return gpgme_get_key (ctx, sig->fpr, r_key, 0, 0);
+  return gpgme_get_key (ctx, sig->fpr, r_key, 0);
 @end example
 @end deftypefun
 
@@ -3548,16 +4586,21 @@ the data object @var{cipher} and stores it into the data object
 @var{plain}.  If @var{cipher} contains signatures, they will be
 verified.
 
-After the operation completed, @code{gpgme_op_get_sig_status} and
-@code{gpgme_op_get_sig_key} can be used to retrieve more information
+After the operation completed, @code{gpgme_op_decrypt_result} and
+@code{gpgme_op_verify_result} can be used to retrieve more information
 about the signatures.
 
-The function returns @code{GPGME_No_Error} if the ciphertext could be
-decrypted successfully, @code{GPGME_Invalid_Value} if @var{ctx},
-@var{cipher}, @var{plain} or @var{r_stat} is not a valid pointer,
-@code{GPGME_No_Data} if @var{cipher} does not contain any data to
-decrypt, @code{GPGME_Decryption_Failed} if @var{cipher} is not a valid
-cipher text, @code{GPGME_Bad_Passphrase} if the passphrase for the
+If the error code @code{GPG_ERR_NO_DATA} is returned, @var{cipher}
+does not contain any data to decrypt.  However, it might still be
+signed.  The information about detected signatures is available with
+@code{gpgme_op_verify_result} in this case.
+
+The function returns the error code @code{GPG_ERR_NO_ERROR} if the
+ciphertext could be decrypted successfully, @code{GPG_ERR_INV_VALUE}
+if @var{ctx}, @var{cipher} or @var{plain} is not a valid pointer,
+@code{GPG_ERR_NO_DATA} if @var{cipher} does not contain any data to
+decrypt, @code{GPG_ERR_DECRYPT_FAILED} if @var{cipher} is not a valid
+cipher text, @code{GPG_ERR_BAD_PASSPHRASE} if the passphrase for the
 secret key could not be retrieved, and passes through any errors that
 are reported by the crypto engine support routines.
 @end deftypefun
@@ -3568,11 +4611,11 @@ The function @code{gpgme_op_decrypt_verify_start} initiates a
 calling @code{gpgme_wait} on the context.  @xref{Waiting For
 Completion}.
 
-The function returns @code{GPGME_No_Error} if the operation could be
-started successfully, @code{GPGME_Invalid_Value} if @var{ctx},
-@var{cipher}, @var{plain} or @var{r_stat} is not a valid pointer, and
-@code{GPGME_No_Data} if @var{cipher} does not contain any data to
-decrypt.
+The function returns the error code @code{GPG_ERR_NO_ERROR} if the
+operation could be started successfully, @code{GPG_ERR_INV_VALUE} if
+@var{ctx}, @var{cipher}, @var{plain} or @var{r_stat} is not a valid
+pointer, and @code{GPG_ERR_NO_DATA} if @var{cipher} does not contain
+any data to decrypt.
 @end deftypefun
 
 
@@ -3590,6 +4633,7 @@ set is changed).
 @menu
 * Selecting Signers::             How to choose the keys to sign with.
 * Creating a Signature::          How to create a signature.
+* Signature Notation Data::       How to add notation data to a signature.
 @end menu
 
 
@@ -3648,7 +4692,8 @@ mode settings of the context are ignored.
 The function @code{gpgme_op_sign} creates a signature for the text in
 the data object @var{plain} and returns it in the data object
 @var{sig}.  The type of the signature created is determined by the
-@acronym{ASCII} armor and text mode attributes set for the context
+@acronym{ASCII} armor (or, if that is not set, by the encoding
+specified for @var{sig}), the text mode attributes set for the context
 @var{ctx} and the requested signature mode @var{mode}.
 
 After the operation completed successfully, the result can be
@@ -3658,13 +4703,14 @@ If an S/MIME signed message is created using the CMS crypto engine,
 the number of certificates to include in the message can be specified
 with @code{gpgme_set_include_certs}.  @xref{Included Certificates}.
 
-The function returns @code{GPGME_No_Error} if the signature could be
-created successfully, @code{GPGME_Invalid_Value} if @var{ctx},
-@var{plain} or @var{sig} is not a valid pointer, @code{GPGME_No_Data}
-if the signature could not be created, @code{GPGME_Bad_Passphrase} if
-the passphrase for the secret key could not be retrieved, and passes
-through any errors that are reported by the crypto engine support
-routines.
+The function returns the error code @code{GPG_ERR_NO_ERROR} if the
+signature could be created successfully, @code{GPG_ERR_INV_VALUE} if
+@var{ctx}, @var{plain} or @var{sig} is not a valid pointer,
+@code{GPG_ERR_NO_DATA} if the signature could not be created,
+@code{GPG_ERR_BAD_PASSPHRASE} if the passphrase for the secret key
+could not be retrieved, @code{GPG_ERR_UNUSABLE_SECKEY} if there are
+invalid signers, and passes through any errors that are reported by the
+crypto engine support routines.
 @end deftypefun
 
 @deftypefun gpgme_error_t gpgme_op_sign_start (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{plain}}, @w{gpgme_data_t @var{sig}}, @w{gpgme_sig_mode_t @var{mode}})
@@ -3672,8 +4718,8 @@ The function @code{gpgme_op_sign_start} initiates a
 @code{gpgme_op_sign} operation.  It can be completed by calling
 @code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
 
-The function returns @code{GPGME_No_Error} if the operation could be
-started successfully, and @code{GPGME_Invalid_Value} if @var{ctx},
+The function returns the error code @code{GPG_ERR_NO_ERROR} if the operation could be
+started successfully, and @code{GPG_ERR_INV_VALUE} if @var{ctx},
 @var{plain} or @var{sig} is not a valid pointer.
 @end deftypefun
 
@@ -3696,7 +4742,7 @@ The public key algorithm used to create this signature.
 @item gpgme_hash_algo_t
 The hash algorithm used to create this signature.
 
-@item unsigned long class
+@item unsigned int sig_class
 The signature class of this signature.
 
 @item long int timestamp
@@ -3715,8 +4761,8 @@ signature, you can retrieve the pointer to the result with
 members:
 
 @table @code
-@item gpgme_invalid_user_id_t invalid_signers
-A linked list with information about all invalid user IDs for which a
+@item gpgme_invalid_key_t invalid_signers
+A linked list with information about all invalid keys for which a
 signature could not be created.
 
 @item gpgme_new_signature_t signatures
@@ -3726,125 +4772,121 @@ A linked list with information about all signatures created.
 
 @deftypefun gpgme_sign_result_t gpgme_op_sign_result (@w{gpgme_ctx_t @var{ctx}})
 The function @code{gpgme_op_sign_result} returns a
-@code{gpgme_sign_result_t} pointer to a structure holding the result of a
-@code{gpgme_op_sign} operation.  The pointer is only valid if the last
-operation on the context was a @code{gpgme_op_sign} or
-@code{gpgme_op_sign_start} operation, and if this operation finished
-successfully.  The returned pointer is only valid until the next
-operation is started on the context.
+@code{gpgme_sign_result_t} pointer to a structure holding the result
+of a @code{gpgme_op_sign} operation.  The pointer is only valid if the
+last operation on the context was a @code{gpgme_op_sign},
+@code{gpgme_op_sign_start}, @code{gpgme_op_encrypt_sign} or
+@code{gpgme_op_encrypt_sign_start} operation.  If that operation
+failed, the function might return a @code{NULL} pointer, The returned
+pointer is only valid until the next operation is started on the
+context.
 @end deftypefun
 
 
-@node Encrypt
-@subsection Encrypt
-@cindex encryption
-@cindex cryptographic operation, encryption
+@node Signature Notation Data
+@subsubsection Signature Notation Data
+@cindex notation data
+@cindex signature notation data
+@cindex policy URL
 
-One plaintext can be encrypted for several recipients at the same
-time.  The list of recipients is created independently of any context,
-and then passed to the encryption operation.
+Using the following functions, you can attach arbitrary notation data
+to a signature.  This information is then available to the user when
+the signature is verified.
 
-@menu
-* Selecting Recipients::          How to choose the recipients.
-* Encrypting a Plaintext::        How to encrypt a plaintext.
-@end menu
-
-
-@node Selecting Recipients
-@subsubsection Selecting Recipients
-@cindex encryption, selecting recipients
-@cindex recipients
-
-@deftp {Data type} gpgme_recipients_t
-The @code{gpgme_recipients_t} type is a handle for a set of recipients
-that can be used in an encryption process.
-@end deftp
-
-@deftypefun gpgme_error_t gpgme_recipients_new (@w{gpgme_recipients_t *@var{r_rset}})
-The function @code{gpgme_recipients_new} creates a new, empty set of
-recipients and returns a handle for it in @var{r_rset}.
+@deftypefun void gpgme_sig_notation_clear (@w{gpgme_ctx_t @var{ctx}})
+The function @code{gpgme_sig_notation_clear} removes the notation data
+from the context @var{ctx}.  Subsequent signing operations from this
+context will not include any notation data.
 
-The function returns @code{GPGME_No_Error} if the recipient set could
-be created successfully, and @code{GPGME_Out_Of_Core} if not enough
-memory was available.
+Every context starts with an empty notation data list.
 @end deftypefun
 
-@deftypefun void gpgme_recipients_release (@w{gpgme_recipients_t @var{rset}})
-The function @code{gpgme_recipients_release} destroys the set of
-recipients @var{rset} and releases all associated resources.
-@end deftypefun
+@deftypefun gpgme_error_t gpgme_sig_notation_add (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{name}}, @w{const char *@var{value}}, @w{gpgme_sig_notation_flags_t @var{flags}})
+The function @code{gpgme_sig_notation_add} adds the notation data with
+the name @var{name} and the value @var{value} to the context
+@var{ctx}.
 
-@deftypefun gpgme_error_t gpgme_recipients_add_name (@w{gpgme_recipients_t @var{rset}}, @w{const char *@var{name}})
-The function @code{gpgme_recipients_add_name} adds the recipient
-@var{name} to the set of recipients @var{rset}.  This is equivalent to
-@code{gpgme_recipients_add_name_with_validity} with a validity of
-@code{GPGME_VALIDITY_UNKNOWN}.
+Subsequent signing operations will include this notation data, as well
+as any other notation data that was added since the creation of the
+context or the last @code{gpgme_sig_notation_clear} operation.
 
-The function returns @code{GPGME_No_Error} if the recipient was added
-successfully, @code{GPGME_Invalid_Value} if @var{rset} or @var{name}
-is not a valid pointer, and @code{GPGME_Out_Of_Core} if not enough
-memory is available.
-@end deftypefun
+The arguments @var{name} and @var{value} must be @code{NUL}-terminated
+strings in human-readable form.  The flag
+@code{GPGME_SIG_NOTATION_HUMAN_READABLE} is implied
+(non-human-readable notation data is currently not supported).  The
+strings must be in UTF-8 encoding.
 
-@deftypefun gpgme_error_t gpgme_recipients_add_name_with_validity (@w{gpgme_recipients_t @var{rset}}, @w{const char *@var{name}}, @w{gpgme_validity_t @var{val}})
-The function @code{gpgme_recipients_add_name_with_validity} adds the
-recipient @var{name} with the validity @var{val} to the set of
-recipients @var{rset}.  If the validity is not known, the function
-@code{gpgme_recipients_add_name} can be used.
-@xref{Information About Keys}, for the possible values for @var{val}.
+If @var{name} is @code{NULL}, then @var{value} should be a policy URL.
 
-The function returns @code{GPGME_No_Error} if the recipient was added
-successfully, @code{GPGME_Invalid_Value} if @var{rset} or @var{name}
-is not a valid pointer, and @code{GPGME_Out_Of_Core} if not enough
-memory is available.
+The function @code{gpgme_sig_notation_add} returns the error code
+@code{GPG_ERR_NO_ERROR} if the notation data could be added
+successfully, @code{GPG_ERR_INV_VALUE} if @var{ctx} is not a valid
+pointer, or if @var{name}, @var{value} and @var{flags} are an invalid
+combination.  The function also passes through any errors that are
+reported by the crypto engine support routines.
 @end deftypefun
 
-@deftypefun {unsigned int} gpgme_recipients_count (@w{const @var{gpgme_recipients_t rset}})
-The function @code{gpgme_recipients_count} returns the number of
-recipients in the set @var{rset}.
-@end deftypefun
+@deftypefun gpgme_sig_notation_t gpgme_sig_notation_get (@w{const gpgme_ctx_t @var{ctx}})
+The function @code{gpgme_sig_notation_get} returns the linked list of
+notation data structures that are contained in the context @var{ctx}.
 
-@deftypefun gpgme_error_t gpgme_recipients_enum_open (@w{const gpgme_recipients_t @var{rset}}, @w{void **@var{iter}})
-The function @code{gpgme_recipients_enum_open} creates a new iterator
-@var{iter} that can be used to walk through the set of recipients in
-@var{rset}, using @code{gpgme_recipients_enum_read}.
+If @var{ctx} is not a valid pointer, or there is no notation data
+added for this context, @code{NULL} is returned.
+@end deftypefun
 
-If the iterator is not needed anymore, it can be closed with
-@code{gpgme_recipients_enum_close}.
 
-The function returns @code{GPGME_No_Error} if the enumerator was
-successfully created and @code{GPGME_Invalid_Value} if @var{rset} or
-@var{iter} is not a valid pointer.
-@end deftypefun
+@node Encrypt
+@subsection Encrypt
+@cindex encryption
+@cindex cryptographic operation, encryption
 
-@deftypefun {const char *} gpgme_recipients_enum_read (@w{const gpgme_recipients_t @var{rset}}, @w{void **@var{iter}})
-The function @code{gpgme_recipients_enum_read} returns a string
-containing the name of the next recipient in the set @var{rset} for
-the iterator @var{iter}.  The string is valid as long as @var{rset} is
-valid or the function is called the next time with the same recipient
-set and iterator, whatever is earlier.
-@end deftypefun
+One plaintext can be encrypted for several recipients at the same
+time.  The list of recipients is created independently of any context,
+and then passed to the encryption operation.
 
-@deftypefun gpgme_error_t gpgme_recipients_enum_close (@w{const gpgme_recipients_t @var{rset}}, @w{void **@var{iter}})
-The function @code{gpgme_recipients_enum_close} releases the iterator
-@var{iter} for the recipient set @var{rset}.
-@end deftypefun
+@menu
+* Encrypting a Plaintext::        How to encrypt a plaintext.
+@end menu
 
 
 @node Encrypting a Plaintext
 @subsubsection Encrypting a Plaintext
 
-@deftypefun gpgme_error_t gpgme_op_encrypt (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_recipients_t @var{rset}}, @w{gpgme_data_t @var{plain}}, @w{gpgme_data_t @var{cipher}})
-The function @code{gpgme_op_encrypt} encrypts the plaintext in the data
-object @var{plain} for the recipients @var{rset} and stores the
+@deftypefun gpgme_error_t gpgme_op_encrypt (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t @var{recp}[]}, @w{gpgme_encrypt_flags_t @var{flags}}, @w{gpgme_data_t @var{plain}}, @w{gpgme_data_t @var{cipher}})
+The function @code{gpgme_op_encrypt} encrypts the plaintext in the
+data object @var{plain} for the recipients @var{recp} and stores the
 ciphertext in the data object @var{cipher}.  The type of the
-ciphertext created is determined by the @acronym{ASCII} armor and text
-mode attributes set for the context @var{ctx}.
+ciphertext created is determined by the @acronym{ASCII} armor (or, if
+that is not set, by the encoding specified for @var{cipher}) and the
+text mode attributes set for the context @var{ctx}.
+
+@var{key} must be a @code{NULL}-terminated array of keys.  The user
+must keep references for all keys during the whole duration of the
+call (but see @code{gpgme_op_encrypt_start} for the requirements with
+the asynchronous variant).
+
+The value in @var{flags} is a bitwise-or combination of one or
+multiple of the following bit values:
 
-If @code{GPGME_Invalid_UserID} is returned, some recipients in
-@var{rset} are invalid, but not all.  In this case the plaintext is
-encrypted for all valid recipients and returned in @var{cipher}.  More
-information about the invalid recipients is available with
+@table @code
+@item GPGME_ENCRYPT_ALWAYS_TRUST
+The @code{GPGME_ENCRYPT_ALWAYS_TRUST} symbol specifies that all the
+recipients in @var{recp} should be trusted, even if the keys do not
+have a high enough validity in the keyring.  This flag should be used
+with care; in general it is not a good idea to use any untrusted keys.
+
+@item GPGME_ENCRYPT_NO_ENCRYPT_TO
+The @code{GPGME_ENCRYPT_NO_ENCRYPT_TO} symbol specifies that no
+default or hidden default recipients as configured in the crypto
+backend should be included.  This can be useful for managing different
+user profiles.
+@end table
+
+If @code{GPG_ERR_UNUSABLE_PUBKEY} is returned, some recipients in
+@var{recp} are invalid, but not all.  In this case the plaintext might
+be encrypted for all valid recipients and returned in @var{cipher} (if
+this happens depends on the crypto engine).  More information about
+the invalid recipients is available with
 @code{gpgme_op_encrypt_result}.
 
 If @var{recp} is @code{NULL}, symmetric rather than public key
@@ -3854,26 +4896,29 @@ crypto backend needs to retrieve a passphrase from the user.
 Symmetric encryption is currently only supported for the OpenPGP
 crypto backend.
 
-The function returns @code{GPGME_No_Error} if the ciphertext could be
-created successfully, @code{GPGME_Invalid_Value} if @var{ctx},
-@var{rset}, @var{plain} or @var{cipher} is not a valid pointer,
-@code{GPGME_No_UserID} if @var{rset} does not contain any valid
-recipients, @code{GPGME_Invalid_UserID} if @var{rset} contains some
-invalid recipients, @code{GPGME_Bad_Passphrase} if the passphrase for
-the secret key could not be retrieved, and passes through any errors
-that are reported by the crypto engine support routines.
+The function returns the error code @code{GPG_ERR_NO_ERROR} if the
+ciphertext could be created successfully, @code{GPG_ERR_INV_VALUE} if
+@var{ctx}, @var{recp}, @var{plain} or @var{cipher} is not a valid
+pointer, @code{GPG_ERR_UNUSABLE_PUBKEY} if @var{recp} contains some
+invalid recipients, @code{GPG_ERR_BAD_PASSPHRASE} if the passphrase
+for the symmetric key could not be retrieved, and passes through any
+errors that are reported by the crypto engine support routines.
 @end deftypefun
 
-@deftypefun gpgme_error_t gpgme_op_encrypt_start (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_recipients_t @var{rset}}, @w{gpgme_data_t @var{plain}}, @w{gpgme_data_t @var{cipher}})
+@deftypefun gpgme_error_t gpgme_op_encrypt_start (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t @var{recp}[]}, @w{gpgme_encrypt_flags_t @var{flags}}, @w{gpgme_data_t @var{plain}}, @w{gpgme_data_t @var{cipher}})
 The function @code{gpgme_op_encrypt_start} initiates a
 @code{gpgme_op_encrypt} operation.  It can be completed by calling
 @code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
 
-The function returns @code{GPGME_No_Error} if the operation could be
-started successfully, @code{GPGME_Invalid_Value} if @var{ctx},
-@var{rset}, @var{plain} or @var{cipher} is not a valid pointer, and
-@code{GPGME_No_UserID} if @var{rset} does not contain any valid
-recipients.
+References to the keys only need to be held for the duration of this
+call.  The user can release its references to the keys after this
+function returns, even if the operation is not yet finished.
+
+The function returns the error code @code{GPG_ERR_NO_ERROR} if the
+operation could be started successfully, @code{GPG_ERR_INV_VALUE} if
+@var{ctx}, @var{rset}, @var{plain} or @var{cipher} is not a valid
+pointer, and @code{GPG_ERR_UNUSABLE_PUBKEY} if @var{rset} does not
+contain any valid recipients.
 @end deftypefun
 
 @deftp {Data type} {gpgme_encrypt_result_t}
@@ -3884,24 +4929,26 @@ data, you can retrieve the pointer to the result with
 members:
 
 @table @code
-@item gpgme_invalid_user_id_t invalid_recipients
-A linked list with information about all invalid user IDs for which
+@item gpgme_invalid_key_t invalid_recipients
+A linked list with information about all invalid keys for which
 the data could not be encrypted.
 @end table
 @end deftp
 
 @deftypefun gpgme_encrypt_result_t gpgme_op_encrypt_result (@w{gpgme_ctx_t @var{ctx}})
 The function @code{gpgme_op_encrypt_result} returns a
-@code{gpgme_encrypt_result_t} pointer to a structure holding the result of
-a @code{gpgme_op_encrypt} operation.  The pointer is only valid if the
-last operation on the context was a @code{gpgme_op_encrypt} or
-@code{gpgme_op_encrypt_start} operation, and if this operation
-finished successfully.  The returned pointer is only valid until the
-next operation is started on the context.
+@code{gpgme_encrypt_result_t} pointer to a structure holding the
+result of a @code{gpgme_op_encrypt} operation.  The pointer is only
+valid if the last operation on the context was a
+@code{gpgme_op_encrypt}, @code{gpgme_op_encrypt_start},
+@code{gpgme_op_sign} or @code{gpgme_op_sign_start} operation.  If this
+operation failed, this might be a @code{NULL} pointer.  The returned
+pointer is only valid until the next operation is started on the
+context.
 @end deftypefun
 
 
-@deftypefun gpgme_error_t gpgme_op_encrypt_sign (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_recipients_t @var{rset}}, @w{gpgme_data_t @var{plain}}, @w{gpgme_data_t @var{cipher}})
+@deftypefun gpgme_error_t gpgme_op_encrypt_sign (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t @var{recp}[]}, @w{gpgme_encrypt_flags_t @var{flags}}, @w{gpgme_data_t @var{plain}}, @w{gpgme_data_t @var{cipher}})
 The function @code{gpgme_op_encrypt_sign} does a combined encrypt and
 sign operation.  It is used like @code{gpgme_op_encrypt}, but the
 ciphertext also contains signatures for the signers listed in
@@ -3911,17 +4958,16 @@ The combined encrypt and sign operation is currently only available
 for the OpenPGP crypto engine.
 @end deftypefun
 
-@deftypefun gpgme_error_t gpgme_op_encrypt_sign_start (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_recipients_t @var{rset}}, @w{gpgme_data_t @var{plain}}, @w{gpgme_data_t @var{cipher}})
+@deftypefun gpgme_error_t gpgme_op_encrypt_sign_start (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t @var{recp}}, @w{gpgme_encrypt_flags_t @var{flags}}, @w{gpgme_data_t @var{plain}}, @w{gpgme_data_t @var{cipher}})
 The function @code{gpgme_op_encrypt_sign_start} initiates a
 @code{gpgme_op_encrypt_sign} operation.  It can be completed by
 calling @code{gpgme_wait} on the context.  @xref{Waiting For
 Completion}.
 
-The function returns @code{GPGME_No_Error} if the operation could be
-started successfully, @code{GPGME_Invalid_Value} if @var{ctx},
-@var{rset}, @var{plain} or @var{cipher} is not a valid pointer, and
-@code{GPGME_No_UserID} if @var{rset} does not contain any valid
-recipients.
+The function returns the error code @code{GPG_ERR_NO_ERROR} if the
+operation could be started successfully, and @code{GPG_ERR_INV_VALUE}
+if @var{ctx}, @var{rset}, @var{plain} or @var{cipher} is not a valid
+pointer.
 @end deftypefun
 
 
@@ -3943,6 +4989,7 @@ time.
 @menu
 * Waiting For Completion::        Waiting until an operation is completed.
 * Using External Event Loops::    Advanced control over what happens when.
+* Cancellation::                  How to end pending operations prematurely.
 @end menu
 
 
@@ -4012,7 +5059,7 @@ decide when to check the file descriptors and when to invoke the
 callback functions.  Usually this is done in an event loop, that also
 checks for events in other parts of the program.  If the callback
 functions are only called when the file descriptors are ready,
-@acronym{GPGME} will never block.  This gives the user mroe control
+@acronym{GPGME} will never block.  This gives the user more control
 over the program flow, and allows to perform other tasks when
 @acronym{GPGME} would block otherwise.
 
@@ -4026,6 +5073,7 @@ programs.
 * I/O Callback Example::          An example how to use I/O callbacks.
 * I/O Callback Example GTK+::     How to use @acronym{GPGME} with GTK+.
 * I/O Callback Example GDK::      How to use @acronym{GPGME} with GDK.
+* I/O Callback Example Qt::       How to use @acronym{GPGME} with Qt.
 @end menu
 
 
@@ -4050,7 +5098,7 @@ the return value to be reserved for later use.
 @deftp {Data type} {gpgme_error_t (*gpgme_register_io_cb_t) (@w{void *@var{data}}, @w{int @var{fd}}, @w{int @var{dir}}, @w{gpgme_io_cb_t @var{fnc}}, @w{void *@var{fnc_data}}, @w{void **@var{tag}})}
 @tindex gpgme_register_io_cb_t
 The @code{gpgme_register_io_cb_t} type is the type of functions which can
-be called by @acronym{GPGME} to register an I/O callback funtion
+be called by @acronym{GPGME} to register an I/O callback function
 @var{fnc} for the file descriptor @var{fd} with the user.
 @var{fnc_data} should be passed as the first argument to @var{fnc}
 when the handler is invoked (the second argument should be @var{fd}).
@@ -4164,8 +5212,8 @@ callback handler.  It must be specified.
 
 @item gpgme_event_io_cb_t event
 This is the function called by @acronym{GPGME} to signal an event for
-an operation.  It is optional, but if you don't specify it, you can
-not retrieve the return value of the operation.
+an operation.  It must be specified, because at least the start event
+must be processed.
 
 @item void *event_data
 This is passed as the first argument to the @code{event} function when
@@ -4199,7 +5247,7 @@ monitor these file descriptors for activity and call the appropriate
 I/O callbacks.
 
 The following example illustrates how to do that.  The example uses
-locking to show in which way the the callbacks and the event loop can
+locking to show in which way the callbacks and the event loop can
 run concurrently.  For the event loop, we use a fixed array.  For a
 real-world implementation, you should use a dynamically sized
 structure because the number of file descriptors needed for a crypto
@@ -4261,7 +5309,7 @@ add_io_cb (void *data, int fd, int dir, gpgme_io_cb_t fnc, void *fnc_data,
     @}
   pthread_mutex_unlock (&loop->lock);
   if (i == MAX_FDS)
-    return GPGME_General_Error;
+    return gpg_error (GPG_ERR_GENERAL);
   *r_tag = &fds[i];
   return 0;
 @}
@@ -4280,13 +5328,12 @@ void
 event_io_cb (void *data, gpgme_event_io_t type, void *type_data)
 @{
   struct op_result *result = data;
-  gpgme_error_t *err = data;
 
   /* We don't support list operations here.  */
   if (type == GPGME_EVENT_DONE)
     @{
       result->done = 1;
-      result->err = *data;
+      result->err = *type_data;
     @}
 @}
 @end example
@@ -4378,6 +5425,8 @@ main (int argc, char *argv[])
     &result
   @};
 
+  init_gpgme (void);
+
   /* Initialize the loop structure.  */
   loop.lock = PTHREAD_MUTEX_INITIALIZER;
   for (i = 0; i < MAX_FDS; i++)
@@ -4398,7 +5447,8 @@ main (int argc, char *argv[])
     @}
   if (err)
     @{
-      fprintf (stderr, "gpgme error: %s\n", gpgme_strerror (err));
+      fprintf (stderr, "gpgme error: %s: %s\n",
+               gpgme_strsource (err), gpgme_strerror (err));
       exit (1);
     @}
 
@@ -4410,7 +5460,8 @@ main (int argc, char *argv[])
     @}
   if (!result.err)
     @{
-      fprintf (stderr, "verification failed: %s\n", gpgme_strerror (result.err));
+      fprintf (stderr, "verification failed: %s: %s\n",
+               gpgme_strsource (result.err), gpgme_strerror (result.err));
       exit (1);
     @}
   /* Evaluate STATUS.  */
@@ -4525,24 +5576,143 @@ my_gpgme_register_io_callback (void *data, int fd, int dir, gpgme_io_cb_t fnc,
 @end example
 
 
-@include gpl.texi
+@node I/O Callback Example Qt
+@subsubsection I/O Callback Example Qt
+@cindex Qt, using @acronym{GPGME} with
 
+The I/O callback interface can also be used to integrate
+@acronym{GPGME} with the Qt event loop.  The following code snippets
+show how this can be done using the appropriate register and remove
+I/O callback functions.  In this example, the private data of the
+register I/O callback function is unused.  The event notifications is
+missing because it does not require any Qt specific setup.
 
-@include fdl.texi
+@example
+#include <qsocketnotifier.h>
+#include <qapplication.h>
+
+struct IOCB @{
+  IOCB( GpgmeIOCb f, void * d, QSocketNotifier * n )
+    : func( f ), data( d ), notifier( n ) @{@}
+  GpgmeIOCb func;
+  void * data;
+  QSocketNotifier * notifier;
+@}
 
+class MyApp : public QApplication @{
+
+  // ...
+  
+  static void registerGpgmeIOCallback( void * data, int fd, int dir,
+                                       GpgmeIOCb func, void * func_data,
+                                       void ** tag ) @{
+    QSocketNotifier * n =
+      new QSocketNotifier( fd, dir ? QSocketNotifier::Read
+                                   : QSocketNotifier::Write );
+    connect( n, SIGNAL(activated(int)),
+             qApp, SLOT(slotGpgmeIOCallback(int)) );
+    qApp->mIOCBs.push_back( IOCB( func, func_data, n ) );
+    *tag = (void*)n;
+  @}
 
-@node Concept Index
-@unnumbered Concept Index
+  static void removeGpgmeIOCallback( void * tag ) @{
+    if ( !tag ) return;
+    QSocketNotifier * n = static_cast<QSocketNotifier*>( tag );
+    for ( QValueList<IOCB>::iterator it = qApp->mIOCBs.begin() ;
+          it != qApp->mIOCBs.end() ; ++it )
+      if ( it->notifier == n ) @{
+        delete it->notifier;
+        qApp->mIOCBs.erase( it );
+        return;
+      @}
+  @}
 
-@printindex cp
+public slots:
+  void slotGpgmeIOCallback( int fd ) @{
+    for ( QValueList<IOCB>::const_iterator it = mIOCBs.begin() ;
+          it != mIOCBs.end() ; ++it )
+      if ( it->notifier && it->notifier->socket() == fd )
+        (*(it->func)) ( it->func_data, fd );
+  @}
+
+  // ...
+
+private:
+  QValueList<IOCB> mIOCBs;
+  // ...
+@};
+@end example
 
 
+@node Cancellation
+@subsection Cancellation
+@cindex cryptographic operation, aborting
+@cindex cryptographic operation, cancelling
+@cindex aborting operations
+@cindex cancelling operations
+
+Sometimes you do not want to wait for an operation to finish.
+@acronym{GPGME} provides two different functions to achieve that.  The
+function @code{gpgme_cancel} takes effect immediately.  When it
+returns, the operation is effectively canceled.  However, it has some
+limitations and can not be used with synchronous operations.  In
+contrast, the function @code{gpgme_cancel_async} can be used with any
+context and from any thread, but it is not guaranteed to take effect
+immediately.  Instead, cancellation occurs at the next possible time
+(typically the next time I/O occurs in the target context).
+
+@deftypefun gpgme_ctx_t gpgme_cancel (@w{gpgme_ctx_t @var{ctx}})
+The function @code{gpgme_cancel} attempts to cancel a pending
+operation in the context @var{ctx}.  This only works if you use the
+global event loop or your own event loop.
+
+If you use the global event loop, you must not call @code{gpgme_wait}
+or @code{gpgme_wait} during cancellation.  After successful
+cancellation, you can call @code{gpgme_wait} (optionally waiting on
+@var{ctx}), and the context @var{ctx} will appear as if it had
+finished with the error code @code{GPG_ERR_CANCEL}.
+
+If you use your an external event loop, you must ensure that no I/O
+callbacks are invoked for this context (for example by halting the
+event loop).  On successful cancellation, all registered I/O callbacks
+for this context will be unregistered, and a @code{GPGME_EVENT_DONE}
+event with the error code @code{GPG_ERR_CANCEL} will be signaled.
+
+The function returns an error code if the cancellation failed (in this
+case the state of @var{ctx} is not modified).
+@end deftypefun
+
+
+@deftypefun gpgme_ctx_t gpgme_cancel_async (@w{gpgme_ctx_t @var{ctx}})
+The function @code{gpgme_cancel} attempts to cancel a pending
+operation in the context @var{ctx}.  This can be called by any thread
+at any time after starting an operation on the context, but will not
+take effect immediately.  The actual cancellation happens at the next
+time GPGME processes I/O in that context.
+
+The function returns an error code if the cancellation failed (in this
+case the state of @var{ctx} is not modified).
+@end deftypefun
+
+@c **********************************************************
+@c *******************  Appendices  *************************
+@c **********************************************************
+
+@include uiserver.texi
+
+@include lesser.texi
+
+@include gpl.texi
+
 @node Function and Data Index
 @unnumbered Function and Data Index
 
 @printindex fn
 
+@node Concept Index
+@unnumbered Concept Index
+
+@printindex cp
+
 
-@summarycontents
-@contents
 @bye