Dies ist gpgme.info, hergestellt von Makeinfo Version 4.2 aus
gpgme.texi.

   This file documents the GPGME library.

   This is Edition 0.4.0, last updated 22 December 2002, of `The `GnuPG
Made Easy' Reference Manual', for Version 0.4.0.

   Copyright (C) 2002 g10 Code GmbH.

   Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with the
Invariant Sections being "Free Software Needs Free Documentation" and
"GNU Lesser General Public License", the Front-Cover texts being (a)
(see below), and with the Back-Cover Texts being (b) (see below).  A
copy of the license is included in the section entitled "GNU Free
Documentation License".

Main Menu
*********

   This is Edition 0.4.0, last updated 22 December 2002, of `The `GnuPG
Made Easy' Reference Manual', for Version 0.4.0 of the GPGME library.

Appendices

Indices

Introduction
************

   `GnuPG Made Easy' (GPGME) is a C language library that allows to add
support for cryptography to a program.  It is designed to make access
to crypto engines like GnuPG or GpgSM easier for applications.  GPGME
provides a high-level crypto API for encryption, decryption, signing,
signature verification and key management.

   GPGME uses GnuPG and GpgSM as its backends to support OpenPGP and
the Cryptographic Message Syntax (CMS).

Getting Started
===============

   This library documents the GPGME library programming interface.  All
functions and data types provided by the library are explained.

   The reader is assumed to possess basic knowledge about cryptography
in general, and public key cryptography in particular.  The underlying
cryptographic engines that are used by the library are not explained,
but where necessary, special features or requirements by an engine are
mentioned as far as they are relevant to GPGME or its users.

   This manual can be used in several ways.  If read from the beginning
to the end, it gives a good introduction into the library and how it
can be used in an application.  Forward references are included where
necessary.  Later on, the manual can be used as a reference manual to
get just the information needed about any particular interface of the
library.  Experienced programmers might want to start looking at the
examples at the end of the manual, and then only read up those parts of
the interface which are unclear.

Features
========

   GPGME has a couple of advantages over other libraries doing a
similar job, and over implementing support for GnuPG or other crypto
engines into your application directly.

it's free software
     Anybody can use, modify, and redistribute it under the terms of
     the GNU General Public License (see Copying).

it's flexible
     GPGME provides transparent support for several cryptographic
     protocols by different engines.  Currently, GPGME supports the
     OpenPGP protocol using GnuPG as the backend, and the Cryptographic
     Message Syntax using GpgSM as the backend.

it's easy
     GPGME hides the differences between the protocols and engines from
     the programmer behind an easy-to-use interface.  This way the
     programmer can focus on the other parts of the program, and still
     integrate strong cryptography in his application.  Once support for
     GPGME has been added to a program, it is easy to add support for
     other crypto protocols once GPGME backends provide them.

Overview
========

   GPGME provides a data abstraction that is used to pass data to the
crypto engine, and receive returned data from it.  Data can be read
from memory or from files, but it can also be provided by a callback
function.

   The actual cryptographic operations are always set within a context.
A context provides configuration parameters that define the behaviour
of all operations performed within it.  Only one operation per context
is allowed at any time, but when one operation is finished, you can run
the next operation in the same context.  There can be more than one
context, and all can run different operations at the same time.

   Furthermore, GPGME has rich key management facilities including
listing keys, querying their attributes, generating, importing,
exporting and deleting keys, and acquiring information about the trust
path.

   With some precautions, GPGME can be used in a multi-threaded
environment, although it is not completely thread safe and thus needs
the support of the application.

Preparation
***********

   To use GPGME, you have to perform some changes to your sources and
the build system.  The necessary changes are small and explained in the
following sections.  At the end of this chapter, it is described how
the library is initialized, and how the requirements of the library are
verified.

Header
======

   All interfaces (data types and functions) of the library are defined
in the header file `gpgme.h'.  You must include this in all programs
using the library, either directly or through some other header file,
like this:

     #include <gpgme.h>

   The name space of GPGME is `gpgme_*' for function names, `Gpgme*'
for data types and `GPGME_*' for other symbols.  Symbols internal to
GPGME take the form `_gpgme_*'.

   Because GPGME links to the Assuan library, linking to GPGME will
