python: Initialize GPGME for the user.
[gpgme.git] / doc / gpgme.texi
index 92289c2..8d666c3 100644 (file)
@@ -1,4 +1,5 @@
-\input texinfo                  @c -*- Texinfo -*-
+\input texinfo                   @c -*- mode: texinfo; coding: utf-8; -*-
+@documentencoding UTF-8
 @setfilename gpgme.info
 @settitle The `GnuPG Made Easy' Reference Manual
 
@@ -7,12 +8,42 @@
 * @acronym{GPGME}: (gpgme).          Adding support for cryptography to your program.
 @end direntry
 
-@include version.texi
-
 @c Unify some of the indices.
 @syncodeindex tp fn
 @syncodeindex pg fn
 
+@copying
+Copyright @copyright{} 2002, 2003, 2004, 2005, 2006, 2007,
+2008, 2010, 2012, 2013, 2014 g10 Code GmbH.
+
+@quotation
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU General Public License as published by the
+Free Software Foundation; either version 3 of the License, or (at your
+option) any later version. The text of the license can be found in the
+section entitled ``Copying''.
+@end quotation
+
+This document is distributed in the hope that it will be useful, but
+WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+General Public License for more details.
+@end copying
+
+@include version.texi
+
+@c Macros used by the description of the UI server protocol
+@macro clnt
+  @sc{c:} @c
+@end macro
+@macro srvr
+  @sc{s:} @c
+@end macro
+
+
+@c
+@c  T I T L E  P A G E
+@c
 @ifinfo
 This file documents the @acronym{GPGME} library.
 
@@ -21,27 +52,14 @@ This is Edition @value{EDITION}, last updated @value{UPDATED}, of
 @value{VERSION}.
 
 @c NOTE: Don't forget to update the year for the TeX version, too.
-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
+@insertcopying
 
 @end ifinfo
 
-@iftex
-@shorttitlepage The `GnuPG Made Easy' Reference Manual
-@end iftex
+@c We do not want that bastard short titlepage.
+@c @iftex
+@c @shorttitlepage The `GnuPG Made Easy' Reference Manual
+@c @end iftex
 @titlepage
 @center @titlefont{The `GnuPG Made Easy'}
 @sp 1
@@ -54,25 +72,15 @@ Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
 @center for version @value{VERSION}
 @page
 @vskip 0pt plus 1filll
-Copyright @copyright{} 2002, 2003, 2004 g10 Code GmbH.
+Published by g10 Code GmbH@* Hüttenstr. 61@* 40699 Erkrath, Germany
 
-
-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
+@insertcopying
 @end titlepage
 @page
 
+@summarycontents
+@contents
+
 @ifnottex
 @node Top
 @top Main Menu
@@ -92,15 +100,19 @@ This is Edition @value{EDITION}, last updated @value{UPDATED}, of
 
 Appendices
 
