python: Initialize GPGME for the user.
[gpgme.git] / doc / gpgme.texi
index 8eeaafc..8d666c3 100644 (file)
@@ -1,5 +1,5 @@
-\input texinfo                   @c -*- mode: texinfo; coding: latin-1; -*-
-@documentencoding ISO-8859-1
+\input texinfo                   @c -*- mode: texinfo; coding: utf-8; -*-
+@documentencoding UTF-8
 @setfilename gpgme.info
 @settitle The `GnuPG Made Easy' Reference Manual
 
@@ -14,7 +14,7 @@
 
 @copying
 Copyright @copyright{} 2002, 2003, 2004, 2005, 2006, 2007,
-2008, 2010, 2012, 2013 g10 Code GmbH.
+2008, 2010, 2012, 2013, 2014 g10 Code GmbH.
 
 @quotation
 Permission is granted to copy, distribute and/or modify this document
@@ -72,7 +72,7 @@ This is Edition @value{EDITION}, last updated @value{UPDATED}, of
 @center for version @value{VERSION}
 @page
 @vskip 0pt plus 1filll
-Published by g10 Code GmbH@* Hüttenstr. 61@* 40699 Erkrath, Germany
+Published by g10 Code GmbH@* Hüttenstr. 61@* 40699 Erkrath, Germany
 
 @insertcopying
 @end titlepage
@@ -113,7 +113,6 @@ Indices
 * Concept Index::                 Index of concepts and programs.
 * Function and Data Index::       Index of functions, variables and data types.
 
-
 @detailmenu
  --- The Detailed Node Listing ---
 
@@ -170,6 +169,7 @@ Manipulating Data Buffers
 
 * Data Buffer I/O Operations::    I/O operations on data buffers.
 * Data Buffer Meta-Data::         Meta-data manipulation of data buffers.
+* Data Buffer Convenience::       Convenience function for data buffers.
 
 Contexts
 
@@ -180,6 +180,7 @@ Contexts
 * Key Management::                Managing keys with @acronym{GPGME}.
 * Trust Item Management::         Managing trust items with @acronym{GPGME}.
 * Crypto Operations::             Using a context for cryptography.
+* Miscellaneous::                 Miscellaneous operations.
 * Run Control::                   Controlling how operations are run.
 
 Context Attributes
@@ -188,10 +189,12 @@ Context Attributes
 * Crypto Engine::                 Configuring the crypto engine.
 * ASCII Armor::                   Requesting @acronym{ASCII} armored output.
 * Text Mode::                     Choosing canonical text mode.
+* Offline Mode::                  Choosing offline mode.
 * Included Certificates::         Including a number of certificates.
 * Key Listing Mode::              Selecting key listing mode.
 * Passphrase Callback::           Getting the passphrase from the user.
 * Progress Meter Callback::       Being informed about the progress.
+* Status Message Callback::       Status messages received from gpg.
 * Locale::                        Setting the locale of a context.
 
 Key Management
@@ -204,6 +207,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.
+* Changing Passphrases::          Change the passphrase of a key.
 * Advanced Key Editing::          Advanced key edit operation.
 
 Trust Item Management
@@ -230,6 +234,10 @@ Encrypt
 
 * Encrypting a Plaintext::        How to encrypt a plaintext.
 
+Miscellaneous
+
+* Running other Programs::        Running other Programs
+
 Run Control
 
 * Waiting For Completion::        Waiting until an operation is completed.
@@ -385,8 +393,8 @@ to @acronym{GPGME} take the form @code{_gpgme_*} and @code{_GPGME_*}.
 
 Because @acronym{GPGME} makes use of the GPG Error library, using
 @acronym{GPGME} will also use the @code{GPG_ERR_*} name space
-directly, and the @code{gpg_err*} and @code{gpg_str*} name space
-indirectly.
+directly, and the @code{gpg_err*}, @code{gpg_str*}, and @code{gpgrt_*}
+name space indirectly.
 
 
 @node Building the Source
@@ -493,18 +501,42 @@ support by default and just use that.  The compatibility modes (small
 file sizes or dual mode) can be considered an historic artefact, only
 useful to allow for a transitional period.
 
-@acronym{GPGME} is compiled using largefile support by default.  This
-means that your application must do the same, at least as far as it is
-relevant for using the @file{gpgme.h} header file.  All types in this
-header files refer to their largefile counterparts, if they are
-different from any default types on the system.
-
-You can enable largefile support, if it is different from the default
-on the system the application is compiled on, by using the Autoconf
-macro @code{AC_SYS_LARGEFILE}.  If you do this, then you don't need to
-worry about anything else: It will just work.  In this case you might
-also want to use @code{AC_FUNC_FSEEKO} to take advantage of some new
-interfaces, and @code{AC_TYPE_OFF_T} (just in case).
+On POSIX platforms @acronym{GPGME} is compiled using largefile support
+by default.  This means that your application must do the same, at
+least as far as it is relevant for using the @file{gpgme.h} header
+file.  All types in this header files refer to their largefile
+counterparts, if they are different from any default types on the
+system.
+
+On 32 and 64 bit Windows platforms @code{off_t} is declared as 32 bit
+signed integer.  There is no specific support for LFS in the C
+library.  The recommendation from Microsoft is to use the native
+interface (@code{CreateFile} et al.) for large files.  Released binary
+versions of @acronym{GPGME} (libgpgme-11.dll) have always been build
+with a 32 bit @code{off_t}.  To avoid an ABI break we stick to this
+convention for 32 bit Windows by using @code{long} there.
+@acronym{GPGME} versions for 64 bit Windows have never been released
+and thus we are able to use @code{int64_t} instead of @code{off_t}
+there.  For easier migration the typedef @code{gpgme_off_t} has been
+defined.  The reason we cannot use @code{off_t} directly is that some
+toolchains (e.g. mingw64) introduce a POSIX compatible hack for
+@code{off_t}.  Some widely used toolkits make use of this hack and in
+turn @acronym{GPGME} would need to use it also.  However, this would
+introduce an ABI break and existing software making use of libgpgme
+might suffer from a severe break.  Thus with version 1.4.2 we
+redefined all functions using @code{off_t} to use @code{gpgme_off_t}
+which is defined as explained above.  This way we keep the ABI well
+defined and independent of any toolchain hacks.  The bottom line is
+that LFS support in @acronym{GPGME} is only available on 64 bit
+versions of Windows.
+
+On POSIX platforms you can enable largefile support, if it is
+different from the default on the system the application is compiled
+on, by using the Autoconf macro @code{AC_SYS_LARGEFILE}.  If you do
+this, then you don't need to worry about anything else: It will just
+work.  In this case you might also want to use @code{AC_FUNC_FSEEKO}
+to take advantage of some new interfaces, and @code{AC_TYPE_OFF_T}
+(just in case).
 
 If you do not use Autoconf, you can define the preprocessor symbol
 @code{_FILE_OFFSET_BITS} to 64 @emph{before} including any header
@@ -545,7 +577,10 @@ given.
 Additionally, the function defines @code{GPGME_CFLAGS} to the flags
 needed for compilation of the program to find the @file{gpgme.h}
 header file, and @code{GPGME_LIBS} to the linker flags needed to link
-the program to the @acronym{GPGME} library.
+the program to the @acronym{GPGME} library.  If the used helper script
+does not match the target type you are building for a warning is
+printed and the string @code{libgcrypt} is appended to the variable
+@code{gpg_config_script_warn}.
 
 @code{AM_PATH_GPGME_PTH} checks for the version of @acronym{GPGME}
 that can be used with GNU Pth, and defines @code{GPGME_PTH_CFLAGS} and
@@ -554,6 +589,16 @@ that can be used with GNU Pth, and defines @code{GPGME_PTH_CFLAGS} and
 @code{AM_PATH_GPGME_PTHREAD} checks for the version of @acronym{GPGME}
 that can be used with the native pthread implementation, and defines
 @code{GPGME_PTHREAD_CFLAGS} and @code{GPGME_PTHREAD_LIBS}.
+
+This macro searches for @command{gpgme-config} along the PATH.  If
+you are cross-compiling, it is useful to set the environment variable
+@code{SYSROOT} to the top directory of your target.  The macro will
+then first look for the helper program in the @file{bin} directory
+below that top directory.  An absolute directory name must be used for
+@code{SYSROOT}.  Finally, if the configure command line option
+@code{--with-gpgme-prefix} is used, only its value is used for the top
+directory below which the helper script is expected.
+
 @end defmac
 
 You can use the defined Autoconf variables like this in your
@@ -624,14 +669,49 @@ does not return a detailed error code).
 On some systems it is not easy to set environment variables and thus
 hard to use @acronym{GPGME}'s internal trace facility for debugging.
 This function has been introduced as an alternative way to enable
-debugging.  It is important to assure that only one thread accesses
-@acronym{GPGME} functions between a call to this function and after
-the return from the call to @code{gpgme_check_version}.
+debugging and for a couple of other rarely used tweaks.  It is
+important to assure that only one thread accesses @acronym{GPGME}
+functions between a call to this function and after the return from
+the call to @code{gpgme_check_version}.
 
-To enable debugging, you need to call this function as early as
-possible --- even before @code{gpgme_check_version} --- with the
-string ``debug'' for @var{name} and @var{value} identical to the value
-used with the environment variable @code{GPGME_DEBUG}.
+All currently supported features require that this function is called
+as early as possible --- even before @code{gpgme_check_version}.  The
+features are identified by the following values for @var{name}:
+
+@table @code
+@item "debug"
+To enable debugging use the string ``debug'' for @var{name} and
+@var{value} identical to the value used with the environment variable
+@code{GPGME_DEBUG}.
+
+@item "disable-gpgconf"
+Using this feature with any @var{value} disables the detection of the
+gpgconf program and thus forces GPGME to fallback into the simple
+OpenPGP only mode.  It may be used to force the use of GnuPG-1 on
+systems which have both GPG versions installed.  Note that in general
+the use of @code{gpgme_set_engine_info} is a better way to select a
+specific engine version.
+
+@item "gpgconf-name"
+@itemx "gpg-name"
+Set the name of the gpgconf respective gpg binary.  The defaults are
+@code{GNU/GnuPG/gpgconf} and @code{GNU/GnuPG/gpg}.  Under Unix the
+leading directory part is ignored.  Under Windows the leading
+directory part is used as the default installation directory; the
+@code{.exe} suffix is added by GPGME.  Use forward slashed even under
+Windows.
+
+@item "w32-inst-dir"
+On Windows GPGME needs to know its installation directory to find its
+spawn helper.  This is in general no problem because a DLL has this
+information.  Some applications however link statically to GPGME and
+thus GPGME can only figure out the installation directory of this
+application which may be wrong in certain cases.  By supplying an
+installation directory as value to this flag, GPGME will assume that
+that directory is the installation directory.  This flag has no effect
+on non-Windows platforms.
+
+@end table
 
 This function returns @code{0} on success.  In contrast to other
 functions the non-zero return value on failure does not convey any
@@ -801,6 +881,9 @@ Under development.  Please ask on @email{gnupg-devel@@gnupg.org} for help.
 @item GPGME_PROTOCOL_UISERVER
 Under development.  Please ask on @email{gnupg-devel@@gnupg.org} for help.
 
+@item GPGME_PROTOCOL_SPAWN
+Special protocol for use with @code{gpgme_op_spawn}.
+
 @item GPGME_PROTOCOL_UNKNOWN
 Reserved for future extension.  You may use this to indicate that the
 used protocol is not known to the application.  Currently,
@@ -829,6 +912,41 @@ allocated string describing the protocol @var{protocol}, or
 @section Engine Version Check
 @cindex version check, of the engines
 
+@deftypefun @w{const char *} gpgme_get_dirinfo (@w{cons char *@var{what}})
+The function @code{gpgme_get_dirinfo} returns a statically allocated
+string with the value associated to @var{what}.  The returned values
+are the defaults and won't change even after
+@code{gpgme_set_engine_info} has been used to configure a different
+engine.  @code{NULL} is returned if no value is available.  Commonly
+supported values for @var{what} are:
+
+@table @code
+@item homedir
+Return the default home directory.
+
+@item agent-socket
+Return the name of the socket to connect to the gpg-agent.
+
+@item uiserver-socket
+Return the name of the socket to connect to the user interface server.
+
+@item gpgconf-name
+Return the file name of the engine configuration tool.
+
+@item gpg-name
+Return the file name of the OpenPGP engine.
+
+@item gpgsm-name
+Return the file name of the CMS engine.
+
+@item g13-name
+Return the name of the file container encryption engine.
+
+@end table
+
+@end deftypefun
+
+
 @deftypefun gpgme_error_t gpgme_engine_check_version (@w{gpgme_protocol_t @var{protocol}})
 The function @code{gpgme_engine_check_version} verifies that the
 engine implementing the protocol @var{PROTOCOL} is installed in the
@@ -867,7 +985,8 @@ reserved for future use, so always check before you use it.
 @item const char *home_dir
 This is a string holding the directory name of the crypto engine's
 configuration directory.  If it is @code{NULL}, then the default
-directory is used.
+directory is used.  See @code{gpgme_get_dirinfo} on how to get the
+default directory.
 
 @item const char *version
 This is a string containing the version number of the crypto engine.
@@ -1041,16 +1160,19 @@ 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_ECC
+This value is a generic indicator for ellipic curve algorithms.
 
 @item GPGME_PK_ECDSA
 This value indicates ECDSA, the Elliptic Curve Digital Signature
-Algorithm as defined by FIPS 186-2.
+Algorithm as defined by FIPS 186-2 and RFC-6637.
 
 @item GPGME_PK_ECDH
-This value indicates ECDH, the Eliptic Curve Diffie-Hellmann encryption
-algorithm as defined by the ECC in OpenPGP draft.
+This value indicates ECDH, the Eliptic Curve Diffie-Hellmann
+encryption algorithm as defined by RFC-6637.
+
+@item GPGME_PK_EDDSA
+This value indicates the EdDSA algorithm.
 
 @end table
 @end deftp
@@ -1065,6 +1187,14 @@ If @var{algo} is not a valid public key algorithm, @code{NULL} is
 returned.
 @end deftypefun
 
+@deftypefun {char *} gpgme_pubkey_algo_string (@w{gpgme_subkey_t @var{key}})
+The function @code{gpgme_pubkey_algo_string} is a convenience function
+to build and return an algorithm string in the same way GnuPG does
+(e.g. ``rsa2048'' or ``ed25519'').  The caller must free the result
+using @code{gpgme_free}.  On error (e.g. invalid argument or memory
+exhausted), the function returns NULL and sets @code{ERRNO}.
+@end deftypefun
+
 
 @node Hash Algorithms
 @section Hash Algorithms
@@ -1091,6 +1221,7 @@ that are supported by @acronym{GPGME}.  Possible values are:
 @item GPGME_MD_SHA256
 @item GPGME_MD_SHA384
 @item GPGME_MD_SHA512
+@item GPGME_MD_SHA224
 @item GPGME_MD_MD4
 @item GPGME_MD_CRC32
 @item GPGME_MD_CRC32_RFC1510
@@ -1538,6 +1669,20 @@ by using memory buffers or files rather than pipes or sockets.  This
 might be relevant, for example, if the external event loop mechanism
 is used.
 
+@deftp {Data type} {gpgme_off_t}
+On POSIX platforms the @code{gpgme_off_t} type is an alias for
+@code{off_t}; it may be used interchangeable.  On Windows platforms
+@code{gpgme_off_t} is defined as a long (i.e. 32 bit) for 32 bit
+Windows and as a 64 bit signed integer for 64 bit Windows.
+@end deftp
+
+@deftp {Data type} {gpgme_ssize_t}
+The @code{gpgme_ssize_t} type is an alias for @code{ssize_t}.  It has
+only been introduced to overcome portability problems pertaining to
+the declaration of @code{ssize_t} by different toolchains.
+@end deftp
+
+
 @menu
 * Creating Data Buffers::         Creating new data buffers.
 * Destroying Data Buffers::       Releasing data buffers.
@@ -1830,9 +1975,11 @@ case, the data object @var{dh} is destroyed.
 
 @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.
+@code{gpgme_data_release_and_get_mem} and
+@code{gpgme_pubkey_algo_string}.  It should be used instead of the
+system libraries @code{free} function in case different allocators are
+used by a program.  This is often the case if gpgme is used under
+Windows as a DLL.
 @end deftypefun
 
 
@@ -1847,6 +1994,7 @@ be used to manipulate both.
 @menu
 * Data Buffer I/O Operations::    I/O operations on data buffers.
 * Data Buffer Meta-Data::         Meta-data manipulation of data buffers.
+* Data Buffer Convenience::       Convenience function for data buffers.
 @end menu
 
 
@@ -2009,6 +2157,56 @@ The function @code{gpgme_data_set_encoding} changes the encoding of
 the data object with the handle @var{dh} to @var{enc}.
 @end deftypefun
 
+@node Data Buffer Convenience
+@subsection Data Buffer Convenience Functions
+@cindex data buffer, convenience
+@cindex type of data
+@cindex identify
+
+@deftp {Data type} {enum gpgme_data_type_t}
+@tindex gpgme_data_type_t
+The @code{gpgme_data_type_t} type is used to return the detected type
+of the content of a data buffer.
+@end deftp
+
+@table @code
+@item GPGME_DATA_TYPE_INVALID
+This is returned by @code{gpgme_data_identify} if it was not possible
+to identify the data.  Reasons for this might be a non-seekable stream
+or a memory problem.  The value is 0.
+@item GPGME_DATA_TYPE_UNKNOWN
+The type of the data is not known.
+@item GPGME_DATA_TYPE_PGP_SIGNED
+The data is an OpenPGP signed message.  This may be a binary
+signature, a detached one or a cleartext signature.
+@item GPGME_DATA_TYPE_PGP_OTHER
+This is a generic OpenPGP message.  In most cases this will be
+encrypted data.
+@item GPGME_DATA_TYPE_PGP_KEY
+This is an OpenPGP key (private or public).
+@item GPGME_DATA_TYPE_CMS_SIGNED
+This is a CMS signed message.
+@item GPGME_DATA_TYPE_CMS_ENCRYPTED
+This is a CMS encrypted (enveloped data) message.
+@item GPGME_DATA_TYPE_CMS_OTHER
+This is used for other CMS message types.
+@item GPGME_DATA_TYPE_X509_CERT
+The data is a X.509 certificate
+@item GPGME_DATA_TYPE_PKCS12
+The data is a PKCS#12 message.  This is commonly used to exchange
+private keys for X.509.
+@end table
+
+@deftypefun gpgme_data_type_t gpgme_data_identify (@w{gpgme_data_t @var{dh}})
+The function @code{gpgme_data_identify} returns the type of the data
+with the handle @var{dh}.  If it is not possible to perform the
+identification, the function returns zero
+(@code{GPGME_DATA_TYPE_INVALID}).  Note that depending on how the data
+object has been created the identification may not be possible or the
+data object may change its internal state (file pointer moved).  For
+file or memory based data object, the state should not change.
+@end deftypefun
+
 
 @c
 @c    Chapter Contexts
@@ -2037,6 +2235,7 @@ cryptographic operations.
 * Key Management::                Managing keys with @acronym{GPGME}.
 * Trust Item Management::         Managing trust items with @acronym{GPGME}.
 * Crypto Operations::             Using a context for cryptography.
+* Miscellaneous::                 Miscellaneous operations
 * Run Control::                   Controlling how operations are run.
 @end menu
 
@@ -2111,10 +2310,12 @@ started.  In fact, these references are accessed through the
 * Crypto Engine::                 Configuring the crypto engine.
 * ASCII Armor::                   Requesting @acronym{ASCII} armored output.
 * Text Mode::                     Choosing canonical text mode.
-* Included Certificates::       Including a number of certificates.
+* Offline Mode::                  Choosing offline mode.
+* Included Certificates::         Including a number of certificates.
 * Key Listing Mode::              Selecting key listing mode.
 * Passphrase Callback::           Getting the passphrase from the user.
 * Progress Meter Callback::       Being informed about the progress.
+* Status Message Callback::       Status messages received from gpg.
 * Locale::                        Setting the locale of a context.
 @end menu
 
@@ -2239,6 +2440,37 @@ valid pointer.
 @end deftypefun
 
 
+@node Offline Mode
+@subsection Offline Mode
+@cindex context, offline mode
+@cindex offline mode
+
+@deftypefun void gpgme_set_offline (@w{gpgme_ctx_t @var{ctx}}, @w{int @var{yes}})
+The function @code{gpgme_set_offline} specifies if offline mode
+should be used.  By default, offline mode is not used.
+
+The offline mode specifies if dirmngr should be used to do additional
+validation that might require connections to external services.
+(e.g. CRL / OCSP checks).
+
+Offline mode only affects the keylist mode @code{GPGME_KEYLIST_MODE_VALIDATE}
+and is only relevant to the CMS crypto engine. Offline mode
+is ignored otherwise.
+
+This option may be extended in the future to completely disable
+the use of dirmngr for any engine.
+
+Offline mode is disabled if @var{yes} is zero, and enabled
+otherwise.
+@end deftypefun
+
+@deftypefun int gpgme_get_offline (@w{gpgme_ctx_t @var{ctx}})
+The function @code{gpgme_get_offline} returns 1 if offline
+mode is enabled, and @code{0} if it is not, or if @var{ctx} is not a
+valid pointer.
+@end deftypefun
+
+
 @node Included Certificates
 @subsection Included Certificates
 @cindex certificates, included
@@ -2311,6 +2543,13 @@ signature notations on key signatures should be included in the listed
 keys.  This only works if @code{GPGME_KEYLIST_MODE_SIGS} is also
 enabled.
 
+@item GPGME_KEYLIST_MODE_WITH_SECRET
+The @code{GPGME_KEYLIST_MODE_WITH_SECRET} returns information about
+the presence of a corresponding secret key in a public key listing.  A
+public key listing with this mode is slower than a standard listing
+but can be used instead of a second run to list the secret keys.  This
+is only supported for GnuPG versions >= 2.1.
+
 @item GPGME_KEYLIST_MODE_EPHEMERAL
 The @code{GPGME_KEYLIST_MODE_EPHEMERAL} symbol specifies that keys
 flagged as ephemeral are included in the listing.
@@ -2461,6 +2700,70 @@ the corresponding value will not be returned.
 @end deftypefun
 
 
+@node Status Message Callback
+@subsection Status Message Callback
+@cindex callback, status message
+@cindex status message callback
+
+@deftp {Data type} {gpgme_error_t (*gpgme_status_cb_t)(void *@var{hook}, const char *@var{keyword}, const char *@var{args})}
+@tindex gpgme_status_cb_t
+The @code{gpgme_status_cb_t} type is the type of function usable as
+a status message callback function.
+
+The argument @var{keyword} is the name of the status message while the
+@var{args} argument contains any arguments for the status message.
+
+If an error occurs, return the corresponding @code{gpgme_error_t}
+value. Otherwise, return @code{0}.
+@end deftp
+
+@deftypefun void gpgme_set_status_cb (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_status_cb_t @var{statusfunc}}, @w{void *@var{hook_value}})
+The function @code{gpgme_set_status_cb} sets the function that is used when a
+status message is received from gpg to @var{statusfunc}. The function
+@var{statusfunc} needs to be implemented by the user, and whenever it is
+called, it is called with its first argument being @var{hook_value}.  By
+default, no status message callback function is set.
+
+The user can disable the use of a status message callback function by calling
+@code{gpgme_set_status_cb} with @var{statusfunc} being @code{NULL}.
+@end deftypefun
+
+@deftypefun void gpgme_get_status_cb (@w{gpgme_ctx_t @var{ctx}}, @w{gpgme_status_cb_t *@var{statusfunc}}, @w{void **@var{hook_value}})
+The function @code{gpgme_get_status_cb} returns the function that is used to
+process status messages from gpg in @var{*statusfunc}, and the first argument
+for this function in @var{*hook_value}.  If no status message callback is set,
+or @var{ctx} is not a valid pointer, @code{NULL} is returned in both
+variables.
+@end deftypefun
+
+@deftypefun {gpgme_error_t} gpgme_set_ctx_flag  @
+            (@w{gpgme_ctx_t @var{ctx}}, @
+            @w{const char *@var{name}}, @
+            @w{const char *@var{value}})
+
+Some minor properties of the context can be controlled with flags set
+by this function.  The properties are identified by the following
+values for @var{name}:
+
+@table @code
+@item "full-status"
+Using a @var{value} of "1" the status callback set by
+gpgme_set_status_cb returns all status lines with the exception of
+PROGRESS lines.  With the default of "0" the status callback is only
+called in certain situations.
+
+@item "raw-description"
+Setting the @var{value} to "1" returns human readable strings in a raw
+format.  For example the non breaking space characters ("~") will not
+be removed from the @code{description} field of the
+@code{gpgme_tofu_info_t} object.
+
+@end table
+
+This function returns @code{0} on success.
+@end deftypefun
+
+
 @node Locale
 @subsection Locale
 @cindex locale, default
@@ -2507,8 +2810,8 @@ signers are specified.  This is always done by specifying the
 respective keys that should be used for the operation.  The following
 section describes how such keys can be selected and manipulated.
 
-@deftp {Data type} gpgme_sub_key_t
-The @code{gpgme_sub_key_t} type is a pointer to a subkey structure.
+@deftp {Data type} gpgme_subkey_t
+The @code{gpgme_subkey_t} type is a pointer to a subkey structure.
 Sub keys are one component of a @code{gpgme_key_t} object.  In fact,
 subkeys are those parts that contains the real information about the
 individual cryptographic keys that belong to the same key object.  One
@@ -2518,7 +2821,7 @@ the linked list is also called the primary key.
 The subkey structure has the following members:
 
 @table @code
-@item gpgme_sub_key_t next
+@item gpgme_subkey_t next
 This is a pointer to the next subkey structure in the linked list, or
 @code{NULL} if this is the last element.
 
@@ -2551,9 +2854,11 @@ 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.  Note that it will be false
-if the key is actually a stub key; i.e. a secret key operation is
-currently not possible (offline-key).
+This is true if the subkey is a secret key.  Note that it will be
+false if the key is actually a stub key; i.e. a secret key operation
+is currently not possible (offline-key).  This is only set if a
+listing of secret keys has been requested or if
+@code{GPGME_KEYLIST_MODE_WITH_SECRET} is active.
 
 @item gpgme_pubkey_algo_t pubkey_algo
 This is the public key algorithm supported by this subkey.
@@ -2575,6 +2880,16 @@ timestamp is invalid, and 0 if it is not available.
 @item long int expires
 This is the expiration timestamp of the subkey, or 0 if the subkey
 does not expire.
+
+@item unsigned int is_cardkey : 1
+True if the secret key is stored on a smart card.
+
+@item char *card_number
+The serial number of a smart card holding this key or @code{NULL}.
+
+@item char *curve
+For ECC algorithms the name of the curve.
+
 @end table
 @end deftp
 
@@ -2734,9 +3049,10 @@ 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.  Note, that this will always be
-true even if the corresponding subkey flag may be false (offline/stub
-keys).
+This is true if the key is a secret key.  Note, that this will always
+be true even if the corresponding subkey flag may be false
+(offline/stub keys).  This is only set if a listing of secret keys has
+been requested or if @code{GPGME_KEYLIST_MODE_WITH_SECRET} is active.
 
 @item gpgme_protocol_t protocol
 This is the protocol supported by this key.
@@ -2757,7 +3073,7 @@ chain ID, which can be used to built the certificate chain.
 If @code{protocol} is @code{GPGME_PROTOCOL_OpenPGP}, then this is the
 owner trust.
 
-@item gpgme_sub_key_t subkeys
+@item gpgme_subkey_t subkeys
 This is a linked list with the subkeys of the key.  The first subkey
 in the list is the primary key and usually available.
 
@@ -3434,6 +3750,21 @@ keys it removes all signatures except for the latest self-signatures.
 For X.509 keys it has no effect.
 
 
+@item GPGME_EXPORT_MODE_SECRET
+Instead of exporting the public key, the secret key is exported.  This
+may not be combined with @code{GPGME_EXPORT_MODE_EXTERN}.  For X.509
+the export format is PKCS#8.
+
+@item GPGME_EXPORT_MODE_RAW
+If this flag is used with @code{GPGME_EXPORT_MODE_SECRET} for an X.509
+key the export format will be changed to PKCS#1.  This flag may not be
+used with OpenPGP.
+
+@item GPGME_EXPORT_MODE_PKCS12
+If this flag is used with @code{GPGME_EXPORT_MODE_SECRET} for an X.509
+key the export format will be changed to PKCS#12 which also includes
+the certificate.  This flag may not be used with OpenPGP.
+
 @end table
 
 
@@ -3506,7 +3837,7 @@ 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{keys}.  Only keys of the currently selected protocol of
 @var{ctx} which do have a fingerprint set are considered for export.
 Other keys specified by the @var{keys} are ignored.  In particular
 OpenPGP keys retrieved via an external key listing are not included.
@@ -3579,7 +3910,7 @@ permanent which have been retrieved from an external source (i.e. using
 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
+Only keys of the currently selected protocol of @var{ctx} are
 considered for import.  Other keys specified by the @var{keys} are
 ignored.  As of now all considered keys must have been retrieved using
 the same method, that is the used key listing mode must be identical.
@@ -3666,34 +3997,34 @@ The number of keys without user ID.
 @item int imported
 The total number of imported keys.
 
-@item imported_rsa
+@item int imported_rsa
 The number of imported RSA keys.
 
-@item unchanged
+@item int unchanged
 The number of unchanged keys.
 
-@item new_user_ids
+@item int new_user_ids
 The number of new user IDs.
 
-@item new_sub_keys
+@item int new_sub_keys
 The number of new sub keys.
 
-@item new_signatures
+@item int new_signatures
 The number of new signatures.
 
-@item new_revocations
+@item int new_revocations
 The number of new revocations.
 
-@item secret_read
+@item int secret_read
 The total number of secret keys read.
 
-@item secret_imported
+@item int secret_imported
 The number of imported secret keys.
 
-@item secret_unchanged
+@item int secret_unchanged
 The number of unchanged secret keys.
 
-@item not_imported
+@item int not_imported
 The number of keys not imported.
 
 @item gpgme_import_status_t imports
@@ -4099,9 +4430,6 @@ or @code{NULL} if this is the last element.
 @item gpgme_pubkey_algo_t
 The public key algorithm used in the encryption.
 
-@item unsigned int wrong_key_usage : 1
-This is true if the key was not used according to its policy.
-
 @item char *keyid
 This is the key ID of the key (in hexadecimal digits) used as
 recipient.
@@ -4395,6 +4723,9 @@ The public key algorithm used to create this signature.
 
 @item gpgme_hash_algo_t
 The hash algorithm used to create this signature.
+
+@item char *pka_address
+The mailbox from the PKA information or @code{NULL}.
 @end table
 @end deftp
 
@@ -4747,6 +5078,11 @@ list of signers in the context @var{ctx}.
 Calling this function acquires an additional reference for the key.
 @end deftypefun
 
+@deftypefun @w{unsigned int} gpgme_signers_count (@w{const gpgme_ctx_t @var{ctx}})
+The function @code{gpgme_signers_count} returns the number of signer keys in
+the context @var{ctx}.
+@end deftypefun
+
 @deftypefun gpgme_key_t gpgme_signers_enum (@w{const gpgme_ctx_t @var{ctx}}, @w{int @var{seq}})
 The function @code{gpgme_signers_enum} returns the @var{seq}th key in
 the list of signers in the context @var{ctx}.  An additional reference
@@ -4826,10 +5162,10 @@ list, or @code{NULL} if this is the last element.
 @item gpgme_sig_mode_t type
 The type of this signature.
 
-@item gpgme_pubkey_algo_t
+@item gpgme_pubkey_algo_t pubkey_algo
 The public key algorithm used to create this signature.
 
-@item gpgme_hash_algo_t
+@item gpgme_hash_algo_t hash_algo
 The hash algorithm used to create this signature.
 
 @item unsigned int sig_class
@@ -4950,7 +5286,7 @@ ciphertext created is determined by the @acronym{ASCII} armor (or, if
 that is not set, by the encoding specified for @var{cipher}) and the
 text mode attributes set for the context @var{ctx}.
 
-@var{key} must be a @code{NULL}-terminated array of keys.  The user
+@var{recp} must be a @code{NULL}-terminated array of keys.  The user
 must keep references for all keys during the whole duration of the
 call (but see @code{gpgme_op_encrypt_start} for the requirements with
 the asynchronous variant).
@@ -4970,6 +5306,21 @@ The @code{GPGME_ENCRYPT_NO_ENCRYPT_TO} symbol specifies that no
 default or hidden default recipients as configured in the crypto
 backend should be included.  This can be useful for managing different
 user profiles.
+
+@item GPGME_ENCRYPT_NO_COMPRESS
+The @code{GPGME_ENCRYPT_NO_COMPRESS} symbol specifies that the
+plaintext shall not be compressed before it is encrypted.  This is
+in some cases useful if the length of the encrypted message
+may reveal information about the plaintext.
+
+@item GPGME_ENCRYPT_PREPARE
+@itemx GPGME_ENCRYPT_EXPECT_SIGN
+The @code{GPGME_ENCRYPT_PREPARE} symbol is used with the UI Server
+protocol to prepare an encryption (i.e. sending the
+@code{PREP_ENCRYPT} command).  With the
+@code{GPGME_ENCRYPT_EXPECT_SIGN} symbol the UI Server is advised to
+also expect a sign command.
+
 @end table
 
 If @code{GPG_ERR_UNUSABLE_PUBKEY} is returned, some recipients in
@@ -5061,6 +5412,67 @@ pointer.
 @end deftypefun
 
 
+@node Miscellaneous
+@section Miscellaneous operations
+
+Here are some support functions which are sometimes useful.
+
+@menu
+* Running other Programs::      Running other Programs
+@end menu
+
+
+@node Running other Programs
+@subsection Running other Programs
+
+GPGME features an internal subsystem to run the actual backend
+engines.  Along with data abstraction object this subsystem can be
+used to run arbitrary simple programs which even need not be related
+to cryptographic features.  It may for example be used to run tools
+which are part of the GnuPG system but are not directly accessible
+with the GPGME API.
+
+
+@deftypefun gpgme_error_t gpgme_op_spawn
+            (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{file}}, @
+             @w{const char *@var{argv}[]}, @w{gpgme_data_t @var{datain}}, @
+             @w{gpgme_data_t @var{dataout}}, @w{gpgme_data_t @var{dataerr}}, @
+             @w{unsigned int @var{flags}})
+
+The function @code{gpgme_op_spawn} runs the program @var{file} with
+the arguments taken from the NULL terminated array @var{argv}.  If no
+arguments are required @var{argv} may be given as @code{NULL}.  In the
+latter case or if @code{argv[0]} is the empty string, GPGME uses the
+basename of @var{file} for @code{argv[0]}.  The file descriptors
+@code{stdin}, @code{stdout}, and @code{stderr} are connected to the
+data objects @var{datain}, @var{dataout}, and @var{dataerr}.  If NULL
+is passed for one of these data objects the corresponding file
+descriptor is connected to @file{/dev/null}.
+
+The value in @var{flags} is a bitwise-or combination of one or
+multiple of the following bit values:
+
+@table @code
+@item GPGME_SPAWN_DETACHED
+Under Windows this flag inhibits the allocation of a new console for
+the program.  This is useful for a GUI application which needs to call
+a command line helper tool.
+@item GPGME_SPAWN_ALLOW_SET_FG
+Under Windows this flag allows the called program to put itself into
+the foreground.
+@end table
+@end deftypefun
+
+@deftypefun gpgme_error_t gpgme_op_spawn_start
+            (@w{gpgme_ctx_t @var{ctx}}, @w{const char *@var{file}}, @
+             @w{const char *@var{argv}[]}, @w{gpgme_data_t @var{datain}}, @
+             @w{gpgme_data_t @var{dataout}}, @w{gpgme_data_t @var{dataerr}}, @
+             @w{unsigned int @var{flags}})
+
+This is the asynchronous variant of @code{gpgme_op_spawn}.
+@end deftypefun
+
+
 @node Run Control
 @section Run Control
 @cindex run control
@@ -5241,9 +5653,9 @@ callback handlers must not be run before this event is signalled.
 @item GPGME_EVENT_DONE
 The operation is finished, the last I/O callback for this operation
 was removed.  The accompanying @var{type_data} points to a
-@code{gpgme_error_t} variable that contains the status of the operation
-that finished.  This event is signalled after the last I/O callback
-has been removed.
+@code{struct gpgme_io_event_done_data} variable that contains the
+status of the operation that finished.  This event is signalled after
+the last I/O callback has been removed.
 
 @item GPGME_EVENT_NEXT_KEY
 In a @code{gpgme_op_keylist_start} operation, the next key was
@@ -5281,7 +5693,7 @@ list of possible @code{gpgme_event_io_t} types.
 @node Registering I/O Callbacks
 @subsubsection Registering I/O Callbacks
 
-@deftp {Data type} {struct gpgme_io_cb_ts}
+@deftp {Data type} {struct gpgme_io_cbs}
 @tindex gpgme_event_io_t
 This structure is used to store the I/O callback interface functions
 described in the previous section.  It has the following members:
@@ -5291,7 +5703,7 @@ described in the previous section.  It has the following members:
 This is the function called by @acronym{GPGME} to register an I/O
 callback handler.  It must be specified.
 
-@item void *add_data
+@item void *add_priv
 This is passed as the first argument to the @code{add} function when
 it is called by @acronym{GPGME}.  For example, it can be used to
 determine the event loop to which the file descriptor should be added.
@@ -5305,14 +5717,14 @@ This is the function called by @acronym{GPGME} to signal an event for
 an operation.  It must be specified, because at least the start event
 must be processed.
 
-@item void *event_data
+@item void *event_priv
 This is passed as the first argument to the @code{event} function when
 it is called by @acronym{GPGME}.  For example, it can be used to
 determine the context in which the event has occured.
 @end table
 @end deftp
 
-@deftypefun void gpgme_set_io_cbs (@w{gpgme_ctx_t @var{ctx}}, @w{struct gpgme_io_cb_ts *@var{io_cbs}})
+@deftypefun void gpgme_set_io_cbs (@w{gpgme_ctx_t @var{ctx}}, @w{struct gpgme_io_cbs *@var{io_cbs}})
 The function @code{gpgme_set_io_cbs} enables the I/O callback
 interface for the context @var{ctx}.  The I/O callback functions are
 specified by @var{io_cbs}.
@@ -5321,7 +5733,7 @@ If @var{io_cbs}->@code{add} is @code{NULL}, the I/O callback interface
 is disabled for the context, and normal operation is restored.
 @end deftypefun
 
-@deftypefun void gpgme_get_io_cbs (@w{gpgme_ctx_t @var{ctx}}, @w{struct gpgme_io_cb_ts *@var{io_cbs}})
+@deftypefun void gpgme_get_io_cbs (@w{gpgme_ctx_t @var{ctx}}, @w{struct gpgme_io_cbs *@var{io_cbs}})
 The function @code{gpgme_get_io_cbs} returns the I/O callback
 functions set with @code{gpgme_set_io_cbs} in @var{io_cbs}.
 @end deftypefun
@@ -5511,7 +5923,7 @@ main (int argc, char *argv[])
   gpgme_error_t err;
   gpgme_data_t sig, text;
   int i;
-  struct gpgme_io_cb_ts io_cbs =
+  struct gpgme_io_cbs io_cbs =
   @{
     add_io_cb,
     &loop,
@@ -5762,16 +6174,16 @@ operation in the context @var{ctx}.  This only works if you use the
 global event loop or your own event loop.
 
 If you use the global event loop, you must not call @code{gpgme_wait}
-or @code{gpgme_wait} during cancellation.  After successful
+during cancellation.  After successful
 cancellation, you can call @code{gpgme_wait} (optionally waiting on
 @var{ctx}), and the context @var{ctx} will appear as if it had
 finished with the error code @code{GPG_ERR_CANCEL}.
 
-If you use your an external event loop, you must ensure that no I/O
+If you use an external event loop, you must ensure that no I/O
 callbacks are invoked for this context (for example by halting the
 event loop).  On successful cancellation, all registered I/O callbacks
 for this context will be unregistered, and a @code{GPGME_EVENT_DONE}
-event with the error code @code{GPG_ERR_CANCEL} will be signaled.
+event with the error code @code{GPG_ERR_CANCEL} will be signalled.
 
 The function returns an error code if the cancellation failed (in this
 case the state of @var{ctx} is not modified).
@@ -5814,9 +6226,10 @@ may use @acronym{GPGME}'s built in trace feature.  This feature is
 either enabled using the environment variable @code{GPGME_DEBUG} or,
 if this is not possible, by calling the function
 @code{gpgme_set_global_flag}.  The value is the trace level and
-an optional file name.
+an optional file name.  If no file name is given the trace output is
+printed to @code{stderr}.
 
-@noindenr
+@noindent
 For example
 @smallexample
 GPGME_DEBUG=9:/home/user/mygpgme.log
@@ -5840,15 +6253,15 @@ you run your tests only with play data.
 
 @include gpl.texi
 
-@node Function and Data Index
-@unnumbered Function and Data Index
-
-@printindex fn
-
 @node Concept Index
 @unnumbered Concept Index
 
 @printindex cp
 
+@node Function and Data Index
+@unnumbered Function and Data Index
+
+@printindex fn
+
 
 @bye