also use the `assuan_*' and `_assuan_*' name space indirectly.

Building the Source
===================

   If you want to compile a source file including the `gpgme.h' header
file, you must make sure that the compiler can find it in the directory
hierarchy.  This is accomplished by adding the path to the directory in
which the header file is located to the compilers include file search
path (via the `-I' option).

   However, the path to the include file is determined at the time the
source is configured.  To solve this problem, gpgme ships with a small
helper program `gpgme-config' that knows about the path to the include
file and other configuration options.  The options that need to be
added to the compiler invocation at compile time are output by the
`--cflags' option to `gpgme-config'.  The following example shows how
it can be used at the command line:

     gcc -c foo.c `gpgme-config --cflags`

   Adding the output of `gpgme-config --cflags' to the compilers
command line will ensure that the compiler can find the GPGME header
file.

   A similar problem occurs when linking the program with the library.
Again, the compiler has to find the library files.  For this to work,
the path to the library files has to be added to the library search
path (via the `-L' option).  For this, the option `--libs' to
`gpgme-config' can be used.  For convenience, this option also outputs
all other options that are required to link the program with GPGME (in
particular, the `-lgpgme' option).  The example shows how to link
`foo.o' with the GPGME library to a program `foo'.

     gcc -o foo foo.o `gpgme-config --libs`

   Of course you can also combine both examples to a single command by
specifying both options to `gpgme-config':

     gcc -o foo foo.c `gpgme-config --cflags --libs`

Using Automake
==============

   It is much easier if you use GNU Automake instead writing your own
Makefiles.  If you do that you don't have to worry about finding and
invoking the `gpgme-config' script at all.  GPGME provides an extension
to Automake that does all the work for you.

 - Makro: AM_PATH_GPGME ([MINIMUM-VERSION], [ACTION-IF-FOUND],
          [ACTION-IF-NOT-FOUND])
     Check whether GPGME (at least version MINIMUM-VERSION, if given)
     exists on the host system.  If it is found, execute
     ACTION-IF-FOUND, otherwise do ACTION-IF-NOT-FOUND, if given.

     Additionally, the function defines `GPGME_CFLAGS' to the flags
     needed for compilation of the program to find the `gpgme.h' header
     file, and `GPGME_LIBS' to the linker flags needed to link the
     program to the GPGME library.

   You can use the defined Autoconf variables like this in your
`Makefile.am':

     AM_CPPFLAGS = $(GPGME_CFLAGS)
     LDADD = $(GPGME_LIBS)

Library Version Check
=====================

 - Funktion: const char * gpgme_check_version
          (const char *REQUIRED_VERSION)
     The function `gpgme_check_version' has three 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 GPGME.

     If REQUIRED_VERSION is `NULL', the function returns a pointer to a
     statically allocated string containing the version number of the
     library.

     If REQUIRED_VERSION is not `NULL', it should point to a string
     containing a version number, and the function checks that the
     version of the library is at least as high as the version number
     provided.  In this case, the function returns a pointer to a
     statically allocated string containing the version number of the
     library.  If REQUIRED_VERSION is not a valid version number, or if
     the version requirement is not met, the function returns `NULL'.

     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.

Multi Threading
===============

   The GPGME library is not entirely thread-safe, but it can still be