+* UI Server Protocol::            The GnuPG UI Server Protocol.
+* Debugging::                     How to solve problems.
+
 * Library Copying::               The GNU Lesser General Public License says
                                   how you can copy and share `GnuPG Made Easy'.
+* Copying::                       The GNU General Public License says how you
+                                  can copy and share this manual.
 
 Indices
 
 * Concept Index::                 Index of concepts and programs.
 * Function and Data Index::       Index of functions, variables and data types.
 
-
 @detailmenu
  --- The Detailed Node Listing ---
 
@@ -141,7 +153,7 @@ Error Handling
 * Error Sources::                 A list of important error sources.
 * Error Strings::                 How to get a descriptive string from a value.
 
-Exchanging Data 
+Exchanging Data
 
 * Creating Data Buffers::         Creating new data buffers.
 * Destroying Data Buffers::       Releasing data buffers.
@@ -153,14 +165,22 @@ Creating Data Buffers
 * File Based Data Buffers::       Creating file based data buffers.
 * Callback Based Data Buffers::   Creating callback based data buffers.
 
+Manipulating Data Buffers
+
+* Data Buffer I/O Operations::    I/O operations on data buffers.
+* Data Buffer Meta-Data::         Meta-data manipulation of data buffers.
+* Data Buffer Convenience::       Convenience function for data buffers.
+
 Contexts
 
 * Creating Contexts::             Creating new @acronym{GPGME} contexts.
 * Destroying Contexts::           Releasing @acronym{GPGME} contexts.
+* Result Management::             Managing the result of crypto operations.
 * Context Attributes::            Setting properties of a context.
 * Key Management::                Managing keys with @acronym{GPGME}.
 * Trust Item Management::         Managing trust items with @acronym{GPGME}.
 * Crypto Operations::             Using a context for cryptography.
+* Miscellaneous::                 Miscellaneous operations.
 * Run Control::                   Controlling how operations are run.
 
 Context Attributes
@@ -169,10 +189,12 @@ Context Attributes
 * Crypto Engine::                 Configuring the crypto engine.
 * ASCII Armor::                   Requesting @acronym{ASCII} armored output.
 * Text Mode::                     Choosing canonical text mode.
+* Offline Mode::                  Choosing offline 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.
+* Status Message Callback::       Status messages received from gpg.
 * Locale::                        Setting the locale of a context.
 
 Key Management
@@ -185,6 +207,8 @@ Key Management
 * Exporting Keys::                Retrieving key data from the key ring.
 * Importing Keys::                Adding keys to the key ring.
 * Deleting Keys::                 Removing keys from the key ring.
+* Changing Passphrases::          Change the passphrase of a key.
+* Advanced Key Editing::          Advanced key edit operation.
 
 Trust Item Management
 
@@ -204,11 +228,16 @@ Sign
 
 * Selecting Signers::             How to choose the keys to sign with.
 * Creating a Signature::          How to create a signature.
+* Signature Notation Data::       How to add notation data to a signature.
 
 Encrypt
 
 * Encrypting a Plaintext::        How to encrypt a plaintext.
 
+Miscellaneous
+
+* Running other Programs::        Running other Programs
+
 Run Control
 
 * Waiting For Completion::        Waiting until an operation is completed.
@@ -364,8 +393,8 @@ to @acronym{GPGME} take the form @code{_gpgme_*} and @code{_GPGME_*}.
 
 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.
+directly, and the @code{gpg_err*}, @code{gpg_str*}, and @code{gpgrt_*}
+name space indirectly.
 
 
 @node Building the Source
@@ -472,18 +501,42 @@ 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).
+On POSIX platforms @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.
+
+On 32 and 64 bit Windows platforms @code{off_t} is declared as 32 bit
+signed integer.  There is no specific support for LFS in the C
+library.  The recommendation from Microsoft is to use the native
+interface (@code{CreateFile} et al.) for large files.  Released binary
+versions of @acronym{GPGME} (libgpgme-11.dll) have always been build
+with a 32 bit @code{off_t}.  To avoid an ABI break we stick to this
+convention for 32 bit Windows by using @code{long} there.
+@acronym{GPGME} versions for 64 bit Windows have never been released
+and thus we are able to use @code{int64_t} instead of @code{off_t}
+there.  For easier migration the typedef @code{gpgme_off_t} has been
+defined.  The reason we cannot use @code{off_t} directly is that some
+toolchains (e.g. mingw64) introduce a POSIX compatible hack for
+@code{off_t}.  Some widely used toolkits make use of this hack and in
+turn @acronym{GPGME} would need to use it also.  However, this would
+introduce an ABI break and existing software making use of libgpgme
+might suffer from a severe break.  Thus with version 1.4.2 we
+redefined all functions using @code{off_t} to use @code{gpgme_off_t}
+which is defined as explained above.  This way we keep the ABI well
+defined and independent of any toolchain hacks.  The bottom line is
+that LFS support in @acronym{GPGME} is only available on 64 bit
+versions of Windows.
+
+On POSIX platforms 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
@@ -524,7 +577,10 @@ given.
 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.
+the program to the @acronym{GPGME} library.  If the used helper script
+does not match the target type you are building for a warning is
+printed and the string @code{libgcrypt} is appended to the variable
+@code{gpg_config_script_warn}.
 
 @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
@@ -533,6 +589,16 @@ that can be used with GNU Pth, and defines @code{GPGME_PTH_CFLAGS} and
 @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}.
+
+This macro searches for @command{gpgme-config} along the PATH.  If
+you are cross-compiling, it is useful to set the environment variable
+@code{SYSROOT} to the top directory of your target.  The macro will
+then first look for the helper program in the @file{bin} directory
+below that top directory.  An absolute directory name must be used for
+@code{SYSROOT}.  Finally, if the configure command line option
+@code{--with-gpgme-prefix} is used, only its value is used for the top
+directory below which the helper script is expected.
+
 @end defmac
 
 You can use the defined Autoconf variables like this in your
@@ -559,13 +625,17 @@ automatically by Libtool.
 @cindex version check, of the library
 
 @deftypefun {const char *} gpgme_check_version (@w{const char *@var{required_version}})
-The function @code{gpgme_check_version} has three purposes.  It can be
+The function @code{gpgme_check_version} has four purposes.  It can be
 used to retrieve the version number of the library.  In addition it
 can verify that the version number is higher than a certain required
 version number.  In either case, the function initializes some
 sub-systems, and for this reason alone it must be invoked early in
 your program, before you make use of the other functions in
-@acronym{GPGME}.
+@acronym{GPGME}.  The last purpose is to run selftests.
+
+As a side effect for W32 based systems, the socket layer will get
+initialized.
+
 
 If @var{required_version} is @code{NULL}, the function returns a
 pointer to a statically allocated string containing the version number
@@ -584,6 +654,70 @@ If you use a version of a library that is backwards compatible with
 older releases, but contains additional interfaces which your program
 uses, this function provides a run-time check if the necessary
 features are provided by the installed version of the library.
+
+If a selftest fails, the function may still succeed.  Selftest errors
+are returned later when invoking @code{gpgme_new}, so that a detailed
+error code can be returned (historically, @code{gpgme_check_version}
+does not return a detailed error code).
+@end deftypefun
+
+
+@deftypefun {int} gpgme_set_global_flag  @
+            (@w{const char *@var{name}}, @
+            @w{const char *@var{value}})
+
+On some systems it is not easy to set environment variables and thus
+hard to use @acronym{GPGME}'s internal trace facility for debugging.
+This function has been introduced as an alternative way to enable
+debugging and for a couple of other rarely used tweaks.  It is
+important to assure that only one thread accesses @acronym{GPGME}
+functions between a call to this function and after the return from
+the call to @code{gpgme_check_version}.
+
+All currently supported features require that this function is called
+as early as possible --- even before @code{gpgme_check_version}.  The
+features are identified by the following values for @var{name}:
+
+@table @code
+@item "debug"
+To enable debugging use the string ``debug'' for @var{name} and
+@var{value} identical to the value used with the environment variable
+@code{GPGME_DEBUG}.
+
+@item "disable-gpgconf"
+Using this feature with any @var{value} disables the detection of the
+gpgconf program and thus forces GPGME to fallback into the simple
+OpenPGP only mode.  It may be used to force the use of GnuPG-1 on
+systems which have both GPG versions installed.  Note that in general
+the use of @code{gpgme_set_engine_info} is a better way to select a
+specific engine version.
+
+@item "gpgconf-name"
+@itemx "gpg-name"
+Set the name of the gpgconf respective gpg binary.  The defaults are
+@code{GNU/GnuPG/gpgconf} and @code{GNU/GnuPG/gpg}.  Under Unix the
+leading directory part is ignored.  Under Windows the leading
+directory part is used as the default installation directory; the
+@code{.exe} suffix is added by GPGME.  Use forward slashed even under
+Windows.
+
+@item "w32-inst-dir"
+On Windows GPGME needs to know its installation directory to find its
+spawn helper.  This is in general no problem because a DLL has this
+information.  Some applications however link statically to GPGME and
+thus GPGME can only figure out the installation directory of this
+application which may be wrong in certain cases.  By supplying an
+installation directory as value to this flag, GPGME will assume that
+that directory is the installation directory.  This flag has no effect
+on non-Windows platforms.
+
+@end table
+
+This function returns @code{0} on success.  In contrast to other
+functions the non-zero return value on failure does not convey any
+error code.  For setting ``debug'' the only possible error cause is an
+out of memory condition; which would exhibit itself later anyway.
+Thus the return value may be ignored.
 @end deftypefun
 
 
@@ -597,19 +731,22 @@ pinentry.  Here is an example of a complete initialization:
 #include <gpgme.h>
 
 void
-init_program (void)
+init_gpgme (void)
 @{
   /* Initialize the locale environment.  */
   setlocale (LC_ALL, "");
   gpgme_check_version (NULL);
   gpgme_set_locale (NULL, LC_CTYPE, setlocale (LC_CTYPE, NULL));
+#ifdef LC_MESSAGES
   gpgme_set_locale (NULL, LC_MESSAGES, setlocale (LC_MESSAGES, NULL));
+#endif
 @}
 @end example
 
 Note that you are highly recommended to initialize the locale settings
 like this.  @acronym{GPGME} can not do this for you because it would
-not be thread safe.
+not be thread safe.  The conditional on LC_MESSAGES is only necessary
+for portability to W32 systems.
 
 
 @node Signal Handling
@@ -734,11 +871,29 @@ This specifies the OpenPGP protocol.
 
 @item GPGME_PROTOCOL_CMS
 This specifies the Cryptographic Message Syntax.
+
+@item GPGME_PROTOCOL_ASSUAN
+Under development.  Please ask on @email{gnupg-devel@@gnupg.org} for help.
+
+@item GPGME_PROTOCOL_G13
+Under development.  Please ask on @email{gnupg-devel@@gnupg.org} for help.
+
+@item GPGME_PROTOCOL_UISERVER
+Under development.  Please ask on @email{gnupg-devel@@gnupg.org} for help.
+
+@item GPGME_PROTOCOL_SPAWN
+Special protocol for use with @code{gpgme_op_spawn}.
+
+@item GPGME_PROTOCOL_UNKNOWN
+Reserved for future extension.  You may use this to indicate that the
+used protocol is not known to the application.  Currently,
+@acronym{GPGME} does not accept this value in any operation, though,
+except for @code{gpgme_get_protocol_name}.
 @end table
 @end deftp
 
 
-@deftypefun const char *gpgme_get_protocol_name (@w{gpgme_protocol_t @var{protocol}})
+@deftypefun {const char *} gpgme_get_protocol_name (@w{gpgme_protocol_t @var{protocol}})
 The function @code{gpgme_get_protocol_name} returns a statically
 allocated string describing the protocol @var{protocol}, or
 @code{NULL} if the protocol number is not valid.
@@ -757,6 +912,41 @@ allocated string describing the protocol @var{protocol}, or
 @section Engine Version Check
 @cindex version check, of the engines
 
+@deftypefun @w{const char *} gpgme_get_dirinfo (@w{cons char *@var{what}})
+The function @code{gpgme_get_dirinfo} returns a statically allocated
+string with the value associated to @var{what}.  The returned values
+are the defaults and won't change even after
+@code{gpgme_set_engine_info} has been used to configure a different
+engine.  @code{NULL} is returned if no value is available.  Commonly
+supported values for @var{what} are:
+
+@table @code
+@item homedir
+Return the default home directory.
+
+@item agent-socket
+Return the name of the socket to connect to the gpg-agent.
+
+@item uiserver-socket
+Return the name of the socket to connect to the user interface server.
+
+@item gpgconf-name
+Return the file name of the engine configuration tool.
+
+@item gpg-name
+Return the file name of the OpenPGP engine.
+
+@item gpgsm-name
+Return the file name of the CMS engine.
+
+@item g13-name
+Return the name of the file container encryption engine.
+
+@end table
+
+@end deftypefun
+
+
 @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
@@ -795,7 +985,8 @@ 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.
+directory is used.  See @code{gpgme_get_dirinfo} on how to get the
+default directory.
 
 @item const char *version
 This is a string containing the version number of the crypto engine.
@@ -843,12 +1034,12 @@ if (gpgme_err_code (err) == GPG_ERR_INV_ENGINE)
         if (!info)
           fprintf (stderr, "GPGME compiled without support for protocol %s",
                    gpgme_get_protocol_name (info->protocol));
-        else if (info->path && !info->version)
+        else if (info->file_name && !info->version)
           fprintf (stderr, "Engine %s not installed properly",
-                   info->path);
-        else if (info->path && info->version && info->req_version)
+                   info->file_name);
+        else if (info->file_name && info->version && info->req_version)
           fprintf (stderr, "Engine %s version %s installed, "
-                   "but at least version %s required", info->path,
+                   "but at least version %s required", info->file_name,
                    info->version, info->req_version);
         else
           fprintf (stderr, "Unknown problem with engine for protocol %s",
@@ -923,8 +1114,10 @@ The @acronym{CMS} protocol is specified by @code{GPGME_PROTOCOL_CMS}.
 @cindex algorithms
 
 The crypto backends support a variety of algorithms used in public key
-cryptography.  The following sections list the identifiers used to
-denote such an algorithm.
+cryptography.@footnote{Some engines also provide symmetric only
+encryption; see the description of the encryption function on how to use
+this.}  The following sections list the identifiers used to denote such
+an algorithm.
 
 @menu
 * Public Key Algorithms::         A list of all public key algorithms.
@@ -966,6 +1159,21 @@ This value indicates ElGamal.
 
 @item GPGME_PK_ELG_E
 This value also indicates ElGamal and is used specifically in GnuPG.
+
+@item GPGME_PK_ECC
+This value is a generic indicator for ellipic curve algorithms.
+
+@item GPGME_PK_ECDSA
+This value indicates ECDSA, the Elliptic Curve Digital Signature
+Algorithm as defined by FIPS 186-2 and RFC-6637.
+
+@item GPGME_PK_ECDH
+This value indicates ECDH, the Eliptic Curve Diffie-Hellmann
+encryption algorithm as defined by RFC-6637.
+
+@item GPGME_PK_EDDSA
+This value indicates the EdDSA algorithm.
+
 @end table
 @end deftp
 
@@ -979,6 +1187,14 @@ If @var{algo} is not a valid public key algorithm, @code{NULL} is
 returned.
 @end deftypefun
 
+@deftypefun {char *} gpgme_pubkey_algo_string (@w{gpgme_subkey_t @var{key}})
+The function @code{gpgme_pubkey_algo_string} is a convenience function
+to build and return an algorithm string in the same way GnuPG does
+(e.g. ``rsa2048'' or ``ed25519'').  The caller must free the result
+using @code{gpgme_free}.  On error (e.g. invalid argument or memory
+exhausted), the function returns NULL and sets @code{ERRNO}.
+@end deftypefun
+
 
 @node Hash Algorithms
 @section Hash Algorithms
@@ -1005,6 +1221,7 @@ that are supported by @acronym{GPGME}.  Possible values are:
 @item GPGME_MD_SHA256
 @item GPGME_MD_SHA384
 @item GPGME_MD_SHA512
+@item GPGME_MD_SHA224
 @item GPGME_MD_MD4
 @item GPGME_MD_CRC32
 @item GPGME_MD_CRC32_RFC1510
@@ -1394,12 +1611,15 @@ 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}.
+@deftypefun {int} gpgme_strerror_r (@w{gpgme_error_t @var{err}}, @w{char *@var{buf}}, @w{size_t @var{buflen}})
+The function @code{gpgme_strerror_r} returns the error string for
+@var{err} in the user-supplied buffer @var{buf} of size @var{buflen}.
+This function is, in contrast to @code{gpgme_strerror}, thread-safe if
+a thread-safe @code{strerror_r} function is provided by the system.
+If the function succeeds, 0 is returned and @var{buf} contains the
+string describing the error.  If the buffer was not large enough,
+ERANGE is returned and @var{buf} contains as much of the beginning of
+the error string as fits into the buffer.
 @end deftypefun
 
 
@@ -1441,6 +1661,28 @@ The @code{gpgme_data_t} type is a handle for a container for generic
 data, which is used by @acronym{GPGME} to exchange data with the user.
 @end deftp
 
+@code{gpgme_data_t} objects do not provide notifications on events.
+It is assumed that read and write operations are blocking until data
+is available.  If this is undesirable, the application must ensure
+that all GPGME data operations always have data available, for example
+by using memory buffers or files rather than pipes or sockets.  This
+might be relevant, for example, if the external event loop mechanism
+is used.
+
+@deftp {Data type} {gpgme_off_t}
+On POSIX platforms the @code{gpgme_off_t} type is an alias for
+@code{off_t}; it may be used interchangeable.  On Windows platforms
+@code{gpgme_off_t} is defined as a long (i.e. 32 bit) for 32 bit
+Windows and as a 64 bit signed integer for 64 bit Windows.
+@end deftp
+
+@deftp {Data type} {gpgme_ssize_t}
+The @code{gpgme_ssize_t} type is an alias for @code{ssize_t}.  It has
+only been introduced to overcome portability problems pertaining to
+the declaration of @code{ssize_t} by different toolchains.
+@end deftp
+
+
 @menu
 * Creating Data Buffers::         Creating new data buffers.
 * Destroying Data Buffers::       Releasing data buffers.
@@ -1471,7 +1713,7 @@ Memory based data objects store all data in allocated memory.  This is
 convenient, but only practical for an amount of data that is a
 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 
+using one of the other data object
 
 @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}
@@ -1552,6 +1794,10 @@ 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.
 
+Note that GPGME assumes that the file descriptor is set to blocking
+mode.  Errors during I/O operations, except for EINTR, are usually
+fatal for crypto operations.
+
 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
 data object was successfully created, and @code{GPG_ERR_ENOMEM} if not
 enough memory is available.
@@ -1567,6 +1813,10 @@ 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.
 
+Note that GPGME assumes that the stream is in blocking mode.  Errors
+during I/O operations, except for EINTR, are usually fatal for crypto
+operations.
+
 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
 data object was successfully created, and @code{GPG_ERR_ENOMEM} if not
 enough memory is available.
@@ -1588,6 +1838,10 @@ data object.  The function should read up to @var{size} bytes from the
 current read position into the space starting at @var{buffer}.  The
 @var{handle} is provided by the user at data object creation time.
 
+Note that GPGME assumes that the read blocks until data is available.
+Errors during I/O operations, except for EINTR, are usually fatal for
+crypto operations.
+
 The function should return the number of bytes read, 0 on EOF, and -1
 on error.  If an error occurs, @var{errno} should be set to describe
 the type of the error.
@@ -1601,6 +1855,10 @@ data object.  The function should write up to @var{size} bytes to the
 current write position from the space starting at @var{buffer}.  The
 @var{handle} is provided by the user at data object creation time.
 
+Note that GPGME assumes that the write blocks until data is available.
+Errors during I/O operations, except for EINTR, are usually fatal for
+crypto operations.
+
 The function should return the number of bytes written, and -1 on
 error.  If an error occurs, @var{errno} should be set to describe the
 type of the error.
@@ -1705,18 +1963,47 @@ The function @code{gpgme_data_release_and_get_mem} is like
 @code{gpgme_data_release}, except that it returns the data buffer and
 its length that was provided by the object.
 
-The user has to release the buffer with @code{free}.  In case the user
-provided the data buffer in non-copy mode, a copy will be made for
-this purpose.
+The user has to release the buffer with @code{gpgme_free}.  In case
+the user provided the data buffer in non-copy mode, a copy will be
+made for this purpose.
 
 In case an error returns, or there is no suitable data buffer that can
-be returned to the user, the function will return @code{NULL}.
+be returned to the user, the function will return @code{NULL}.  In any
+case, the data object @var{dh} is destroyed.
+@end deftypefun
+
+
+@deftypefun void gpgme_free (@w{void *@var{buffer}})
+The function @code{gpgme_free} releases the memory returned by
+@code{gpgme_data_release_and_get_mem} and
+@code{gpgme_pubkey_algo_string}.  It should be used instead of the
+system libraries @code{free} function in case different allocators are
+used by a program.  This is often the case if gpgme is used under
+Windows as a DLL.
 @end deftypefun
 
 
 @node Manipulating Data Buffers
 @section Manipulating Data Buffers
-@cindex data buffere, manipulation
+@cindex data buffer, manipulation
+
+Data buffers contain data and meta-data.  The following operations can
+be used to manipulate both.
+
+
+@menu
+* Data Buffer I/O Operations::    I/O operations on data buffers.
+* Data Buffer Meta-Data::         Meta-data manipulation of data buffers.
+* Data Buffer Convenience::       Convenience function for data buffers.
+@end menu
+
+
+@node Data Buffer I/O Operations
+@subsection Data Buffer I/O Operations
+@cindex data buffer, I/O operations
+@cindex data buffer, read
+@cindex data buffer, write
+@cindex data buffer, seek
 
 @deftypefun ssize_t gpgme_data_read (@w{gpgme_data_t @var{dh}}, @w{void *@var{buffer}}, @w{size_t @var{length}})
 The function @code{gpgme_data_read} reads up to @var{length} bytes
@@ -1738,7 +2025,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
 
-@deftypefun off_t gpgme_data_seek (@w{gpgme_data_t @var{dh}}, @w{off_t *@var{offset}}, @w{int @var{whence}})
+@deftypefun off_t gpgme_data_seek (@w{gpgme_data_t @var{dh}}, @w{off_t @var{offset}}, @w{int @var{whence}})
 The function @code{gpgme_data_seek} changes the current read/write
 position.
 
@@ -1747,15 +2034,15 @@ interpreted.  It must be one of the following symbolic constants:
 
 @table @code
 @item SEEK_SET
-Specifies that @var{whence} is a count of characters from the
+Specifies that @var{offset} is a count of characters from the
 beginning of the data object.
 
 @item SEEK_CUR
-Specifies that @var{whence} is a count of characters from the current
+Specifies that @var{offset} is a count of characters from the current
 file position.  This count may be positive or negative.
 
 @item SEEK_END
-Specifies that @var{whence} is a count of characters from the end of
+Specifies that @var{offset} is a count of characters from the end of
 the data object.  A negative count specifies a position within the
 current extent of the data object; a positive count specifies a
 position past the current end.  If you set the position past the
@@ -1783,14 +2070,47 @@ The function @code{gpgme_data_rewind} is equivalent to:
 @end example
 @end deftypefun
 
-@c
-@c  gpgme_data_encoding_t
-@c
+
+
+
+@node Data Buffer Meta-Data
+@subsection Data Buffer Meta-Data
+@cindex data buffer, meta-data
+@cindex data buffer, file name
+@cindex data buffer, encoding
+
+@deftypefun {char *} gpgme_data_get_file_name (@w{gpgme_data_t @var{dh}})
+The function @code{gpgme_data_get_file_name} returns a pointer to a
+string containing the file name associated with the data object.  The
+file name will be stored in the output when encrypting or signing the
+data and will be returned to the user when decrypting or verifying the
+output data.
+
+If no error occurs, the string containing the file name is returned.
+Otherwise, @code{NULL} will be returned.
+@end deftypefun
+
+
+@deftypefun gpgme_error_t gpgme_data_set_file_name (@w{gpgme_data_t @var{dh}}, @w{const char *@var{file_name}})
+The function @code{gpgme_data_set_file_name} sets the file name
+associated with the data object.  The file name will be stored in the
+output when encrypting or signing the data and will be returned to the
+user when decrypting or verifying the output data.
+
+The function returns the error code @code{GPG_ERR_INV_VALUE} if
+@var{dh} is not a valid pointer and @code{GPG_ERR_ENOMEM} if not
+enough memory is available.
+@end deftypefun
+
+
 @deftp {Data type} {enum gpgme_data_encoding_t}
 @tindex gpgme_data_encoding_t
 The @code{gpgme_data_encoding_t} type specifies the encoding of a
-@code{gpgme_data_t} object.  This encoding is useful to give the backend
-a hint on the type of data.  The following data types are available:
+@code{gpgme_data_t} object.  For input data objects, the encoding is
+useful to give the backend a hint on the type of data.  For output
+data objects, the encoding can specify the output data format on
+certain operations.  Please note that not all backends support all
+encodings on all operations.  The following data types are available:
 
 @table @code
 @item GPGME_DATA_ENCODING_NONE
@@ -1809,6 +2129,19 @@ scheme as used by @acronym{MIME} and other protocols.
 @item GPGME_DATA_ENCODING_ARMOR
 This specifies that the data is encoded in an armored form as used by
 OpenPGP and PEM.
+
+@item GPGME_DATA_ENCODING_URL
+The data is a list of linefeed delimited URLs.  This is only useful with
+@code{gpgme_op_import}.
+
+@item GPGME_DATA_ENCODING_URL0
+The data is a list of binary zero delimited URLs.  This is only useful
+with @code{gpgme_op_import}.
+
+@item GPGME_DATA_ENCODING_URLESC
+The data is a list of linefeed delimited URLs with all control and space
+characters percent escaped.  This mode is is not yet implemented.
+
 @end table
 @end deftp
 
@@ -1824,10 +2157,60 @@ The function @code{gpgme_data_set_encoding} changes the encoding of
 the data object with the handle @var{dh} to @var{enc}.
 @end deftypefun
 
+@node Data Buffer Convenience
+@subsection Data Buffer Convenience Functions
+@cindex data buffer, convenience
+@cindex type of data
+@cindex identify
+
+@deftp {Data type} {enum gpgme_data_type_t}
+@tindex gpgme_data_type_t
+The @code{gpgme_data_type_t} type is used to return the detected type
+of the content of a data buffer.
+@end deftp
+
+@table @code
+@item GPGME_DATA_TYPE_INVALID
+This is returned by @code{gpgme_data_identify} if it was not possible
+to identify the data.  Reasons for this might be a non-seekable stream
+or a memory problem.  The value is 0.
+@item GPGME_DATA_TYPE_UNKNOWN
+The type of the data is not known.
+@item GPGME_DATA_TYPE_PGP_SIGNED
+The data is an OpenPGP signed message.  This may be a binary
+signature, a detached one or a cleartext signature.
+@item GPGME_DATA_TYPE_PGP_OTHER
+This is a generic OpenPGP message.  In most cases this will be
+encrypted data.
+@item GPGME_DATA_TYPE_PGP_KEY
+This is an OpenPGP key (private or public).
+@item GPGME_DATA_TYPE_CMS_SIGNED
+This is a CMS signed message.
+@item GPGME_DATA_TYPE_CMS_ENCRYPTED
+This is a CMS encrypted (enveloped data) message.
+@item GPGME_DATA_TYPE_CMS_OTHER
+This is used for other CMS message types.
+@item GPGME_DATA_TYPE_X509_CERT
+The data is a X.509 certificate
+@item GPGME_DATA_TYPE_PKCS12
+The data is a PKCS#12 message.  This is commonly used to exchange
+private keys for X.509.
+@end table
+
+@deftypefun gpgme_data_type_t gpgme_data_identify (@w{gpgme_data_t @var{dh}})
+The function @code{gpgme_data_identify} returns the type of the data
+with the handle @var{dh}.  If it is not possible to perform the
+identification, the function returns zero
+(@code{GPGME_DATA_TYPE_INVALID}).  Note that depending on how the data
+object has been created the identification may not be possible or the
+data object may change its internal state (file pointer moved).  For
+file or memory based data object, the state should not change.
+@end deftypefun
+
 
 @c
 @c    Chapter Contexts
-@c 
+@c
 @node Contexts
 @chapter Contexts
 @cindex context
@@ -1847,10 +2230,12 @@ cryptographic operations.
 @menu
 * Creating Contexts::             Creating new @acronym{GPGME} contexts.
 * Destroying Contexts::           Releasing @acronym{GPGME} contexts.
+* Result Management::             Managing the result of crypto operations.
 * Context Attributes::            Setting properties of a context.
 * Key Management::                Managing keys with @acronym{GPGME}.
 * Trust Item Management::         Managing trust items with @acronym{GPGME}.
 * Crypto Operations::             Using a context for cryptography.
+* Miscellaneous::                 Miscellaneous operations
 * Run Control::                   Controlling how operations are run.
 @end menu
 
@@ -1866,7 +2251,11 @@ and returns a handle for it in @var{ctx}.
 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
 context was successfully created, @code{GPG_ERR_INV_VALUE} if
 @var{ctx} is not a valid pointer, and @code{GPG_ERR_ENOMEM} if not
-enough memory is available.
+enough memory is available.  Also, it returns
+@code{GPG_ERR_NOT_OPERATIONAL} if @code{gpgme_check_version} was not
+called to initialize GPGME, and @code{GPG_ERR_SELFTEST_FAILED} if a
+selftest failed.  Currently, the only selftest is for Windows MingW32
+targets to see if @code{-mms-bitfields} was used (as required).
 @end deftypefun
 
 
@@ -1880,6 +2269,38 @@ The function @code{gpgme_release} destroys the context with the handle
 @end deftypefun
 
 
+@node Result Management
+@section Result Management
+@cindex context, result of operation
+
+The detailed result of an operation is returned in operation-specific
+structures such as @code{gpgme_decrypt_result_t}.  The corresponding
+retrieval functions such as @code{gpgme_op_decrypt_result} provide
+static access to the results after an operation completes.  The
+following interfaces make it possible to detach a result structure
+from its associated context and give it a lifetime beyond that of the
+current operation or context.
+
+@deftypefun void gpgme_result_ref (@w{void *@var{result}})
+The function @code{gpgme_result_ref} acquires an additional reference
+for the result @var{result}, which may be of any type
+@code{gpgme_*_result_t}.  As long as the user holds a reference, the
+result structure is guaranteed to be valid and unmodified.
+@end deftypefun
+
+@deftypefun void gpgme_result_unref (@w{void *@var{result}})
+The function @code{gpgme_result_unref} releases a reference for the
+result @var{result}.  If this was the last reference, the result
+structure will be destroyed and all resources associated to it will be
+released.
+@end deftypefun
+
+Note that a context may hold its own references to result structures,
+typically until the context is destroyed or the next operation is
+started.  In fact, these references are accessed through the
+@code{gpgme_op_*_result} functions.
+
+
 @node Context Attributes
 @section Context Attributes
 @cindex context, attributes
@@ -1889,10 +2310,12 @@ The function @code{gpgme_release} destroys the context with the handle
 * 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.
+* Offline Mode::                  Choosing offline 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.
+* Status Message Callback::       Status messages received from gpg.
 * Locale::                        Setting the locale of a context.
 @end menu
 
@@ -2017,6 +2440,37 @@ valid pointer.
 @end deftypefun
 
 
+@node Offline Mode
+@subsection Offline Mode
+@cindex context, offline mode
+@cindex offline mode
+
+@deftypefun void gpgme_set_offline (@w{gpgme_ctx_t @var{ctx}}, @w{int @var{yes}})
+The function @code{gpgme_set_offline} specifies if offline mode
+should be used.  By default, offline mode is not used.
+
+The offline mode specifies if dirmngr should be used to do additional
+validation that might require connections to external services.
+(e.g. CRL / OCSP checks).
+
+Offline mode only affects the keylist mode @code{GPGME_KEYLIST_MODE_VALIDATE}
+and is only relevant to the CMS crypto engine. Offline mode
+is ignored otherwise.
+
+This option may be extended in the future to completely disable
+the use of dirmngr for any engine.
+
+Offline mode is disabled if @var{yes} is zero, and enabled
+otherwise.
+@end deftypefun
+
+@deftypefun int gpgme_get_offline (@w{gpgme_ctx_t @var{ctx}})
+The function @code{gpgme_get_offline} returns 1 if offline
+mode is enabled, and @code{0} if it is not, or if @var{ctx} is not a
+valid pointer.
+@end deftypefun
+
+
 @node Included Certificates
 @subsection Included Certificates
 @cindex certificates, included
@@ -2074,20 +2528,37 @@ is the default.
 
 @item GPGME_KEYLIST_MODE_EXTERN
 The @code{GPGME_KEYLIST_MODE_EXTERN} symbol specifies that an external
-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.
+source should be searched for keys in the keylisting operation.  The
+type of external source is dependant on the crypto engine used and
+whether it is combined with @code{GPGME_KEYLIST_MODE_LOCAL}.  For
+example, it can be a remote keyserver or LDAP certificate server.
 
 @item GPGME_KEYLIST_MODE_SIGS
 The @code{GPGME_KEYLIST_MODE_SIGS} symbol specifies that the key
 signatures should be included in the listed keys.
 
+@item GPGME_KEYLIST_MODE_SIG_NOTATIONS
+The @code{GPGME_KEYLIST_MODE_SIG_NOTATIONS} symbol specifies that the
+signature notations on key signatures should be included in the listed
+keys.  This only works if @code{GPGME_KEYLIST_MODE_SIGS} is also
+enabled.
+
+@item GPGME_KEYLIST_MODE_WITH_SECRET
+The @code{GPGME_KEYLIST_MODE_WITH_SECRET} returns information about
+the presence of a corresponding secret key in a public key listing.  A
+public key listing with this mode is slower than a standard listing
+but can be used instead of a second run to list the secret keys.  This
+is only supported for GnuPG versions >= 2.1.
+
+@item GPGME_KEYLIST_MODE_EPHEMERAL
+The @code{GPGME_KEYLIST_MODE_EPHEMERAL} symbol specifies that keys
+flagged as ephemeral are included in the listing.
+
 @item GPGME_KEYLIST_MODE_VALIDATE
 The @code{GPGME_KEYLIST_MODE_VALIDATE} symbol specifies that the
 backend should do key or certificate validation and not just get the
 validity information from an internal cache.  This might be an
-expensive operation and is in general not usefule.  Currently only
+expensive operation and is in general not useful.  Currently only
 implemented for the S/MIME backend and ignored for other backends.
 
 @end table
@@ -2096,7 +2567,7 @@ At least one of @code{GPGME_KEYLIST_MODE_LOCAL} and
 @code{GPGME_KEYLIST_MODE_EXTERN} must be specified.  For future binary
 compatibility, you should get the current mode with
 @code{gpgme_get_keylist_mode} and modify it by setting or clearing the
-appropriate bits, and then using that calulcated value in the
+appropriate bits, and then using that calculated value in the
 @code{gpgme_set_keylisting_mode} operation.  This will leave all other
 bits in the mode value intact (in particular those that are not used
 in the current version of the library).
@@ -2143,9 +2614,10 @@ previous attempts failed, then @var{prev_was_bad} is 1, otherwise it
 will be 0.
 
 The user must write the passphrase, followed by a newline character,
-to the file descriptor @var{fd}.  If the user does not return 0
-indicating success, the user must at least write a newline character
-before returning from the callback.
+to the file descriptor @var{fd}.  The function @code{gpgme_io_writen}
+should be used for the write operation.  Note that if the user returns
+0 to indicate 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
@@ -2228,6 +2700,70 @@ the corresponding value will not be returned.
 @end deftypefun
 
 
+@node Status Message Callback
+@subsection Status Message Callback
+@cindex callback, status message
+@cindex status message callback
+
+@deftp {Data type} {gpgme_error_t (*gpgme_status_cb_t)(void *@var{hook}, const char *@var{keyword}, const char *@var{args})}
+@tindex gpgme_status_cb_t
+The @code{gpgme_status_cb_t} type is the type of function usable as
+a status message callback function.
+
+The argument @var{keyword} is the name of the status message while the
+@var{args} argument contains any arguments for the status message.
+
+If an error occurs, return the corresponding @code{gpgme_error_t}
+value. Otherwise, return @code{0}.
+@end deftp
+
+@deftypefun void gpgme_set_status_cb (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_status_cb_t @var{statusfunc}}, @w{void *@var{hook_value}})
+The function @code{gpgme_set_status_cb} sets the function that is used when a
+status message is received from gpg to @var{statusfunc}. The function
+@var{statusfunc} needs to be implemented by the user, and whenever it is
+called, it is called with its first argument being @var{hook_value}.  By
+default, no status message callback function is set.
+
+The user can disable the use of a status message callback function by calling
+@code{gpgme_set_status_cb} with @var{statusfunc} being @code{NULL}.
+@end deftypefun
+
+@deftypefun void gpgme_get_status_cb (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_status_cb_t *@var{statusfunc}}, @w{void **@var{hook_value}})
+The function @code{gpgme_get_status_cb} returns the function that is used to
+process status messages from gpg in @var{*statusfunc}, and the first argument
+for this function in @var{*hook_value}.  If no status message callback is set,
+or @var{ctx} is not a valid pointer, @code{NULL} is returned in both
+variables.
+@end deftypefun
+
+@deftypefun {gpgme_error_t} gpgme_set_ctx_flag  @
+            (@w{gpgme_ctx_t @var{ctx}}, @
+            @w{const char *@var{name}}, @
+            @w{const char *@var{value}})
+
+Some minor properties of the context can be controlled with flags set
+by this function.  The properties are identified by the following
+values for @var{name}:
+
+@table @code
+@item "full-status"
+Using a @var{value} of "1" the status callback set by
+gpgme_set_status_cb returns all status lines with the exception of
+PROGRESS lines.  With the default of "0" the status callback is only
+called in certain situations.
+
+@item "raw-description"
+Setting the @var{value} to "1" returns human readable strings in a raw
+format.  For example the non breaking space characters ("~") will not
+be removed from the @code{description} field of the
+@code{gpgme_tofu_info_t} object.
+
+@end table
+
+This function returns @code{0} on success.
+@end deftypefun
+
+
 @node Locale
 @subsection Locale
 @cindex locale, default
@@ -2274,8 +2810,8 @@ 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} gpgme_sub_key_t
-The @code{gpgme_sub_key_t} type is a pointer to a subkey structure.
+@deftp {Data type} gpgme_subkey_t
+The @code{gpgme_subkey_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
@@ -2285,7 +2821,7 @@ the linked list is also called the primary key.
 The subkey structure has the following members:
 
 @table @code
-@item gpgme_sub_key_t next
+@item gpgme_subkey_t next
 This is a pointer to the next subkey structure in the linked list, or
 @code{NULL} if this is the last element.
 
@@ -2313,8 +2849,16 @@ This is true if the subkey can be used to create key certificates.
 @item unsigned int can_authenticate : 1
 This is true if the subkey can be used for authentication.
 
+@item unsigned int is_qualified : 1
+This is true if the subkey can be used for qualified signatures
+according to local government regulations.
+
 @item unsigned int secret : 1
-This is true if the subkey is a secret key.
+This is true if the subkey is a secret key.  Note that it will be
+false if the key is actually a stub key; i.e. a secret key operation
+is currently not possible (offline-key).  This is only set if a
+listing of secret keys has been requested or if
+@code{GPGME_KEYLIST_MODE_WITH_SECRET} is active.
 
 @item gpgme_pubkey_algo_t pubkey_algo
 This is the public key algorithm supported by this subkey.
@@ -2327,7 +2871,7 @@ This is the key ID of the subkey in hexadecimal digits.
 
 @item char *fpr
 This is the fingerprint of the subkey in hexadecimal digits, if
-available.  This is usually only available for the primary key.
+available.
 
 @item long int timestamp
 This is the creation timestamp of the subkey.  This is -1 if the
@@ -2336,6 +2880,16 @@ 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.
+
+@item unsigned int is_cardkey : 1
+True if the secret key is stored on a smart card.
+
+@item char *card_number
+The serial number of a smart card holding this key or @code{NULL}.
+
+@item char *curve
+For ECC algorithms the name of the curve.
+
 @end table
 @end deftp
 
@@ -2346,7 +2900,13 @@ validate user IDs on the key.
 
 The signatures on a key are only available if the key was retrieved
 via a listing operation with the @code{GPGME_KEYLIST_MODE_SIGS} mode
-enabled, because it is expensive to retrieve all signatures of a key.
+enabled, because it can be expensive to retrieve all signatures of a
+key.
+
+The signature notations on a key signature are only available if the
+key was retrieved via a listing operation with the
+@code{GPGME_KEYLIST_MODE_SIG_NOTATIONS} mode enabled, because it can
+be expensive to retrieve all signature notations.
 
 The key signature structure has the following members:
 
@@ -2401,6 +2961,9 @@ This is the comment component of @code{uid}, if available.
 
 @item char *email
 This is the email component of @code{uid}, if available.
+
+@item gpgme_sig_notation_t notations
+This is a linked list with the notation data and policy URLs.
 @end table
 @end deftp
 
@@ -2481,8 +3044,15 @@ key certificates.
 This is true if the key (ie one of its subkeys) can be used for
 authentication.
 
+@item unsigned int is_qualified : 1
+This is true if the key can be used for qualified signatures according
+to local government regulations.
+
 @item unsigned int secret : 1
-This is true if the key is a secret key.
+This is true if the key is a secret key.  Note, that this will always
+be true even if the corresponding subkey flag may be false
+(offline/stub keys).  This is only set if a listing of secret keys has
+been requested or if @code{GPGME_KEYLIST_MODE_WITH_SECRET} is active.
 
 @item gpgme_protocol_t protocol
 This is the protocol supported by this key.
@@ -2498,12 +3068,12 @@ 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
+@item gpgme_subkey_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.
 
@@ -2522,6 +3092,8 @@ in the list is the main (or primary) user ID.
 * Exporting Keys::                Retrieving key data from the key ring.
 * Importing Keys::                Adding keys to the key ring.
 * Deleting Keys::                 Removing keys from the key ring.
+* Changing Passphrases::          Change the passphrase of a key.
+* Advanced Key Editing::          Advanced key edit operation.
 @end menu
 
 
@@ -2609,7 +3181,7 @@ The function returns the error code @code{GPG_ERR_INV_VALUE} if
 @end deftypefun
 
 @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
+The function @code{gpgme_op_keylist_end} ends a pending key list
 operation in the context @var{ctx}.
 
 After the operation completed successfully, the result of the key
@@ -2627,6 +3199,7 @@ and e-mail address of the main user ID:
 
 @example
 gpgme_ctx_t ctx;
+gpgme_key_t key;
 gpgme_error_t err = gpgme_new (&ctx);
 
 if (!err)
@@ -2637,15 +3210,19 @@ if (!err)
         err = gpgme_op_keylist_next (ctx, &key);
         if (err)
           break;
-        printf ("%s: %s <%s>\n", key->keyid, key->name, key->email);
+        printf ("%s:", key->subkeys->keyid);
+        if (key->uids && key->uids->name)
+          printf (" %s", key->uids->name);
+        if (key->uids && key->uids->email)
+          printf (" <%s>", key->uids->email);
+        putchar ('\n');
         gpgme_key_release (key);
       @}
     gpgme_release (ctx);
   @}
 if (gpg_err_code (err) != GPG_ERR_EOF)
   @{
-    fprintf (stderr, "%s: can not list keys: %s\n",
-             argv[0], gpgme_strerror (err));
+    fprintf (stderr, "can not list keys: %s\n", gpgme_strerror (err));
     exit (1);
   @}
 @end example
@@ -2685,7 +3262,7 @@ currently active keylist mode is used to retrieve the key.  The key
 will have one reference for the user.
 
 If the key is not found in the keyring, @code{gpgme_get_key} returns
-the error code @code{GPG_ERR_NO_ERROR} and *@var{r_key} will be set to
+the error code @code{GPG_ERR_EOF} and *@var{r_key} will be set to
 @code{NULL}.
 
 The function returns the error code @code{GPG_ERR_INV_VALUE} if
@@ -3059,14 +3636,13 @@ 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
 the crypto engine used by @var{ctx}.  Here is an example for GnuPG as
-the crypto engine:
+the crypto engine (all parameters of OpenPGP key generation are
+documented in the GPG manual):
 
 @example
 <GnupgKeyParms format="internal">
-Key-Type: DSA
-Key-Length: 1024
-Subkey-Type: ELG-E
-Subkey-Length: 1024
+Key-Type: default
+Subkey-Type: default
 Name-Real: Joe Tester
 Name-Comment: with stupid passphrase
 Name-Email: joe@@foo.bar
@@ -3075,7 +3651,8 @@ Passphrase: abc
 </GnupgKeyParms>
 @end example
 
-Here is an example for GpgSM as the crypto engine:
+Here is an example for GpgSM as the crypto engine (all parameters of
+OpenPGP key generation are documented in the GPGSM manual):
 
 @example
 <GnupgKeyParms format="internal">
@@ -3153,17 +3730,57 @@ operation is started on the context.
 @cindex key, export
 @cindex key ring, export from
 
-@deftypefun gpgme_error_t gpgme_op_export (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{pattern}}, @w{unsigned int @var{reserved}}, @w{gpgme_data_t @var{keydata}})
+Exporting keys means the same as running @command{gpg} with the command
+@option{--export}.  However, a mode flag can be used to change the way
+the export works.  The available mode flags are described below, they
+may be or-ed together.
+
+@table @code
+
+@item GPGME_EXPORT_MODE_EXTERN
+If this bit is set, the output is send directly to the default
+keyserver. This is currently only allowed for OpenPGP keys.  It is good
+practise to not send more than a few dozens key to a keyserver at one
+time.  Using this flag requires that the @var{keydata} argument of the
+export function is set to @code{NULL}.
+
+@item GPGME_EXPORT_MODE_MINIMAL
+If this bit is set, the smallest possible key is exported.  For OpenPGP
+keys it removes all signatures except for the latest self-signatures.
+For X.509 keys it has no effect.
+
+
+@item GPGME_EXPORT_MODE_SECRET
+Instead of exporting the public key, the secret key is exported.  This
+may not be combined with @code{GPGME_EXPORT_MODE_EXTERN}.  For X.509
+the export format is PKCS#8.
+
+@item GPGME_EXPORT_MODE_RAW
+If this flag is used with @code{GPGME_EXPORT_MODE_SECRET} for an X.509
+key the export format will be changed to PKCS#1.  This flag may not be
+used with OpenPGP.
+
+@item GPGME_EXPORT_MODE_PKCS12
+If this flag is used with @code{GPGME_EXPORT_MODE_SECRET} for an X.509
+key the export format will be changed to PKCS#12 which also includes
+the certificate.  This flag may not be used with OpenPGP.
+
+@end table
+
+
+
+@deftypefun gpgme_error_t gpgme_op_export (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{pattern}}, @w{gpgme_export_mode_t @var{mode}}, @w{gpgme_data_t @var{keydata}})
 The function @code{gpgme_op_export} extracts public keys and returns
 them in the data buffer @var{keydata}.  The output format of the key
 data returned is determined by the @acronym{ASCII} armor attribute set
-for the context @var{ctx}.
+for the context @var{ctx}, or, if that is not set, by the encoding
+specified for @var{keydata}.
 
 If @var{pattern} is @code{NULL}, all available keys are returned.
 Otherwise, @var{pattern} contains an engine specific expression that
 is used to limit the list to all keys matching the pattern.
 
-@var{reserved} is reserved for future use and must be @code{0}.
+@var{mode} is usually 0; other values are described above.
 
 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
 operation completed successfully, @code{GPG_ERR_INV_VALUE} if
@@ -3171,7 +3788,7 @@ operation completed successfully, @code{GPG_ERR_INV_VALUE} if
 errors that are reported by the crypto engine support routines.
 @end deftypefun
 
-@deftypefun gpgme_error_t gpgme_op_export_start (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{pattern}}, @w{unsigned int @var{reserved}}, @w{gpgme_data_t @var{keydata}})
+@deftypefun gpgme_error_t gpgme_op_export_start (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{pattern}}, @w{gpgme_export_mode_t @var{mode}}, @w{gpgme_data_t @var{keydata}})
 The function @code{gpgme_op_export_start} initiates a
 @code{gpgme_op_export} operation.  It can be completed by calling
 @code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
@@ -3181,18 +3798,19 @@ 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}})
+@deftypefun gpgme_error_t gpgme_op_export_ext (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{pattern}[]}, @w{gpgme_export_mode_t @var{mode}}, @w{gpgme_data_t @var{keydata}})
 The function @code{gpgme_op_export} extracts public keys and returns
 them in the data buffer @var{keydata}.  The output format of the key
 data returned is determined by the @acronym{ASCII} armor attribute set
-for the context @var{ctx}.
+for the context @var{ctx}, or, if that is not set, by the encoding
+specified for @var{keydata}.
 
 If @var{pattern} or @var{*pattern} is @code{NULL}, all available keys
 are returned.  Otherwise, @var{pattern} is a @code{NULL} terminated
 array of strings that are used to limit the list to all keys matching
 at least one of the patterns verbatim.
 
-@var{reserved} is reserved for future use and must be @code{0}.
+@var{mode} is usually 0; other values are described above.
 
 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
 operation completed successfully, @code{GPG_ERR_INV_VALUE} if
@@ -3200,7 +3818,7 @@ operation completed successfully, @code{GPG_ERR_INV_VALUE} if
 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}})
+@deftypefun gpgme_error_t gpgme_op_export_ext_start (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{pattern}[]}, @w{gpgme_export_mode_t @var{mode}}, @w{gpgme_data_t @var{keydata}})
 The function @code{gpgme_op_export_ext_start} initiates a
 @code{gpgme_op_export_ext} operation.  It can be completed by calling
 @code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
@@ -3211,11 +3829,50 @@ if @var{keydata} is not a valid empty data buffer.
 @end deftypefun
 
 
+@deftypefun gpgme_error_t gpgme_op_export_keys (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t keys[]}, @w{gpgme_export_mode_t @var{mode}}, @w{gpgme_data_t @var{keydata}})
+The function @code{gpgme_op_export_keys} extracts public keys and returns
+them in the data buffer @var{keydata}.  The output format of the key
+data returned is determined by the @acronym{ASCII} armor attribute set
+for the context @var{ctx}, or, if that is not set, by the encoding
+specified for @var{keydata}.
+
+The keys to export are taken form the @code{NULL} terminated array
+@var{keys}.  Only keys of the currently selected protocol of
+@var{ctx} which do have a fingerprint set are considered for export.
+Other keys specified by the @var{keys} are ignored.  In particular
+OpenPGP keys retrieved via an external key listing are not included.
+
+@var{mode} is usually 0; other values are described above.
+
+The function returns the error code @code{GPG_ERR_NO_ERROR} if the
+operation completed successfully, @code{GPG_ERR_INV_VALUE} if
+@var{keydata} is not a valid empty data buffer, @code{GPG_ERR_NO_DATA}
+if no useful keys are in @var{keys} and passes through any errors that
+are reported by the crypto engine support routines.
+@end deftypefun
+
+@deftypefun gpgme_error_t gpgme_op_export_keys_start (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t @var{keys}[]}, @w{gpgme_export_mode_t @var{mode}}, @w{gpgme_data_t @var{keydata}})
+The function @code{gpgme_op_export_keys_start} initiates a
+@code{gpgme_op_export_ext} operation.  It can be completed by calling
+@code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
+
+The function returns the error code @code{GPG_ERR_NO_ERROR} if the
+operation could be started successfully, and @code{GPG_ERR_INV_VALUE}
+if @var{keydata} is not a valid empty data buffer, @code{GPG_ERR_NO_DATA}
+if no useful keys are in @var{keys} and passes through any errors that
+are reported by the crypto engine support routines.
+@end deftypefun
+
+
 @node Importing Keys
 @subsection Importing Keys
 @cindex key, import
 @cindex key ring, import to
 
+Importing keys means the same as running @command{gpg} with the command
+@option{--import}.
+
+
 @deftypefun gpgme_error_t gpgme_op_import (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{keydata}})
 The function @code{gpgme_op_import} adds the keys in the data buffer
 @var{keydata} to the key ring of the crypto engine used by @var{ctx}.
@@ -3242,6 +3899,44 @@ import could be started successfully, @code{GPG_ERR_INV_VALUE} if
 and @code{GPG_ERR_NO_DATA} if @var{keydata} is an empty data buffer.
 @end deftypefun
 
+@deftypefun gpgme_error_t gpgme_op_import_keys (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t *@var{keys}})
+The function @code{gpgme_op_import_keys} adds the keys described by the
+@code{NULL} terminated array @var{keys} to the key ring of the crypto
+engine used by @var{ctx}.  This function is the general interface to
+move a key from one crypto engine to another as long as they are
+compatible.  In particular it is used to actually import and make keys
+permanent which have been retrieved from an external source (i.e. using
+@code{GPGME_KEYLIST_MODE_EXTERN}).  @footnote{Thus it is a replacement
+for the usual workaround of exporting and then importing a key to make
+an X.509 key permanent.}
+
+Only keys of the currently selected protocol of @var{ctx} are
+considered for import.  Other keys specified by the @var{keys} are
+ignored.  As of now all considered keys must have been retrieved using
+the same method, that is the used key listing mode must be identical.
+
+After the operation completed successfully, the result can be
+retrieved with @code{gpgme_op_import_result}.
+
+The function returns the error code @code{GPG_ERR_NO_ERROR} if the
+import was completed successfully, @code{GPG_ERR_INV_VALUE} if
+@var{keydata} if @var{ctx} or @var{keydata} is not a valid pointer,
+@code{GPG_ERR_CONFLICT} if the key listing mode does not match, and
+@code{GPG_ERR_NO_DATA} if no keys are considered for export.
+@end deftypefun
+
+@deftypefun gpgme_error_t gpgme_op_import_keys_start (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t *@var{keys}})
+The function @code{gpgme_op_import_keys_start} initiates a
+@code{gpgme_op_import_keys} operation.  It can be completed by calling
+@code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
+
+The function returns the error code @code{GPG_ERR_NO_ERROR} if the
+import was completed successfully, @code{GPG_ERR_INV_VALUE} if
+@var{keydata} if @var{ctx} or @var{keydata} is not a valid pointer,
+@code{GPG_ERR_CONFLICT} if the key listing mode does not match, and
+@code{GPG_ERR_NO_DATA} if no keys are considered for export.
+@end deftypefun
+
 @deftp {Data type} {gpgme_import_status_t}
 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
@@ -3302,34 +3997,34 @@ The number of keys without user ID.
 @item int imported
 The total number of imported keys.
 
-@item imported_rsa
+@item int imported_rsa
 The number of imported RSA keys.
 
-@item unchanged
+@item int unchanged
 The number of unchanged keys.
 
-@item new_user_ids
+@item int new_user_ids
 The number of new user IDs.
 
-@item new_sub_keys
+@item int new_sub_keys
 The number of new sub keys.
 
-@item new_signatures
+@item int new_signatures
 The number of new signatures.
 
-@item new_revocations
+@item int new_revocations
 The number of new revocations.
 
-@item secret_read
+@item int secret_read
 The total number of secret keys read.
 
-@item secret_imported
+@item int secret_imported
 The number of imported secret keys.
 
-@item secret_unchanged
+@item int secret_unchanged
 The number of unchanged secret keys.
 
-@item not_imported
+@item int not_imported
 The number of keys not imported.
 
 @item gpgme_import_status_t imports
@@ -3397,6 +4092,103 @@ operation was started successfully, and @code{GPG_ERR_INV_VALUE} if
 @end deftypefun
 
 
+@node Changing Passphrases
+@subsection  Changing Passphrases
+@cindex passphrase, change
+
+@deftypefun gpgme_error_t gpgme_op_passwd      @
+             (@w{gpgme_ctx_t @var{ctx}},       @
+              @w{const gpgme_key_t @var{key}}, @
+              @w{unsigned int @var{flags}})
+
+The function @code{gpgme_op_passwd} changes the passphrase of the
+private key associated with @var{key}.  The only allowed value for
+@var{flags} is @code{0}.  The backend engine will usually popup a window
+to ask for the old and the new passphrase.  Thus this function is not
+useful in a server application (where passphrases are not required
+anyway).
+
+Note that old @code{gpg} engines (before version 2.0.15) do not support
+this command and will silently ignore it.
+@end deftypefun
+
+@deftypefun gpgme_error_t gpgme_op_passwd_start      @
+             (@w{gpgme_ctx_t @var{ctx}},       @
+              @w{const gpgme_key_t @var{key}}, @
+              @w{unsigned int @var{flags}})
+
+The function @code{gpgme_op_passwd_start} initiates a
+@code{gpgme_op_passwd} operation.    It can be completed by calling
+@code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
+
+The function returns @code{0} if the operation was started successfully,
+and an error code if one of the arguments is not valid or the oepration
+could not be started.
+@end deftypefun
+
+
+@node Advanced Key Editing
+@subsection Advanced Key Editing
+@cindex key, edit
+
+@deftp {Data type} {gpgme_error_t (*gpgme_edit_cb_t) (@w{void *@var{handle}}, @w{gpgme_status_code_t @var{status}}, @w{const char *@var{args}}, @w{int @var{fd}})}
+@tindex gpgme_edit_cb_t
+The @code{gpgme_edit_cb_t} type is the type of functions which
+@acronym{GPGME} calls if it a key edit operation is on-going.  The
+status code @var{status} and the argument line @var{args} are passed
+through by @acronym{GPGME} from the crypto engine.  The file
+descriptor @var{fd} is -1 for normal status messages.  If @var{status}
+indicates a command rather than a status message, the response to the
+command should be written to @var{fd}.  The @var{handle} is provided
+by the user at start of operation.
+
+The function should return @code{GPG_ERR_NO_ERROR} or an error value.
+@end deftp
+
+@deftypefun gpgme_error_t gpgme_op_edit (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t @var{key}}, @w{gpgme_edit_cb_t @var{fnc}}, @w{void *@var{handle}}, @w{gpgme_data_t @var{out}})
+The function @code{gpgme_op_edit} processes the key @var{KEY}
+interactively, using the edit callback function @var{FNC} with the
+handle @var{HANDLE}.  The callback is invoked for every status and
+command request from the crypto engine.  The output of the crypto
+engine is written to the data object @var{out}.
+
+Note that the protocol between the callback function and the crypto
+engine is specific to the crypto engine and no further support in
+implementing this protocol correctly is provided by @acronym{GPGME}.
+
+The function returns the error code @code{GPG_ERR_NO_ERROR} if the
+edit operation completes successfully, @code{GPG_ERR_INV_VALUE} if
+@var{ctx} or @var{key} is not a valid pointer, and any error returned
+by the crypto engine or the edit callback handler.
+@end deftypefun
+
+@deftypefun gpgme_error_t gpgme_op_edit_start (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t @var{key}}, @w{gpgme_edit_cb_t @var{fnc}}, @w{void *@var{handle}}, @w{gpgme_data_t @var{out}})
+The function @code{gpgme_op_edit_start} initiates a
+@code{gpgme_op_edit} operation.  It can be completed by calling
+@code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
+
+The function returns the error code @code{GPG_ERR_NO_ERROR} if the
+operation was started successfully, and @code{GPG_ERR_INV_VALUE} if
+@var{ctx} or @var{key} is not a valid pointer.
+@end deftypefun
+
+
+@deftypefun gpgme_error_t gpgme_op_card_edit (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t @var{key}}, @w{gpgme_edit_cb_t @var{fnc}}, @w{void *@var{handle}}, @w{gpgme_data_t @var{out}})
+The function @code{gpgme_op_card_edit} is analogous to
+@code{gpgme_op_edit}, but should be used to process the smart card corresponding to the key @var{key}.
+@end deftypefun
+
+@deftypefun gpgme_error_t gpgme_op_card_edit_start (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t @var{key}}, @w{gpgme_edit_cb_t @var{fnc}}, @w{void *@var{handle}}, @w{gpgme_data_t @var{out}})
+The function @code{gpgme_op_card_edit_start} initiates a
+@code{gpgme_op_card_edit} operation.  It can be completed by calling
+@code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
+
+The function returns the error code @code{GPG_ERR_NO_ERROR} if the
+operation was started successfully, and @code{GPG_ERR_INV_VALUE} if
+@var{ctx} or @var{key} is not a valid pointer.
+@end deftypefun
+
+
 @node Trust Item Management
 @section Trust Item Management
 @cindex trust item
@@ -3479,7 +4271,7 @@ there is not enough memory for the operation.
 @end deftypefun
 
 @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
+The function @code{gpgme_op_trustlist_end} ends a pending trust list
 operation in the context @var{ctx}.
 
 The function returns the error code @code{GPG_ERR_INV_VALUE} if
@@ -3638,9 +4430,6 @@ 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.
@@ -3666,8 +4455,12 @@ 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
+@item gpgme_recipient_t recipients
 This is a linked list of recipients to which this message was encrypted.
+
+@item char *file_name
+This is the filename of the original plaintext message file if it is
+known, otherwise this is a null pointer.
 @end table
 @end deftp
 
@@ -3689,6 +4482,8 @@ the context.
 @cindex signature, verification
 @cindex cryptographic operation, verification
 @cindex cryptographic operation, signature check
+@cindex signature notation data
+@cindex notation data
 
 @deftypefun gpgme_error_t gpgme_op_verify (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_data_t @var{sig}}, @w{gpgme_data_t @var{signed_text}}, @w{gpgme_data_t @var{plain}})
 The function @code{gpgme_op_verify} verifies that the signature in the
@@ -3737,9 +4532,45 @@ linked list, or @code{NULL} if this is the last element.
 The name of the notation field.  If this is @code{NULL}, then the
 member @code{value} will contain a policy URL.
 
+@item int name_len
+The length of the @code{name} field.  For strings the length is
+counted without the trailing binary zero.
+
 @item char *value
 The value of the notation field.  If @code{name} is @code{NULL}, then
 this is a policy URL.
+
+@item int value_len
+The length of the @code{value} field.  For strings the length is
+counted without the trailing binary zero.
+
+@item gpgme_sig_notation_flags_t flags
+The accumulated flags field.  This field contains the flags associated
+with the notation data in an accumulated form which can be used as an
+argument to the function @code{gpgme_sig_notation_add}.  The value
+@code{flags} is a bitwise-or combination of one or multiple of the
+following bit values:
+
+@table @code
+@item GPGME_SIG_NOTATION_HUMAN_READABLE
+The @code{GPGME_SIG_NOTATION_HUMAN_READABLE} symbol specifies that the
+notation data is in human readable form
+
+@item GPGME_SIG_NOTATION_CRITICAL
+The @code{GPGME_SIG_NOTATION_CRITICAL} symbol specifies that the
+notation data is critical.
+
+@end table
+
+@item unsigned int human_readable : 1
+This is true if the @code{GPGME_SIG_NOTATION_HUMAN_READABLE} flag is
+set and false otherwise.  This flag is only valid for notation data,
+not for policy URLs.
+
+@item unsigned int critical : 1
+This is true if the @code{GPGME_SIG_NOTATION_CRITICAL} flag is set and
+false otherwise.  This flag is valid for notation data and policy URLs.
+
 @end table
 @end deftp
 
@@ -3788,16 +4619,16 @@ The defined bits are:
   Can't verify due to a missing key or certificate.
 
   @item GPGME_SIGSUM_CRL_MISSING
-  The CRL (or an equivalent mechanism) is not available. 
+  The CRL (or an equivalent mechanism) is not available.
 
   @item GPGME_SIGSUM_CRL_TOO_OLD
   Available CRL is too old.
 
   @item GPGME_SIGSUM_BAD_POLICY
-  A policy requirement was not met. 
+  A policy requirement was not met.
 
   @item GPGME_SIGSUM_SYS_ERROR
-  A system error occured. 
+  A system error occured.
   @end table
 
 @item char *fpr
@@ -3855,12 +4686,46 @@ not expire.
 @item unsigned int wrong_key_usage : 1
 This is true if the key was not used according to its policy.
 
+@item unsigned int pka_trust : 2
+This is set to the trust information gained by means of the PKA system.
+Values are:
+  @table @code
+  @item 0
+        No PKA information available or verification not possible.
+  @item 1
+        PKA verification failed.
+  @item 2
+        PKA verification succeeded.
+  @item 3
+        Reserved for future use.
+  @end table
+Depending on the configuration of the engine, this metric may also be
+reflected by the validity of the signature.
+
+@item unsigned int chain_model : 1
+This is true if the validity of the signature has been checked using the
+chain model.  In the chain model the time the signature has been created
+must be within the validity period of the certificate and the time the
+certificate itself has been created must be within the validity period
+of the issuing certificate.  In contrast the default validation model
+checks the validity of signature as well at the entire certificate chain
+at the current time.
+
+
 @item gpgme_validity_t validity
 The validity of the signature.
 
 @item gpgme_error_t validity_reason
 If a signature is not valid, this provides a reason why.
 
+@item gpgme_pubkey_algo_t
+The public key algorithm used to create this signature.
+
+@item gpgme_hash_algo_t
+The hash algorithm used to create this signature.
+
+@item char *pka_address
+The mailbox from the PKA information or @code{NULL}.
 @end table
 @end deftp
 
@@ -3875,6 +4740,10 @@ a @code{NULL} pointer.  The structure contains the following member:
 @item gpgme_signature_t signatures
 A linked list with information about all signatures for which a
 verification was attempted.
+
+@item char *file_name
+This is the filename of the original plaintext message file if it is
+known, otherwise this is a null pointer.
 @end table
 @end deftp
 
@@ -3947,7 +4816,7 @@ have a different status.  You can get each key's status with
 
 @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;
@@ -3970,27 +4839,27 @@ The function @code{gpgme_get_sig_status} is equivalent to:
        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;
@@ -4004,7 +4873,7 @@ The function @code{gpgme_get_sig_status} is equivalent to:
 
 @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;
@@ -4040,7 +4909,7 @@ The function @code{gpgme_get_sig_string_attr} is equivalent to:
 
 @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;
@@ -4072,22 +4941,22 @@ The function @code{gpgme_get_sig_ulong_attr} is equivalent to:
        @{
        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;
        @}
@@ -4185,6 +5054,7 @@ set is changed).
 @menu
 * Selecting Signers::             How to choose the keys to sign with.
 * Creating a Signature::          How to create a signature.
+* Signature Notation Data::       How to add notation data to a signature.
 @end menu
 
 
@@ -4208,6 +5078,11 @@ list of signers in the context @var{ctx}.
 Calling this function acquires an additional reference for the key.
 @end deftypefun
 
+@deftypefun @w{unsigned int} gpgme_signers_count (@w{const gpgme_ctx_t @var{ctx}})
+The function @code{gpgme_signers_count} returns the number of signer keys in
+the context @var{ctx}.
+@end deftypefun
+
 @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
@@ -4243,7 +5118,8 @@ mode settings of the context are ignored.
 The function @code{gpgme_op_sign} creates a signature for the text in
 the data object @var{plain} and returns it in the data object
 @var{sig}.  The type of the signature created is determined by the
-@acronym{ASCII} armor and text mode attributes set for the context
+@acronym{ASCII} armor (or, if that is not set, by the encoding
+specified for @var{sig}), the text mode attributes set for the context
 @var{ctx} and the requested signature mode @var{mode}.
 
 After the operation completed successfully, the result can be
@@ -4286,10 +5162,10 @@ list, or @code{NULL} if this is the last element.
 @item gpgme_sig_mode_t type
 The type of this signature.
 
-@item gpgme_pubkey_algo_t
+@item gpgme_pubkey_algo_t pubkey_algo
 The public key algorithm used to create this signature.
 
-@item gpgme_hash_algo_t
+@item gpgme_hash_algo_t hash_algo
 The hash algorithm used to create this signature.
 
 @item unsigned int sig_class
@@ -4327,12 +5203,64 @@ 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
+failed, the function might return a @code{NULL} pointer. The returned
 pointer is only valid until the next operation is started on the
 context.
 @end deftypefun
 
 
+@node Signature Notation Data
+@subsubsection Signature Notation Data
+@cindex notation data
+@cindex signature notation data
+@cindex policy URL
+
+Using the following functions, you can attach arbitrary notation data
+to a signature.  This information is then available to the user when
+the signature is verified.
+
+@deftypefun void gpgme_sig_notation_clear (@w{gpgme_ctx_t @var{ctx}})
+The function @code{gpgme_sig_notation_clear} removes the notation data
+from the context @var{ctx}.  Subsequent signing operations from this
+context will not include any notation data.
+
+Every context starts with an empty notation data list.
+@end deftypefun
+
+@deftypefun gpgme_error_t gpgme_sig_notation_add (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{name}}, @w{const char *@var{value}}, @w{gpgme_sig_notation_flags_t @var{flags}})
+The function @code{gpgme_sig_notation_add} adds the notation data with
+the name @var{name} and the value @var{value} to the context
+@var{ctx}.
+
+Subsequent signing operations will include this notation data, as well
+as any other notation data that was added since the creation of the
+context or the last @code{gpgme_sig_notation_clear} operation.
+
+The arguments @var{name} and @var{value} must be @code{NUL}-terminated
+strings in human-readable form.  The flag
+@code{GPGME_SIG_NOTATION_HUMAN_READABLE} is implied
+(non-human-readable notation data is currently not supported).  The
+strings must be in UTF-8 encoding.
+
+If @var{name} is @code{NULL}, then @var{value} should be a policy URL.
+
+The function @code{gpgme_sig_notation_add} returns the error code
+@code{GPG_ERR_NO_ERROR} if the notation data could be added
+successfully, @code{GPG_ERR_INV_VALUE} if @var{ctx} is not a valid
+pointer, or if @var{name}, @var{value} and @var{flags} are an invalid
+combination.  The function also passes through any errors that are
+reported by the crypto engine support routines.
+@end deftypefun
+
+@deftypefun gpgme_sig_notation_t gpgme_sig_notation_get (@w{const gpgme_ctx_t @var{ctx}})
+The function @code{gpgme_sig_notation_get} returns the linked list of
+notation data structures that are contained in the context @var{ctx}.
+
+If @var{ctx} is not a valid pointer, or there is no notation data
+added for this context, @code{NULL} is returned.
+@end deftypefun
+
+
 @node Encrypt
 @subsection Encrypt
 @cindex encryption
@@ -4351,13 +5279,14 @@ and then passed to the encryption operation.
 @subsubsection Encrypting a Plaintext
 
 @deftypefun gpgme_error_t gpgme_op_encrypt (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_key_t @var{recp}[]}, @w{gpgme_encrypt_flags_t @var{flags}}, @w{gpgme_data_t @var{plain}}, @w{gpgme_data_t @var{cipher}})
-The function @code{gpgme_op_encrypt} encrypts the plaintext in the data
-object @var{plain} for the recipients @var{recp} and stores the
+The function @code{gpgme_op_encrypt} encrypts the plaintext in the
+data object @var{plain} for the recipients @var{recp} and stores the
 ciphertext in the data object @var{cipher}.  The type of the
-ciphertext created is determined by the @acronym{ASCII} armor and text
-mode attributes set for the context @var{ctx}.
+ciphertext created is determined by the @acronym{ASCII} armor (or, if
+that is not set, by the encoding specified for @var{cipher}) and the
+text mode attributes set for the context @var{ctx}.
 
-@var{key} must be a @code{NULL}-terminated array of keys.  The user
+@var{recp} 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).
@@ -4371,6 +5300,27 @@ The @code{GPGME_ENCRYPT_ALWAYS_TRUST} symbol specifies that all the
 recipients in @var{recp} should be trusted, even if the keys do not
 have a high enough validity in the keyring.  This flag should be used
 with care; in general it is not a good idea to use any untrusted keys.
+
+@item GPGME_ENCRYPT_NO_ENCRYPT_TO
+The @code{GPGME_ENCRYPT_NO_ENCRYPT_TO} symbol specifies that no
+default or hidden default recipients as configured in the crypto
+backend should be included.  This can be useful for managing different
+user profiles.
+
+@item GPGME_ENCRYPT_NO_COMPRESS
+The @code{GPGME_ENCRYPT_NO_COMPRESS} symbol specifies that the
+plaintext shall not be compressed before it is encrypted.  This is
+in some cases useful if the length of the encrypted message
+may reveal information about the plaintext.
+
+@item GPGME_ENCRYPT_PREPARE
+@itemx GPGME_ENCRYPT_EXPECT_SIGN
+The @code{GPGME_ENCRYPT_PREPARE} symbol is used with the UI Server
+protocol to prepare an encryption (i.e. sending the
+@code{PREP_ENCRYPT} command).  With the
+@code{GPGME_ENCRYPT_EXPECT_SIGN} symbol the UI Server is advised to
+also expect a sign command.
+
 @end table
 
 If @code{GPG_ERR_UNUSABLE_PUBKEY} is returned, some recipients in
@@ -4462,6 +5412,67 @@ pointer.
 @end deftypefun
 
 
+@node Miscellaneous
+@section Miscellaneous operations
+
+Here are some support functions which are sometimes useful.
+
+@menu
+* Running other Programs::      Running other Programs
+@end menu
+
+
+@node Running other Programs
+@subsection Running other Programs
+
+GPGME features an internal subsystem to run the actual backend
+engines.  Along with data abstraction object this subsystem can be
+used to run arbitrary simple programs which even need not be related
+to cryptographic features.  It may for example be used to run tools
+which are part of the GnuPG system but are not directly accessible
+with the GPGME API.
+
+
+@deftypefun gpgme_error_t gpgme_op_spawn
+            (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{file}}, @
+             @w{const char *@var{argv}[]}, @w{gpgme_data_t @var{datain}}, @
+             @w{gpgme_data_t @var{dataout}}, @w{gpgme_data_t @var{dataerr}}, @
+             @w{unsigned int @var{flags}})
+
+The function @code{gpgme_op_spawn} runs the program @var{file} with
+the arguments taken from the NULL terminated array @var{argv}.  If no
+arguments are required @var{argv} may be given as @code{NULL}.  In the
+latter case or if @code{argv[0]} is the empty string, GPGME uses the
+basename of @var{file} for @code{argv[0]}.  The file descriptors
+@code{stdin}, @code{stdout}, and @code{stderr} are connected to the
+data objects @var{datain}, @var{dataout}, and @var{dataerr}.  If NULL
+is passed for one of these data objects the corresponding file
+descriptor is connected to @file{/dev/null}.
+
+The value in @var{flags} is a bitwise-or combination of one or
+multiple of the following bit values:
+
+@table @code
+@item GPGME_SPAWN_DETACHED
+Under Windows this flag inhibits the allocation of a new console for
+the program.  This is useful for a GUI application which needs to call
+a command line helper tool.
+@item GPGME_SPAWN_ALLOW_SET_FG
+Under Windows this flag allows the called program to put itself into
+the foreground.
+@end table
+@end deftypefun
+
+@deftypefun gpgme_error_t gpgme_op_spawn_start
+            (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{file}}, @
+             @w{const char *@var{argv}[]}, @w{gpgme_data_t @var{datain}}, @
+             @w{gpgme_data_t @var{dataout}}, @w{gpgme_data_t @var{dataerr}}, @
+             @w{unsigned int @var{flags}})
+
+This is the asynchronous variant of @code{gpgme_op_spawn}.
+@end deftypefun
+
+
 @node Run Control
 @section Run Control
 @cindex run control
@@ -4550,7 +5561,7 @@ decide when to check the file descriptors and when to invoke the
 callback functions.  Usually this is done in an event loop, that also
 checks for events in other parts of the program.  If the callback
 functions are only called when the file descriptors are ready,
-@acronym{GPGME} will never block.  This gives the user mroe control
+@acronym{GPGME} will never block.  This gives the user more control
 over the program flow, and allows to perform other tasks when
 @acronym{GPGME} would block otherwise.
 
@@ -4589,7 +5600,7 @@ the return value to be reserved for later use.
 @deftp {Data type} {gpgme_error_t (*gpgme_register_io_cb_t) (@w{void *@var{data}}, @w{int @var{fd}}, @w{int @var{dir}}, @w{gpgme_io_cb_t @var{fnc}}, @w{void *@var{fnc_data}}, @w{void **@var{tag}})}
 @tindex gpgme_register_io_cb_t
 The @code{gpgme_register_io_cb_t} type is the type of functions which can
-be called by @acronym{GPGME} to register an I/O callback funtion
+be called by @acronym{GPGME} to register an I/O callback function
 @var{fnc} for the file descriptor @var{fd} with the user.
 @var{fnc_data} should be passed as the first argument to @var{fnc}
 when the handler is invoked (the second argument should be @var{fd}).
@@ -4642,9 +5653,9 @@ 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{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.
+@code{struct gpgme_io_event_done_data} 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
@@ -4682,7 +5693,7 @@ list of possible @code{gpgme_event_io_t} types.
 @node Registering I/O Callbacks
 @subsubsection Registering I/O Callbacks
 
-@deftp {Data type} {struct gpgme_io_cb_ts}
+@deftp {Data type} {struct gpgme_io_cbs}
 @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:
@@ -4692,7 +5703,7 @@ described in the previous section.  It has the following members:
 This is the function called by @acronym{GPGME} to register an I/O
 callback handler.  It must be specified.
 
-@item void *add_data
+@item void *add_priv
 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.
@@ -4703,17 +5714,17 @@ callback handler.  It must be specified.
 
 @item gpgme_event_io_cb_t event
 This is the function called by @acronym{GPGME} to signal an event for
-an operation.  It is optional, but if you don't specify it, you can
-not retrieve the return value of the operation.
+an operation.  It must be specified, because at least the start event
+must be processed.
 
-@item void *event_data
+@item void *event_priv
 This is passed as the first argument to the @code{event} function when
 it is called by @acronym{GPGME}.  For example, it can be used to
 determine the context in which the event has occured.
 @end table
 @end deftp
 
-@deftypefun void gpgme_set_io_cbs (@w{gpgme_ctx_t @var{ctx}}, @w{struct gpgme_io_cb_ts *@var{io_cbs}})
+@deftypefun void gpgme_set_io_cbs (@w{gpgme_ctx_t @var{ctx}}, @w{struct gpgme_io_cbs *@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}.
@@ -4722,7 +5733,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{gpgme_ctx_t @var{ctx}}, @w{struct gpgme_io_cb_ts *@var{io_cbs}})
+@deftypefun void gpgme_get_io_cbs (@w{gpgme_ctx_t @var{ctx}}, @w{struct gpgme_io_cbs *@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
@@ -4738,13 +5749,16 @@ monitor these file descriptors for activity and call the appropriate
 I/O callbacks.
 
 The following example illustrates how to do that.  The example uses
-locking to show in which way the the callbacks and the event loop can
+locking to show in which way the callbacks and the event loop can
 run concurrently.  For the event loop, we use a fixed array.  For a
 real-world implementation, you should use a dynamically sized
 structure because the number of file descriptors needed for a crypto
 operation in @acronym{GPGME} is not predictable.
 
 @example
+#include <assert.h>
+#include <errno.h>
+#include <stdlib.h>
 #include <pthread.h>
 #include <sys/types.h>
 #include <gpgme.h>
@@ -4764,6 +5778,7 @@ struct one_fd
   int dir;
   gpgme_io_cb_t fnc;
   void *fnc_data;
+  void *loop;
 @};
 
 struct event_loop
@@ -4795,6 +5810,7 @@ add_io_cb (void *data, int fd, int dir, gpgme_io_cb_t fnc, void *fnc_data,
          fds[i].dir = dir;
          fds[i].fnc = fnc;
          fds[i].fnc_data = fnc_data;
+         fds[i].loop = loop;
          break;
        @}
     @}
@@ -4809,6 +5825,7 @@ void
 remove_io_cb (void *tag)
 @{
   struct one_fd *fd = tag;
+  struct event_loop *loop = fd->loop;
 
   pthread_mutex_lock (&loop->lock);
   fd->fd = -1;
@@ -4840,11 +5857,12 @@ do_select (struct event_loop *loop)
   fd_set wfds;
   int i, n;
   int any = 0;
+  struct one_fd *fdlist = loop->fds;
 
   pthread_mutex_lock (&loop->lock);
   FD_ZERO (&rfds);
   FD_ZERO (&wfds);
-  for (i = 0; i < FDLIST_MAX; i++)
+  for (i = 0; i < MAX_FDS; i++)
     if (fdlist[i].fd != -1)
       FD_SET (fdlist[i].fd, fdlist[i].dir ? &rfds : &wfds);
   pthread_mutex_unlock (&loop->unlock);
@@ -4859,7 +5877,7 @@ do_select (struct event_loop *loop)
     return n;  /* Error or timeout.  */
 
   pthread_mutex_lock (&loop->lock);
-  for (i = 0; i < FDLIST_MAX && n; i++)
+  for (i = 0; i < MAX_FDS && n; i++)
     @{
       if (fdlist[i].fd != -1)
        @{
@@ -4890,7 +5908,6 @@ wait_for_op (struct event_loop *loop, struct op_result *result)
       ret = do_select (loop);
     @}
   while (ret >= 0 && !result->done);
-  return ret;
 @}
 @end example
 
@@ -4905,9 +5922,8 @@ main (int argc, char *argv[])
   gpgme_ctx_t ctx;
   gpgme_error_t err;
   gpgme_data_t sig, text;
-  gpgme_sig_stat_t status;
   int i;
-  struct gpgme_io_cb_ts io_cbs =
+  struct gpgme_io_cbs io_cbs =
   @{
     add_io_cb,
     &loop,
@@ -4916,8 +5932,10 @@ main (int argc, char *argv[])
     &result
   @};
 
+  init_gpgme (void);
+
   /* Initialize the loop structure.  */
-  loop.lock = PTHREAD_MUTEX_INITIALIZER;
+  pthread_mutex_init (&loop.lock, NULL);
   for (i = 0; i < MAX_FDS; i++)
     loop->fds[i].fd = -1;
 
@@ -4932,7 +5950,7 @@ main (int argc, char *argv[])
   if (!err)
     @{
        gpgme_set_io_cbs (ctx, &io_cbs);
-       err = gpgme_op_verify_start (ctx, sig, text, &status);
+       err = gpgme_op_verify_start (ctx, sig, text, NULL);
     @}
   if (err)
     @{
@@ -4953,7 +5971,7 @@ main (int argc, char *argv[])
                gpgme_strsource (result.err), gpgme_strerror (result.err));
       exit (1);
     @}
-  /* Evaluate STATUS.  */
+  /* Evaluate verify result.  */
   @dots{}
   return 0;
 @}
@@ -5091,7 +6109,7 @@ struct IOCB @{
 class MyApp : public QApplication @{
 
   // ...
-  
+
   static void registerGpgmeIOCallback( void * data, int fd, int dir,
                                        GpgmeIOCb func, void * func_data,
                                        void ** tag ) @{
@@ -5140,13 +6158,15 @@ private:
 @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.
+Sometimes you do not want to wait for an operation to finish.
+@acronym{GPGME} provides two different functions to achieve that.  The
+function @code{gpgme_cancel} takes effect immediately.  When it
+returns, the operation is effectively canceled.  However, it has some
+limitations and can not be used with synchronous operations.  In
+contrast, the function @code{gpgme_cancel_async} can be used with any
+context and from any thread, but it is not guaranteed to take effect
+immediately.  Instead, cancellation occurs at the next possible time
+(typically the next time I/O occurs in the target context).
 
 @deftypefun gpgme_ctx_t gpgme_cancel (@w{gpgme_ctx_t @var{ctx}})
 The function @code{gpgme_cancel} attempts to cancel a pending
@@ -5154,37 +6174,94 @@ 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
+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
+If you use 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.
+event with the error code @code{GPG_ERR_CANCEL} will be signalled.
 
 The function returns an error code if the cancellation failed (in this
 case the state of @var{ctx} is not modified).
 @end deftypefun
 
 
+@deftypefun gpgme_ctx_t gpgme_cancel_async (@w{gpgme_ctx_t @var{ctx}})
+The function @code{gpgme_cancel} attempts to cancel a pending
+operation in the context @var{ctx}.  This can be called by any thread
+at any time after starting an operation on the context, but will not
+take effect immediately.  The actual cancellation happens at the next
+time GPGME processes I/O in that context.
+
+The function returns an error code if the cancellation failed (in this
+case the state of @var{ctx} is not modified).
+@end deftypefun
+
+@c **********************************************************
+@c *******************  Appendices  *************************
+@c **********************************************************
+
+@include uiserver.texi
+
+@node Debugging
+@appendix How to solve problems
+@cindex debug
+@cindex GPGME_DEBUG
+
+Everyone knows that software often does not do what it should do and thus
+there is a need to track down problems.  This is in particular true
+for applications using a complex library like @acronym{GPGME} and of
+course also for the library itself.  Here we give a few hints on how
+to solve such problems.
+
+First of all you should make sure that the keys you want to use are
+installed in the GnuPG engine and are usable.  Thus the first test is
+to run the desired operation using @command{gpg} or @command{gpgsm} on
+the command line.  If you can't figure out why things don't work, you
+may use @acronym{GPGME}'s built in trace feature.  This feature is
+either enabled using the environment variable @code{GPGME_DEBUG} or,
+if this is not possible, by calling the function
+@code{gpgme_set_global_flag}.  The value is the trace level and
+an optional file name.  If no file name is given the trace output is
+printed to @code{stderr}.
+
+@noindent
+For example
+@smallexample
+GPGME_DEBUG=9:/home/user/mygpgme.log
+@end smallexample
+@noindent
+(Note that under Windows you use a semicolon in place of the colon to
+separate the fields.)
+
+A trace level of 9 is pretty verbose and thus you may want to start
+off with a lower level.  The exact definition of the trace levels and
+the output format may change with any release; you need to check the
+source code for details.  In any case the trace log should be helpful
+to understand what is going going on.  Warning: The trace log may
+reveal sensitive details like passphrases or other data you use in
+your application.  If you are asked to send a log file, make sure that
+you run your tests only with play data.
+
+
+
 @include lesser.texi
 
+@include gpl.texi
 
 @node Concept Index
 @unnumbered Concept Index
 
 @printindex cp
 
-
 @node Function and Data Index
 @unnumbered Function and Data Index
 
 @printindex fn
 
 
-@summarycontents
-@contents
 @bye