Adjust configure.ac for modern autoconf.
[gpgme.git] / doc / gpgme.texi
index c1f9e61..72b9e22 100644 (file)
@@ -1,4 +1,5 @@
-\input texinfo                  @c -*- Texinfo -*-
+\input texinfo                   @c -*- mode: texinfo; coding: latin-1; -*-
+@documentencoding ISO-8859-1
 @setfilename gpgme.info
 @settitle The `GnuPG Made Easy' Reference Manual
 
@@ -7,12 +8,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 g10 Code GmbH.
+
+@quotation
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU General Public License as published by the
+Free Software Foundation; either version 3 of the License, or (at your
+option) any later version. The text of the license can be found in the
+section entitled ``Copying''.
+@end quotation
+
+This document is distributed in the hope that it will be useful, but
+WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+General Public License for more details.
+@end copying
+
+@include version.texi
+
+@c Macros used by the description of the UI server protocol
+@macro clnt
+  @sc{c:} @c
+@end macro
+@macro srvr
+  @sc{s:} @c
+@end macro
+
+
+@c 
+@c  T I T L E  P A G E
+@c
 @ifinfo
 This file documents the @acronym{GPGME} library.
 
@@ -20,22 +51,15 @@ This is Edition @value{EDITION}, last updated @value{UPDATED}, of
 @cite{The `GnuPG Made Easy' Reference Manual}, for Version
 @value{VERSION}.
 
-Copyright @copyright{} 2002, 2003, 2004 g10 Code GmbH.
-
-Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.1 or
-any later version published by the Free Software Foundation; with the
-Invariant Sections being ``Free Software Needs Free Documentation'' and
-``GNU Lesser General Public License'', the Front-Cover texts being (a)
-(see below), and with the Back-Cover Texts being (b) (see below).  A
-copy of the license is included in the section entitled ``GNU Free
-Documentation License''.
+@c NOTE: Don't forget to update the year for the TeX version, too.
+@insertcopying
 
 @end ifinfo
 