used in a multi-threaded environment if some care is taken.  If the
following requirements are met, there should be no race conditions to
worry about:

   * GPGME supports the thread libraries pthread and GNU Pth.  The
     support for this has to be enabled at compile time.  GPGME will
     automatically detect the location in which the thread libraries
     are installed and activate the support for them.

     Support for other thread libraries is very easy to add.  Please
     contact us if you have the need.

   * If you link your program dynamically to GPGME and your supported
     thread library, GPGME will automatically detect the presence of
     this library and activate its use.  If you link to both pthread
     and GNU Pth, GPGME will use the pthread support.  This feature
     requires weak symbol support.

   * If you link your program statically to GPGME, there is currently
     no easy way to make sure that GPGME detects the presence of the
     thread library.  This will be solved in a future version.

   * The function `gpgme_check_version' must be called before any other
     function in the library, because it initializes the thread support
     subsystem in GPGME.  To achieve this in all generality, it is
     necessary to synchronize the call to this function with all other
     calls to functions in the library, using the synchronization
     mechanisms available in your thread library.  Otherwise, specific
     compiler or CPU memory cache optimizations could lead to the
     situation where a thread is started and uses GPGME before the
     effects of the initialization are visible for this thread.  It
     doesn't even suffice to call `gpgme_check_version' before creating
     this other thread(1).

     For example, if you are using POSIX threads, each thread that
     wants to call functions in GPGME could call the following function
     before any function in the library:

          #include <pthread.h>

          void
          initialize_gpgme (void)
          {
            static int gpgme_init;
            static pthread_mutext_t gpgme_init_lock = PTHREAD_MUTEX_INITIALIZER;

            pthread_mutex_lock (&gpgme_init_lock);
            if (!gpgme_init)
              {
                gpgme_check_version ();
                gpgme_init = 1;
              }
            pthread_mutex_unlock (&gpgme_init_lock);
          }

   * Any `GpgmeData', `GpgmeCtx' and `GpgmeRecipients' object must only
     be accessed by one thread at a time.  If multiple threads want to
     deal with the same object, the caller has to make sure that
     operations on this object are fully synchronized.

   * Only one thread at any time is allowed to call `gpgme_wait'.  If
     multiple threads call this function, the caller must make sure that
     all invocations are fully synchronized.

   ---------- Footnotes ----------

   (1) In SMP systems the new thread could be started on another CPU
before the effects of the initialization are seen by that CPU's memory
cache.  Not doing proper synchronization here leads to the same
problems the double-checked locking idiom has.  You might find that if
you don't do proper synchronization, it still works in most
configurations.  Don't let this fool you.  Someday it might lead to
subtle bugs when someone tries it on a DEC Alpha or an SMP machine.

Protocols and Engines
*********************

   GPGME supports several cryptographic protocols, however, it does not
implement them.  Rather it uses backends (also called engines) which
implement the protocol.  GPGME uses inter-process communication to pass
data back and forth between the application and the backend, but the
details of the communication protocol and invocation of the backends is
completely hidden by the interface.  All complexity is handled by
GPGME.  Where an exchange of information between the application and
the backend is necessary, GPGME provides the necessary callback function
hooks and further interfaces.

 - Data type: enum GpgmeProtocol
     The `GpgmeProtocol' type specifies the set of possible protocol
     values that are supported by GPGME.  The following protocols are
     supported:

    `GPGME_PROTOCOL_OpenPGP'
          This specifies the OpenPGP protocol.

    `GPGME_PROTOCOL_CMS'
          This specifies the Cryptographic Message Syntax.

Engine Version Check
====================

 - Funktion: GpgmeError gpgme_engine_check_version
          (GpgmeProtocol PROTOCOL)
     The function `gpgme_engine_check_version' verifies that the engine
     implementing the protocol PROTOCOL is installed in the expected
     path and meets the version requirement of GPGME.

     This function returns `GPGME_No_Error' if the engine is available
     and `GPGME_Invalid_Engine' if it is not.

Engine Information
==================

 - Funktion: const char * gpgme_get_engine_info (void)
     The function `gpgme_get_engine_info' returns an XML string
     containing information about the available protocols and the
     engine which implement them.  The following information is returned
     for each engine:

    `<protocol>'
          The name of the protocol.

    `<version>'
          The version of the engine.

    `<path>'
          The path to the engine binary.

     A string is always returned.  If an error occurs, the string will
     contain an `<error>' tag with a description of the failure.

   Here is the example output of what `gpgme_get_engine_info' might
return on your system:

     <EngineInfo>
      <engine>
       <protocol>OpenPGP</protocol>
       <version>1.0.6</version>
       <path>/usr/bin/gpg</path>
      </engine>
      <engine>
       <protocol>CMS</protocol>
       <version>0.0.0</version>
       <path>/usr/bin/gpgsm</path>
      </engine>
     </EngineInfo>

OpenPGP
=======

   OpenPGP is implemented by GnuPG, the GNU Privacy Guard.  This is the
first protocol that was supported by GPGME.

   The OpenPGP protocol is specified by `GPGME_PROTOCOL_OpenPGP'.

