doc/
[gpgme.git] / doc / gpgme.texi
index 8c34f89..92289c2 100644 (file)
@@ -20,16 +20,22 @@ This is Edition @value{EDITION}, last updated @value{UPDATED}, of
 @cite{The `GnuPG Made Easy' Reference Manual}, for Version
 @value{VERSION}.
 
-Copyright @copyright{} 2002, 2003 g10 Code GmbH.
+@c NOTE: Don't forget to update the year for the TeX version, too.
+Copyright @copyright{} 2002, 2003, 2004 g10 Code GmbH.
 
-Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.1 or
-any later version published by the Free Software Foundation; with the
-Invariant Sections being ``Free Software Needs Free Documentation'' and
-``GNU Lesser General Public License'', the Front-Cover texts being (a)
-(see below), and with the Back-Cover Texts being (b) (see below).  A
-copy of the license is included in the section entitled ``GNU Free
-Documentation License''.
+The GPGME reference manual is free software; you can redistribute it
+and/or modify it under the terms of the GNU Lesser General Public
+License as published by the Free Software Foundation; either version
+2.1 of the License, or (at your option) any later version.
+
+The GPGME reference manual is distributed in the hope that it will be
+useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+Lesser General Public License for more details.
+
+You should have received a copy of the GNU Lesser General Public
+License along with this program; if not, write to the Free Software
+Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
 
 @end ifinfo
 
@@ -48,16 +54,22 @@ Documentation License''.
 @center for version @value{VERSION}
 @page
 @vskip 0pt plus 1filll
-Copyright @copyright{} 2002, 2003 g10 Code GmbH.
-
-Permission is granted to copy, distribute and/or modify this document
-under the terms of the GNU Free Documentation License, Version 1.1 or
-any later version published by the Free Software Foundation; with the
-Invariant Sections being ``Free Software Needs Free Documentation'' and
-``GNU Lesser General Public License'', the Front-Cover texts being (a)
-(see below), and with the Back-Cover Texts being (b) (see below).  A
-copy of the license is included in the section entitled ``GNU Free
-Documentation License''.
+Copyright @copyright{} 2002, 2003, 2004 g10 Code GmbH.
+
+
+The GPGME reference manual is free software; you can redistribute it
+and/or modify it under the terms of the GNU Lesser General Public
+License as published by the Free Software Foundation; either version
+2.1 of the License, or (at your option) any later version.
+
+The GPGME reference manual is distributed in the hope that it will be
+useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+Lesser General Public License for more details.
+
+You should have received a copy of the GNU Lesser General Public
+License along with this program; if not, write to the Free Software
+Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA
 @end titlepage
 @page
 
@@ -80,10 +92,8 @@ This is Edition @value{EDITION}, last updated @value{UPDATED}, of
 
 Appendices
 
-* Copying::                       The GNU General Public License says how you
-                                  can copy and share `GnuPG Made Easy'.
-* Free Documentation License::    This manual is under the GNU Free
-                                  Documentation License.
+* Library Copying::               The GNU Lesser General Public License says
+                                  how you can copy and share `GnuPG Made Easy'.
 
 Indices
 
@@ -104,6 +114,7 @@ Preparation
 
 * Header::                        What header file you need to include.
 * Building the Source::           Compiler options to be used.
+* Largefile Support (LFS)::       How to use @acronym{GPGME} with LFS.
 * Using Automake::                Compiler options to be used the easy way.
 * Using Libtool::                 Avoiding compiler options entirely.
 * Library Version Check::         Getting and verifying the library version.
@@ -114,6 +125,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.
 
@@ -154,6 +166,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.
@@ -200,6 +213,7 @@ Run Control
 
 * Waiting For Completion::        Waiting until an operation is completed.
 * Using External Event Loops::    Advanced control over what happens when.
+* Cancellation::                  How to end pending operations prematurely.
 
 Using External Event Loops
 
@@ -208,6 +222,7 @@ Using External Event Loops
 * I/O Callback Example::          An example how to use I/O callbacks.
 * I/O Callback Example GTK+::     How to integrate @acronym{GPGME} in GTK+.
 * I/O Callback Example GDK::      How to integrate @acronym{GPGME} in GDK.
+* I/O Callback Example Qt::       How to integrate @acronym{GPGME} in Qt.
 
 @end detailmenu
 @end menu
@@ -265,7 +280,7 @@ engines into your application directly.
 @table @asis
 @item it's free software
 Anybody can use, modify, and redistribute it under the terms of the GNU
-General Public License (@pxref{Copying}).
+Lesser General Public License (@pxref{Library Copying}).
 
 @item it's flexible
 @acronym{GPGME} provides transparent support for several cryptographic
@@ -320,6 +335,7 @@ of the library are verified.
 @menu
 * Header::                        What header file you need to include.
 * Building the Source::           Compiler options to be used.
+* Largefile Support (LFS)::       How to use @acronym{GPGME} with LFS.
 * Using Automake::                Compiler options to be used the easy way.
 * Using Libtool::                 Avoiding compiler options entirely.
 * Library Version Check::         Getting and verifying the library version.
@@ -407,6 +423,82 @@ Supported thread packages are @option{--thread=pth} and
 @option{--thread=pthread}.
 
 
+@node Largefile Support (LFS)
+@section Largefile Support (LFS)
+@cindex largefile support
+@cindex LFS
+
+@acronym{GPGME} is compiled with largefile support by default, if it
+is available on the system.  This means that GPGME supports files
+larger than two gigabyte in size, if the underlying operating system
+can.  On some systems, largefile support is already the default.  On
+such systems, nothing special is required.  However, some systems
+provide only support for files up to two gigabyte in size by default.
+Support for larger file sizes has to be specifically enabled.
+
+To make a difficult situation even more complex, such systems provide
+two different types of largefile support.  You can either get all
+relevant functions replaced with alternatives that are largefile
+capable, or you can get new functions and data types for largefile
+support added.  Those new functions have the same name as their
+smallfile counterparts, but with a suffix of 64.
+
+An example: The data type @code{off_t} is 32 bit wide on GNU/Linux PC
+systems.  To address offsets in large files, you can either enable
+largefile support add-on.  Then a new data type @code{off64_t} is
+provided, which is 64 bit wide.  Or you can replace the existing
+@code{off_t} data type with its 64 bit wide counterpart.  All
+occurences of @code{off_t} are then automagically replaced.
+
+As if matters were not complex enough, there are also two different
+types of file descriptors in such systems.  This is important because
+if file descriptors are exchanged between programs that use a
+different maximum file size, certain errors must be produced on some
+file descriptors to prevent subtle overflow bugs from occuring.
+
+As you can see, supporting two different maximum file sizes at the
+same time is not at all an easy task.  However, the maximum file size
+does matter for @acronym{GPGME}, because some data types it uses in
+its interfaces are affected by that.  For example, the @code{off_t}
+data type is used in the @code{gpgme_data_seek} function, to match its
+@acronym{POSIX} counterpart.  This affects the call-frame of the
+function, and thus the ABI of the library.  Furthermore, file
+descriptors can be exchanged between GPGME and the application.
+
+For you as the user of the library, this means that your program must
+be compiled in the same file size mode as the library.  Luckily, there
+is absolutely no valid reason for new programs to not enable largefile
+support by default and just use that.  The compatibility modes (small
+file sizes or dual mode) can be considered an historic artefact, only
+useful to allow for a transitional period.
+
+@acronym{GPGME} is compiled using largefile support by default.  This
+means that your application must do the same, at least as far as it is
+relevant for using the @file{gpgme.h} header file.  All types in this
+header files refer to their largefile counterparts, if they are
+different from any default types on the system.
+
+You can enable largefile support, if it is different from the default
+on the system the application is compiled on, by using the Autoconf
+macro @code{AC_SYS_LARGEFILE}.  If you do this, then you don't need to
+worry about anything else: It will just work.  In this case you might
+also want to use @code{AC_FUNC_FSEEKO} to take advantage of some new
+interfaces, and @code{AC_TYPE_OFF_T} (just in case).
+
+If you do not use Autoconf, you can define the preprocessor symbol
+@code{_FILE_OFFSET_BITS} to 64 @emph{before} including any header
+files, for example by specifying the option
+@code{-D_FILE_OFFSET_BITS=64} on the compiler command line.  You will
+also want to define the preprocessor symbol @code{LARGEFILE_SOURCE} to
+1 in this case, to take advantage of some new interfaces.
+
+If you do not want to do either of the above, you probably know enough
+about the issue to invent your own solution.  Just keep in mind that
+the @acronym{GPGME} header file expects that largefile support is
+enabled, if it is available.  In particular, we do not support dual
+mode (@code{_LARGEFILE64_SOURCE}).
+
+
 @node Using Automake
 @section Using Automake
 @cindex automake
@@ -496,9 +588,9 @@ features are provided by the installed version of the library.
 
 
 After initializing @acronym{GPGME}, you should set the locale
-information to the locale required for your output terminal (only
-required if your program runs on a text terminal, rather than in the X
-Window environment).  Here is an example of a complete initialization:
+information to the locale required for your output terminal.  This
+locale information is needed for example for the curses and Gtk
+pinentry.  Here is an example of a complete initialization:
 
 @example
 #include <locale.h>
@@ -655,6 +747,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
@@ -699,6 +792,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,
@@ -713,10 +811,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.
@@ -760,6 +858,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
@@ -1731,8 +1860,8 @@ 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
@@ -1757,6 +1886,7 @@ The function @code{gpgme_release} destroys the context with the handle
 
 @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.
@@ -1792,6 +1922,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
@@ -1854,6 +2028,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
@@ -1884,7 +2061,7 @@ certificates to include into an S/MIME signed message.
 @cindex key listing mode
 @cindex key listing, mode of
 
-@deftypefun void gpgme_set_keylist_mode (@w{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:
@@ -1905,6 +2082,14 @@ certificate server.
 @item GPGME_KEYLIST_MODE_SIGS
 The @code{GPGME_KEYLIST_MODE_SIGS} symbol specifies that the key
 signatures should be included in the listed keys.
+
+@item GPGME_KEYLIST_MODE_VALIDATE
+The @code{GPGME_KEYLIST_MODE_VALIDATE} symbol specifies that the
+backend should do key or certificate validation and not just get the
+validity information from an internal cache.  This might be an
+expensive operation and is in general not usefule.  Currently only
+implemented for the S/MIME backend and ignored for other backends.
+
 @end table
 
 At least one of @code{GPGME_KEYLIST_MODE_LOCAL} and
@@ -1978,7 +2163,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
@@ -2177,7 +2364,7 @@ This is true if the key signature is expired.
 @item unsigned int invalid : 1
 This is true if the key signature is invalid.
 
-@item unsigned int disabled : 1
+@item unsigned int exportable : 1
 This is true if the key signature is exportable.
 
 @item gpgme_pubkey_algo_t pubkey_algo
@@ -2199,7 +2386,7 @@ signature does not expire.
 This is the status of the signature and has the same meaning as the
 member of the same name in a @code{gpgme_signature_t} object.
 
-@item unsigned int class
+@item unsigned int sig_class
 This specifies the signature class of the key signature.  The meaning
 is specific to the crypto engine.
 
@@ -2260,6 +2447,9 @@ The @code{gpgme_key_t} type is a pointer to a key object.  It has the
 following members:
 
 @table @code
+@item gpgme_keylist_mode_t keylist_mode
+The keylist mode that was active when the key was retrieved.
+
 @item unsigned int revoked : 1
 This is true if the key is revoked.
 
@@ -2270,7 +2460,10 @@ This is true if the key is expired.
 This is true if the key is disabled.
 
 @item unsigned int invalid : 1
-This is true if the key is invalid.
+This is true if the key is invalid. This might have several reasons,
+for a example for the S/MIME backend, it will be set in during key
+listsing if the key could not be validated due to a missing
+certificates or unmatched policies.
 
 @item unsigned int can_encrypt : 1
 This is true if the key (ie one of its subkeys) can be used for
@@ -2348,7 +2541,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.
@@ -2371,7 +2569,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.
@@ -3418,9 +3622,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:
@@ -3429,6 +3662,12 @@ members:
 @item char *unsupported_algorithm
 If an unsupported algorithm was encountered, this string describes the
 algorithm that is not supported.
+
+@item unsigned int wrong_key_usage : 1
+This is true if the key was not used according to its policy.
+
+@item gpgme_recipient_t recipient
+This is a linked list of recipients to which this message was encrypted.
 @end table
 @end deftp
 
@@ -3514,7 +3753,7 @@ following members:
 This is a pointer to the next new signature structure in the linked
 list, or @code{NULL} if this is the last element.
 
-@item gpgme_sigsum_t summary;
+@item gpgme_sigsum_t summary
 This is a bit vector giving a summary of the signature status.  It
 provides an easy interface to a defined semantic of the signature
 status.  Checking just one bit is sufficient to see whether a
@@ -3583,6 +3822,12 @@ status codes are of interest:
   verify the signature has expired.  For the combined result this status
   means that all signatures are valid and all keys are expired.
 
+  @item GPG_ERR_CERT_REVOKED
+  This status indicates that the signature is valid but the key used
+  to verify the signature has been revoked.  For the combined result
+  this status means that all signatures are valid and all keys are
+  revoked.
+
   @item GPG_ERR_BAD_SIGNATURE
   This status indicates that the signature is invalid.  For the combined
   result this status means that all signatures are invalid.
@@ -3607,7 +3852,7 @@ The creation timestamp of this signature.
 The expiration timestamp of this signature, or 0 if the signature does
 not expire.
 
-@item int wrong_key_usage : 1;
+@item unsigned int wrong_key_usage : 1
 This is true if the key was not used according to its policy.
 
 @item gpgme_validity_t validity
@@ -3633,14 +3878,18 @@ verification was attempted.
 @end table
 @end deftp
 
-@deftypefun gpgme_sign_result_t gpgme_op_verify_result (@w{gpgme_ctx_t @var{ctx}})
+@deftypefun gpgme_verify_result_t gpgme_op_verify_result (@w{gpgme_ctx_t @var{ctx}})
 The function @code{gpgme_op_verify_result} returns a
-@code{gpgme_verify_result_t} pointer to a structure holding the result of
-a @code{gpgme_op_verify} operation.  The pointer is only valid if the
-last operation on the context was a @code{gpgme_op_verify} or
-@code{gpgme_op_verify_start} operation, and if this operation finished
-successfully.  The returned pointer is only valid until the next
-operation is started on the context.
+@code{gpgme_verify_result_t} pointer to a structure holding the result
+of a @code{gpgme_op_verify} operation.  The pointer is only valid if
+the last operation on the context was a @code{gpgme_op_verify},
+@code{gpgme_op_verify_start}, @code{gpgme_op_decrypt_verify} or
+@code{gpgme_op_decrypt_verify_start} operation, and if this operation
+finished successfully (for @code{gpgme_op_decrypt_verify} and
+@code{gpgme_op_decrypt_verify_start}, the error code
+@code{GPG_ERR_NO_DATA} counts as successful in this context).  The
+returned pointer is only valid until the next operation is started on
+the context.
 @end deftypefun
 
 
@@ -3871,7 +4120,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
 
@@ -3893,6 +4142,11 @@ After the operation completed, @code{gpgme_op_decrypt_result} and
 @code{gpgme_op_verify_result} can be used to retrieve more information
 about the signatures.
 
+If the error code @code{GPG_ERR_NO_DATA} is returned, @var{cipher}
+does not contain any data to decrypt.  However, it might still be
+signed.  The information about detected signatures is available with
+@code{gpgme_op_verify_result} in this case.
+
 The function returns the error code @code{GPG_ERR_NO_ERROR} if the
 ciphertext could be decrypted successfully, @code{GPG_ERR_INV_VALUE}
 if @var{ctx}, @var{cipher} or @var{plain} is not a valid pointer,
@@ -4038,7 +4292,7 @@ The public key algorithm used to create this signature.
 @item gpgme_hash_algo_t
 The hash algorithm used to create this signature.
 
-@item unsigned int class
+@item unsigned int sig_class
 The signature class of this signature.
 
 @item long int timestamp
@@ -4226,6 +4480,7 @@ time.
 @menu
 * Waiting For Completion::        Waiting until an operation is completed.
 * Using External Event Loops::    Advanced control over what happens when.
+* Cancellation::                  How to end pending operations prematurely.
 @end menu
 
 
@@ -4309,6 +4564,7 @@ programs.
 * I/O Callback Example::          An example how to use I/O callbacks.
 * I/O Callback Example GTK+::     How to use @acronym{GPGME} with GTK+.
 * I/O Callback Example GDK::      How to use @acronym{GPGME} with GDK.
+* I/O Callback Example Qt::       How to use @acronym{GPGME} with Qt.
 @end menu
 
 
@@ -4809,10 +5065,112 @@ my_gpgme_register_io_callback (void *data, int fd, int dir, gpgme_io_cb_t fnc,
 @end example
 
 
-@include gpl.texi
+@node I/O Callback Example Qt
+@subsubsection I/O Callback Example Qt
+@cindex Qt, using @acronym{GPGME} with
+
+The I/O callback interface can also be used to integrate
+@acronym{GPGME} with the Qt event loop.  The following code snippets
+show how this can be done using the appropriate register and remove
+I/O callback functions.  In this example, the private data of the
+register I/O callback function is unused.  The event notifications is
+missing because it does not require any Qt specific setup.
+
+@example
+#include <qsocketnotifier.h>
+#include <qapplication.h>
+
+struct IOCB @{
+  IOCB( GpgmeIOCb f, void * d, QSocketNotifier * n )
+    : func( f ), data( d ), notifier( n ) @{@}
+  GpgmeIOCb func;
+  void * data;
+  QSocketNotifier * notifier;
+@}
+
+class MyApp : public QApplication @{
+
+  // ...
+  
+  static void registerGpgmeIOCallback( void * data, int fd, int dir,
+                                       GpgmeIOCb func, void * func_data,
+                                       void ** tag ) @{
+    QSocketNotifier * n =
+      new QSocketNotifier( fd, dir ? QSocketNotifier::Read
+                                   : QSocketNotifier::Write );
+    connect( n, SIGNAL(activated(int)),
+             qApp, SLOT(slotGpgmeIOCallback(int)) );
+    qApp->mIOCBs.push_back( IOCB( func, func_data, n ) );
+    *tag = (void*)n;
+  @}
+
+  static void removeGpgmeIOCallback( void * tag ) @{
+    if ( !tag ) return;
+    QSocketNotifier * n = static_cast<QSocketNotifier*>( tag );
+    for ( QValueList<IOCB>::iterator it = qApp->mIOCBs.begin() ;
+          it != qApp->mIOCBs.end() ; ++it )
+      if ( it->notifier == n ) @{
+        delete it->notifier;
+        qApp->mIOCBs.erase( it );
+        return;
+      @}
+  @}
+
+public slots:
+  void slotGpgmeIOCallback( int fd ) @{
+    for ( QValueList<IOCB>::const_iterator it = mIOCBs.begin() ;
+          it != mIOCBs.end() ; ++it )
+      if ( it->notifier && it->notifier->socket() == fd )
+        (*(it->func)) ( it->func_data, fd );
+  @}
+
+  // ...
+
+private:
+  QValueList<IOCB> mIOCBs;
+  // ...
+@};
+@end example
+
+
+@node Cancellation
+@subsection Cancellation
+@cindex cryptographic operation, aborting
+@cindex cryptographic operation, cancelling
+@cindex aborting operations
+@cindex cancelling operations
+
+Sometimes you do not want to wait for an operation to finish.  If you
+use external I/O callbacks, you can cancel a pending operation.
+However, you must ensure that no other thread is currently using the
+context in which the operation you want to cancel runs.  This includes
+callback handlers.  So your external event loop must either be halted
+or otherwise it must be guaranteed that no installed I/O callbacks are
+run for this context.
+
+@deftypefun gpgme_ctx_t gpgme_cancel (@w{gpgme_ctx_t @var{ctx}})
+The function @code{gpgme_cancel} attempts to cancel a pending
+operation in the context @var{ctx}.  This only works if you use the
+global event loop or your own event loop.
+
+If you use the global event loop, you must not call @code{gpgme_wait}
+or @code{gpgme_wait} during cancellation.  After successful
+cancellation, you can call @code{gpgme_wait} (optionally waiting on
+@var{ctx}), and the context @var{ctx} will appear as if it had
+finished with the error code @code{GPG_ERR_CANCEL}.
+
+If you use your an external event loop, you must ensure that no I/O
+callbacks are invoked for this context (for example by halting the
+event loop).  On successful cancellation, all registered I/O callbacks
+for this context will be unregistered, and a @code{GPGME_EVENT_DONE}
+event with the error code @code{GPG_ERR_CANCEL} will be signaled.
+
+The function returns an error code if the cancellation failed (in this
+case the state of @var{ctx} is not modified).
+@end deftypefun
 
 
-@include fdl.texi
+@include lesser.texi
 
 
 @node Concept Index