doc/
[gpgme.git] / doc / gpgme.texi
index 6b82298..92289c2 100644 (file)
@@ -20,16 +20,22 @@ 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.
+@c NOTE: Don't forget to update the year for the TeX version, too.
+Copyright @copyright{} 2002, 2003, 2004 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''.
+The GPGME reference manual is free software; you can redistribute it
+and/or modify it under the terms of the GNU Lesser General Public
+License as published by the Free Software Foundation; either version
+2.1 of the License, or (at your option) any later version.
+
+The GPGME reference manual 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
+Lesser General Public License for more details.
+
+You should have received a copy of the GNU Lesser General Public
+License along with this program; if not, write to the Free Software
+Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
 
 @end ifinfo
 
@@ -48,16 +54,22 @@ Documentation License''.
 @center for version @value{VERSION}
 @page
 @vskip 0pt plus 1filll
-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''.
+Copyright @copyright{} 2002, 2003, 2004 g10 Code GmbH.
+
+
+The GPGME reference manual is free software; you can redistribute it
+and/or modify it under the terms of the GNU Lesser General Public
+License as published by the Free Software Foundation; either version
+2.1 of the License, or (at your option) any later version.
+
+The GPGME reference manual 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
+Lesser General Public License for more details.
+
+You should have received a copy of the GNU Lesser General Public
+License along with this program; if not, write to the Free Software
+Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
 @end titlepage
 @page
 
@@ -73,16 +85,15 @@ This is Edition @value{EDITION}, last updated @value{UPDATED}, of
 * Introduction::                  How to use this manual.
 * Preparation::                   What you should do before using the library.
 * Protocols and Engines::         Supported crypto protocols.
+* Algorithms::                    Supported algorithms.
 * Error Handling::                Error numbers and their meanings.
 * Exchanging Data::               Passing data to and from @acronym{GPGME}.
 * Contexts::                      Handling @acronym{GPGME} contexts.
 
 Appendices
 