Cryptographic Message Syntax
============================

   CMS is implemented by GpgSM, the S/MIME implementation for GnuPG.

   The CMS protocol is specified by `GPGME_PROTOCOL_CMS'.

Error Handling
**************

   Many functions in GPGME can return an error if they fail.  For this
reason, the application should always catch the error condition and
take appropriate measures, for example by releasing the resources and
passing the error up to the caller, or by displaying a descriptive
message to the user and cancelling the operation.

   Some error values do not indicate a system error or an error in the
operation, but the result of an operation that failed properly.  For
example, if you try to decrypt a tempered message, the decryption will
fail.  Another error value actually means that the end of a data buffer
or list has been reached.  The following descriptions explain what each
error message means in general.  Some error values have specific
meanings if returned by a specific function.  Such cases are described
in the documentation of those functions.

Error Values
============

 - Data type: enum GpgmeError
     The `GpgmeError' type specifies the set of all error values that
     are used by GPGME.  Possible values are:

    `GPGME_EOF'
          This value indicates the end of a list, buffer or file.

    `GPGME_No_Error'
          This value indicates success.  The value of this error is `0'.

    `GPGME_General_Error'
          This value means that something went wrong, but either there
          is not enough information about the problem to return a more
          useful error value, or there is no separate error value for
          this type of problem.

    `GPGME_Out_Of_Core'
          This value means that an out-of-memory condition occurred.

    `GPGME_Invalid_Value'
          This value means that some user provided data was out of
          range.  This can also refer to objects.  For example, if an
          empty `GpgmeData' object was expected, but one containing
          data was provided, this error value is returned.

    `GPGME_Busy'
          This value is returned if you try to start a new operation in
          a context that is already busy with some earlier operation
          which was not cancelled or finished yet.

    `GPGME_No_Request'
          This value is in some sense the opposite of `GPGME_Busy'.
          There is no pending operation, but it is required for the
          function to succeed.

    `GPGME_Exec_Error'
          This value means that an error occurred when trying to spawn
          a child process.

    `GPGME_Too_Many_Procs'
          This value means that there are too many active backend
          processes.

    `GPGME_Pipe_Error'
          This value means that the creation of a pipe failed.

    `GPGME_No_Recipients'
          This value means that no valid recipients for a message have
          been set.

    `GPGME_Invalid_Recipients'
          This value means that some, but not all, recipients for a
          message have been invalid.

    `GPGME_No_Data'
          This value means that a `GpgmeData' object which was expected
          to have content was found empty.

    `GPGME_Conflict'
          This value means that a conflict of some sort occurred.

    `GPGME_Not_Implemented'
          This value indicates that the specific function (or
          operation) is not implemented.  This error should never
          happen.  It can only occur if you use certain values or
          configuration options which do not work, but for which we
          think that they should work at some later time.

    `GPGME_Read_Error'
          This value means that an I/O read operation failed.

    `GPGME_Write_Error'
          This value means that an I/O write operation failed.

    `GPGME_Invalid_Type'
          This value means that a user provided object was of a wrong or
          incompatible type.  Usually this refers to the type of a
          `GpgmeData' object.

    `GPGME_Invalid_Mode'
          This value means that a `GpgmeData' object has an incorrect
          mode of operation (for example, doesn't support output
          although it is attempted to use it as an output buffer).

    `GPGME_File_Error'
          This value means that a file I/O operation failed.  The value
          of ERRNO contains the system error value.

    `GPGME_Decryption_Failed'
          This value indicates that a decryption operation was
          unsuccessful.

    `GPGME_No_Passphrase'
          This value means that the user did not provide a passphrase
          when requested.

    `GPGME_Canceled'
          This value means that the operation was canceled.

    `GPGME_Invalid_Key'
          This value means that a key was invalid.

    `GPGME_Invalid_Engine'
          This value means that the engine that implements the desired
          protocol is currently not available.  This can either be
          because the sources were configured to exclude support for
          this engine, or because the engine is not installed properly.

Error Strings
=============

 - Funktion: const char * gpgme_strerror (GpgmeError ERR)
     The function `gpgme_strerror' returns a pointer to a statically
     allocated string containing a description of the error with the
     error value ERR.  This string can be used to output a diagnostic
     message to the user.

     The following example illustrates the use of `gpgme_strerror':

          GpgmeCtx ctx;
          GpgmeError err = gpgme_new (&ctx);
          if (err)
            {
              fprintf (stderr, "%s: creating GpgME context failed: %s\n",
                       argv[0], gpgme_strerror (err));
              exit (1);
            }

Exchanging Data
***************

   A lot of data has to be exchanged between the user and the crypto
engine, like plaintext messages, ciphertext, signatures and information
about the keys.  The technical details about exchanging the data
information are completely abstracted by GPGME.  The user provides and
receives the data via `GpgmeData' objects, regardless of the
communication protocol between GPGME and the crypto engine in use.

 - Data type: GpgmeData
     The `GpgmeData' type is a handle for a container for generic data,
     which is used by GPGME to exchange data with the user.

Creating Data Buffers
=====================

   Data objects can be based on memory, files, or callback functions
provided by the user.  Not all operations are supported by all objects.

Memory Based Data Buffers
-------------------------

   Memory based data objects store all data in allocated memory.  This
is convenient, but only practical for an amount of data that is a
fraction of the available physical memory.  The data has to be copied
from its source and to its destination, which can often be avoided by
using one of the other data object

 - Funktion: GpgmeError gpgme_data_new (GpgmeData *DH)
     The function `gpgme_data_new' creates a new `GpgmeData' object and
     returns a handle for it in DH.  The data object is memory based
     and initially empty.

     The function returns `GPGME_No_Error' if the data object was
     successfully created, `GPGME_Invalid_Value' if DH is not a valid
     pointer, and `GPGME_Out_Of_Core' if not enough memory is available.

 - Funktion: GpgmeError gpgme_data_new_from_mem (GpgmeData *DH,
          const char *BUFFER, size_t SIZE, int COPY)
     The function `gpgme_data_new_from_mem' creates a new `GpgmeData'
     object and fills it with SIZE bytes starting from BUFFER.

     If COPY is not zero, a private copy of the data is made.  If COPY
     is zero, the data is taken from the specified buffer as needed,
     and the user has to ensure that the buffer remains valid for the
     whole life span of the data object.

     The function returns `GPGME_No_Error' if the data object was
     successfully created, `GPGME_Invalid_Value' if DH or BUFFER is not
     a valid pointer, and `GPGME_Out_Of_Core' if not enough memory is
     available.

 - Funktion: GpgmeError gpgme_data_new_from_file (GpgmeData *DH,
          const char *FILENAME, int COPY)
     The function `gpgme_data_new_from_file' creates a new `GpgmeData'
     object and fills it with the content of the file FILENAME.

     If COPY is not zero, the whole file is read in at initialization
     time and the file is not used anymore after that.  This is the only
     mode supported currently.  Later, a value of zero for COPY might
     cause all reads to be delayed until the data is needed, but this is
     not yet implemented.

     The function returns `GPGME_No_Error' if the data object was
     successfully created, `GPGME_Invalid_Value' if DH or FILENAME is
     not a valid pointer, `GPGME_File_Error' if an I/O operation fails,
     `GPGME_Not_Implemented' if CODE is zero, and `GPGME_Out_Of_Core'
     if not enough memory is available.

 - Funktion: GpgmeError gpgme_data_new_from_filepart (GpgmeData *DH,
          const char *FILENAME, FILE *FP, off_t OFFSET, size_t LENGTH)
     The function `gpgme_data_new_from_filepart' creates a new
     `GpgmeData' object and fills it with a part of the file specified
     by FILENAME or FP.

     Exactly one of FILENAME and FP must be non-zero, the other must be
     zero.  The argument that is not zero specifies the file from which
     LENGTH bytes are read into the data object, starting from OFFSET.

     The function returns `GPGME_No_Error' if the data object was
     successfully created, `GPGME_Invalid_Value' if DH and exactly one
     of FILENAME and FP is not a valid pointer, `GPGME_File_Error' if
     an I/O operation fails, and `GPGME_Out_Of_Core' if not enough
     memory is available.