-@iftex
-@shorttitlepage The `GnuPG Made Easy' Reference Manual
-@end iftex
+@c We do not want that bastard short titlepage.
+@c @iftex
+@c @shorttitlepage The `GnuPG Made Easy' Reference Manual
+@c @end iftex
 @titlepage
 @center @titlefont{The `GnuPG Made Easy'}
 @sp 1
@@ -48,19 +72,15 @@ Documentation License''.
 @center for version @value{VERSION}
 @page
 @vskip 0pt plus 1filll
-Copyright @copyright{} 2002, 2003 g10 Code GmbH.
+Published by g10 Code GmbH@* Hüttenstr. 61@* 40699 Erkrath, Germany
 
-Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.1 or
-any later version published by the Free Software Foundation; with the
-Invariant Sections being ``Free Software Needs Free Documentation'' and
-``GNU Lesser General Public License'', the Front-Cover texts being (a)
-(see below), and with the Back-Cover Texts being (b) (see below).  A
-copy of the license is included in the section entitled ``GNU Free
-Documentation License''.
+@insertcopying
 @end titlepage
 @page
 
+@summarycontents
+@contents
+
 @ifnottex
 @node Top
 @top Main Menu
@@ -80,10 +100,12 @@ This is Edition @value{EDITION}, last updated @value{UPDATED}, of
 
 Appendices
 
+* UI Server Protocol::            The GnuPG UI Server Protocol.
+
+* Library Copying::               The GNU Lesser General Public License says
+                                  how you can copy and share `GnuPG Made Easy'.
 * Copying::                       The GNU General Public License says how you
-                                  can copy and share `GnuPG Made Easy'.
-* Free Documentation License::    This manual is under the GNU Free
-                                  Documentation License.
+                                  can copy and share this manual.
 
 Indices
 
@@ -115,6 +137,7 @@ Protocols and Engines
 
 * Engine Version Check::          Verifying the engine version.
 * Engine Information::            Obtaining more information about the engines.
+* Engine Configuration::          Changing the engine configuration.
 * OpenPGP::                       Support for the OpenPGP protocol.
 * Cryptographic Message Syntax::  Support for the CMS.
 
@@ -142,10 +165,16 @@ Creating Data Buffers
 * File Based Data Buffers::       Creating file based data buffers.
 * Callback Based Data Buffers::   Creating callback based data buffers.
 
+Manipulating Data Buffers
+
+* Data Buffer I/O Operations::    I/O operations on data buffers.
+* Data Buffer Meta-Data::         Meta-data manipulation of data buffers.
+
 Contexts
 
 * Creating Contexts::             Creating new @acronym{GPGME} contexts.
 * Destroying Contexts::           Releasing @acronym{GPGME} contexts.
+* Result Management::             Managing the result of crypto operations.
 * Context Attributes::            Setting properties of a context.
 * Key Management::                Managing keys with @acronym{GPGME}.
 * Trust Item Management::         Managing trust items with @acronym{GPGME}.
@@ -155,6 +184,7 @@ Contexts
 Context Attributes
 
 * Protocol Selection::            Selecting the protocol used by a context.
+* 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.
@@ -173,6 +203,7 @@ Key Management
 * Exporting Keys::                Retrieving key data from the key ring.
 * Importing Keys::                Adding keys to the key ring.
 * Deleting Keys::                 Removing keys from the key ring.
+* Advanced Key Editing::          Advanced key edit operation.
 
 Trust Item Management
 
@@ -192,6 +223,7 @@ 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
 
@@ -268,7 +300,7 @@ engines into your application directly.
 @table @asis
 @item it's free software
 Anybody can use, modify, and redistribute it under the terms of the GNU
-General Public License (@pxref{Copying}).
+Lesser General Public License (@pxref{Library Copying}).
 
 @item it's flexible
 @acronym{GPGME} provides transparent support for several cryptographic
@@ -547,13 +579,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
@@ -572,6 +608,11 @@ 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
 
 
@@ -585,19 +626,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
@@ -722,11 +766,26 @@ 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_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.
@@ -735,6 +794,7 @@ allocated string describing the protocol @var{protocol}, or
 @menu
 * Engine Version Check::          Verifying the engine version.
 * Engine Information::            Obtaining more information about the engines.
+* Engine Configuration::          Changing the engine configuration.
 * OpenPGP::                       Support for the OpenPGP protocol.
 * Cryptographic Message Syntax::  Support for the CMS.
 @end menu
@@ -779,6 +839,11 @@ This is a string holding the file name of the executable of the crypto
 engine.  Currently, it is never @code{NULL}, but using @code{NULL} is
 reserved for future use, so always check before you use it.
 
+@item const char *home_dir
+This is a string holding the directory name of the crypto engine's
+configuration directory.  If it is @code{NULL}, then the default
+directory is used.
+
 @item const char *version
 This is a string containing the version number of the crypto engine.
 It might be @code{NULL} if the version number can not be determined,
@@ -793,10 +858,10 @@ reserved for future use, so always check before you use it.
 @end table
 @end deftp
 
-@deftypefun gpgme_error_t gpgme_get_engine_info (gpgme_engine_info_t *info)
+@deftypefun gpgme_error_t gpgme_get_engine_info (@w{gpgme_engine_info_t *@var{info}})
 The function @code{gpgme_get_engine_info} returns a linked list of
 engine info structures in @var{info}.  Each info structure describes
-one configured backend.
+the defaults of one configured backend.
 
 The memory for the info structures is allocated the first time this
 function is invoked, and must not be freed by the caller.
@@ -825,12 +890,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",
@@ -840,6 +905,37 @@ if (gpgme_err_code (err) == GPG_ERR_INV_ENGINE)
 @end example
 
 
+@node Engine Configuration
+@section Engine Configuration
+@cindex engine, configuration of
+@cindex configuration of crypto backend
+
+You can change the configuration of a backend engine, and thus change
+the executable program and configuration directory to be used.  You
+can make these changes the default or set them for some contexts
+individually.
+
+@deftypefun gpgme_error_t gpgme_set_engine_info (@w{gpgme_protocol_t @var{proto}}, @w{const char *@var{file_name}}, @w{const char *@var{home_dir}})
+The function @code{gpgme_set_engine_info} changes the default
+configuration of the crypto engine implementing the protocol
+@var{proto}.
+
+@var{file_name} is the file name of the executable program
+implementing this protocol, and @var{home_dir} is the directory name
+of the configuration directory for this crypto engine.  If
+@var{home_dir} is @code{NULL}, the engine's default will be used.
+
+The new defaults are not applied to already created GPGME contexts.
+
+This function returns the error code @code{GPG_ERR_NO_ERROR} if
+successful, or an eror code on failure.
+@end deftypefun
+
+The functions @code{gpgme_ctx_get_engine_info} and
+@code{gpgme_ctx_set_engine_info} can be used to change the engine
+configuration per context.  @xref{Crypto Engine}.
+
+
 @node OpenPGP
 @section OpenPGP
 @cindex OpenPGP
@@ -874,8 +970,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.
@@ -917,6 +1015,18 @@ This value indicates ElGamal.
 
 @item GPGME_PK_ELG_E
 This value also indicates ElGamal and is used specifically in GnuPG.
+
+@item GPGME_PK_ELG_E
+This value also indicates ElGamal and is used specifically in GnuPG.
+
+@item GPGME_PK_ECDSA
+This value indicates ECDSA, the Elliptic Curve Digital Signature
+Algorithm as defined by FIPS 186-2.
+
+@item GPGME_PK_ECDH
+This value indicates ECDH, the Eliptic Curve Diffie-Hellmann encryption
+algorithm as defined by the ECC in OpenPGP draft.
+
 @end table
 @end deftp
 
@@ -1345,12 +1455,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
 
 
@@ -1392,6 +1505,14 @@ The @code{gpgme_data_t} type is a handle for a container for generic
 data, which is used by @acronym{GPGME} to exchange data with the user.
 @end deftp
 
+@code{gpgme_data_t} objects do not provide notifications on events.
+It is assumed that read and write operations are blocking until data
+is available.  If this is undesirable, the application must ensure
+that all GPGME data operations always have data available, for example
+by using memory buffers or files rather than pipes or sockets.  This
+might be relevant, for example, if the external event loop mechanism
+is used.
+
 @menu
 * Creating Data Buffers::         Creating new data buffers.
 * Destroying Data Buffers::       Releasing data buffers.
@@ -1503,6 +1624,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.
@@ -1518,6 +1643,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.
@@ -1539,6 +1668,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.
@@ -1552,6 +1685,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.
@@ -1656,18 +1793,44 @@ The function @code{gpgme_data_release_and_get_mem} is like
 @code{gpgme_data_release}, except that it returns the data buffer and
 its length that was provided by the object.
 
-The user has to release the buffer with @code{free}.  In case the user
-provided the data buffer in non-copy mode, a copy will be made for
-this purpose.
+The user has to release the buffer with @code{gpgme_free}.  In case
+the user provided the data buffer in non-copy mode, a copy will be
+made for this purpose.
 
 In case an error returns, or there is no suitable data buffer that can
-be returned to the user, the function will return @code{NULL}.
+be returned to the user, the function will return @code{NULL}.  In any
+case, the data object @var{dh} is destroyed.
+@end deftypefun
+
+
+@deftypefun void gpgme_free (@w{void *@var{buffer}})
+The function @code{gpgme_free} releases the memory returned by
+@code{gpgme_data_release_and_get_mem}.  It should be used instead of
+the system libraries @code{free} function in case different allocators
+are used in a single program.
 @end deftypefun
 
 
 @node Manipulating Data Buffers
 @section Manipulating Data Buffers
-@cindex data buffere, manipulation
+@cindex data buffer, manipulation
+
+Data buffers contain data and meta-data.  The following operations can
+be used to manipulate both.
+
+
+@menu
+* Data Buffer I/O Operations::    I/O operations on data buffers.
+* Data Buffer Meta-Data::         Meta-data manipulation of data buffers.
+@end menu
+
+
+@node Data Buffer I/O Operations
+@subsection Data Buffer I/O Operations
+@cindex data buffer, I/O operations
+@cindex data buffer, read
+@cindex data buffer, write
+@cindex data buffer, seek
 
 @deftypefun ssize_t gpgme_data_read (@w{gpgme_data_t @var{dh}}, @w{void *@var{buffer}}, @w{size_t @var{length}})
 The function @code{gpgme_data_read} reads up to @var{length} bytes
@@ -1689,7 +1852,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.
 
@@ -1698,15 +1861,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
@@ -1734,14 +1897,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
@@ -1760,6 +1956,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
 
@@ -1798,6 +2007,7 @@ cryptographic operations.
 @menu
 * Creating Contexts::             Creating new @acronym{GPGME} contexts.
 * Destroying Contexts::           Releasing @acronym{GPGME} contexts.
+* Result Management::             Managing the result of crypto operations.
 * Context Attributes::            Setting properties of a context.
 * Key Management::                Managing keys with @acronym{GPGME}.
 * Trust Item Management::         Managing trust items with @acronym{GPGME}.
@@ -1811,13 +2021,17 @@ cryptographic operations.
 @cindex context, creation
 
 @deftypefun gpgme_error_t gpgme_new (@w{gpgme_ctx_t *@var{ctx}})
-The function @code{gpgme_data_new} creates a new @code{gpgme_ctx_t}
-object and returns a handle for it in @var{ctx}.
+The function @code{gpgme_new} creates a new @code{gpgme_ctx_t} object
+and returns a handle for it in @var{ctx}.
 
 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
 context was successfully created, @code{GPG_ERR_INV_VALUE} if
 @var{ctx} is not a valid pointer, and @code{GPG_ERR_ENOMEM} if not
-enough memory is available.
+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
 
 
@@ -1831,12 +2045,45 @@ The function @code{gpgme_release} destroys the context with the handle
 @end deftypefun
 
 
+@node Result Management
+@section Result Management
+@cindex context, result of operation
+
+The detailed result of an operation is returned in operation-specific
+structures such as @code{gpgme_decrypt_result_t}.  The corresponding
+retrieval functions such as @code{gpgme_op_decrypt_result} provide
+static access to the results after an operation completes.  The
+following interfaces make it possible to detach a result structure
+from its associated context and give it a lifetime beyond that of the
+current operation or context.
+
+@deftypefun void gpgme_result_ref (@w{void *@var{result}})
+The function @code{gpgme_result_ref} acquires an additional reference
+for the result @var{result}, which may be of any type
+@code{gpgme_*_result_t}.  As long as the user holds a reference, the
+result structure is guaranteed to be valid and unmodified.
+@end deftypefun
+
+@deftypefun void gpgme_result_unref (@w{void *@var{result}})
+The function @code{gpgme_result_unref} releases a reference for the
+result @var{result}.  If this was the last reference, the result
+structure will be destroyed and all resources associated to it will be
+released.
+@end deftypefun
+
+Note that a context may hold its own references to result structures,
+typically until the context is destroyed or the next operation is
+started.  In fact, these references are accessed through the
+@code{gpgme_op_*_result} functions.
+
+
 @node Context Attributes
 @section Context Attributes
 @cindex context, attributes
 
 @menu
 * Protocol Selection::            Selecting the protocol used by a context.
+* 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.
@@ -1872,6 +2119,50 @@ The function @code{gpgme_get_protocol} retrieves the protocol currently
 use with the context @var{ctx}.
 @end deftypefun
 
+
+@node Crypto Engine
+@subsection Crypto Engine
+@cindex context, configuring engine
+@cindex engine, configuration per context
+
+The following functions can be used to set and retrieve the
+configuration of the crypto engines of a specific context.  The
+default can also be retrieved without any particular context.
+@xref{Engine Information}.  The default can also be changed globally.
+@xref{Engine Configuration}.
+
+@deftypefun gpgme_engine_info_t gpgme_ctx_get_engine_info (@w{gpgme_ctx_t @var{ctx}})
+The function @code{gpgme_ctx_get_engine_info} returns a linked list of
+engine info structures.  Each info structure describes the
+configuration of one configured backend, as used by the context
+@var{ctx}.
+
+The result is valid until the next invocation of
+@code{gpgme_ctx_set_engine_info} for this particular context.
+
+This function can not fail.
+@end deftypefun
+
+@deftypefun gpgme_error_t gpgme_ctx_set_engine_info (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_protocol_t @var{proto}}, @w{const char *@var{file_name}}, @w{const char *@var{home_dir}})
+The function @code{gpgme_ctx_set_engine_info} changes the
+configuration of the crypto engine implementing the protocol
+@var{proto} for the context @var{ctx}.
+
+@var{file_name} is the file name of the executable program
+implementing this protocol, and @var{home_dir} is the directory name
+of the configuration directory for this crypto engine.  If
+@var{home_dir} is @code{NULL}, the engine's default will be used.
+
+Currently this function must be used before starting the first crypto
+operation.  It is unspecified if and when the changes will take effect
+if the function is called after starting the first operation on the
+context @var{ctx}.
+
+This function returns the error code @code{GPG_ERR_NO_ERROR} if
+successful, or an eror code on failure.
+@end deftypefun
+
+
 @c FIXME: Unfortunately, using @acronym here breaks texi2dvi.
 @node ASCII Armor
 @subsection @acronym{ASCII} Armor
@@ -1934,6 +2225,9 @@ default, only the sender's certificate is included.  The possible
 values of @var{nr_of_certs} are:
 
 @table @code
+@item GPGME_INCLUDE_CERTS_DEFAULT
+Fall back to the default of the crypto backend.  This is the default
+for GPGME.
 @item -2
 Include all certificates except the root certificate.
 @item -1
@@ -1964,7 +2258,7 @@ certificates to include into an S/MIME signed message.
 @cindex key listing mode
 @cindex key listing, mode of
 
-@deftypefun void gpgme_set_keylist_mode (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_keylist_mode_t @var{mode}})
+@deftypefun gpgme_error_t gpgme_set_keylist_mode (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_keylist_mode_t @var{mode}})
 The function @code{gpgme_set_keylist_mode} changes the default
 behaviour of the key listing functions.  The value in @var{mode} is a
 bitwise-or combination of one or multiple of the following bit values:
@@ -1977,20 +2271,30 @@ 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_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
@@ -1999,7 +2303,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).
@@ -2046,9 +2350,9 @@ previous attempts failed, then @var{prev_was_bad} is 1, otherwise it
 will be 0.
 
 The user must write the passphrase, followed by a newline character,
-to the file descriptor @var{fd}.  If the user does not return 0
-indicating success, the user must at least write a newline character
-before returning from the callback.
+to the file descriptor @var{fd}.  If the user returns 0 indicating
+success, the user must at least write a newline character before
+returning from the callback.
 
 If an error occurs, return the corresponding @code{gpgme_error_t}
 value.  You can use the error code @code{GPG_ERR_CANCELED} to abort
@@ -2066,7 +2370,9 @@ function is set.
 Not all crypto engines require this callback to retrieve the
 passphrase.  It is better if the engine retrieves the passphrase from
 a trusted agent (a daemon process), rather than having each user to
-implement their own passphrase query.
+implement their own passphrase query.  Some engines do not even
+support an external passphrase callback at all, in this case the error
+code @code{GPG_ERR_NOT_SUPPORTED} is returned.
 
 The user can disable the use of a passphrase callback function by
 calling @code{gpgme_set_passphrase_cb} with @var{passfunc} being
@@ -2214,8 +2520,14 @@ This is true if the subkey can be used to create key certificates.
 @item unsigned int can_authenticate : 1
 This is true if the subkey can be used for authentication.
 
+@item unsigned int is_qualified : 1
+This is true if the subkey can be used for qualified signatures
+according to local government regulations.
+
 @item unsigned int secret : 1
-This is true if the subkey is a secret key.
+This is true if the subkey is a secret key.  Note that it will be false
+if the key is actually a stub key; i.e. a secret key operation is
+currently not possible (offline-key).
 
 @item gpgme_pubkey_algo_t pubkey_algo
 This is the public key algorithm supported by this subkey.
@@ -2228,7 +2540,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
@@ -2247,7 +2559,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:
 
@@ -2302,6 +2620,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
 
@@ -2348,7 +2669,7 @@ The @code{gpgme_key_t} type is a pointer to a key object.  It has the
 following members:
 
 @table @code
-@item unsigned int keylist_mode
+@item gpgme_keylist_mode_t keylist_mode
 The keylist mode that was active when the key was retrieved.
 
 @item unsigned int revoked : 1
@@ -2382,8 +2703,14 @@ 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).
 
 @item gpgme_protocol_t protocol
 This is the protocol supported by this key.
@@ -2423,6 +2750,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
 
 
@@ -2442,7 +2771,12 @@ in the list.
 
 If @var{pattern} is @code{NULL}, all available keys are returned.
 Otherwise, @var{pattern} contains an engine specific expression that
-is used to limit the list to all keys matching the pattern.
+is used to limit the list to all keys matching the pattern.  Note that
+the total length of the pattern is restricted to an engine-specific
+maximum (a couple of hundred characters are usually accepted).  The
+pattern should be used to restrict the search to a certain common name
+or user, not to list many specific keys at once by listing their
+fingerprints or key IDs.
 
 If @var{secret_only} is not @code{0}, the list is restricted to secret
 keys only.
@@ -2465,7 +2799,13 @@ everything up so that subsequent invocations of
 If @var{pattern} or @var{*pattern} is @code{NULL}, all available keys
 are returned.  Otherwise, @var{pattern} is a @code{NULL} terminated
 array of strings that are used to limit the list to all keys matching
-at least one of the patterns verbatim.
+at least one of the patterns verbatim.  Note that the total length of
+all patterns is restricted to an engine-specific maximum (the exact
+limit also depends on the number of patterns and amount of quoting
+required, but a couple of hundred characters are usually accepted).
+Patterns should be used to restrict the search to a certain common
+name or user, not to list many specific keys at once by listing their
+fingerprints or key IDs.
 
 If @var{secret_only} is not @code{0}, the list is restricted to secret
 keys only.
@@ -2499,7 +2839,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
@@ -2517,6 +2857,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)
@@ -2527,15 +2868,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
@@ -2575,7 +2920,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
@@ -2949,14 +3294,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
@@ -2965,7 +3309,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">
@@ -3043,17 +3388,42 @@ 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.
+
+
+@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
@@ -3061,7 +3431,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}.
@@ -3071,18 +3441,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
@@ -3090,7 +3461,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}.
@@ -3101,11 +3472,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 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}.
@@ -3132,6 +3542,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 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
@@ -3287,6 +3735,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
@@ -3369,7 +3914,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
@@ -3512,9 +4057,38 @@ operation could be started successfully, and @code{GPG_ERR_INV_VALUE}
 if @var{cipher} or @var{plain} is not a valid pointer.
 @end deftypefun
 
+@deftp {Data type} {gpgme_recipient_t}
+This is a pointer to a structure used to store information about the
+recipient of an encrypted text which is decrypted in a
+@code{gpgme_op_decrypt} operation.  This information (except for the
+status field) is even available before the operation finished
+successfully, for example in a passphrase callback.  The structure
+contains the following members:
+
+@table @code
+@item gpgme_recipient_t next
+This is a pointer to the next recipient structure in the linked list,
+or @code{NULL} if this is the last element.
+
+@item gpgme_pubkey_algo_t
+The public key algorithm used in the encryption.
+
+@item unsigned int wrong_key_usage : 1
+This is true if the key was not used according to its policy.
+
+@item char *keyid
+This is the key ID of the key (in hexadecimal digits) used as
+recipient.
+
+@item gpgme_error_t status
+This is an error number with the error code GPG_ERR_NO_SECKEY if the
+secret key for this recipient is not available, and 0 otherwise.
+@end table
+@end deftp
+
 @deftp {Data type} {gpgme_decrypt_result_t}
 This is a pointer to a structure used to store the result of a
-@code{gpgme_op_decrypt} operation.  After successfully encrypting
+@code{gpgme_op_decrypt} operation.  After successfully decrypting
 data, you can retrieve the pointer to the result with
 @code{gpgme_op_decrypt_result}.  The structure contains the following
 members:
@@ -3526,6 +4100,13 @@ algorithm that is not supported.
 
 @item unsigned int wrong_key_usage : 1
 This is true if the key was not used according to its policy.
+
+@item gpgme_recipient_t recipient
+This is a linked list of recipients to which this message was encrypted.
+
+@item char *file_name
+This is the filename of the original plaintext message file if it is
+known, otherwise this is a null pointer.
 @end table
 @end deftp
 
@@ -3547,6 +4128,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
@@ -3595,9 +4178,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
 
@@ -3713,12 +4332,43 @@ 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.
 @end table
 @end deftp
 
@@ -3733,6 +4383,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
 
@@ -3978,7 +4632,7 @@ The function @code{gpgme_get_sig_key} is equivalent to:
   if (!sig || idx)
     return gpg_error (GPG_ERR_EOF);
 
-  return gpgme_get_key (ctx, sig->fpr, r_key, 0, 0);
+  return gpgme_get_key (ctx, sig->fpr, r_key, 0);
 @end example
 @end deftypefun
 
@@ -4043,6 +4697,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
 
 
@@ -4101,7 +4756,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
@@ -4185,12 +4841,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
@@ -4209,11 +4917,12 @@ 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
 must keep references for all keys during the whole duration of the
@@ -4229,6 +4938,12 @@ The @code{GPGME_ENCRYPT_ALWAYS_TRUST} symbol specifies that all the
 recipients in @var{recp} should be trusted, even if the keys do not
 have a high enough validity in the keyring.  This flag should be used
 with care; in general it is not a good idea to use any untrusted keys.
+
+@item GPGME_ENCRYPT_NO_ENCRYPT_TO
+The @code{GPGME_ENCRYPT_NO_ENCRYPT_TO} symbol specifies that no
+default or hidden default recipients as configured in the crypto
+backend should be included.  This can be useful for managing different
+user profiles.
 @end table
 
 If @code{GPG_ERR_UNUSABLE_PUBKEY} is returned, some recipients in
@@ -4408,7 +5123,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.
 
@@ -4447,7 +5162,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}).
@@ -4561,8 +5276,8 @@ callback handler.  It must be specified.
 
 @item gpgme_event_io_cb_t event
 This is the function called by @acronym{GPGME} to signal an event for
-an operation.  It is optional, but if you don't specify it, you can
-not retrieve the return value of the operation.
+an operation.  It must be specified, because at least the start event
+must be processed.
 
 @item void *event_data
 This is passed as the first argument to the @code{event} function when
@@ -4596,13 +5311,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>
@@ -4622,6 +5340,7 @@ struct one_fd
   int dir;
   gpgme_io_cb_t fnc;
   void *fnc_data;
+  void *loop;
 @};
 
 struct event_loop
@@ -4653,6 +5372,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;
        @}
     @}
@@ -4667,6 +5387,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;
@@ -4698,11 +5419,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);
@@ -4717,7 +5439,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)
        @{
@@ -4748,7 +5470,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
 
@@ -4763,7 +5484,6 @@ 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 =
   @{
@@ -4774,8 +5494,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;
 
@@ -4790,7 +5512,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)
     @{
@@ -4811,7 +5533,7 @@ main (int argc, char *argv[])
                gpgme_strsource (result.err), gpgme_strerror (result.err));
       exit (1);
     @}
-  /* Evaluate STATUS.  */
+  /* Evaluate verify result.  */
   @dots{}
   return 0;
 @}
@@ -4998,13 +5720,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
@@ -5028,24 +5752,36 @@ case the state of @var{ctx} is not modified).
 @end deftypefun
 
 
-@include gpl.texi
-
+@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.
 
-@include fdl.texi
+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 **********************************************************
 
-@node Concept Index
-@unnumbered Concept Index
+@include uiserver.texi
 
-@printindex cp
+@include lesser.texi
 
+@include gpl.texi
 
 @node Function and Data Index
 @unnumbered Function and Data Index
 
 @printindex fn
 
+@node Concept Index
+@unnumbered Concept Index
+
+@printindex cp
+
 
-@summarycontents
-@contents
 @bye