-* 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.
+* Library Copying::               The GNU Lesser General Public License says
+                                  how you can copy and share `GnuPG Made Easy'.
 
 Indices
 
@@ -103,20 +114,31 @@ 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.
 
+Algorithms
+
+* Public Key Algorithms::         A list of all public key algorithms.
+* Hash Algorithms::               A list of all hash 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 
@@ -144,12 +166,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
 
@@ -165,7 +189,7 @@ Key Management
 Trust Item Management
 
 * Listing Trust Items::           Browsing the list of available trust items.
-* Information About Trust Items:: Requesting detailed information about trust items.
+* Information About Trust Items:: Requesting information about trust items.
 * Manipulating Trust Items::      Operations on trust items.
 
 Crypto Operations
@@ -175,7 +199,6 @@ Crypto Operations
 * Decrypt and Verify::            Decrypting a signed ciphertext.
 * Sign::                          Creating a signature.
 * Encrypt::                       Encrypting a plaintext.
-* Detailed Results::              How to obtain more info about the operation.
 
 Sign
 
@@ -184,14 +207,13 @@ Sign
 
 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.
-* Cancelling an Operation::       Interrupting a running operation.
 * Using External Event Loops::    Advanced control over what happens when.
+* Cancellation::                  How to end pending operations prematurely.
 
 Using External Event Loops
 
@@ -200,6 +222,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
@@ -209,9 +232,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
@@ -257,7 +280,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
@@ -312,8 +335,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
 
@@ -332,14 +358,14 @@ like this:
 #include <gpgme.h>
 @end example
 
-The name space of @acronym{GPGME} is @code{gpgme_*} for function
-names, @code{Gpgme*} for data types and @code{GPGME_*} for other
-symbols.  Symbols internal to @acronym{GPGME} take the form
-@code{_gpgme_*}.
+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
@@ -365,9 +391,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,
@@ -390,14 +416,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.
 
@@ -406,6 +514,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
@@ -415,6 +525,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
@@ -426,6 +544,16 @@ 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
@@ -459,6 +587,59 @@ features are provided by the installed version of the library.
 @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_program (void)
+@{
+  /* Initialize the locale environment.  */
+  setlocale (LC_ALL, "");
+  gpgme_check_version (NULL);
+  gpgme_set_locale (NULL, LC_CTYPE, setlocale (LC_CTYPE, NULL));
+  gpgme_set_locale (NULL, LC_MESSAGES, setlocale (LC_MESSAGES, NULL));
+@}
+@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.
+
+
+@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
@@ -474,79 +655,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.  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{GpgmeData}, @code{GpgmeCtx} and @code{GpgmeRecipients}
-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
 
 
@@ -563,29 +716,38 @@ 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
 hooks and further interfaces.
 
-@deftp {Data type} {enum GpgmeProtocol}
-@tindex GpgmeProtocol
-The @code{GpgmeProtocol} type specifies the set of possible protocol
+@deftp {Data type} {enum gpgme_protocol_t}
+@tindex gpgme_protocol_t
+The @code{gpgme_protocol_t} type specifies the set of possible protocol
 values that are supported by @acronym{GPGME}.  The following protocols
 are supported:
 
 @table @code
 @item GPGME_PROTOCOL_OpenPGP
 This specifies the OpenPGP protocol.
+
 @item GPGME_PROTOCOL_CMS
 This specifies the Cryptographic Message Syntax.
 @end table
 @end deftp
 
+
+@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.
+@end deftypefun
+
 @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
@@ -595,13 +757,13 @@ This specifies the Cryptographic Message Syntax.
 @section Engine Version Check
 @cindex version check, of the engines
 
-@deftypefun GpgmeError gpgme_engine_check_version (@w{GpgmeProtocol @var{protocol}})
+@deftypefun gpgme_error_t gpgme_engine_check_version (@w{gpgme_protocol_t @var{protocol}})
 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
 
 
@@ -609,44 +771,124 @@ and @code{GPGME_Invalid_Engine} if it is not.
 @section Engine Information
 @cindex engine, information about
 
-@deftypefun {const char *} gpgme_get_engine_info (void)
-The function @code{gpgme_get_engine_info} returns an @acronym{XML}
-string containing information about the available protocols and the
-engine which implement them.  The following information is returned
-for each engine:
-
-@table @samp
-@item <protocol>
-The name of the protocol.
-@item <version>
-The version of the engine.
-@item <path>
-The path to the engine binary.
+@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 engine.  The structure contains the following
+elements:
+
+@table @code
+@item gpgme_engine_info_t next
+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 crypto engine is used.  You can
+convert this to a string with @code{gpgme_get_protocol_name} for
+printing.
+
+@item const char *file_name
+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,
+for example because the executable doesn't exist or is invalid.
+
+@item const char *req_version
+This is a string containing the minimum required version number of the
+crypto engine for @acronym{GPGME} to work correctly.  This is the
+version number that @code{gpgme_engine_check_version} verifies
+against.  Currently, it is never @code{NULL}, but using @code{NULL} is
+reserved for future use, so always check before you use it.
 @end table
+@end deftp
+
+@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
+the defaults of one configured backend.
 
-A string is always returned.  If an error occurs, the string will
-contain an @samp{<error>} tag with a description of the failure.
+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 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 output of what @code{gpgme_get_engine_info} might
-return on your system:
+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
-<EngineInfo>
- <engine>
-  <protocol>OpenPGP</protocol>
-  <version>1.0.6</version>
-  <path>/usr/bin/gpg</path>
- </engine>
- <engine>
-  <protocol>CMS</protocol>
-  <version>0.0.0</version>
-  <path>/usr/bin/gpgsm</path>
- </engine>
-</EngineInfo>
+gpgme_ctx_t ctx;
+gpgme_error_t err;
+
+[...]
+
+if (gpgme_err_code (err) == GPG_ERR_INV_ENGINE)
+  @{
+    gpgme_engine_info_t info;
+    err = gpgme_get_engine_info (&info);
+    if (!err)
+      @{
+        while (info && info->protocol != gpgme_get_protocol (ctx))
+          info = info->next;
+        if (!info)
+          fprintf (stderr, "GPGME compiled without support for protocol %s",
+                   gpgme_get_protocol_name (info->protocol));
+        else if (info->path && !info->version)
+          fprintf (stderr, "Engine %s not installed properly",
+                   info->path);
+        else if (info->path && info->version && info->req_version)
+          fprintf (stderr, "Engine %s version %s installed, "
+                   "but at least version %s required", info->path,
+                   info->version, info->req_version);
+        else
+          fprintf (stderr, "Unknown problem with engine for protocol %s",
+                   gpgme_get_protocol_name (info->protocol));
+      @}
+  @}
 @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
@@ -676,6 +918,110 @@ GnuPG.
 The @acronym{CMS} protocol is specified by @code{GPGME_PROTOCOL_CMS}.
 
 
+@node Algorithms
+@chapter Algorithms
+@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.
+
+@menu
+* Public Key Algorithms::         A list of all public key algorithms.
+* Hash Algorithms::               A list of all hash algorithms.
+@end menu
+
+
+@node Public Key Algorithms
+@section Public Key Algorithms
+@cindex algorithms, public key
+@cindex public key algorithms
+
+Public key algorithms are used for encryption, decryption, signing and
+verification of signatures.
+
+@deftp {Data type} {enum gpgme_pubkey_algo_t}
+@tindex gpgme_pubkey_algo_t
+The @code{gpgme_pubkey_algo_t} type specifies the set of all public key
+algorithms that are supported by @acronym{GPGME}.  Possible values
+are:
+
+@table @code
+@item GPGME_PK_RSA
+This value indicates the RSA (Rivest, Shamir, Adleman) algorithm.
+
+@item GPGME_PK_RSA_E
+Deprecated.  This value indicates the RSA (Rivest, Shamir, Adleman)
+algorithm for encryption and decryption only.
+
+@item GPGME_PK_RSA_S
+Deprecated.  This value indicates the RSA (Rivest, Shamir, Adleman)
+algorithm for signing and verification only.
+
+@item GPGME_PK_DSA
+This value indicates DSA, the Digital Signature Algorithm.
+
+@item GPGME_PK_ELG
+This value indicates ElGamal.
+
+@item GPGME_PK_ELG_E
+This value also indicates ElGamal and is used specifically in GnuPG.
+@end table
+@end deftp
+
+@deftypefun {const char *} gpgme_pubkey_algo_name (@w{gpgme_pubkey_algo_t @var{algo}})
+The function @code{gpgme_pubkey_algo_name} returns a pointer to a
+statically allocated string containing a description of the public key
+algorithm @var{algo}.  This string can be used to output the name of
+the public key algorithm to the user.
+
+If @var{algo} is not a valid public key algorithm, @code{NULL} is
+returned.
+@end deftypefun
+
+
+@node Hash Algorithms
+@section Hash Algorithms
+@cindex algorithms, hash
+@cindex algorithms, message digest
+@cindex hash algorithms
+@cindex message digest algorithms
+
+Hash (message digest) algorithms are used to compress a long message
+to make it suitable for public key cryptography.
+
+@deftp {Data type} {enum gpgme_hash_algo_t}
+@tindex gpgme_hash_algo_t
+The @code{gpgme_hash_algo_t} type specifies the set of all hash algorithms
+that are supported by @acronym{GPGME}.  Possible values are:
+
+@table @code
+@item GPGME_MD_MD5
+@item GPGME_MD_SHA1
+@item GPGME_MD_RMD160
+@item GPGME_MD_MD2
+@item GPGME_MD_TIGER
+@item GPGME_MD_HAVAL
+@item GPGME_MD_SHA256
+@item GPGME_MD_SHA384
+@item GPGME_MD_SHA512
+@item GPGME_MD_MD4
+@item GPGME_MD_CRC32
+@item GPGME_MD_CRC32_RFC1510
+@item GPGME_MD_CRC24_RFC2440
+@end table
+@end deftp
+
+@deftypefun {const char *} gpgme_hash_algo_name (@w{gpgme_hash_algo_t @var{algo}})
+The function @code{gpgme_hash_algo_name} returns a pointer to a
+statically allocated string containing a description of the hash
+algorithm @var{algo}.  This string can be used to output the name of
+the hash algorithm to the user.
+
+If @var{algo} is not a valid hash algorithm, @code{NULL} is returned.
+@end deftypefun
+
+
 @node Error Handling
 @chapter Error Handling
 @cindex error handling
@@ -691,152 +1037,391 @@ 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
 
-@deftp {Data type} {enum GpgmeError}
-@tindex GpgmeError
-The @code{GpgmeError} type specifies the set of all error values that
-are used by @acronym{GPGME}.  Possible values are:
+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}.
+
+The list of error sources that might occur in applications using
+@acronym{GPGME} is:
+
+@table @code
+@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 GPGME_EOF
+@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{GpgmeData}
-object was expected, but one containing data was provided, this error
-value is returned.
-
-@item GPGME_Busy
-This value is returned if you try to start a new operation in a
-context that is already busy with some earlier operation which was not
-cancelled or finished yet.
-
-@item GPGME_No_Request
-This value is in some sense the opposite of @code{GPGME_Busy}.  There
-is no pending operation, but it is required for the function to
-succeed.
-
-@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_Recipients 
-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_Recipients 
-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{GpgmeData} 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_Invalid_Type
-This value means that a user provided object was of a wrong or
-incompatible type.  Usually this refers to the type of a
-@code{GpgmeData} object.
-
-@item GPGME_Invalid_Mode
-This value means that a @code{GpgmeData} object has an incorrect mode
-of operation (for example, doesn't support output although it is
-attempted to use it as an output buffer).
-
-@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_No_Passphrase
-This value means that the user did not provide a passphrase when
-requested.
+@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 GPG_ERR_AMBIGUOUS_NAME
+This value indicates that a user ID or other specifier did not specify
+a unique key.
+
+@item GPG_ERR_WRONG_KEY_USAGE
+This value indicates that a key is not used appropriately.
+
+@item GPG_ERR_CERT_REVOKED
+This value indicates that a key signature was revoced.
+
+@item GPG_ERR_CERT_EXPIRED
+This value indicates that a key signature expired.
+
+@item GPG_ERR_NO_CRL_KNOWN
+This value indicates that no certificate revocation list is known for
+the certificate.
+
+@item GPG_ERR_NO_POLICY_MATCH
+This value indicates that a policy issue occured.
+
+@item GPG_ERR_NO_SECKEY
+This value indicates that no secret key for the user ID is available.
+
+@item GPG_ERR_MISSING_CERT
+This value indicates that a key could not be imported because the
+issuer certificate is missing.
+
+@item GPG_ERR_BAD_CERT_CHAIN
+This value indicates that a key could not be imported because its
+certificate chain is not good, for example it could be too long.
+
+@item GPG_ERR_UNSUPPORTED_ALGORITHM
+This value means a verification failed because the cryptographic
+algorithm is not supported by the crypto backend.
+
+@item GPG_ERR_BAD_SIGNATURE
+This value means a verification failed because the signature is bad.
+
+@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{GpgmeError @var{err}})
+@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 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 {char *} gpgme_strerror_r (@w{gpgme_error_t @var{err}})
+The function @code{gpgme_strerror_r} returns a pointer to a
+dynamically 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.  When it is not needed
+anymore, the user must deallocate it with @code{free}.
+@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 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 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}:
 
 @example
-GpgmeCtx ctx;
-GpgmeError err = gpgme_new (&ctx);
+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
@@ -847,12 +1432,12 @@ A lot of data has to be exchanged between the user and the crypto
 engine, like plaintext messages, ciphertext, signatures and
 information about the keys.  The technical details about exchanging
 the data information are completely abstracted by @acronym{GPGME}.
-The user provides and receives the data via @code{GpgmeData} objects,
+The user provides and receives the data via @code{gpgme_data_t} objects,
 regardless of the communication protocol between @acronym{GPGME} and
 the crypto engine in use.
 
-@deftp {Data type} {GpgmeData}
-The @code{GpgmeData} type is a handle for a container for generic
+@deftp {Data type} {gpgme_data_t}
+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
 
@@ -888,20 +1473,20 @@ fraction of the available physical memory.  The data has to be copied
 from its source and to its destination, which can often be avoided by
 using one of the other data object 
 
-@deftypefun GpgmeError gpgme_data_new (@w{GpgmeData *@var{dh}})
-The function @code{gpgme_data_new} creates a new @code{GpgmeData}
+@deftypefun gpgme_error_t gpgme_data_new (@w{gpgme_data_t *@var{dh}})
+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 GpgmeError gpgme_data_new_from_mem (@w{GpgmeData *@var{dh}}, @w{const char *@var{buffer}}, @w{size_t @var{size}}, @w{int @var{copy}})
+@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}})
 The function @code{gpgme_data_new_from_mem} creates a new
-@code{GpgmeData} object and fills it with @var{size} bytes starting
+@code{gpgme_data_t} object and fills it with @var{size} bytes starting
 from @var{buffer}.
 
 If @var{copy} is not zero, a private copy of the data is made.  If
@@ -909,15 +1494,15 @@ 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 GpgmeError gpgme_data_new_from_file (@w{GpgmeData *@var{dh}}, @w{const char *@var{filename}}, @w{int @var{copy}})
+@deftypefun gpgme_error_t gpgme_data_new_from_file (@w{gpgme_data_t *@var{dh}}, @w{const char *@var{filename}}, @w{int @var{copy}})
 The function @code{gpgme_data_new_from_file} creates a new
-@code{GpgmeData} object and fills it with the content of the file
+@code{gpgme_data_t} object and fills it with the content of the file
 @var{filename}.
 
 If @var{copy} is not zero, the whole file is read in at initialization
@@ -926,16 +1511,16 @@ 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 GpgmeError gpgme_data_new_from_filepart (@w{GpgmeData *@var{dh}}, @w{const char *@var{filename}}, @w{FILE *@var{fp}}, @w{off_t @var{offset}}, @w{size_t @var{length}})
+@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}})
 The function @code{gpgme_data_new_from_filepart} creates a new
-@code{GpgmeData} object and fills it with a part of the file specified
+@code{gpgme_data_t} object and fills it with a part of the file specified
 by @var{filename} or @var{fp}.
 
 Exactly one of @var{filename} and @var{fp} must be non-zero, the other
@@ -943,11 +1528,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
 
 
@@ -958,9 +1542,9 @@ File based data objects operate directly on file descriptors or
 streams.  Only a small amount of data is stored in core at any time,
 so the size of the data objects is not limited by @acronym{GPGME}.
 
-@deftypefun GpgmeError gpgme_data_new_from_fd (@w{GpgmeData *@var{dh}}, @w{int @var{fd}})
+@deftypefun gpgme_error_t gpgme_data_new_from_fd (@w{gpgme_data_t *@var{dh}}, @w{int @var{fd}})
 The function @code{gpgme_data_new_from_fd} creates a new
-@code{GpgmeData} object and uses the file descriptor @var{fd} to read
+@code{gpgme_data_t} object and uses the file descriptor @var{fd} to read
 from (if used as an input data object) and write to (if used as an
 output data object).
 
@@ -968,14 +1552,14 @@ 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.
+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 GpgmeError gpgme_data_new_from_stream (@w{GpgmeData *@var{dh}}, @w{FILE *@var{stream}})
+@deftypefun gpgme_error_t gpgme_data_new_from_stream (@w{gpgme_data_t *@var{dh}}, @w{FILE *@var{stream}})
 The function @code{gpgme_data_new_from_stream} creates a new
-@code{GpgmeData} object and uses the I/O stream @var{stream} to read
+@code{gpgme_data_t} object and uses the I/O stream @var{stream} to read
 from (if used as an input data object) and write to (if used as an
 output data object).
 
@@ -983,9 +1567,9 @@ 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.
+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
 
 
@@ -996,9 +1580,9 @@ If neither memory nor file based data objects are a good fit for your
 application, you can implement the functions a data object provides
 yourself and create a data object from these callback functions.
 
-@deftp {Data type} {ssize_t (*GpgmeDataReadCb) (@w{void *@var{handle}}, @w{void @var{*buffer}}, @w{size_t @var{size}})}
-@tindex GpgmeDataReadCb
-The @code{GpgmeDataReadCb} type is the type of functions which
+@deftp {Data type} {ssize_t (*gpgme_data_read_cb_t) (@w{void *@var{handle}}, @w{void @var{*buffer}}, @w{size_t @var{size}})}
+@tindex gpgme_data_read_cb_t
+The @code{gpgme_data_read_cb_t} type is the type of functions which
 @acronym{GPGME} calls if it wants to read data from a user-implemented
 data object.  The function should read up to @var{size} bytes from the
 current read position into the space starting at @var{buffer}.  The
@@ -1009,9 +1593,9 @@ on error.  If an error occurs, @var{errno} should be set to describe
 the type of the error.
 @end deftp
 
-@deftp {Data type} {ssize_t (*GpgmeDataWriteCb) (@w{void *@var{handle}}, @w{const void @var{*buffer}}, @w{size_t @var{size}})}
-@tindex GpgmeDataWriteCb
-The @code{GpgmeDataWriteCb} type is the type of functions which
+@deftp {Data type} {ssize_t (*gpgme_data_write_cb_t) (@w{void *@var{handle}}, @w{const void @var{*buffer}}, @w{size_t @var{size}})}
+@tindex gpgme_data_write_cb_t
+The @code{gpgme_data_write_cb_t} type is the type of functions which
 @acronym{GPGME} calls if it wants to write data to a user-implemented
 data object.  The function should write up to @var{size} bytes to the
 current write position from the space starting at @var{buffer}.  The
@@ -1022,9 +1606,9 @@ error.  If an error occurs, @var{errno} should be set to describe the
 type of the error.
 @end deftp
 
-@deftp {Data type} {off_t (*GpgmeDataSeekCb) (@w{void *@var{handle}}, @w{off_t @var{offset}}, @w{int @var{whence}})}
-@tindex GpgmeDataSeekCb
-The @code{GpgmeDataSeekCb} type is the type of functions which
+@deftp {Data type} {off_t (*gpgme_data_seek_cb_t) (@w{void *@var{handle}}, @w{off_t @var{offset}}, @w{int @var{whence}})}
+@tindex gpgme_data_seek_cb_t
+The @code{gpgme_data_seek_cb_t} type is the type of functions which
 @acronym{GPGME} calls if it wants to change the current read/write
 position in a user-implemented data object, just like the @code{lseek}
 function.
@@ -1034,57 +1618,57 @@ error.  If an error occurs, @var{errno} should be set to describe the
 type of the error.
 @end deftp
 
-@deftp {Data type} {void (*GpgmeDataReleaseCb) (@w{void *@var{handle}})}
-@tindex GpgmeDataReleaseCb
-The @code{GpgmeDataReleaseCb} type is the type of functions which
+@deftp {Data type} {void (*gpgme_data_release_cb_t) (@w{void *@var{handle}})}
+@tindex gpgme_data_release_cb_t
+The @code{gpgme_data_release_cb_t} type is the type of functions which
 @acronym{GPGME} calls if it wants to destroy a user-implemented data
 object.  The @var{handle} is provided by the user at data object
 creation time.
 @end deftp
 
-@deftp {Data type} {struct GpgmeDataCbs}
+@deftp {Data type} {struct gpgme_data_cbs}
 This structure is used to store the data callback interface functions
 described above.  It has the following members:
 
 @table @code
-@item GpgmeDataReadCb read
+@item gpgme_data_read_cb_t read
 This is the function called by @acronym{GPGME} to read data from the
 data object.  It is only required for input data object.
 
-@item GpgmeDataWriteCb write
+@item gpgme_data_write_cb_t write
 This is the function called by @acronym{GPGME} to write data to the
 data object.  It is only required for output data object.
 
-@item GpgmeDataSeekCb seek
+@item gpgme_data_seek_cb_t seek
 This is the function called by @acronym{GPGME} to change the current
 read/write pointer in the data object (if available).  It is optional.
 
-@item GpgmeDataReleaseCb release
+@item gpgme_data_release_cb_t release
 This is the function called by @acronym{GPGME} to release a data
 object.  It is optional.
 @end table
 @end deftp
 
-@deftypefun GpgmeError gpgme_data_new_from_cbs (@w{GpgmeData *@var{dh}}, @w{struct GpgmeDataCbs *@var{cbs}}, @w{void *@var{handle}})
+@deftypefun gpgme_error_t gpgme_data_new_from_cbs (@w{gpgme_data_t *@var{dh}}, @w{gpgme_data_cbs_t @var{cbs}}, @w{void *@var{handle}})
 The function @code{gpgme_data_new_from_cbs} creates a new
-@code{GpgmeData} object and uses the user-provided callback functions
+@code{gpgme_data_t} object and uses the user-provided callback functions
 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
 compatibility.  Don't use it.  It will be removed in a future version
 of @acronym{GPGME}.
 
-@deftypefun GpgmeError gpgme_data_new_with_read_cb (@w{GpgmeData *@var{dh}}, @w{int (*@var{readfunc})} (@w{void *@var{hook}}, @w{char *@var{buffer}}, @w{size_t @var{count}}, @w{size_t *@var{nread}}), @w{void *@var{hook_value}})
+@deftypefun gpgme_error_t gpgme_data_new_with_read_cb (@w{gpgme_data_t *@var{dh}}, @w{int (*@var{readfunc})} (@w{void *@var{hook}}, @w{char *@var{buffer}}, @w{size_t @var{count}}, @w{size_t *@var{nread}}), @w{void *@var{hook_value}})
 The function @code{gpgme_data_new_with_read_cb} creates a new
-@code{GpgmeData} object and uses the callback function @var{readfunc}
+@code{gpgme_data_t} object and uses the callback function @var{readfunc}
 to retrieve the data on demand.  As the callback function can supply
 the data in any way it wants, this is the most flexible data type
 @acronym{GPGME} provides.  However, it can not be used to write data.
@@ -1099,10 +1683,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
 
 
@@ -1110,13 +1694,13 @@ not enough memory is available.
 @section Destroying Data Buffers
 @cindex data buffer, destruction
 
-@deftypefun void gpgme_data_release (@w{GpgmeData @var{dh}})
+@deftypefun void gpgme_data_release (@w{gpgme_data_t @var{dh}})
 The function @code{gpgme_data_release} destroys the data object with
 the handle @var{dh}.  It releases all associated resources that were
 not provided by the user in the first place.
 @end deftypefun
 
-@deftypefun {char *} gpgme_data_release_and_get_mem (@w{GpgmeData @var{dh}}, @w{size_t *@var{length}})
+@deftypefun {char *} gpgme_data_release_and_get_mem (@w{gpgme_data_t @var{dh}}, @w{size_t *@var{length}})
 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.
@@ -1134,19 +1718,18 @@ be returned to the user, the function will return @code{NULL}.
 @section Manipulating Data Buffers
 @cindex data buffere, manipulation
 
-@deftypefun ssize_t gpgme_data_read (@w{GpgmeData @var{dh}}, @w{void *@var{buffer}}, @w{size_t @var{length}})
+@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
 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
 
-@deftypefun ssize_t gpgme_data_write (@w{GpgmeData @var{dh}}, @w{const void *@var{buffer}}, @w{size_t @var{size}})
+@deftypefun ssize_t gpgme_data_write (@w{gpgme_data_t @var{dh}}, @w{const void *@var{buffer}}, @w{size_t @var{size}})
 The function @code{gpgme_data_write} writes up to @var{size} bytes
 starting from @var{buffer} into the data object with the handle
 @var{dh} at the current write position.
@@ -1155,12 +1738,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 (GpgmeData dh, off_t offset, int whence);
-
-@deftypefun off_t gpgme_data_seek (@w{GpgmeData @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.
 
@@ -1196,22 +1774,22 @@ If the function fails, -1 is returned and @var{errno} is set.
 The following function is deprecated and should not be used.  It will
 be removed in a future version of @acronym{GPGME}.
 
-@deftypefun GpgmeError gpgme_data_rewind (@w{GpgmeData @var{dh}})
+@deftypefun gpgme_error_t gpgme_data_rewind (@w{gpgme_data_t @var{dh}})
 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  GpgmeDataEncoding
+@c  gpgme_data_encoding_t
 @c
-@deftp {Data type} {enum GpgmeDataEncoding}
-@tindex GpgmeDataEncoding
-The @code{GpgmeDataEncoding} type specifies the encoding of a
-@code{GpgmeData} object.  This encoding is useful to give the backend
+@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:
 
 @table @code
@@ -1234,14 +1812,14 @@ OpenPGP and PEM.
 @end table
 @end deftp
 
-@deftypefun GpgmeDataEncoding gpgme_data_get_encoding (@w{GpgmeData @var{dh}})
+@deftypefun gpgme_data_encoding_t gpgme_data_get_encoding (@w{gpgme_data_t @var{dh}})
 The function @code{gpgme_data_get_encoding} returns the encoding of
 the data object with the handle @var{dh}.  If @var{dh} is not a valid
 pointer (e.g. @code{NULL}) @code{GPGME_DATA_ENCODING_NONE} is
 returned.
 @end deftypefun
 
-@deftypefun GpgmeError gpgme_data_set_encoding (@w{GpgmeData @var{dh}, GpgmeDataEncoding @var{enc}})
+@deftypefun gpgme_error_t gpgme_data_set_encoding (@w{gpgme_data_t @var{dh}, gpgme_data_encoding_t @var{enc}})
 The function @code{gpgme_data_set_encoding} changes the encoding of
 the data object with the handle @var{dh} to @var{enc}.
 @end deftypefun
@@ -1260,8 +1838,8 @@ configuration parameters.  By using several contexts you can run
 several cryptographic operations in parallel, with different
 configuration.
 
-@deftp {Data type} {GpgmeCtx}
-The @code{GpgmeCtx} type is a handle for a @acronym{GPGME} context,
+@deftp {Data type} {gpgme_ctx_t}
+The @code{gpgme_ctx_t} type is a handle for a @acronym{GPGME} context,
 which is used to hold the configuration, status and result of
 cryptographic operations.
 @end deftp
@@ -1281,14 +1859,14 @@ cryptographic operations.
 @section Creating Contexts
 @cindex context, creation
 
-@deftypefun GpgmeError gpgme_new (@w{GpgmeCtx *@var{ctx}})
-The function @code{gpgme_data_new} creates a new @code{GpgmeCtx}
-object and returns a handle for it in @var{ctx}.
+@deftypefun gpgme_error_t gpgme_new (@w{gpgme_ctx_t *@var{ctx}})
+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 @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 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.
 @end deftypefun
 
 
@@ -1296,7 +1874,7 @@ available.
 @section Destroying Contexts
 @cindex context, destruction
 
-@deftypefun void gpgme_release (@w{GpgmeCtx @var{ctx}})
+@deftypefun void gpgme_release (@w{gpgme_ctx_t @var{ctx}})
 The function @code{gpgme_release} destroys the context with the handle
 @var{ctx} and releases all associated resources.
 @end deftypefun
@@ -1308,12 +1886,14 @@ The function @code{gpgme_release} destroys the context with the handle
 
 @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
 
 
@@ -1322,7 +1902,7 @@ The function @code{gpgme_release} destroys the context with the handle
 @cindex context, selecting protocol
 @cindex protocol, selecting
 
-@deftypefun GpgmeError gpgme_set_protocol (@w{GpgmeCtx @var{ctx}}, @w{GpgmeProtocol @var{proto}})
+@deftypefun gpgme_error_t gpgme_set_protocol (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_protocol_t @var{proto}})
 The function @code{gpgme_set_protocol} sets the protocol used within
 the context @var{ctx} to @var{proto}.  All crypto operations will be
 performed by the crypto engine configured for that protocol.
@@ -1332,23 +1912,68 @@ 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 GpgmeProtocol gpgme_get_protocol (@w{GpgmeCtx @var{ctx}})
+@deftypefun gpgme_protocol_t gpgme_get_protocol (@w{gpgme_ctx_t @var{ctx}})
 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
 @cindex armor mode
 
-@deftypefun void gpgme_set_armor (@w{GpgmeCtx @var{ctx}}, @w{int @var{yes}})
+@deftypefun void gpgme_set_armor (@w{gpgme_ctx_t @var{ctx}}, @w{int @var{yes}})
 The function @code{gpgme_set_armor} specifies if the output should be
 @acronym{ASCII} armored.  By default, output is not @acronym{ASCII}
 armored.
@@ -1357,7 +1982,7 @@ armored.
 enabled otherwise.
 @end deftypefun
 
-@deftypefun int gpgme_get_armor (@w{GpgmeCtx @var{ctx}})
+@deftypefun int gpgme_get_armor (@w{gpgme_ctx_t @var{ctx}})
 The function @code{gpgme_get_armor} returns 1 if the output is
 @acronym{ASCII} armored, and @code{0} if it is not, or if @var{ctx} is
 not a valid pointer.
@@ -1370,7 +1995,7 @@ not a valid pointer.
 @cindex text mode
 @cindex canonical text mode
 
-@deftypefun void gpgme_set_textmode (@w{GpgmeCtx @var{ctx}}, @w{int @var{yes}})
+@deftypefun void gpgme_set_textmode (@w{gpgme_ctx_t @var{ctx}}, @w{int @var{yes}})
 The function @code{gpgme_set_textmode} specifies if canonical text mode
 should be used.  By default, text mode is not used.
 
@@ -1385,7 +2010,7 @@ Canonical text mode is disabled if @var{yes} is zero, and enabled
 otherwise.
 @end deftypefun
 
-@deftypefun int gpgme_get_textmode (@w{GpgmeCtx @var{ctx}})
+@deftypefun int gpgme_get_textmode (@w{gpgme_ctx_t @var{ctx}})
 The function @code{gpgme_get_textmode} returns 1 if canonical text
 mode is enabled, and @code{0} if it is not, or if @var{ctx} is not a
 valid pointer.
@@ -1396,13 +2021,16 @@ valid pointer.
 @subsection Included Certificates
 @cindex certificates, included
 
-@deftypefun void gpgme_set_include_certs (@w{GpgmeCtx @var{ctx}}, @w{int @var{nr_of_certs}})
+@deftypefun void gpgme_set_include_certs (@w{gpgme_ctx_t @var{ctx}}, @w{int @var{nr_of_certs}})
 The function @code{gpgme_set_include_certs} specifies how many
 certificates should be included in an S/MIME signed message.  By
 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
@@ -1418,11 +2046,11 @@ 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{GpgmeCtx @var{ctx}})
+@deftypefun int gpgme_get_include_certs (@w{gpgme_ctx_t @var{ctx}})
 The function @code{gpgme_get_include_certs} returns the number of
 certificates to include into an S/MIME signed message.
 @end deftypefun
@@ -1433,7 +2061,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{GpgmeCtx @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:
@@ -1446,10 +2074,22 @@ 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
+source 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.
+
+@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_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 usefule.  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
@@ -1461,13 +2101,13 @@ appropriate bits, and then using that calulcated value in the
 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{GpgmeCtx @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}
@@ -1484,23 +2124,35 @@ current mode otherwise.  Note that 0 is not a valid mode value.
 @cindex callback, passphrase
 @cindex passphrase callback
 
-@deftp {Data type} {const char *(*GpgmePassphraseCb)(void *@var{hook}, const char *@var{desc}, void **@var{r_hd})}
-@tindex GpgmePassphraseCb
-The @code{GpgmePassphraseCb} type is the type of functions usable as
+@deftp {Data type} {gpgme_error_t (*gpgme_passphrase_cb_t)(void *@var{hook}, const char *@var{uid_hint}, const char *@var{passphrase_info}, @w{int @var{prev_was_bad}}, @w{int @var{fd}})}
+@tindex gpgme_passphrase_cb_t
+The @code{gpgme_passphrase_cb_t} type is the type of functions usable as
 passphrase callback function.
 
-The string @var{desc} contains a text usable to be displayed to the
-user of the application.  The function should return a passphrase for
-the context when invoked with @var{desc} not being @code{NULL}.
+The argument @var{uid_hint} might contain a string that gives an
+indication for which user ID the passphrase is required.  If this is
+not available, or not applicable (in the case of symmetric encryption,
+for example), @var{uid_hint} will be @code{NULL}.
+
+The argument @var{passphrase_info}, if not @code{NULL}, will give
+further information about the context in which the passphrase is
+required.  This information is engine and operation specific.
 
-The user may store information about the resources associated with the
-returned passphrase in @var{*r_hd}.  When the passphrase is no longer
-needed by @acronym{GPGME}, the passphrase callback function will be
-called with @var{desc} being @var{NULL}, and @var{r_hd} being the same
-as at the first invocation.
+If this is the repeated attempt to get the passphrase, because
+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.
+
+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{GpgmeCtx @var{ctx}}, @w{GpgmePassphraseCb @var{passfunc}}, @w{void *@var{hook_value}})
+@deftypefun void gpgme_set_passphrase_cb (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_passphrase_cb_t @var{passfunc}}, @w{void *@var{hook_value}})
 The function @code{gpgme_set_passphrase_cb} sets the function that is
 used when a passphrase needs to be provided by the user to
 @var{passfunc}.  The function @var{passfunc} needs to implemented by
@@ -1511,14 +2163,16 @@ 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
 @code{NULL}.
 @end deftypefun
 
-@deftypefun void gpgme_get_passphrase_cb (@w{GpgmeCtx @var{ctx}}, @w{GpgmePassphraseCb *@var{passfunc}}, @w{void **@var{hook_value}})
+@deftypefun void gpgme_get_passphrase_cb (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_passphrase_cb_t *@var{passfunc}}, @w{void **@var{hook_value}})
 The function @code{gpgme_get_passphrase_cb} returns the function that
 is used when a passphrase needs to be provided by the user in
 @var{*passfunc}, and the first argument for this function in
@@ -1535,9 +2189,9 @@ the corresponding value will not be returned.
 @cindex callback, progress meter
 @cindex progress meter callback
 
-@deftp {Data type} {const char *(*GpgmeProgressCb)(void *@var{hook}, const char *@var{what}, int @var{type}, int @var{current}, int @var{total})}
-@tindex GpgmeProgressCb
-The @code{GpgmeProgressCb} type is the type of functions usable as
+@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.
 
 The arguments are specific to the crypto engine.  More information
@@ -1546,7 +2200,7 @@ found in the GnuPG source code in the file @file{doc/DETAILS} in the
 section PROGRESS.
 @end deftp
 
-@deftypefun void gpgme_set_progress_cb (@w{GpgmeCtx @var{ctx}}, @w{GpgmeProgressCb @var{progfunc}}, @w{void *@var{hook_value}})
+@deftypefun void gpgme_set_progress_cb (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_progress_cb_t @var{progfunc}}, @w{void *@var{hook_value}})
 The function @code{gpgme_set_progress_cb} sets the function that is
 used when progress information about a cryptographic operation is
 available.  The function @var{progfunc} needs to implemented by the
@@ -1562,7 +2216,7 @@ calling @code{gpgme_set_progress_cb} with @var{progfunc} being
 @code{NULL}.
 @end deftypefun
 
-@deftypefun void gpgme_get_progress_cb (@w{GpgmeCtx @var{ctx}}, @w{GpgmeProgressCb *@var{progfunc}}, @w{void **@var{hook_value}})
+@deftypefun void gpgme_get_progress_cb (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_progress_cb_t *@var{progfunc}}, @w{void **@var{hook_value}})
 The function @code{gpgme_get_progress_cb} returns the function that is
 used to inform the user about the progress made in @var{*progfunc},
 and the first argument for this function in @var{*hook_value}.  If no
@@ -1574,6 +2228,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
@@ -1583,65 +2274,308 @@ signers are specified.  This is always done by specifying the
 respective keys that should be used for the operation.  The following
 section describes how such keys can be selected and manipulated.
 
-@deftp {Data type} GpgmeKey
-The @code{GpgmeKey} type is a handle for a public or secret key, and
-is used to select the key for operations involving it.
+@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
+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.
 
-A key can contain several user IDs and sub keys.
-@end deftp
+The subkey structure has the following members:
 
-@menu
-* Listing Keys::                  Browsing the list of available keys.
-* Information About Keys::        Requesting detailed information about keys.
-* Key Signatures::                Listing the signatures on a key.
-* Manipulating Keys::             Operations on keys.
-* Generating Keys::               Creating new key pairs.
-* 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.
-@end menu
+@table @code
+@item gpgme_sub_key_t next
+This is a pointer to the next subkey structure in the linked list, or
+@code{NULL} if this is the last element.
 
+@item unsigned int revoked : 1
+This is true if the subkey is revoked.
 
-@node Listing Keys
-@subsection Listing Keys
-@cindex listing keys
-@cindex key listing
-@cindex key listing, start
-@cindex key ring, list
-@cindex key ring, search
+@item unsigned int expired : 1
+This is true if the subkey is expired.
 
-@deftypefun GpgmeError gpgme_op_keylist_start (@w{GpgmeCtx @var{ctx}}, @w{const char *@var{pattern}}, @w{int @var{secret_only}})
-The function @code{gpgme_op_keylist_start} initiates a key listing
-operation inside the context @var{ctx}.  It sets everything up so that
-subsequent invocations of @code{gpgme_op_keylist_next} return the keys
-in the list.
+@item unsigned int disabled : 1
+This is true if the subkey is disabled.
 
-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.
+@item unsigned int invalid : 1
+This is true if the subkey is invalid.
 
-If @var{secret_only} is not @code{0}, the list is restricted to secret
-keys only.
+@item unsigned int can_encrypt : 1
+This is true if the subkey can be used for encryption.
 
-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_end} is called to finish the operation.
+@item unsigned int can_sign : 1
+This is true if the subkey can be used to create data signatures.
 
-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.
-@end deftypefun
+@item unsigned int can_certify : 1
+This is true if the subkey can be used to create key certificates.
 
-@deftypefun GpgmeError gpgme_op_keylist_ext_start (@w{GpgmeCtx @var{ctx}}, @w{const char *@var{pattern}[]}, @w{int @var{secret_only}}, @w{int @var{reserved}})
-The function @code{gpgme_op_keylist_ext_start} initiates an extended
-key listing operation inside the context @var{ctx}.  It sets
-everything up so that subsequent invocations of
-@code{gpgme_op_keylist_next} return the keys in the list.
+@item unsigned int can_authenticate : 1
+This is true if the subkey can be used for authentication.
 
-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.
+@item unsigned int secret : 1
+This is true if the subkey is a secret key.
+
+@item gpgme_pubkey_algo_t pubkey_algo
+This is the public key algorithm supported by this subkey.
+
+@item unsigned int length
+This is the length of the subkey (in bits).
+
+@item char *keyid
+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.
+
+@item long int timestamp
+This is the creation timestamp of the subkey.  This is -1 if the
+timestamp is invalid, and 0 if it is not available.
+
+@item long int expires
+This is the expiration timestamp of the subkey, or 0 if the subkey
+does not expire.
+@end table
+@end deftp
+
+@deftp {Data type} gpgme_key_sig_t
+The @code{gpgme_key_sig_t} type is a pointer to a key signature structure.
+Key signatures are one component of a @code{gpgme_key_t} object, and
+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.
+
+The key signature structure has the following members:
+
+@table @code
+@item gpgme_key_sig_t next
+This is a pointer to the next key signature structure in the linked
+list, or @code{NULL} if this is the last element.
+
+@item unsigned int revoked : 1
+This is true if the key signature is a revocation signature.
+
+@item unsigned int expired : 1
+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 exportable : 1
+This is true if the key signature is exportable.
+
+@item gpgme_pubkey_algo_t pubkey_algo
+This is the public key algorithm used to create the signature.
+
+@item char *keyid
+This is the key ID of the key (in hexadecimal digits) used to create
+the signature.
+
+@item long int timestamp
+This is the creation timestamp of the key signature.  This is -1 if
+the timestamp is invalid, and 0 if it is not available.
+
+@item long int expires
+This is the expiration timestamp of the key signature, or 0 if the key
+signature does not expire.
+
+@item gpgme_error_t status
+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 sig_class
+This specifies the signature class of the key signature.  The meaning
+is specific to the crypto engine.
+
+@item char *uid
+This is the main user ID of the key used to create the signature.
+
+@item char *name
+This is the name component of @code{uid}, if available.
+
+@item char *comment
+This is the comment component of @code{uid}, if available.
+
+@item char *email
+This is the email component of @code{uid}, if available.
+@end table
+@end deftp
+
+@deftp {Data type} gpgme_user_id_t
+A user ID is a component of a @code{gpgme_key_t} object.  One key can
+have many user IDs.  The first one in the list is the main (or
+primary) user ID.
+
+The user ID structure has the following members.
+
+@table @code
+@item gpgme_user_id_t next
+This is a pointer to the next user ID structure in the linked list, or
+@code{NULL} if this is the last element.
+
+@item unsigned int revoked : 1
+This is true if the user ID is revoked.
+
+@item unsigned int invalid : 1
+This is true if the user ID is invalid.
+
+@item gpgme_validity_t validity
+This specifies the validity of the user ID.
+
+@item char *uid
+This is the user ID string.
+
+@item char *name
+This is the name component of @code{uid}, if available.
+
+@item char *comment
+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_key_sig_t signatures
+This is a linked list with the signatures on this user ID.
+@end table
+@end deftp
+
+@deftp {Data type} gpgme_key_t
+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.
+
+@item unsigned int expired : 1
+This is true if the key is expired.
+
+@item unsigned int disabled : 1
+This is true if the key is disabled.
+
+@item unsigned int invalid : 1
+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 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
+authentication.
+
+@item unsigned int secret : 1
+This is true if the key is a secret key.
+
+@item gpgme_protocol_t protocol
+This is the protocol supported by this key.
+
+@item char *issuer_serial
+If @code{protocol} is @code{GPGME_PROTOCOL_CMS}, then this is the
+issuer serial.
+
+@item char *issuer_name
+If @code{protocol} is @code{GPGME_PROTOCOL_CMS}, then this is the
+issuer name.
+
+@item char *chain_id
+If @code{protocol} is @code{GPGME_PROTOCOL_CMS}, then this is the
+chain ID, which can be used to built the certificate chain.
+@item gpgme_validity_t owner_trust
+If @code{protocol} is @code{GPGME_PROTOCOL_OpenPGP}, then this is the
+owner trust.
+
+@item gpgme_sub_key_t subkeys
+This is a linked list with the subkeys of the key.  The first subkey
+in the list is the primary key and usually available.
+
+@item gpgme_user_id_t uids
+This is a linked list with the user IDs of the key.  The first user ID
+in the list is the main (or primary) user ID.
+@end table
+@end deftp
+
+@menu
+* Listing Keys::                  Browsing the list of available keys.
+* Information About Keys::        Requesting detailed information about keys.
+* Key Signatures::                Listing the signatures on a key.
+* Manipulating Keys::             Operations on keys.
+* Generating Keys::               Creating new key pairs.
+* 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.
+@end menu
+
+
+@node Listing Keys
+@subsection Listing Keys
+@cindex listing keys
+@cindex key listing
+@cindex key listing, start
+@cindex key ring, list
+@cindex key ring, search
+
+@deftypefun gpgme_error_t gpgme_op_keylist_start (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{pattern}}, @w{int @var{secret_only}})
+The function @code{gpgme_op_keylist_start} initiates a key listing
+operation inside the context @var{ctx}.  It sets everything up so that
+subsequent invocations of @code{gpgme_op_keylist_next} return the keys
+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.  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{GPG_ERR_EOF}), or
+@code{gpgme_op_keylist_end} is called to finish the operation.
+
+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}})
+The function @code{gpgme_op_keylist_ext_start} initiates an extended
+key listing operation inside the context @var{ctx}.  It sets
+everything up so that subsequent invocations of
+@code{gpgme_op_keylist_next} return the keys in the list.
+
+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.  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.
@@ -1649,40 +2583,42 @@ 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 GpgmeError gpgme_op_keylist_next (@w{GpgmeCtx @var{ctx}}, @w{GpgmeKey *@var{r_key}})
+@deftypefun gpgme_error_t gpgme_op_keylist_next (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t *@var{r_key}})
 The function @code{gpgme_op_keylist_next} returns the next key in the
 list created by a previous @code{gpgme_op_keylist_start} operation in
 the context @var{ctx}.  The key will have one reference for the user.
 @xref{Manipulating Keys}.
 
-This is the only way to get at @code{GpgmeKey} objects in
+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, @code{GPGME_No_Request} if there
-is no pending operation, @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 GpgmeError gpgme_op_keylist_end (@w{GpgmeCtx @var{ctx}})
+@deftypefun gpgme_error_t gpgme_op_keylist_end (@w{gpgme_ctx_t @var{ctx}})
 The function @code{gpgme_op_keylist_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, @code{GPGME_No_Request} if there is no pending
-operation, @code{GPGME_Out_Of_Core} if at some time during the
-operation there was not enough memory available.
+After the operation completed successfully, the result of the key
+listing operation can be retrieved with
+@code{gpgme_op_keylist_result}.
+
+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
@@ -1690,23 +2626,23 @@ string (@code{g10code}) can be listed with their key ID and the name
 and e-mail address of the main user ID:
 
 @example
-GpgmeCtx ctx;
-GpgmeError err = gpgme_new (&ctx);
+gpgme_ctx_t ctx;
+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: %s <%s>\n", key->keyid, key->name, key->email);
         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));
@@ -1714,24 +2650,49 @@ if (err)
   @}
 @end example
 
+@deftp {Data type} {gpgme_keylist_result_t}
+This is a pointer to a structure used to store the result of a
+@code{gpgme_op_keylist_*} operation.  After successfully ending a key
+listing operation, you can retrieve the pointer to the result with
+@code{gpgme_op_keylist_result}.  The structure contains the following
+member:
+
+@table @code
+@item unsigned int truncated : 1
+This is true if the crypto backend had to truncate the result, and
+less than the desired keys could be listed.
+@end table
+@end deftp
+
+@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.
+@end deftypefun
+
 In a simple program, for which a blocking operation is acceptable, the
 following function can be used to retrieve a single key.
 
-@deftypefun GpgmeError gpgme_get_key (@w{GpgmeCtx @var{ctx}}, @w{const char *@var{fpr}}, @w{GpgmeKey *@var{r_key}}, @w{int @var{secret}}, @w{int @var{force_update}})
+@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 key cache or 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.
+(or key ID) @var{fpr} from the crypto backend and return it in
+@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 @code{GPGME_KEYLIST_MODE_SIGS} mode is active, the key will be
-retrieved with the key signatures (and updated if necessary).
+If the key is not found in the keyring, @code{gpgme_get_key} returns
+the error code @code{GPG_ERR_NO_ERROR} 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_Busy} if there is a
-pending operation, @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
 
 
@@ -1741,17 +2702,47 @@ the operation there was not enough memory available.
 @cindex key, attributes
 @cindex attributes, of a key
 
-@deftypefun {char *} gpgme_key_get_as_xml (@w{GpgmeKey @var{key}})
-The function @code{gpgme_key_get_as_xml} returns a string in
-@acronym{XML} format describing the key @var{key}.  The user has to
-release the string with @code{free}.
+Please see the beginning of this section for more information about
+@code{gpgme_key_t} objects.
 
-The function returns @code{NULL} if @var{key} is not a valid pointer,
-or there is not enough memory available.
-@end deftypefun
+@deftp {Data type} gpgme_validity_t
+The @code{gpgme_validity_t} type is used to specify the validity of a user ID
+in a key.  The following validities are defined:
 
-@deftp {Data type} GpgmeAttr
-The @code{GpgmeAttr} type is used to specify a key or trust item
+@table @code
+@item GPGME_VALIDITY_UNKNOWN
+The user ID is of unknown validity.  The string representation of this
+validity is ``?''.
+
+@item GPGME_VALIDITY_UNDEFINED
+The validity of the user ID is undefined.  The string representation of this
+validity is ``q''.
+
+@item GPGME_VALIDITY_NEVER
+The user ID is never valid.  The string representation of this
+validity is ``n''.
+
+@item GPGME_VALIDITY_MARGINAL
+The user ID is marginally valid.  The string representation of this
+validity is ``m''.
+
+@item GPGME_VALIDITY_FULL
+The user ID is fully valid.  The string representation of this
+validity is ``f''.
+
+@item GPGME_VALIDITY_ULTIMATE
+The user ID is ultimately valid.  The string representation of this
+validity is ``u''.
+@end table
+@end deftp
+
+
+The following interfaces are deprecated and only provided for backward
+compatibility.  Don't use them.  They will be removed in a future
+version of @acronym{GPGME}.
+
+@deftp {Data type} gpgme_attr_t
+The @code{gpgme_attr_t} type is used to specify a key or trust item
 attribute.  The following attributes are defined:
 
 @table @code
@@ -1786,7 +2777,7 @@ XXX FIXME  (also for trust items)
 
 @item GPGME_ATTR_USERID
 This is a user ID.  There can be more than one user IDs in a
-@var{GpgmeKey} object.  The first one (with index 0) is the primary
+@var{gpgme_key_t} object.  The first one (with index 0) is the primary
 user ID.  The user ID is representable as a number.
 
 For trust items, this is the user ID associated with this trust item.
@@ -1859,14 +2850,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
@@ -1882,38 +2873,7 @@ is representable as a string.
 @end table
 @end deftp
 
-@deftp {Data type} GpgmeValidity
-The @code{GpgmeValidity} type is used to specify the validity of a user ID
-in a key.  The following validities are defined:
-
-@table @code
-@item GPGME_VALIDITY_UNKNOWN
-The user ID is of unknown validity.  The string representation of this
-validity is ``?''.
-
-@item GPGME_VALIDITY_UNDEFINED
-The validity of the user ID is undefined.  The string representation of this
-validity is ``q''.
-
-@item GPGME_VALIDITY_NEVER
-The user ID is never valid.  The string representation of this
-validity is ``n''.
-
-@item GPGME_VALIDITY_MARGINAL
-The user ID is marginally valid.  The string representation of this
-validity is ``m''.
-
-@item GPGME_VALIDITY_FULL
-The user ID is fully valid.  The string representation of this
-validity is ``f''.
-
-@item GPGME_VALIDITY_ULTIMATE
-The user ID is ultimately valid.  The string representation of this
-validity is ``u''.
-@end table
-@end deftp
-
-@deftypefun {const char *} gpgme_key_get_string_attr (@w{GpgmeKey @var{key}}, @w{GpgmeAttr @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}})
+@deftypefun {const char *} gpgme_key_get_string_attr (@w{gpgme_key_t @var{key}}, @w{gpgme_attr_t @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}})
 The function @code{gpgme_key_get_string_attr} returns the value of the
 string-representable attribute @var{what} of key @var{key}.  If the
 attribute is an attribute of a sub key or an user ID, @var{idx}
@@ -1928,7 +2888,7 @@ string, @var{key} is not a valid pointer, @var{idx} out of range,
 or @var{reserved} not @code{NULL}.
 @end deftypefun
 
-@deftypefun {unsigned long} gpgme_key_get_ulong_attr (@w{GpgmeKey @var{key}}, @w{GpgmeAttr @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}})
+@deftypefun {unsigned long} gpgme_key_get_ulong_attr (@w{gpgme_key_t @var{key}}, @w{gpgme_attr_t @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}})
 The function @code{gpgme_key_get_ulong_attr} returns the value of the
 number-representable attribute @var{what} of key @var{key}.  If the
 attribute is an attribute of a sub key or an user ID, @var{idx}
@@ -1937,8 +2897,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
 
 
@@ -1947,6 +2907,10 @@ or @var{reserved} not @code{NULL}.
 @cindex key, signatures
 @cindex signatures, on a key
 
+The following interfaces are deprecated and only provided for backward
+compatibility.  Don't use them.  They will be removed in a future
+version of @acronym{GPGME}.
+
 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.
@@ -1956,8 +2920,8 @@ key, you have to make sure that the key was listed with signatures
 enabled.  One convenient, but blocking, way to do this is to use the
 function @code{gpgme_get_key}.
 
-@deftp {Data type} GpgmeAttr
-The @code{GpgmeAttr} type is used to specify a key signature
+@deftp {Data type} gpgme_attr_t
+The @code{gpgme_attr_t} type is used to specify a key signature
 attribute.  The following attributes are defined:
 
 @table @code
@@ -2018,7 +2982,7 @@ This is the same value as returned by @code{gpgme_get_sig_status}.
 @end table
 @end deftp
 
-@deftypefun {const char *} gpgme_key_sig_get_string_attr (@w{GpgmeKey @var{key}}, @w{int @var{uid_idx}}, @w{GpgmeAttr @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}})
+@deftypefun {const char *} gpgme_key_sig_get_string_attr (@w{gpgme_key_t @var{key}}, @w{int @var{uid_idx}}, @w{gpgme_attr_t @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}})
 The function @code{gpgme_key_sig_get_string_attr} returns the value of
 the string-representable attribute @var{what} of the signature
 @var{idx} on the user ID @var{uid_idx} in the key @var{key}.  The
@@ -2032,7 +2996,7 @@ string, @var{key} is not a valid pointer, @var{uid_idx} or @var{idx}
 out of range, or @var{reserved} not @code{NULL}.
 @end deftypefun
 
-@deftypefun {unsigned long} gpgme_key_sig_get_ulong_attr (@w{GpgmeKey @var{key}}, @w{int @var{uid_idx}}, @w{GpgmeAttr @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}})
+@deftypefun {unsigned long} gpgme_key_sig_get_ulong_attr (@w{gpgme_key_t @var{key}}, @w{int @var{uid_idx}}, @w{gpgme_attr_t @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}})
 The function @code{gpgme_key_sig_get_ulong_attr} returns the value of
 the number-representable attribute @var{what} of the signature
 @var{idx} on the user ID @var{uid_idx} in the key @var{key}.  The
@@ -2049,18 +3013,24 @@ out of range, or @var{reserved} not @code{NULL}.
 @subsection Manipulating Keys
 @cindex key, manipulation
 
-@deftypefun void gpgme_key_ref (@w{GpgmeKey @var{key}})
+@deftypefun void gpgme_key_ref (@w{gpgme_key_t @var{key}})
 The function @code{gpgme_key_ref} acquires an additional reference for
 the key @var{key}.
 @end deftypefun
 
-@deftypefun void gpgme_key_unref (@w{GpgmeKey @var{key}})
-@deftypefunx void gpgme_key_release (@w{GpgmeKey @var{key}})
-The function @code{gpgme_key_ref} releases a reference for the key
+@deftypefun void gpgme_key_unref (@w{gpgme_key_t @var{key}})
+The function @code{gpgme_key_unref} releases a reference for the key
 @var{key}.  If this was the last reference, the key will be destroyed
 and all resources associated to it will be released.
+@end deftypefun
+
 
-The function @code{gpgme_key_release} is an alias for
+The following interface is deprecated and only provided for backward
+compatibility.  Don't use it.  It will be removed in a future version
+of @acronym{GPGME}.
+
+@deftypefun void gpgme_key_release (@w{gpgme_key_t @var{key}})
+The function @code{gpgme_key_release} is equivalent to
 @code{gpgme_key_unref}.
 @end deftypefun
 
@@ -2070,24 +3040,21 @@ The function @code{gpgme_key_release} is an alias for
 @cindex key, creation
 @cindex key ring, add
 
-@deftypefun GpgmeError gpgme_op_genkey (@w{GpgmeCtx @var{ctx}}, @w{const char *@var{parms}}, @w{GpgmeData @var{pubkey}}, @w{GpgmeData @var{seckey}}, @w{char **@var{fpr}})
+@deftypefun gpgme_error_t gpgme_op_genkey (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{parms}}, @w{gpgme_data_t @var{public}}, @w{gpgme_data_t @var{secret}})
 The function @code{gpgme_op_genkey} generates a new key pair in the
-context @var{ctx} and puts it into the standard key ring if both
-@var{pubkey} and @var{seckey} are @code{NULL}.  In this case the
-function returns immediately after starting the operation, and does
-not wait for it to complete.  If @var{pubkey} is not @code{NULL} it
-should be the handle for an empty (newly created) data object, and
-upon successful completion the data object will contain the public
-key.  If @var{seckey} is not @code{NULL} it should be the handle for
-an empty (newly created) data object, and upon successful completion
-the data object will contain the secret key.
-
-Note that not all crypto engines support this interface equally.
-GnuPG does not support @var{pubkey} and @var{subkey}, they should be
-both @code{NULL}, and the key pair will be added to the standard key
-ring.  GpgSM does only support @var{pubkey}, the secret key will be
-stored by @command{gpg-agent}.  GpgSM expects @var{pubkey} being not
-@code{NULL}.
+context @var{ctx}.  The meaning of @var{public} and @var{secret}
+depends on the crypto backend.
+
+GnuPG does not support @var{public} and @var{secret}, they should be
+@code{NULL}.  GnuPG will generate a key pair and add it to the
+standard key ring.  The fingerprint of the generated key is available
+with @code{gpgme_op_genkey_result}.
+
+GpgSM requires @var{public} to be a writable data object.  GpgSM will
+generate a secret key (which will be stored by @command{gpg-agent},
+and return a certificate request in @var{public}, which then needs to
+be signed by the certification authority and imported before it can be
+used.  GpgSM does not make the fingerprint available.
 
 The argument @var{parms} specifies parameters for the key in an XML
 string.  The details about the format of @var{parms} are specific to
@@ -2109,6 +3076,7 @@ Passphrase: abc
 @end example
 
 Here is an example for GpgSM as the crypto engine:
+
 @example
 <GnupgKeyParms format="internal">
 Key-Type: RSA
@@ -2120,32 +3088,63 @@ Name-Email: joe@@foo.bar
 
 Strings should be given in UTF-8 encoding.  The only format supported
 for now is ``internal''.  The content of the @code{GnupgKeyParms}
-container is passed verbatim to GnuPG.  Control statements are not
-allowed.
+container is passed verbatim to the crypto backend.  Control
+statements are not allowed.
 
-If @var{fpr} is not a null pointer, the function succeeds, and the
-crypto engine supports it, *@var{fpr} will contain a string with the
-fingerprint of the key, allocated with @code{malloc}.  If both a
-primary and a sub key was generated, the fingerprint of the primary
-key will be returned.  If the crypto engine does not provide the
-fingerprint, *@var{fpr} will be a null pointer.
+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{pubkey} or
-@var{seckey} 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 GpgmeError gpgme_op_genkey_start (@w{GpgmeCtx @var{ctx}}, @w{const char *@var{parms}}, @w{GpgmeData @var{pubkey}}, @w{GpgmeData @var{seckey}})
+@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}})
 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{pubkey} or
-@var{seckey} 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}
+This is a pointer to a structure used to store the result of a
+@code{gpgme_op_genkey} operation.  After successfully generating a
+key, you can retrieve the pointer to the result with
+@code{gpgme_op_genkey_result}.  The structure contains the following
+members:
+
+@table @code
+@item unsigned int primary : 1
+This is a flag that is set to 1 if a primary key was created and to 0
+if not.
+
+@item unsigned int sub : 1
+This is a flag that is set to 1 if a subkey was created and to 0
+if not.
+
+@item char *fpr
+This is the fingerprint of the key that was created.  If both a
+primary and a sub key were generated, the fingerprint of the primary
+key will be returned.  If the crypto engine does not provide the
+fingerprint, @code{fpr} will be a null pointer.
+@end table
+@end deftp
+
+@deftypefun gpgme_genkey_result_t gpgme_op_genkey_result (@w{gpgme_ctx_t @var{ctx}})
+The function @code{gpgme_op_genkey_result} returns a
+@code{gpgme_genkey_result_t} pointer to a structure holding the result of
+a @code{gpgme_op_genkey} operation.  The pointer is only valid if the
+last operation on the context was a @code{gpgme_op_genkey} or
+@code{gpgme_op_genkey_start} operation, and if this operation finished
+successfully.  The returned pointer is only valid until the next
+operation is started on the context.
 @end deftypefun
 
 
@@ -2154,28 +3153,61 @@ a valid XML string, and @code{GPGME_Not_Supported} if @var{pubkey} or
 @cindex key, export
 @cindex key ring, export from
 
-@deftypefun GpgmeError gpgme_op_export (@w{GpgmeCtx @var{ctx}}, @w{GpgmeRecipients @var{recipients}}, @w{GpgmeData @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}.
+@deftypefun gpgme_error_t gpgme_op_export (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{pattern}}, @w{unsigned int @var{reserved}}, @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}.
+
+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{reserved} is reserved for future use and must be @code{0}.
 
-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.
+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 GpgmeError gpgme_op_export_start (@w{GpgmeCtx @var{ctx}}, @w{GpgmeRecipients @var{recipients}}, @w{GpgmeData @var{keydata}})
+@deftypefun gpgme_error_t gpgme_op_export_start (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{pattern}}, @w{unsigned int @var{reserved}}, @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{unsigned int @var{reserved}}, @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}.
+
+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{reserved} is reserved for future use and must be @code{0}.
+
+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{unsigned int @var{reserved}}, @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
 
 
@@ -2184,37 +3216,153 @@ data buffer.
 @cindex key, import
 @cindex key ring, import to
 
-@deftypefun GpgmeError gpgme_op_import (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{keydata}})
+@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.
 
-More information about the import is available with
-@code{gpgme_get_op_info}.  @xref{Detailed Results}.
+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 GpgmeError gpgme_op_import_start (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{keydata}})
+@deftypefun gpgme_error_t gpgme_op_import_start (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{keydata}})
 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 GpgmeError gpgme_op_import_ext (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{keydata}}, @w{int *@var{nr}})
-The function @code{gpgme_op_import_ext} is like
-@code{gpgme_op_import}, but also returns the number of processed keys
-in @var{nr}.  This is the same as the @code{count} information in the
-detailed results available with @code{gpgme_get_op_info}.
+@deftp {Data type} {gpgme_import_status_t}
+This is a pointer to a structure used to store a part of the result of
+a @code{gpgme_op_import} operation.  For each considered key one
+status is added that contains information about the result of the
+import.  The structure contains the following members:
+
+@table @code
+@item gpgme_import_status_t next
+This is a pointer to the next status structure in the linked list, or
+@code{NULL} if this is the last element.
+
+@item char *fpr
+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 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
+information about what part of the key was imported.  If the key was
+already known, this might be 0.
+
+@table @code
+@item GPGME_IMPORT_NEW
+The key was new.
+
+@item GPGME_IMPORT_UID
+The key contained new user IDs.
+
+@item GPGME_IMPORT_SIG
+The key contained new signatures.
+
+@item GPGME_IMPORT_SUBKEY
+The key contained new sub keys.
+
+@item GPGME_IMPORT_SECRET
+The key contained a secret key.
+@end table
+@end table
+@end deftp
+
+@deftp {Data type} {gpgme_import_result_t}
+This is a pointer to a structure used to store the result of a
+@code{gpgme_op_import} operation.  After a successful import
+operation, you can retrieve the pointer to the result with
+@code{gpgme_op_import_result}.  The structure contains the following
+members:
+
+@table @code
+@item int considered
+The total number of considered keys.
+
+@item int no_user_id
+The number of keys without user ID.
+
+@item int imported
+The total number of imported keys.
+
+@item imported_rsa
+The number of imported RSA keys.
+
+@item unchanged
+The number of unchanged keys.
+
+@item new_user_ids
+The number of new user IDs.
+
+@item new_sub_keys
+The number of new sub keys.
+
+@item new_signatures
+The number of new signatures.
+
+@item new_revocations
+The number of new revocations.
+
+@item secret_read
+The total number of secret keys read.
+
+@item secret_imported
+The number of imported secret keys.
+
+@item secret_unchanged
+The number of unchanged secret keys.
+
+@item not_imported
+The number of keys not imported.
+
+@item gpgme_import_status_t imports
+A list of gpgme_import_status_t objects which contain more information
+about the keys for which an import was attempted.
+@end table
+@end deftp
+
+@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_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.
+@end deftypefun
+
+The following interface is deprecated and only provided for backward
+compatibility.  Don't use it.  It will be removed in a future version
+of @acronym{GPGME}.
+
+@deftypefun gpgme_error_t gpgme_op_import_ext (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{keydata}}, @w{int *@var{nr}})
+The function @code{gpgme_op_import_ext} is equivalent to:
+
+@example
+  gpgme_error_t err = gpgme_op_import (ctx, keydata);
+  if (!err)
+    @{
+      gpgme_import_result_t result = gpgme_op_import_result (ctx);
+      *nr = result->considered;
+    @}
+@end example
 @end deftypefun
 
 
@@ -2223,27 +3371,29 @@ detailed results available with @code{gpgme_get_op_info}.
 @cindex key, delete
 @cindex key ring, delete from
 
-@deftypefun GpgmeError gpgme_op_delete (@w{GpgmeCtx @var{ctx}}, @w{const GpgmeKey @var{key}}, @w{int @var{allow_secret}})
+@deftypefun gpgme_error_t gpgme_op_delete (@w{gpgme_ctx_t @var{ctx}}, @w{const gpgme_key_t @var{key}}, @w{int @var{allow_secret}})
 The function @code{gpgme_op_delete} deletes the key @var{key} from the
 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, 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 GpgmeError gpgme_op_delete_start (@w{GpgmeCtx @var{ctx}}, @w{const GpgmeKey @var{key}}, @w{int @var{allow_secret}})
+@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}})
 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
 
 
@@ -2253,13 +3403,35 @@ started successfully, and @code{GPGME_Invalid_Value} if @var{ctx} or
 
 @strong{Caution:} The trust items interface is experimental.
 
-@deftp {Data type} GpgmeTrustItem
-The @code{GpgmeTrustItem} type is a handle for a trust item.
+@deftp {Data type} gpgme_trust_item_t
+The @code{gpgme_trust_item_t} type is a pointer to a trust item object.
+It has the following members:
+
+@table @code
+@item char *keyid
+This is a string describing the key to which this trust items belongs.
+
+@item int type
+This is the type of the trust item.  A value of 1 refers to a key, a
+value of 2 refers to a user ID.
+
+@item int level
+This is the trust level.
+
+@item char *owner_trust
+The owner trust if @code{type} is 1.
+
+@item char *validity
+The calculated validity.
+
+@item char *name
+The user name if @code{type} is 2.
+@end table
 @end deftp
 
 @menu
 * Listing Trust Items::           Browsing the list of available trust items.
-* Information About Trust Items:: Requesting detailed information about trust items.
+* Information About Trust Items:: Requesting information about trust items.
 * Manipulating Trust Items::      Operations on trust items.
 @end menu
 
@@ -2268,7 +3440,7 @@ The @code{GpgmeTrustItem} type is a handle for a trust item.
 @subsection Listing Trust Items
 @cindex trust item list
 
-@deftypefun GpgmeError gpgme_op_trustlist_start (@w{GpgmeCtx @var{ctx}}, @w{const char *@var{pattern}}, @w{int @var{max_level}})
+@deftypefun gpgme_error_t gpgme_op_trustlist_start (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{pattern}}, @w{int @var{max_level}})
 The function @code{gpgme_op_trustlist_start} initiates a trust item
 listing operation inside the context @var{ctx}.  It sets everything up
 so that subsequent invocations of @code{gpgme_op_trustlist_next} return
@@ -2281,40 +3453,38 @@ 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 GpgmeError gpgme_op_trustlist_next (@w{GpgmeCtx @var{ctx}}, @w{GpgmeTrustItem *@var{r_item}})
+@deftypefun gpgme_error_t gpgme_op_trustlist_next (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_trust_item_t *@var{r_item}})
 The function @code{gpgme_op_trustlist_next} returns the next trust
 item in the list created by a previous @code{gpgme_op_trustlist_start}
 operation in the context @var{ctx}.  The trust item can be destroyed
 with @code{gpgme_trust_item_release}.  @xref{Manipulating Trust Items}.
 
-This is the only way to get at @code{GpgmeTrustItem} objects in
+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, @code{GPGME_No_Request} if there
-is no pending operation, @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_item} is not a valid pointer, and @code{GPG_ERR_ENOMEM} if
+there is not enough memory for the operation.
 @end deftypefun
 
-@deftypefun GpgmeError gpgme_op_trustlist_end (@w{GpgmeCtx @var{ctx}})
+@deftypefun gpgme_error_t gpgme_op_trustlist_end (@w{gpgme_ctx_t @var{ctx}})
 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, @code{GPGME_No_Request} if there is no pending
-operation, @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
 
 
@@ -2324,102 +3494,412 @@ operation there was not enough memory available.
 @cindex trust item, attributes
 @cindex attributes, of a trust item
 
+The following interfaces are deprecated and only provided for backward
+compatibility.  Don't use them.  They will be removed in a future
+version of @acronym{GPGME}.
+
 Trust items have attributes which can be queried using the interfaces
 below.  The attribute identifiers are shared with those for key
 attributes.  @xref{Information About Keys}.
 
-@deftypefun {const char *} gpgme_trust_item_get_string_attr (@w{GpgmeTrustItem @var{item}}, @w{GpgmeAttr @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}})
-The function @code{gpgme_trust_item_get_string_attr} returns the value
-of the string-representable attribute @var{what} of trust item
-@var{item}.  The arguments @var{idx} and @var{reserved} are reserved
-for later use and should be @code{0} and @code{NULL} respectively.
+@deftypefun {const char *} gpgme_trust_item_get_string_attr (@w{gpgme_trust_item_t @var{item}}, @w{gpgme_attr_t @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}})
+The function @code{gpgme_trust_item_get_string_attr} returns the value
+of the string-representable attribute @var{what} of trust item
+@var{item}.  The arguments @var{idx} and @var{reserved} are reserved
+for later use and should be @code{0} and @code{NULL} respectively.
+
+The string returned is only valid as long as the key is valid.
+
+The function returns @code{0} if an attribute can't be returned as a
+string, @var{key} is not a valid pointer, @var{idx} out of range,
+or @var{reserved} not @code{NULL}.
+@end deftypefun
+
+@deftypefun int gpgme_trust_item_get_int_attr (@w{gpgme_trust_item_t @var{item}}, @w{gpgme_attr_t @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}})
+The function @code{gpgme_trust_item_get_int_attr} returns the value of
+the number-representable attribute @var{what} of trust item
+@var{item}.  If the attribute occurs more than once in the trust item,
+the index is specified by @var{idx}.  However, currently no such
+attribute exists, so @var{idx} should be @code{0}.  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}.
+@end deftypefun
+
+
+@node Manipulating Trust Items
+@subsection Manipulating Trust Items
+@cindex trust item, manipulation
+
+@deftypefun void gpgme_trust_item_ref (@w{gpgme_trust_item_t @var{item}})
+The function @code{gpgme_trust_item_ref} acquires an additional
+reference for the trust item @var{item}.
+@end deftypefun
+
+@deftypefun void gpgme_trust_item_unref (@w{gpgme_trust_item_t @var{item}})
+The function @code{gpgme_trust_item_unref} releases a reference for
+the trust item @var{item}.  If this was the last reference, the trust
+item will be destroyed and all resources associated to it will be
+released.
+@end deftypefun
+
+
+The following interface is deprecated and only provided for backward
+compatibility.  Don't use it.  It will be removed in a future version
+of @acronym{GPGME}.
+
+@deftypefun void gpgme_trust_item_release (@w{gpgme_trust_item_t @var{item}})
+The function @code{gpgme_trust_item_release} is an alias for
+@code{gpgme_trust_item_unref}.
+@end deftypefun
+
+
+@node Crypto Operations
+@section Crypto Operations
+@cindex cryptographic operation
+
+Sometimes, the result of a crypto operation returns a list of invalid
+keys encountered in processing the request.  The following structure
+is used to hold information about such a key.
+
+@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_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 *fpr
+The fingerprint or key ID of the invalid key encountered.
+
+@item gpgme_error_t reason
+An error code describing the reason why the key was found invalid.
+@end table
+@end deftp
+
+
+@menu
+* Decrypt::                       Decrypting a ciphertext.
+* Verify::                        Verifying a signature.
+* Decrypt and Verify::            Decrypting a signed ciphertext.
+* Sign::                          Creating a signature.
+* Encrypt::                       Encrypting a plaintext.
+@end menu
+
+
+@node Decrypt
+@subsection Decrypt
+@cindex decryption
+@cindex cryptographic operation, decryption
+
+@deftypefun gpgme_error_t gpgme_op_decrypt (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{cipher}}, @w{gpgme_data_t @var{plain}})
+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 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
+
+@deftypefun gpgme_error_t gpgme_op_decrypt_start (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{cipher}}, @w{gpgme_data_t @var{plain}})
+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 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 decrypting
+data, you can retrieve the pointer to the result with
+@code{gpgme_op_decrypt_result}.  The structure contains the following
+members:
+
+@table @code
+@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.
+@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.
+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
+
+
+@node Verify
+@subsection Verify
+@cindex verification
+@cindex signature, verification
+@cindex cryptographic operation, verification
+@cindex cryptographic operation, signature check
+
+@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
+data object @var{sig} is a valid signature.  If @var{sig} is a
+detached signature, then the signed text should be provided in
+@var{signed_text} and @var{plain} should be a null pointer.
+Otherwise, if @var{sig} is a normal (or cleartext) signature,
+@var{signed_text} should be a null pointer and @var{plain} should be a
+writable data object that will contain the plaintext after successful
+verification.
+
+The results of the individual signature verifications can be retrieved
+with @code{gpgme_op_verify_result}.
+
+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}})
+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 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}
+This is a pointer to a structure used to store a part of the result of
+a @code{gpgme_op_verify} operation.  The structure contains the
+following members:
+
+@table @code
+@item gpgme_sig_notation_t next
+This is a pointer to the next new signature notation structure in the
+linked list, or @code{NULL} if this is the last element.
+
+@item char *name
+The name of the notation field.  If this is @code{NULL}, then the
+member @code{value} will contain a policy URL.
+
+@item char *value
+The value of the notation field.  If @code{name} is @code{NULL}, then
+this is a policy URL.
+@end table
+@end deftp
+
+@deftp {Data type} {gpgme_signature_t}
+This is a pointer to a structure used to store a part of the result of
+a @code{gpgme_op_verify} operation.  The structure contains the
+following members:
+
+@table @code
+@item gpgme_signature_t next
+This is a pointer to the next new signature structure in the linked
+list, or @code{NULL} if this is the last element.
+
+@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
+signature is valid without any restrictions.
+
+The defined bits are:
+  @table @code
+  @item GPGME_SIGSUM_VALID
+  The signature is fully valid.
+
+  @item GPGME_SIGSUM_GREEN
+  The signature is good but one might want to display some extra
+  information.  Check the other bits.
+
+  @item GPGME_SIGSUM_RED
+  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.
+
+  @item GPGME_SIGSUM_KEY_REVOKED
+  The key or at least one certificate has been revoked.
+
+  @item GPGME_SIGSUM_KEY_EXPIRED
+  The key or one of the certificates has expired. It is probably a good
+  idea to display the date of the expiration.
+
+  @item GPGME_SIGSUM_SIG_EXPIRED
+  The signature has expired.
+
+  @item GPGME_SIGSUM_KEY_MISSING
+  Can't verify due to a missing key or certificate.
+
+  @item GPGME_SIGSUM_CRL_MISSING
+  The CRL (or an equivalent mechanism) is not available. 
+
+  @item GPGME_SIGSUM_CRL_TOO_OLD
+  Available CRL is too old.
 
-The string returned is only valid as long as the key is valid.
+  @item GPGME_SIGSUM_BAD_POLICY
+  A policy requirement was not met. 
 
-The function returns @code{0} if an attribute can't be returned as a
-string, @var{key} is not a valid pointer, @var{idx} out of range,
-or @var{reserved} not @code{NULL}.
-@end deftypefun
+  @item GPGME_SIGSUM_SYS_ERROR
+  A system error occured. 
+  @end table
 
-@deftypefun int gpgme_trust_item_get_int_attr (@w{GpgmeTrustItem @var{item}}, @w{GpgmeAttr @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}})
-The function @code{gpgme_trust_item_get_int_attr} returns the value of
-the number-representable attribute @var{what} of trust item
-@var{item}.  If the attribute occurs more than once in the trust item,
-the index is specified by @var{idx}.  However, currently no such
-attribute exists, so @var{idx} should be @code{0}.  The argument
-@var{reserved} is reserved for later use and should be @code{NULL}.
+@item char *fpr
+This is the fingerprint or key ID of the signature.
 
-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}.
-@end deftypefun
+@item gpgme_error_t status
+This is the status of the signature.  In particular, the following
+status codes are of interest:
 
+  @table @code
+  @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 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 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 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 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 GPG_ERR_GENERAL
+  This status indicates that there was some other error which prevented
+  the signature verification.
+  @end table
 
-@node Manipulating Trust Items
-@subsection Manipulating Trust Items
-@cindex trust item, manipulation
+@item gpgme_sig_notation_t notations
+This is a linked list with the notation data and policy URLs.
 
-@deftypefun void gpgme_trust_item_release (@w{GpgmeTrustItem @var{item}})
-The function @code{gpgme_trust_item_release} destroys a
-@code{GpgmeTrustItem} object and releases all associated resources.
-@end deftypefun
+@item unsigned long timestamp
+The creation timestamp of this signature.
 
-@node Crypto Operations
-@section Crypto Operations
-@cindex cryptographic operation
+@item unsigned long exp_timestamp
+The expiration timestamp of this signature, or 0 if the signature does
+not expire.
 
-@menu
-* Decrypt::                       Decrypting a ciphertext.
-* Verify::                        Verifying a signature.
-* Decrypt and Verify::            Decrypting a signed ciphertext.
-* Sign::                          Creating a signature.
-* Encrypt::                       Encrypting a plaintext.
-* Detailed Results::              How to obtain more info about the operation.
-@end menu
+@item unsigned int wrong_key_usage : 1
+This is true if the key was not used according to its policy.
 
+@item gpgme_validity_t validity
+The validity of the signature.
 
-@node Decrypt
-@subsection Decrypt
-@cindex decryption
-@cindex cryptographic operation, decryption
+@item gpgme_error_t validity_reason
+If a signature is not valid, this provides a reason why.
 
-@deftypefun GpgmeError gpgme_op_decrypt (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{cipher}}, @w{GpgmeData @var{plain}})
-The function @code{gpgme_op_decrypt} decrypts the ciphertext in the
-data object @var{cipher} and stores it into the data object
-@var{plain}.
+@end table
+@end deftp
 
-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_No_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
+@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 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:
 
-@deftypefun GpgmeError gpgme_op_decrypt_start (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{cipher}}, @w{GpgmeData @var{plain}})
-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}.
+@table @code
+@item gpgme_signature_t signatures
+A linked list with information about all signatures for which a
+verification was attempted.
+@end table
+@end deftp
 
-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.
+@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},
+@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
 
 
-@node Verify
-@subsection Verify
-@cindex verification
-@cindex signature, verification
-@cindex cryptographic operation, verification
-@cindex cryptographic operation, signature check
-@cindex signature, status
+The following interfaces are deprecated and only provided for backward
+compatibility.  Don't use them.  They will be removed in a future
+version of @acronym{GPGME}.
 
-@deftp {Data type} {enum GpgmeSigStat}
-@tindex GpgmeSigStat
-The @code{GpgmeSigStat} type holds the result of a signature check, or
+@deftp {Data type} {enum gpgme_sig_stat_t}
+@tindex gpgme_sig_stat_t
+The @code{gpgme_sig_stat_t} type holds the result of a signature check, or
 the combined result of all signatures.  The following results are
 possible:
 
@@ -2465,188 +3945,183 @@ have a different status.  You can get each key's status with
 @end table
 @end deftp
 
+@deftypefun {const char *} gpgme_get_sig_status (@w{gpgme_ctx_t @var{ctx}}, @w{int @var{idx}}, @w{gpgme_sig_stat_t *@var{r_stat}}, @w{time_t *@var{r_created}})
+The function @code{gpgme_get_sig_status} is equivalent to:
+@example
+  gpgme_verify_result_t result;
+  gpgme_signature_t sig;
 
-@deftypefun GpgmeError gpgme_op_verify (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{sig}}, @w{GpgmeData @var{signed_text}}, @w{GpgmeData @var{plain}})
-The function @code{gpgme_op_verify} verifies that the signature in the
-data object @var{sig} is a valid signature.  If @var{sig} is a
-detached signature, then the signed text should be provided in
-@var{signed_text} and @var{plain} should be a null pointer.
-Otherwise, if @var{sig} is a normal (or cleartext) signature,
-@var{signed_text} should be a null pointer and @var{plain} should be a
-writable data object that will contain the plaintext after successful
-verification.
-
-The results of the individual signature verifications can be retrieved
-with @code{gpgme_get_sig_status} and @code{gpgme_get_sig_key}.
-
-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.
-@end deftypefun
+  result = gpgme_op_verify_result (ctx);
+  sig = result->signatures;
 
-@deftypefun GpgmeError gpgme_op_verify_start (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{sig}}, @w{GpgmeData @var{signed_text}}, @w{GpgmeData @var{plain}})
-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}.
+  while (sig && idx)
+    @{
+      sig = sig->next;
+      idx--;
+    @}
+  if (!sig || idx)
+    return NULL;
 
-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.
+  if (r_stat)
+    @{
+      switch (gpg_err_code (sig->status))
+       @{
+       case GPG_ERR_NO_ERROR:
+         *r_stat = GPGME_SIG_STAT_GOOD;
+         break;
+         
+       case GPG_ERR_BAD_SIGNATURE:
+         *r_stat = GPGME_SIG_STAT_BAD;
+         break;
+         
+       case GPG_ERR_NO_PUBKEY:
+         *r_stat = GPGME_SIG_STAT_NOKEY;
+         break;
+         
+       case GPG_ERR_NO_DATA:
+         *r_stat = GPGME_SIG_STAT_NOSIG;
+         break;
+         
+       case GPG_ERR_SIG_EXPIRED:
+         *r_stat = GPGME_SIG_STAT_GOOD_EXP;
+         break;
+         
+       case GPG_ERR_KEY_EXPIRED:
+         *r_stat = GPGME_SIG_STAT_GOOD_EXPKEY;
+         break;
+         
+       default:
+         *r_stat = GPGME_SIG_STAT_ERROR;
+         break;
+       @}
+    @}
+  if (r_created)
+    *r_created = sig->timestamp;
+  return sig->fpr;
+@end example
 @end deftypefun
 
-@deftypefun {const char *} gpgme_get_sig_status (@w{GpgmeCtx @var{ctx}}, @w{int @var{idx}}, @w{GpgmeSigStat *@var{r_stat}}, @w{time_t *@var{r_created}})
-The function @code{gpgme_get_sig_status} receives information about a
-signature after the @code{gpgme_op_verify} or
-@code{gpgme_op_verify_decrypt} operation.  A single detached signature
-can contain signatures by more than one key.  The @var{idx} specifies
-which signature's information should be retrieved, starting from
-@var{0}.
-
-The status of the signature will be returned in @var{r_stat} if it is
-not @code{NULL}.  The creation time stamp of the signature will be
-returned in @var{r_created} if it is not @var{NULL}.
-
-The function returns a statically allocated string that contains the
-fingerprint of the key which signed the plaintext, or @code{NULL} if
-@var{ctx} is not a valid pointer, the operation is still pending, or
-no verification could be performed.
-@end deftypefun
+@deftypefun {const char *} gpgme_get_sig_string_attr (@w{gpgme_ctx_t @var{ctx}}, @w{int @var{idx}}, @w{gpgme_attr_t @var{what}}, @w{int @var{whatidx}})
+The function @code{gpgme_get_sig_string_attr} is equivalent to:
+@example
+  gpgme_verify_result_t result;
+  gpgme_signature_t sig;
 
-@deftypefun {const char *} gpgme_get_sig_string_attr (@w{GpgmeCtx @var{ctx}}, @w{int @var{idx}}, @w{GpgmeAttr @var{what}}, @w{int @var{whatidx}})
-This function is similar to @code{gpgme_get_sig_status} but may be used
-to retrieve more detailed information.  @var{ctx} should be the context
-used for the last signature verification, @var{idx} is used to enumerate
-over all signatures starting with @code{0} and @var{whatidx} should be
-@code{0} unless otherwise stated.
+  result = gpgme_op_verify_result (ctx);
+  sig = result->signatures;
 
-The following values may be used for @var{what}:
-@table @code
-@item GPGME_ATTR_FPR
-Return the fingerprint of the key used to create the signature.
+  while (sig && idx)
+    @{
+      sig = sig->next;
+      idx--;
+    @}
+  if (!sig || idx)
+    return NULL;
 
-@item GPGME_ATTR_ERRTOK
-Return a token with a more detailed error description.  A @var{whatidx}
-of @code{0} returns an error token associated with validity calculation,
-a value of @code{1} return an error token related to the certificate
-checking.
+  switch (what)
+    @{
+    case GPGME_ATTR_FPR:
+      return sig->fpr;
+
+    case GPGME_ATTR_ERRTOK:
+      if (whatidx == 1)
+        return sig->wrong_key_usage ? "Wrong_Key_Usage" : "";
+      else
+       return "";
+    default:
+      break;
+    @}
 
-@end table
+  return NULL;
+@end example
 @end deftypefun
 
-@deftypefun {const char *} gpgme_get_sig_ulong_attr (@w{GpgmeCtx @var{ctx}}, @w{int @var{idx}}, @w{GpgmeAttr @var{waht}}, @w{int @var{whatidx}})
-This function is similar to @code{gpgme_get_sig_string_attr} but used
-for attributes which can be represented by an @code{unsigned long} data
-type.  @var{ctx} should be the context used for the last signature
-verification, @var{idx} is used to enumerate over all signatures
-starting with @code{0} and @var{whatidx} should be @code{0} unless
-otherwise stated.
-
-The following values may be used for @var{what}:
-@table @code
-@item GPGME_ATTR_CREATED
-Return the creation time of the signature in seconds since Epoch.  This
-is the same value as returned by @code{gpgme_get_sig_status}.
-
-@item GPGME_ATTR_EXPIRE
-Return the expiration time of the signature in seconds since Epoch. 
-
-@item GPGME_ATTR_VALIDITY
-Returns the validity of the key used to create the signature.  This is a
-shortcut function which avoids an extra key lookup.  The value returned
-is one of @code{GPGME_VALIDITY_UNKNOWN}, @code{GPGME_VALIDITY_NEVER},
-@code{GPGME_VALIDITY_MARGINAL} or @code{GPGME_VALIDITY_FULL}.
-
-@item GPGME_ATTR_SIG_STATUS
-This is the same value as returned by @code{gpgme_get_sig_status}.
-
-@item GPGME_ATTR_SIG_SUMMARY
-This returns a bit vector giving a summary of the signature status.
-Itprovides an easy interface to a defined semantic of the signature
-status.  Checking just one bit is sufficient to see whether a signature
-is valid without any restrictions.
-
-The defined bits are:
-  @table @code
-  @item GPGME_SIGSUM_VALID
-  The signature is fully valid.
-
-  @item GPGME_SIGSUM_GREEN
-  The signature is good but one might want to display some extra
-  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
-  signature invalid when the message was received prior to the cause for
-  the revocation.
-
-  @item GPGME_SIGSUM_KEY_REVOKED
-  The key or at least one certificate has been revoked.
-
-  @item GPGME_SIGSUM_KEY_EXPIRED
-  The key or one of the certificates has expired. It is probably a good
-  idea to display the date of the expiration.
+@deftypefun {const char *} gpgme_get_sig_ulong_attr (@w{gpgme_ctx_t @var{ctx}}, @w{int @var{idx}}, @w{gpgme_attr_t @var{waht}}, @w{int @var{whatidx}})
+The function @code{gpgme_get_sig_ulong_attr} is equivalent to:
+@example
+  gpgme_verify_result_t result;
+  gpgme_signature_t sig;
 
-  @item GPGME_SIGSUM_SIG_EXPIRED
-  The signature has expired.
+  result = gpgme_op_verify_result (ctx);
+  sig = result->signatures;
 
-  @item GPGME_SIGSUM_KEY_MISSING
-  Can't verifydue to a missing key o certificate.
+  while (sig && idx)
+    @{
+      sig = sig->next;
+      idx--;
+    @}
+  if (!sig || idx)
+    return 0;
 
-  @item GPGME_SIGSUM_CRL_MISSING
-  The CRL (or an equivalent mechanism) is not available. 
+  switch (what)
+    @{
+    case GPGME_ATTR_CREATED:
+      return sig->timestamp;
 
-  @item GPGME_SIGSUM_CRL_TOO_OLD
-  Available CRL is too old.
+    case GPGME_ATTR_EXPIRE:
+      return sig->exp_timestamp;
 
-  @item GPGME_SIGSUM_BAD_POLICY
-  A policy requirement was not met. 
+    case GPGME_ATTR_VALIDITY:
+      return (unsigned long) sig->validity;
 
-  @item GPGME_SIGSUM_SYS_ERROR
-  A system error occured. 
+    case GPGME_ATTR_SIG_STATUS:
+      switch (sig->status)
+       @{
+       case GPG_ERR_NO_ERROR:
+         return GPGME_SIG_STAT_GOOD;
+         
+       case GPG_ERR_BAD_SIGNATURE:
+         return GPGME_SIG_STAT_BAD;
+         
+       case GPG_ERR_NO_PUBKEY:
+         return GPGME_SIG_STAT_NOKEY;
+         
+       case GPG_ERR_NO_DATA:
+         return GPGME_SIG_STAT_NOSIG;
+         
+       case GPG_ERR_SIG_EXPIRED:
+         return GPGME_SIG_STAT_GOOD_EXP;
+         
+       case GPG_ERR_KEY_EXPIRED:
+         return GPGME_SIG_STAT_GOOD_EXPKEY;
+         
+       default:
+         return GPGME_SIG_STAT_ERROR;
+       @}
 
-  @end table
+    case GPGME_ATTR_SIG_SUMMARY:
+      return sig->summary;
 
-@end table
+    default:
+      break;
+    @}
+  return 0;
+@end example
 @end deftypefun
 
+@deftypefun {const char *} gpgme_get_sig_key (@w{gpgme_ctx_t @var{ctx}}, @w{int @var{idx}}, @w{gpgme_key_t *@var{r_key}})
+The function @code{gpgme_get_sig_key} is equivalent to:
 
-@deftypefun {const char *} gpgme_get_sig_key (@w{GpgmeCtx @var{ctx}}, @w{int @var{idx}}, @w{GpgmeKey *@var{r_key}})
-The function @code{gpgme_get_sig_status} receives a @code{GpgmeKey}
-object for the key which was used to verify the signature after the
-@code{gpgme_op_verify} or @code{gpgme_op_verify_decrypt} operation.  A
-single detached signature can contain signatures by more than one key.
-The @var{idx} specifies which signature's information should be
-retrieved, starting from @var{0}.  The key will have on reference for
-the user.
-
-The function is a convenient way to retrieve the keys belonging to the
-fingerprints returned by @code{gpgme_get_sig_status}.
-
-The function returns @code{GPGME_No_Error} if the key could be
-returned, @code{GPGME_Invalid_Value} if @var{r_key} is not a valid
-pointer, @code{GPGME_Invalid_Key} if the fingerprint is not valid,
-@code{GPGME_EOF} if @var{idx} is too large, or some other error value
-if a problem occurred requesting the key.
-@end deftypefun
+@example
+  gpgme_verify_result_t result;
+  gpgme_signature_t sig;
 
-@deftypefun {char *} gpgme_get_notation (@w{GpgmeCtx @var{ctx}})
-The function @code{gpgme_get_notation} can be used to retrieve
-notation data from the last signature check in the context @var{ctx}.
+  result = gpgme_op_verify_result (ctx);
+  sig = result->signatures;
 
-If there is notation data available from the last signature check,
-this function may be used to return this notation data as a string.
-The string is an XML representation of that data embedded in a
-<notation> container.  The user has to release the string with
-@code{free}.
+  while (sig && idx)
+    @{
+      sig = sig->next;
+      idx--;
+    @}
+  if (!sig || idx)
+    return gpg_error (GPG_ERR_EOF);
 
-The function returns a string if the notation data is available or
-@code{NULL} if there is no such data available.
+  return gpgme_get_key (ctx, sig->fpr, r_key, 0);
+@end example
 @end deftypefun
 
 
@@ -2657,37 +4132,42 @@ The function returns a string if the notation data is available or
 @cindex signature check
 @cindex cryptographic operation, decryption and verification
 
-@deftypefun GpgmeError gpgme_op_decrypt_verify (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{cipher}}, @w{GpgmeData @var{plain}})
+@deftypefun gpgme_error_t gpgme_op_decrypt_verify (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{cipher}}, @w{gpgme_data_t @var{plain}})
 The function @code{gpgme_op_decrypt_verify} decrypts the ciphertext in
 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_No_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
 
-@deftypefun GpgmeError gpgme_op_decrypt_verify (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{cipher}}, @w{GpgmeData @var{plain}})
+@deftypefun gpgme_error_t gpgme_op_decrypt_verify (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{cipher}}, @w{gpgme_data_t @var{plain}})
 The function @code{gpgme_op_decrypt_verify_start} initiates a
 @code{gpgme_op_decrypt_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{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
 
 
@@ -2713,7 +4193,7 @@ set is changed).
 @cindex signature, selecting signers
 @cindex signers, selecting
 
-@deftypefun void gpgme_signers_clear (@w{GpgmeCtx @var{ctx}})
+@deftypefun void gpgme_signers_clear (@w{gpgme_ctx_t @var{ctx}})
 The function @code{gpgme_signers_clear} releases a reference for each
 key on the signers list and removes the list of signers from the
 context @var{ctx}.
@@ -2721,14 +4201,14 @@ context @var{ctx}.
 Every context starts with an empty list.
 @end deftypefun
 
-@deftypefun GpgmeError gpgme_signers_add (@w{GpgmeCtx @var{ctx}}, @w{const GpgmeKey @var{key}})
+@deftypefun gpgme_error_t gpgme_signers_add (@w{gpgme_ctx_t @var{ctx}}, @w{const gpgme_key_t @var{key}})
 The function @code{gpgme_signers_add} adds the key @var{key} to the
 list of signers in the context @var{ctx}.
 
 Calling this function acquires an additional reference for the key.
 @end deftypefun
 
-@deftypefun GpgmeKey gpgme_signers_enum (@w{const GpgmeCtx @var{ctx}}, @w{int @var{seq}})
+@deftypefun gpgme_key_t gpgme_signers_enum (@w{const gpgme_ctx_t @var{ctx}}, @w{int @var{seq}})
 The function @code{gpgme_signers_enum} returns the @var{seq}th key in
 the list of signers in the context @var{ctx}.  An additional reference
 is acquired for the user.
@@ -2740,9 +4220,9 @@ If @var{seq} is out of range, @code{NULL} is returned.
 @node Creating a Signature
 @subsubsection Creating a Signature
 
-@deftp {Data type} {enum GpgmeSigMode}
-@tindex GpgmeSigMode
-The @code{GpgmeSigMode} type is used to specify the desired type of a
+@deftp {Data type} {enum gpgme_sig_mode_t}
+@tindex gpgme_sig_mode_t
+The @code{gpgme_sig_mode_t} type is used to specify the desired type of a
 signature.  The following modes are available:
 
 @table @code
@@ -2759,151 +4239,146 @@ mode settings of the context are ignored.
 @end table
 @end deftp
 
-@deftypefun GpgmeError gpgme_op_sign (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{plain}}, @w{GpgmeData @var{sig}}, @w{GpgmeSigMode @var{mode}})
+@deftypefun gpgme_error_t gpgme_op_sign (@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}})
 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
 @var{ctx} and the requested signature mode @var{mode}.
 
-More information about the signatures is available with
-@code{gpgme_get_op_info}.  @xref{Detailed Results}.
+After the operation completed successfully, the result can be
+retrieved with @code{gpgme_op_sign_result}.
 
 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_No_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 GpgmeError gpgme_op_sign_start (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{plain}}, @w{GpgmeData @var{sig}}, @w{GpgmeSigMode @var{mode}})
+@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}})
 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
 
+@deftp {Data type} {gpgme_new_signature_t}
+This is a pointer to a structure used to store a part of the result of
+a @code{gpgme_op_sign} operation.  The structure contains the
+following members:
 
-@node Encrypt
-@subsection Encrypt
-@cindex encryption
-@cindex cryptographic operation, encryption
-
-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.
-
-@menu
-* Selecting Recipients::          How to choose the recipients.
-* Encrypting a Plaintext::        How to encrypt a plaintext.
-@end menu
-
+@table @code
+@item gpgme_new_signature_t next
+This is a pointer to the next new signature structure in the linked
+list, or @code{NULL} if this is the last element.
 
-@node Selecting Recipients
-@subsubsection Selecting Recipients
-@cindex encryption, selecting recipients
-@cindex recipients
+@item gpgme_sig_mode_t type
+The type of this signature.
 
-@deftp {Data type} GpgmeRecipients
-The @code{GpgmeRecipients} type is a handle for a set of recipients
-that can be used in an encryption process.
-@end deftp
+@item gpgme_pubkey_algo_t
+The public key algorithm used to create this signature.
 
-@deftypefun GpgmeError gpgme_recipients_new (@w{GpgmeRecipients *@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}.
+@item gpgme_hash_algo_t
+The hash algorithm used to create this signature.
 
-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.
-@end deftypefun
+@item unsigned int sig_class
+The signature class of this signature.
 
-@deftypefun void gpgme_recipients_release (@w{GpgmeRecipients @var{rset}})
-The function @code{gpgme_recipients_release} destroys the set of
-recipients @var{rset} and releases all associated resources.
-@end deftypefun
+@item long int timestamp
+The creation timestamp of this signature.
 
-@deftypefun GpgmeError gpgme_recipients_add_name (@w{GpgmeRecipients @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}.
+@item char *fpr
+The fingerprint of the key which was used to create this signature.
+@end table
+@end deftp
 
-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
+@deftp {Data type} {gpgme_sign_result_t}
+This is a pointer to a structure used to store the result of a
+@code{gpgme_op_sign} operation.  After successfully generating a
+signature, you can retrieve the pointer to the result with
+@code{gpgme_op_sign_result}.  The structure contains the following
+members:
 
-@deftypefun GpgmeError gpgme_recipients_add_name_with_validity (@w{GpgmeRecipients @var{rset}}, @w{const char *@var{name}}, @w{GpgmeValidity @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}.
+@table @code
+@item gpgme_invalid_key_t invalid_signers
+A linked list with information about all invalid keys for which a
+signature could not be created.
 
-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
+@item gpgme_new_signature_t signatures
+A linked list with information about all signatures created.
+@end table
+@end deftp
 
-@deftypefun {unsigned int} gpgme_recipients_count (@w{const @var{GpgmeRecipients rset}})
-The function @code{gpgme_recipients_count} returns the number of
-recipients in the set @var{rset}.
+@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},
+@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
 
-@deftypefun GpgmeError gpgme_recipients_enum_open (@w{const GpgmeRecipients @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 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 GpgmeRecipients @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 GpgmeError gpgme_recipients_enum_close (@w{const GpgmeRecipients @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 GpgmeError gpgme_op_encrypt (@w{GpgmeCtx @var{ctx}}, @w{GpgmeRecipients @var{rset}}, @w{GpgmeData @var{plain}}, @w{GpgmeData @var{cipher}})
+@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{rset} and stores the
+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}.
 
-If @code{GPGME_Invalid_Recipients} 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
-@code{gpgme_get_op_info}.  @xref{Detailed Results}.
+@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:
+
+@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.
+@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
 encryption is performed.  Symmetrically encrypted cipher text can be
@@ -2912,30 +4387,59 @@ 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_Recipients} if @var{rset} does not contain any valid
-recipients, @code{GPGME_Invalid_Recipients} if @var{rset} contains
-some invalid recipients, @code{GPGME_No_Passphrase} if the passphrase
-for the secret key could not be retrieved, and passes through any
+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 GpgmeError gpgme_op_encrypt_start (@w{GpgmeCtx @var{ctx}}, @w{GpgmeRecipients @var{rset}}, @w{GpgmeData @var{plain}}, @w{GpgmeData @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_Recipients} 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}
+This is a pointer to a structure used to store the result of a
+@code{gpgme_op_encrypt} operation.  After successfully encrypting
+data, you can retrieve the pointer to the result with
+@code{gpgme_op_encrypt_result}.  The structure contains the following
+members:
+
+@table @code
+@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}, @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 GpgmeError gpgme_op_encrypt_sign (@w{GpgmeCtx @var{ctx}}, @w{GpgmeRecipients @var{rset}}, @w{GpgmeData @var{plain}}, @w{GpgmeData @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
@@ -2945,52 +4449,16 @@ The combined encrypt and sign operation is currently only available
 for the OpenPGP crypto engine.
 @end deftypefun
 
-@deftypefun GpgmeError gpgme_op_encrypt_sign_start (@w{GpgmeCtx @var{ctx}}, @w{GpgmeRecipients @var{rset}}, @w{GpgmeData @var{plain}}, @w{GpgmeData @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_Recipients} if @var{rset} does not contain any valid
-recipients.
-@end deftypefun
-
-
-@node Detailed Results
-@subsection Detailed Results
-@cindex cryptographic operation, detailed results
-
-@deftypefun {char *} gpgme_get_op_info (@w{GpgmeCtx @var{ctx}}, @w{int @var{reserved}})
-The function @code{gpgme_get_op_info} retrieves more information about
-the last crypto operation.
-
-The function returns a string in the XML format.  The user has to
-release the string with @code{free}.
-
-Here is a sample of the information that might be returned:
-@example
-<GnupgOperationInfo>
-  <signature>
-    <detached/> <!-- or cleartext or standard -->
-    <algo>17</algo>
-    <hashalgo>2</hashalgo>
-    <micalg>pgp-sha1</micalg>
-    <sigclass>01</sigclass>
-    <created>9222222</created>
-    <fpr>121212121212121212</fpr>
-  </signature>
-</GnupgOperationInfo>
-@end example
-
-Currently, the only operations that return additional information are
-encrypt, sign and import.  @xref{Encrypt}, @xref{Sign},
-@xref{Importing Keys}.
-
-The function returns a string or @code{NULL} if no such data is
-available.
+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
 
 
@@ -3011,8 +4479,8 @@ time.
 
 @menu
 * Waiting For Completion::        Waiting until an operation is completed.
-* Cancelling an Operation::       Interrupting a running operation.
 * Using External Event Loops::    Advanced control over what happens when.
+* Cancellation::                  How to end pending operations prematurely.
 @end menu
 
 
@@ -3021,7 +4489,7 @@ time.
 @cindex cryptographic operation, wait for
 @cindex wait for completion
 
-@deftypefun GpgmeCtx gpgme_wait (@w{GpgmeCtx @var{ctx}}, @w{GpgmeError *@var{status}}, @w{int @var{hang}})
+@deftypefun gpgme_ctx_t gpgme_wait (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_error_t *@var{status}}, @w{int @var{hang}})
 The function @code{gpgme_wait} continues the pending operation within
 the context @var{ctx}.  In particular, it ensures the data exchange
 between @acronym{GPGME} and the crypto backend and watches over the
@@ -3060,22 +4528,6 @@ error occurs, @code{NULL} is returned and the error is returned in
 @end deftypefun
 
 
-@node Cancelling an Operation
-@subsection Cancelling an Operation
-@cindex cancellation
-@cindex cryptographic operation, cancel
-
-@deftypefun void gpgme_cancel (@w{GpgmeCtx @var{ctx}})
-The function @code{gpgme_cancel} tries to cancel the pending
-operation.  A running synchronous operation in the context or the
-function @code{gpgme_wait} with this context as its @var{ctx} argument
-might notice the cancellation flag and return.  It is currently not
-guaranteed to work under all circumstances.  Its current primary
-purpose is to prevent asking for a passphrase again in the passphrase
-callback.
-@end deftypefun
-
-
 @node Using External Event Loops
 @subsection Using External Event Loops
 @cindex event loop, external
@@ -3112,17 +4564,18 @@ 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
 
 
 @node I/O Callback Interface
 @subsubsection I/O Callback Interface
 
-@deftp {Data type} {GpgmeError (*GpgmeIOCb) (@w{void *@var{data}}, @w{int @var{fd}})}
-@tindex GpgmeIOCb
-The @code{GpgmeIOCb} type is the type of functions which
+@deftp {Data type} {gpgme_error_t (*gpgme_io_cb_t) (@w{void *@var{data}}, @w{int @var{fd}})}
+@tindex gpgme_io_cb_t
+The @code{gpgme_io_cb_t} type is the type of functions which
 @acronym{GPGME} wants to register as I/O callback handlers using the
-@code{GpgmeRegisterIOCb} functions provided by the user.
+@code{gpgme_register_io_cb_t} functions provided by the user.
 
 @var{data} and @var{fd} are provided by @acronym{GPGME} when the I/O
 callback handler is registered, and should be passed through to the
@@ -3133,9 +4586,9 @@ The callback handler always returns @code{0}, but you should consider
 the return value to be reserved for later use.
 @end deftp
 
-@deftp {Data type} {GpgmeError (*GpgmeRegisterIOCb) (@w{void *@var{data}}, @w{int @var{fd}}, @w{int @var{dir}}, @w{GpgmeIOCb @var{fnc}}, @w{void *@var{fnc_data}}, @w{void **@var{tag}})}
-@tindex GpgmeRegisterIOCb
-The @code{GpgmeRegisterIOCb} type is the type of functions which can
+@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
 @var{fnc} for the file descriptor @var{fd} with the user.
 @var{fnc_data} should be passed as the first argument to @var{fnc}
@@ -3145,7 +4598,7 @@ If @var{dir} is 0, @var{fnc} should be called by the user when
 called when @var{fd} is ready for reading.
 
 @var{data} was provided by the user when registering the
-@code{GpgmeRegisterIOCb} function with @acronym{GPGME} and will always
+@code{gpgme_register_io_cb_t} function with @acronym{GPGME} and will always
 be passed as the first argument when registering a callback function.
 For example, the user can use this to determine the event loop to
 which the file descriptor should be added.
@@ -3158,24 +4611,24 @@ associated to this context.
 
 The user should return a unique handle in @var{tag} identifying this
 I/O callback registration, which will be passed to the
-@code{GpgmeRegisterIOCb} function without interpretation when the file
+@code{gpgme_register_io_cb_t} function without interpretation when the file
 descriptor should not be monitored anymore.
 @end deftp
 
-@deftp {Data type} {void (*GpgmeRemoveIOCb) (@w{void *@var{tag}})}
-The @code{GpgmeRemoveIOCb} type is the type of functions which can be
+@deftp {Data type} {void (*gpgme_remove_io_cb_t) (@w{void *@var{tag}})}
+The @code{gpgme_remove_io_cb_t} type is the type of functions which can be
 called by @acronym{GPGME} to remove an I/O callback handler that was
 registered before.  @var{tag} is the handle that was returned by the
-@code{GpgmeRegisterIOCb} for this I/O callback.
+@code{gpgme_register_io_cb_t} for this I/O callback.
 
 @acronym{GPGME} can call this function when a crypto operation is in
 an I/O callback.  It will also call this function when the context is
 destroyed while an operation is pending.
 @end deftp
 
-@deftp {Data type} {enum GpgmeEventIO}
-@tindex GpgmeEventIO
-The @code{GpgmeEventIO} type specifies the type of an event that is
+@deftp {Data type} {enum gpgme_event_io_t}
+@tindex gpgme_event_io_t
+The @code{gpgme_event_io_t} type specifies the type of an event that is
 reported to the user by @acronym{GPGME} as a consequence of an I/O
 operation.  The following events are defined:
 
@@ -3189,38 +4642,38 @@ callback handlers must not be run before this event is signalled.
 @item GPGME_EVENT_DONE
 The operation is finished, the last I/O callback for this operation
 was removed.  The accompanying @var{type_data} points to a
-@code{GpgmeError} variable that contains the status of the operation
+@code{gpgme_error_t} variable that contains the status of the operation
 that finished.  This event is signalled after the last I/O callback
 has been removed.
 
 @item GPGME_EVENT_NEXT_KEY
 In a @code{gpgme_op_keylist_start} operation, the next key was
 received from the crypto engine.  The accompanying @var{type_data} is
-a @code{GpgmeKey} variable that contains the key with one reference
+a @code{gpgme_key_t} variable that contains the key with one reference
 for the user.
 
 @item GPGME_EVENT_NEXT_TRUSTITEM
 In a @code{gpgme_op_trustlist_start} operation, the next trust item
 was received from the crypto engine.  The accompanying @var{type_data}
-is a @code{GpgmeTrustItem} variable that contains the trust item with
+is a @code{gpgme_trust_item_t} variable that contains the trust item with
 one reference for the user.
 @end table
 @end deftp
 
-@deftp {Data type} {void (*GpgmeEventIOCb) (@w{void *@var{data}}, @w{GpgmeEventIO @var{type}}, @w{void *@var{type_data}})}
-The @code{GpgmeEventIOCb} type is the type of functions which can be
+@deftp {Data type} {void (*gpgme_event_io_cb_t) (@w{void *@var{data}}, @w{gpgme_event_io_t @var{type}}, @w{void *@var{type_data}})}
+The @code{gpgme_event_io_cb_t} type is the type of functions which can be
 called by @acronym{GPGME} to signal an event for an operation running
 in a context which has I/O callback functions registered by the user.
 
 @var{data} was provided by the user when registering the
-@code{GpgmeEventIOCb} function with @acronym{GPGME} and will always be
+@code{gpgme_event_io_cb_t} function with @acronym{GPGME} and will always be
 passed as the first argument when registering a callback function.
 For example, the user can use this to determine the context in which
 this event has occured.
 
 @var{type} will specify the type of event that has occured.
 @var{type_data} specifies the event further, as described in the above
-list of possible @code{GpgmeEventIO} types.
+list of possible @code{gpgme_event_io_t} types.
 
 @acronym{GPGME} can call this function in an I/O callback handler.
 @end deftp
@@ -3229,13 +4682,13 @@ list of possible @code{GpgmeEventIO} types.
 @node Registering I/O Callbacks
 @subsubsection Registering I/O Callbacks
 
-@deftp {Data type} {struct GpgmeIOCbs}
-@tindex GpgmeEventIO
+@deftp {Data type} {struct gpgme_io_cb_ts}
+@tindex gpgme_event_io_t
 This structure is used to store the I/O callback interface functions
 described in the previous section.  It has the following members:
 
 @table @code
-@item GpgmeRegisterIOCb add
+@item gpgme_register_io_cb_t add
 This is the function called by @acronym{GPGME} to register an I/O
 callback handler.  It must be specified.
 
@@ -3244,11 +4697,11 @@ This is passed as the first argument to the @code{add} function when
 it is called by @acronym{GPGME}.  For example, it can be used to
 determine the event loop to which the file descriptor should be added.
 
-@item GpgmeRemoveIOCb remove
+@item gpgme_remove_io_cb_t remove
 This is the function called by @acronym{GPGME} to remove an I/O
 callback handler.  It must be specified.
 
-@item GpgmeEventIOCb event
+@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.
@@ -3260,7 +4713,7 @@ determine the context in which the event has occured.
 @end table
 @end deftp
 
-@deftypefun void gpgme_set_io_cbs (@w{GpgmeCtx @var{ctx}}, @w{struct GpgmeIOCbs *@var{io_cbs}})
+@deftypefun void gpgme_set_io_cbs (@w{gpgme_ctx_t @var{ctx}}, @w{struct gpgme_io_cb_ts *@var{io_cbs}})
 The function @code{gpgme_set_io_cbs} enables the I/O callback
 interface for the context @var{ctx}.  The I/O callback functions are
 specified by @var{io_cbs}.
@@ -3269,7 +4722,7 @@ If @var{io_cbs}->@code{add} is @code{NULL}, the I/O callback interface
 is disabled for the context, and normal operation is restored.
 @end deftypefun
 
-@deftypefun void gpgme_get_io_cbs (@w{GpgmeCtx @var{ctx}}, @w{struct GpgmeIOCbs *@var{io_cbs}})
+@deftypefun void gpgme_get_io_cbs (@w{gpgme_ctx_t @var{ctx}}, @w{struct gpgme_io_cb_ts *@var{io_cbs}})
 The function @code{gpgme_get_io_cbs} returns the I/O callback
 functions set with @code{gpgme_set_io_cbs} in @var{io_cbs}.
 @end deftypefun
@@ -3300,7 +4753,7 @@ operation in @acronym{GPGME} is not predictable.
 struct op_result
 @{
   int done;
-  GpgmeError err;
+  gpgme_error_t err;
 @};
 
 /* The following structure holds the data associated with one I/O
@@ -3309,7 +4762,7 @@ struct one_fd
 @{
   int fd;
   int dir;
-  GpgmeIOCb fnc;
+  gpgme_io_cb_t fnc;
   void *fnc_data;
 @};
 
@@ -3325,8 +4778,8 @@ struct event_loop
 The following functions implement the I/O callback interface.
 
 @example
-GpgmeError
-add_io_cb (void *data, int fd, int dir, GpgmeIOCb fnc, void *fnc_data,
+gpgme_error_t
+add_io_cb (void *data, int fd, int dir, gpgme_io_cb_t fnc, void *fnc_data,
           void **r_tag)
 @{
   struct event_loop *loop = data;
@@ -3347,7 +4800,7 @@ add_io_cb (void *data, int fd, int dir, GpgmeIOCb 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;
 @}
@@ -3363,16 +4816,15 @@ remove_io_cb (void *tag)
 @}
 
 void
-event_io_cb (void *data, GpgmeEventIO type, void *type_data)
+event_io_cb (void *data, gpgme_event_io_t type, void *type_data)
 @{
   struct op_result *result = data;
-  GpgmeError *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
@@ -3450,12 +4902,12 @@ main (int argc, char *argv[])
 @{
   struct event_loop loop;
   struct op_result result;
-  GpgmeCtx ctx;
-  GpgmeError err;
-  GpgmeData sig, text;
-  GpgmeSigStat status;
+  gpgme_ctx_t ctx;
+  gpgme_error_t err;
+  gpgme_data_t sig, text;
+  gpgme_sig_stat_t status;
   int i;
-  struct GpgmeIOCbs io_cbs =
+  struct gpgme_io_cb_ts io_cbs =
   @{
     add_io_cb,
     &loop,
@@ -3484,7 +4936,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);
     @}
 
@@ -3496,7 +4949,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.  */
@@ -3522,7 +4976,7 @@ because it does not require any GTK+ specific setup.
 
 struct my_gpgme_io_cb
 @{
-  GpgmeIOCb fnc;
+  gpgme_io_cb_t fnc;
   void *fnc_data;
   guint input_handler_id
 @};
@@ -3542,7 +4996,7 @@ my_gpgme_remove_io_cb (void *data)
 @}
 
 void
-my_gpgme_register_io_callback (void *data, int fd, int dir, GpgmeIOCb fnc,
+my_gpgme_register_io_callback (void *data, int fd, int dir, gpgme_io_cb_t fnc,
                                void *fnc_data, void **tag)
 @{
   struct my_gpgme_io_cb *iocb = g_malloc (sizeof (struct my_gpgme_io_cb));
@@ -3577,7 +5031,7 @@ It is very similar to the GTK+ example in the previous section.
 
 struct my_gpgme_io_cb
 @{
-  GpgmeIOCb fnc;
+  gpgme_io_cb_t fnc;
   void *fnc_data;
   gint tag;
 @};
@@ -3597,7 +5051,7 @@ my_gpgme_remove_io_cb (void *data)
 @}
 
 void
-my_gpgme_register_io_callback (void *data, int fd, int dir, GpgmeIOCb fnc,
+my_gpgme_register_io_callback (void *data, int fd, int dir, gpgme_io_cb_t fnc,
                                void *fnc_data, void **tag)
 @{
   struct my_gpgme_io_cb *iocb = g_malloc (sizeof (struct my_gpgme_io_cb));
@@ -3611,10 +5065,112 @@ my_gpgme_register_io_callback (void *data, int fd, int dir, GpgmeIOCb 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.
+
+@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;
+  @}
+
+  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;
+      @}
+  @}
+
+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.  If you
+use external I/O callbacks, you can cancel a pending operation.
+However, you must ensure that no other thread is currently using the
+context in which the operation you want to cancel runs.  This includes
+callback handlers.  So your external event loop must either be halted
+or otherwise it must be guaranteed that no installed I/O callbacks are
+run for this 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
 
 
-@include fdl.texi
+@include lesser.texi
 
 
 @node Concept Index