File Based Data Buffers
-----------------------

   File based data objects operate directly on file descriptors or
streams.  Only a small amount of data is stored in core at any time, so
the size of the data objects is not limited by GPGME.

 - Funktion: GpgmeError gpgme_data_new_from_fd (GpgmeData *DH, int FD)
     The function `gpgme_data_new_from_fd' creates a new `GpgmeData'
     object and uses the file descriptor FD to read from (if used as an
     input data object) and write to (if used as an output data object).

     When using the data object as an input buffer, the function might
     read a bit more from the file descriptor than is actually needed
     by the crypto engine in the desired operation because of internal
     buffering.

     The function returns `GPGME_No_Error' if the data object was
     successfully created, and `GPGME_Out_Of_Core' if not enough memory
     is available.

 - Funktion: GpgmeError gpgme_data_new_from_stream (GpgmeData *DH,
          FILE *STREAM)
     The function `gpgme_data_new_from_stream' creates a new
     `GpgmeData' object and uses the I/O stream STREAM to read from (if
     used as an input data object) and write to (if used as an output
     data object).

     When using the data object as an input buffer, the function might
     read a bit more from the stream than is actually needed by the
     crypto engine in the desired operation because of internal
     buffering.

     The function returns `GPGME_No_Error' if the data object was
     successfully created, and `GPGME_Out_Of_Core' if not enough memory
     is available.

Callback Based Data Buffers
---------------------------

   If neither memory nor file based data objects are a good fit for your
application, you can implement the functions a data object provides
yourself and create a data object from these callback functions.

 - Data type: ssize_t (*GpgmeDataReadCb) (void *HANDLE, void *BUFFER,
size_t SIZE)
     The `GpgmeDataReadCb' type is the type of functions which GPGME
     calls if it wants to read data from a user-implemented data
     object.  The function should read up to SIZE bytes from the
     current read position into the space starting at BUFFER.  The
     HANDLE is provided by the user at data object creation time.

     The function should return the number of bytes read, 0 on EOF, and
     -1 on error.  If an error occurs, ERRNO should be set to describe
     the type of the error.

 - Data type: ssize_t (*GpgmeDataWriteCb) (void *HANDLE,
const void *BUFFER, size_t SIZE)
     The `GpgmeDataWriteCb' type is the type of functions which GPGME
     calls if it wants to write data to a user-implemented data object.
     The function should write up to SIZE bytes to the current write
     position from the space starting at BUFFER.  The HANDLE is
     provided by the user at data object creation time.

     The function should return the number of bytes written, and -1 on
     error.  If an error occurs, ERRNO should be set to describe the
     type of the error.

 - Data type: off_t (*GpgmeDataSeekCb) (void *HANDLE, off_t OFFSET,
int WHENCE)
     The `GpgmeDataSeekCb' type is the type of functions which GPGME
     calls if it wants to change the current read/write position in a
     user-implemented data object, just like the `lseek' function.

     The function should return the new read/write position, and -1 on
     error.  If an error occurs, ERRNO should be set to describe the
     type of the error.

 - Data type: void (*GpgmeDataReleaseCb) (void *HANDLE)
     The `GpgmeDataReleaseCb' type is the type of functions which GPGME
     calls if it wants to destroy a user-implemented data object.  The
     HANDLE is provided by the user at data object creation time.

 - Data type: struct GpgmeDataCbs
     This structure is used to store the data callback interface
     functions described above.  It has the following members:

    `GpgmeDataReadCb read'
          This is the function called by GPGME to read data from the
          data object.  It is only required for input data object.

    `GpgmeDataWriteCb write'
          This is the function called by GPGME to write data to the
          data object.  It is only required for output data object.

    `GpgmeDataSeekCb seek'
          This is the function called by GPGME to change the current
          read/write pointer in the data object (if available).  It is
          optional.

    `GpgmeDataReleaseCb release'
          This is the function called by GPGME to release a data
          object.  It is optional.

 - Funktion: GpgmeError gpgme_data_new_from_cbs (GpgmeData *DH,
          struct GpgmeDataCbs *CBS, void *HANDLE)
     The function `gpgme_data_new_from_cbs' creates a new `GpgmeData'
     object and uses the user-provided callback functions to operate on
     the data object.

     The handle HANDLE is passed as first argument to the callback
     functions.  This can be used to identify this data object.

     The function returns `GPGME_No_Error' if the data object was
     successfully created, and `GPGME_Out_Of_Core' if not enough memory
     is available.

   The following interface is deprecated and only provided for backward
compatibility.  Don't use it.  It will be removed in a future version
of GPGME.

 - Funktion: GpgmeError gpgme_data_new_with_read_cb (GpgmeData *DH,
          int (*READFUNC) (void *HOOK, char *BUFFER, size_t COUNT,
          size_t *NREAD), void *HOOK_VALUE)
     The function `gpgme_data_new_with_read_cb' creates a new
     `GpgmeData' object and uses the callback function READFUNC to
     retrieve the data on demand.  As the callback function can supply
     the data in any way it wants, this is the most flexible data type
     GPGME provides.  However, it can not be used to write data.

     The callback function receives HOOK_VALUE as its first argument
     whenever it is invoked.  It should return up to COUNT bytes in
     BUFFER, and return the number of bytes actually read in NREAD.  It
     may return `0' in NREAD if no data is currently available.  To
     indicate `EOF' the function should return with an error code of
     `-1' and set NREAD to `0'.  The callback function may support to
     reset its internal read pointer if it is invoked with BUFFER and
     NREAD being `NULL' and COUNT being `0'.

     The function returns `GPGME_No_Error' if the data object was
     successfully created, `GPGME_Invalid_Value' if DH or READFUNC is
     not a valid pointer, and `GPGME_Out_Of_Core' if not enough memory
     is available.

Destroying Data Buffers
=======================

 - Funktion: void gpgme_data_release (GpgmeData DH)
     The function `gpgme_data_release' destroys the data object with
     the handle DH.  It releases all associated resources that were not
     provided by the user in the first place.

 - Funktion: char * gpgme_data_release_and_get_mem (GpgmeData DH,
          size_t *LENGTH)
     The function `gpgme_data_release_and_get_mem' is like
     `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 `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 `NULL'.

Manipulating Data Buffers
=========================

 - Funktion: ssize_t gpgme_data_read (GpgmeData DH, void *BUFFER,
          size_t LENGTH)
     The function `gpgme_data_read' reads up to LENGTH bytes from the
     data object with the handle DH into the space starting at BUFFER.

     If no error occurs, the actual amount read is returned.  If the
     end of the data object is reached, the function returns
     `GPGME_EOF' and sets NREAD to zero.

     In all other cases, the function returns -1 and sets ERRNO.

 - Funktion: ssize_t gpgme_data_write (GpgmeData DH,
          const void *BUFFER, size_t SIZE)
     The function `gpgme_data_write' writes up to SIZE bytes starting
     from BUFFER into the data object with the handle DH at the current
     write position.

     The function returns the number of bytes actually written, or -1
     if an error occurs.  If an error occurs, ERRNO is set.

   /* Set the current position from where the next read or write starts
  in the data object with the handle DH to OFFSET, relativ to
WHENCE.  */ off_t gpgme_data_seek (GpgmeData dh, off_t offset, int
whence);

 - Funktion: off_t gpgme_data_seek (GpgmeData DH, off_t *OFFSET,
          int WHENCE)
     The function `gpgme_data_seek' changes the current read/write
     position.

     The WHENCE argument specifies how the OFFSET should be
     interpreted.  It must be one of the following symbolic constants:

    `SEEK_SET'
          Specifies that WHENCE is a count of characters from the
          beginning of the data object.

    `SEEK_CUR'
          Specifies that WHENCE is a count of characters from the
          current file position.  This count may be positive or
          negative.

    `SEEK_END'
          Specifies that WHENCE 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 current end, and actually write data,
          you will extend the data object with zeros up to that
          position.

     If successful, the function returns the resulting file position,
     measured in bytes from the beginning of the data object.  You can
     use this feature together with `SEEK_CUR' to read the current
     read/write position.

     If the function fails, -1 is returned and ERRNO is set.

   The following function is deprecated and should not be used.  It will
be removed in a future version of GPGME.

 - Funktion: GpgmeError gpgme_data_rewind (GpgmeData DH)
     The function `gpgme_data_rewind' is equivalent to:

            return (gpgme_data_seek (dh, 0, SEEK_SET) == -1)
              ? mk_error (File_Error) : 0;

 - Data type: enum GpgmeDataEncoding
     The `GpgmeDataEncoding' type specifies the encoding of a
     `GpgmeData' object.  This encoding is useful to give the backend a
     hint on the type of data.  The following data types are available:

    `GPGME_DATA_ENCODING_NONE'
          This specifies that the encoding is not known.  This is the
          default for a new data object.  The backend will try its best
          to detect the encoding automatically.

    `GPGME_DATA_ENCODING_BINARY'
          This specifies that the data is encoding in binary form; i.e.
          there is no special encoding.

    `GPGME_DATA_ENCODING_BASE64'
          This specifies that the data is encoded using the Base-64
          encoding scheme as used by MIME and other protocols.

    `GPGME_DATA_ENCODING_ARMOR'
          This specifies that the data is encoded in an armored form as
          used by OpenPGP and PEM.

 - Funktion: GpgmeDataEncoding gpgme_data_get_encoding (GpgmeData DH)
     The function `gpgme_data_get_encoding' returns the encoding of the
     data object with the handle DH.  If DH is not a valid pointer
     (e.g. `NULL') `GPGME_DATA_ENCODING_NONE' is returned.

 - Funktion: GpgmeError gpgme_data_set_encoding
          (GpgmeData DH, GpgmeDataEncoding ENC)
     The function `gpgme_data_set_encoding' changes the encoding of the
     data object with the handle DH to ENC.

Contexts
********

   All cryptographic operations in GPGME are performed within a
context, which contains the internal state of the operation as well as
configuration parameters.  By using several contexts you can run
several cryptographic operations in parallel, with different
configuration.

 - Data type: GpgmeCtx
     The `GpgmeCtx' type is a handle for a GPGME context, which is used
     to hold the configuration, status and result of cryptographic
     operations.

Creating Contexts
=================

 - Funktion: GpgmeError gpgme_new (GpgmeCtx *CTX)
     The function `gpgme_data_new' creates a new `GpgmeCtx' object and
     returns a handle for it in CTX.

     The function returns `GPGME_No_Error' if the context was
     successfully created, `GPGME_Invalid_Value' if CTX is not a valid
     pointer, and `GPGME_Out_Of_Core' if not enough memory is available.

Destroying Contexts
===================

 - Funktion: void gpgme_release (GpgmeCtx CTX)
     The function `gpgme_release' destroys the context with the handle
     CTX and releases all associated resources.

Context Attributes
==================

Protocol Selection
------------------

 - Funktion: GpgmeError gpgme_set_protocol (GpgmeCtx CTX,
          GpgmeProtocol PROTO)
     The function `gpgme_set_protocol' sets the protocol used within
     the context CTX to PROTO.  All crypto operations will be performed
     by the crypto engine configured for that protocol.  See
     Protocols and Engines.

     Setting the protocol with `gpgme_set_protocol' does not check if
     the crypto engine for that protocol is available and installed
     correctly.  See Engine Version Check.

     The function returns `GPGME_No_Error' if the protocol could be set
     successfully, and `GPGME_Invalid_Value' if PROTOCOL is not a valid
     protocol.

 - Funktion: GpgmeProtocol gpgme_get_protocol (GpgmeCtx CTX)
     The function `gpgme_get_protocol' retrieves the protocol currently
     use with the context CTX.

ASCII Armor
-----------

 - Funktion: void gpgme_set_armor (GpgmeCtx CTX, int YES)
     The function `gpgme_set_armor' specifies if the output should be
     ASCII armored.  By default, output is not ASCII armored.

     ASCII armored output is disabled if YES is zero, and enabled
     otherwise.

 - Funktion: int gpgme_get_armor (GpgmeCtx CTX)
     The function `gpgme_get_armor' returns 1 if the output is ASCII
     armored, and `0' if it is not, or if CTX is not a valid pointer.