This is gpgme.info, produced by makeinfo version 4.0 from gpgme.texi.

INFO-DIR-SECTION GNU Libraries
START-INFO-DIR-ENTRY
* GPGME: (gpgme).          Adding support for cryptography to your program.
END-INFO-DIR-ENTRY

   This file documents the GPGME library.

   This is Edition 0.3.14, last updated 12 November 2002, of `The
`GnuPG Made Easy' Reference Manual', for Version 0.3.14.

   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".


File: gpgme.info,  Node: Top,  Next: Introduction,  Up: (dir)

Main Menu
*********

   This is Edition 0.3.14, last updated 12 November 2002, of `The
`GnuPG Made Easy' Reference Manual', for Version 0.3.14 of the GPGME
library.

* Menu:

* Introduction::                  How to use this manual.
* Preparation::                   What you should do before using the library.
* Protocols and Engines::         Supported crypto protocols.
* Error Handling::                Error numbers and their meanings.
* Exchanging Data::               Passing data to and from GPGME.
* Contexts::                      Handling GPGME contexts.

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.

Indices

* Concept Index::                 Index of concepts and programs.
* Function and Data Index::       Index of functions, variables and data types.


 --- The Detailed Node Listing ---

Introduction

* Getting Started::               Purpose of the manual, and how to use it.
* Features::                      Reasons to install and use GPGME.
* Overview::                      Basic architecture of the GPGME library.

Preparation

* Header::                        What header file you need to include.
* Building the Source::           Compiler options to be used.
* Using Automake::                Compiler options to be used the easy way.
* Library Version Check::         Getting and verifying the library version.
* Multi Threading::               How GPGME can be used in an MT environment.

Protocols and Engines

* Engine Version Check::          Verifying the engine version.
* Engine Information::            Obtaining more information about the engines.
* OpenPGP::                       Support for the OpenPGP protocol.
* Cryptographic Message Syntax::  Support for the CMS.

Error Handling

* Error Values::                  A list of all error values used.
* Error Strings::                 How to get a descriptive string from a value.

Exchanging Data

* Creating Data Buffers::         Creating new data buffers.
* Destroying Data Buffers::       Releasing data buffers.
* Manipulating Data Buffers::     Operations on data buffers.

Contexts

* Creating Contexts::             Creating new GPGME contexts.
* Destroying Contexts::           Releasing GPGME contexts.
* Context Attributes::            Setting properties of a context.
* Key Management::                Managing keys with GPGME.
* Trust Item Management::         Managing trust items with GPGME.
* Crypto Operations::             Using a context for cryptography.
* Run Control::                   Controlling how operations are run.

Context Attributes

* Protocol Selection::            Selecting the protocol used by a context.
* ASCII Armor::                   Requesting ASCII armored output.
* Text Mode::                     Choosing canonical text 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.

Key Management

* Listing Keys::                  Browsing the list of available keys.
* Information About Keys::        Requesting detailed information about keys.
* Manipulating Keys::             Operations on keys.
* Generating Keys::               Creating new key pairs.
* 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.

Trust Item Management

* Listing Trust Items::           Browsing the list of available trust items.
* Information About Trust Items:: Requesting detailed information about trust items.
* Manipulating Trust Items::      Operations on trust items.

Crypto Operations

* Decrypt::                       Decrypting a ciphertext.
* Verify::                        Verifying a signature.
* Decrypt and Verify::            Decrypting a signed ciphertext.
* Sign::                          Creating a signature.
* Encrypt::                       Encrypting a plaintext.
* Detailed Results::              How to obtain more info about the operation.

Sign

* Selecting Signers::             How to choose the keys to sign with.
* Creating a Signature::          How to create a signature.

Encrypt

* Selecting Recipients::          How to choose the recipients.
* Encrypting a Plaintext::        How to encrypt a plaintext.

Run Control

* Waiting For Completion::        Waiting until an operation is completed.
* Cancelling an Operation::       Interrupting a running operation.
* Hooking Up Into Idle Time::     Doing something when nothing has to be done.
* Using External Event Loops::    Advanced control over what happens when.

Using External Event Loops

* I/O Callback Interface::        How I/O callbacks are registered.
* Registering I/O Callbacks::     How to use I/O callbacks for a context.
* I/O Callback Example::          An example how to use I/O callbacks.
* I/O Callback Example GTK+::     How to integrate GPGME in GTK+.
* I/O Callback Example GDK::      How to integrate GPGME in GDK.


File: gpgme.info,  Node: Introduction,  Next: Preparation,  Prev: Top,  Up: Top

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).

* Menu:

* Getting Started::               Purpose of the manual, and how to use it.
* Features::                      Reasons to install and use GPGME.
* Overview::                      Basic architecture of the GPGME library.


File: gpgme.info,  Node: Getting Started,  Next: Features,  Up: Introduction

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.


File: gpgme.info,  Node: Features,  Next: Overview,  Prev: Getting Started,  Up: Introduction

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 (*note 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.


File: gpgme.info,  Node: Overview,  Prev: Features,  Up: Introduction

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.


File: gpgme.info,  Node: Preparation,  Next: Protocols and Engines,  Prev: Introduction,  Up: Top

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.

* Menu:

* Header::                        What header file you need to include.
* Building the Source::           Compiler options to be used.
* Using Automake::                Compiler options to be used the easy way.
* Library Version Check::         Getting and verifying the library version.
* Multi Threading::               How GPGME can be used in an MT environment.


File: gpgme.info,  Node: Header,  Next: Building the Source,  Up: Preparation

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.


File: gpgme.info,  Node: Building the Source,  Next: Using Automake,  Prev: Header,  Up: Preparation

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`


File: gpgme.info,  Node: Using Automake,  Next: Library Version Check,  Prev: Building the Source,  Up: Preparation

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.

 - Macro: 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)


File: gpgme.info,  Node: Library Version Check,  Next: Multi Threading,  Prev: Using Automake,  Up: Preparation

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

 - Function: 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.


File: gpgme.info,  Node: Multi Threading,  Prev: Library Version Check,  Up: Preparation

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.


File: gpgme.info,  Node: Protocols and Engines,  Next: Error Handling,  Prev: Preparation,  Up: Top

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.

* Menu:

* Engine Version Check::          Verifying the engine version.
* Engine Information::            Obtaining more information about the engines.
* OpenPGP::                       Support for the OpenPGP protocol.
* Cryptographic Message Syntax::  Support for the CMS.


File: gpgme.info,  Node: Engine Version Check,  Next: Engine Information,  Up: Protocols and Engines

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

 - Function: 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.

 - Function: GpgmeError gpgme_check_engine (void)
     The function `gpgme_check_engine' is equivalent to

          gpgme_engine_check_version (GPGME_PROTOCOL_OpenPGP);

     This function is deprecated and provided for backwards
     compatibility only.  It is obsoleted by
     `gpgme_engine_check_version'.


File: gpgme.info,  Node: Engine Information,  Next: OpenPGP,  Prev: Engine Version Check,  Up: Protocols and Engines

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

 - Function: 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>


File: gpgme.info,  Node: OpenPGP,  Next: Cryptographic Message Syntax,  Prev: Engine Information,  Up: Protocols and Engines

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'.


File: gpgme.info,  Node: Cryptographic Message Syntax,  Prev: OpenPGP,  Up: Protocols and Engines

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

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

   The CMS protocol is specified by `GPGME_PROTOCOL_CMS'.


File: gpgme.info,  Node: Error Handling,  Next: Exchanging Data,  Prev: Protocols and Engines,  Up: Top

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.

* Menu:

* Error Values::                  A list of all error values used.
* Error Strings::                 How to get a descriptive string from a value.


File: gpgme.info,  Node: Error Values,  Next: Error Strings,  Up: Error Handling

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.


File: gpgme.info,  Node: Error Strings,  Prev: Error Values,  Up: Error Handling

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

 - Function: 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);
            }


File: gpgme.info,  Node: Exchanging Data,  Next: Contexts,  Prev: Error Handling,  Up: Top

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.

* Menu:

* Creating Data Buffers::         Creating new data buffers.
* Destroying Data Buffers::       Releasing data buffers.
* Manipulating Data Buffers::     Operations on data buffers.


File: gpgme.info,  Node: Creating Data Buffers,  Next: Destroying Data Buffers,  Up: Exchanging Data

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

 - Function: 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 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.

 - Function: 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.

 - Function: 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.

 - Function: 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.

 - Function: 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.


File: gpgme.info,  Node: Destroying Data Buffers,  Next: Manipulating Data Buffers,  Prev: Creating Data Buffers,  Up: Exchanging Data

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

 - Function: 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.

 - Function: 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'.


File: gpgme.info,  Node: Manipulating Data Buffers,  Prev: Destroying Data Buffers,  Up: Exchanging Data

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

 - Function: GpgmeError gpgme_data_read (GpgmeData DH, void *BUFFER,
          size_t LENGTH, size_t *NREAD)
     The function `gpgme_data_read' reads up to LENGTH bytes from the
     data object with the handle DH into the space starting at BUFFER.
     The actual amount read is returned in NREAD.

     If BUFFER is `NULL', the function returns the amount of bytes
     available in NREAD without changing the read pointer.  This is not
     supported by all types of data objects.  If this function is not
     supported, `GPGME_Invalid_Type' 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 `GPGME_No_Error' if the
     operation was successfully performed and `GPGME_Invalid_Value' if
     DH is not a valid pointer.

 - Function: GpgmeError gpgme_data_rewind (GpgmeData DH)
     The function `gpgme_data_rewind' resets the read pointer of the
     data object with the handle DH, so that a subsequent
     `gpgme_data_read' operation starts at the beginning of the data.

     The function returns `GPGME_No_Error' if the operation was
     successfully performed, `GPGME_Not_Implemented' if the operation
     is not supported (for example, by a read callback function
     supplied by the user) and `GPGME_Invalid_Value' if DH is not a
     valid pointer.

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

     The function returns `GPGME_No_Error' if the operation was
     successfully performed, `GPGME_Invalid_Value' if DH or BUFFER is
     not a valid pointer, `GPGME_Invalid_Type' or `GPGME_Invalid_Mode'
     if the data object type does not support writing, and
     `GPGME_Out_Of_Core' if not enough memory is available.

 - Data type: enum GpgmeDataType
     The `GpgmeDataType' type specifies the type of a `GpgmeData'
     object.  The following data types are available:

    `GPGME_DATA_TYPE_NONE'
          This specifies that the type is not yet determined.

    `GPGME_DATA_TYPE_MEM'
          This specifies that the data is stored in memory.

    `GPGME_DATA_TYPE_FD'
          This type is not implemented.

    `GPGME_DATA_TYPE_FILE'
          This type is not implemented.

    `GPGME_DATA_TYPE_CB'
          This type specifies that the data is provided by a callback
          function implemented by the user.

 - Function: GpgmeDataType gpgme_data_get_type (GpgmeData DH)
     The function `gpgme_data_get_type' returns the type of the data
     object with the handle DH.  If DH is not a valid pointer,
     `GPGME_DATA_TYPE_NONE' is returned.

 - 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.

 - Function: 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.

 - Function: 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.


File: gpgme.info,  Node: Contexts,  Next: Copying,  Prev: Exchanging Data,  Up: Top

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.

* Menu:

* Creating Contexts::             Creating new GPGME contexts.
* Destroying Contexts::           Releasing GPGME contexts.
* Context Attributes::            Setting properties of a context.
* Key Management::                Managing keys with GPGME.
* Trust Item Management::         Managing trust items with GPGME.
* Crypto Operations::             Using a context for cryptography.
* Run Control::                   Controlling how operations are run.


File: gpgme.info,  Node: Creating Contexts,  Next: Destroying Contexts,  Up: Contexts

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

 - Function: 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.


File: gpgme.info,  Node: Destroying Contexts,  Next: Context Attributes,  Prev: Creating Contexts,  Up: Contexts

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

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


File: gpgme.info,  Node: Context Attributes,  Next: Key Management,  Prev: Destroying Contexts,  Up: Contexts

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

* Menu:

* Protocol Selection::            Selecting the protocol used by a context.
* ASCII Armor::                   Requesting ASCII armored output.
* Text Mode::                     Choosing canonical text 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.


File: gpgme.info,  Node: Protocol Selection,  Next: ASCII Armor,  Up: Context Attributes

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

 - Function: 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.  *Note
     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.  *Note 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.

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


File: gpgme.info,  Node: ASCII Armor,  Next: Text Mode,  Prev: Protocol Selection,  Up: Context Attributes

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

 - Function: 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.

 - Function: 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.


File: gpgme.info,  Node: Text Mode,  Next: Included Certificates,  Prev: ASCII Armor,  Up: Context Attributes

Text Mode
---------

 - Function: void gpgme_set_textmode (GpgmeCtx CTX, int YES)
     The function `gpgme_set_textmode' specifies if canonical text mode
     should be used.  By default, text mode is not used.

     Text mode is for example used for the RFC2015 signatures; note that
     the updated RFC 3156 mandates that the mail user agent does some
     preparations so that text mode is not needed anymore.

     This option is only relevant to the OpenPGP crypto engine, and
     ignored by all other engines.

     Canonical text mode is disabled if YES is zero, and enabled
     otherwise.

 - Function: int gpgme_get_textmode (GpgmeCtx CTX)
     The function `gpgme_get_textmode' returns 1 if canonical text mode
     is enabled, and `0' if it is not, or if CTX is not a valid pointer.


File: gpgme.info,  Node: Included Certificates,  Next: Key Listing Mode,  Prev: Text Mode,  Up: Context Attributes

Included Certificates
---------------------

 - Function: void gpgme_set_include_certs (GpgmeCtx CTX,
          int NR_OF_CERTS)
     The function `gpgme_set_include_certs' specifies how many
     certificates should be included in an S/MIME signed message.  By
     default, only the sender's certificate is included.  The possible
     values of NR_OF_CERTS are:

    `-2'
          Include all certificates except the root certificate.

    `-1'
          Include all certificates.

    `0'
          Include no certificates.

    `1'
          Include the sender's certificate only.

    `n'
          Include the first n certificates of the certificates path,
          starting from the sender's certificate.  The number `n' must
          be positive.

     Values of NR_OF_CERTS smaller than -2 are undefined.

     This option is only relevant to the CMS crypto engine, and ignored
     by all other engines.

 - Function: int gpgme_get_include_certs (GpgmeCtx CTX)
     The function `gpgme_get_include_certs' returns the number of
     certificates to include into an S/MIME signed message.


File: gpgme.info,  Node: Key Listing Mode,  Next: Passphrase Callback,  Prev: Included Certificates,  Up: Context Attributes

Key Listing Mode
----------------

 - Function: void gpgme_set_keylist_mode (GpgmeCtx CTX, int MODE)
     The function `gpgme_set_keylist_mode' changes the default
     behaviour of the key listing functions.  The value in MODE is a
     bitwise-or combination of one or multiple of the following bit
     values:

    `GPGME_KEYLIST_MODE_LOCAL'
          The `GPGME_KEYLIST_MODE_LOCAL' symbol specifies that the local
          keyring should be searched for keys in the keylisting
          operation.  This is the default.

    `GPGME_KEYLIST_MODE_EXTERN'
          The `GPGME_KEYLIST_MODE_EXTERN' symbol specifies that an
          external source should be should be searched for keys in the
          keylisting operation.  The type of external source is
          dependant on the crypto engine used.  For example, it can be
          a remote keyserver or LDAP certificate server.

     At least one of `GPGME_KEYLIST_MODE_LOCAL' and
     `GPGME_KEYLIST_MODE_EXTERN' must be specified.  For future binary
     compatibility, you should get the current mode with
     `gpgme_get_keylist_mode' and modify it by setting or clearing the
     appropriate bits, and then using that calulcated value in the
     `gpgme_set_keylisting_mode' operation.  This will leave all other
     bits in the mode value intact (in particular those that are not
     used in the current version of the library).

     The function returns `GPGME_No_Error' if the mode could be set
     correctly, and `GPGME_Invalid_Value' if CTX is not a valid pointer
     or MODE is not a valid mode.

 - Function: int gpgme_get_keylist_mode (GpgmeCtx CTX)
     The function `gpgme_get_keylist_mode' returns the current key
     listing mode of the context CTX.  This value can then be modified
     and used in a subsequent `gpgme_set_keylist_mode' operation to
     only affect the desired bits (and leave all others intact).

     The function returns 0 if CTX is not a valid pointer, and the
     current mode otherwise.  Note that 0 is not a valid mode value.


File: gpgme.info,  Node: Passphrase Callback,  Next: Progress Meter Callback,  Prev: Key Listing Mode,  Up: Context Attributes

Passphrase Callback
-------------------

 - Data type: const char *(*GpgmePassphraseCb)(void *HOOK, const char
*DESC, void **R_HD)
     The `GpgmePassphraseCb' type is the type of functions usable as
     passphrase callback function.

     The string DESC contains a text usable to be displayed to the user
     of the application.  The function should return a passphrase for
     the context when invoked with DESC not being `NULL'.

     The user may store information about the resources associated with
     the returned passphrase in *R_HD.  When the passphrase is no longer
     needed by GPGME, the passphrase callback function will be called
     with DESC being NULL, and R_HD being the same as at the first
     invocation.

 - Function: void gpgme_set_passphrase_cb (GpgmeCtx CTX,
          GpgmePassphraseCb PASSFUNC, void *HOOK_VALUE)
     The function `gpgme_set_passphrase_cb' sets the function that is
     used when a passphrase needs to be provided by the user to
     PASSFUNC.  The function PASSFUNC needs to implemented by the user,
     and whenever it is called, it is called with its first argument
     being HOOK_VALUE.  By default, no passphrase callback 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.

     The user can disable the use of a passphrase callback function by
     calling `gpgme_set_passphrase_cb' with PASSFUNC being `NULL'.

 - Function: void gpgme_get_passphrase_cb (GpgmeCtx CTX,
          GpgmePassphraseCb *PASSFUNC, void **HOOK_VALUE)
     The function `gpgme_get_passphrase_cb' returns the function that
     is used when a passphrase needs to be provided by the user in
     *PASSFUNC, and the first argument for this function in
     *HOOK_VALUE.  If no passphrase callback is set, or CTX is not a
     valid pointer, `NULL' is returned in both variables.

     PASSFUNC or HOOK_VALUE can be `NULL'.  In this case, the
     corresponding value will not be returned.


File: gpgme.info,  Node: Progress Meter Callback,  Prev: Passphrase Callback,  Up: Context Attributes

Progress Meter Callback
-----------------------

 - Data type: const char *(*GpgmeProgressCb)(void *HOOK, const char
*WHAT, int TYPE, int CURRENT, int TOTAL)
     The `GpgmeProgressCb' type is the type of functions usable as
     progress callback function.

     The arguments are specific to the crypto engine.  More information
     about the progress information returned from the GnuPG engine can
     be found in the GnuPG source code in the file `doc/DETAILS' in the
     section PROGRESS.

 - Function: void gpgme_set_progress_cb (GpgmeCtx CTX,
          GpgmeProgressCb PROGFUNC, void *HOOK_VALUE)
     The function `gpgme_set_progress_cb' sets the function that is
     used when progress information about a cryptographic operation is
     available.  The function PROGFUNC needs to implemented by the
     user, and whenever it is called, it is called with its first
     argument being HOOK_VALUE.  By default, no progress callback
     function is set.

     Setting a callback function allows an interactive program to
     display progress information about a long operation to the user.

     The user can disable the use of a progress callback function by
     calling `gpgme_set_progress_cb' with PROGFUNC being `NULL'.

 - Function: void gpgme_get_progress_cb (GpgmeCtx CTX,
          GpgmeProgressCb *PROGFUNC, void **HOOK_VALUE)
     The function `gpgme_get_progress_cb' returns the function that is
     used to inform the user about the progress made in *PROGFUNC, and
     the first argument for this function in *HOOK_VALUE.  If no
     progress callback is set, or CTX is not a valid pointer, `NULL' is
     returned in both variables.

     PROGFUNC or HOOK_VALUE can be `NULL'.  In this case, the
     corresponding value will not be returned.


File: gpgme.info,  Node: Key Management,  Next: Trust Item Management,  Prev: Context Attributes,  Up: Contexts

Key Management
==============

   Some of the cryptographic operations require that recipients or
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.

 - Data type: GpgmeKey
     The `GpgmeKey' type is a handle for a public or secret key, and is
     used to select the key for operations involving it.

     A key can contain several user IDs and sub keys.

* Menu:

* Listing Keys::                  Browsing the list of available keys.
* Information About Keys::        Requesting detailed information about keys.
* Manipulating Keys::             Operations on keys.
* Generating Keys::               Creating new key pairs.
* 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.


File: gpgme.info,  Node: Listing Keys,  Next: Information About Keys,  Up: Key Management

Listing Keys
------------

 - Function: GpgmeError gpgme_op_keylist_start (GpgmeCtx CTX,
          const char *PATTERN, int SECRET_ONLY)
     The function `gpgme_op_keylist_start' initiates a key listing
     operation inside the context CTX.  It sets everything up so that
     subsequent invocations of `gpgme_op_keylist_next' return the keys
     in the list.

     If PATTERN is `NULL', all available keys are returned.  Otherwise,
     PATTERN contains an engine specific expression that is used to
     limit the list to all keys matching the pattern.

     If SECRET_ONLY is not `0', the list is restricted to secret keys
     only.

     The context will be busy until either all keys are received (and
     `gpgme_op_keylist_next' returns `GPGME_EOF'), or
     `gpgme_op_keylist_end' is called to finish the operation.

     The function returns `GPGME_Invalid_Value' if CTX is not a valid
     pointer, and passes through any errors that are reported by the
     crypto engine support routines.

 - Function: GpgmeError gpgme_op_keylist_ext_start (GpgmeCtx CTX,
          const char *PATTERN[], int SECRET_ONLY, int RESERVED)
     The function `gpgme_op_keylist_ext_start' initiates an extended
     key listing operation inside the context CTX.  It sets everything
     up so that subsequent invocations of `gpgme_op_keylist_next'
     return the keys in the list.

     If PATTERN or *PATTERN is `NULL', all available keys are returned.
     Otherwise, PATTERN is a `NULL' terminated array of strings that
     are used to limit the list to all keys matching at least one of
     the patterns verbatim.

     If SECRET_ONLY is not `0', the list is restricted to secret keys
     only.

     The value of RESERVED must be `0'.

     The context will be busy until either all keys are received (and
     `gpgme_op_keylist_next' returns `GPGME_EOF'), or
     `gpgme_op_keylist_end' is called to finish the operation.

     The function returns `GPGME_Invalid_Value' if CTX is not a valid
     pointer, and passes through any errors that are reported by the
     crypto engine support routines.

 - Function: GpgmeError gpgme_op_keylist_next (GpgmeCtx CTX,
          GpgmeKey *R_KEY)
     The function `gpgme_op_keylist_next' returns the next key in the
     list created by a previous `gpgme_op_keylist_start' operation in
     the context CTX.  The key will have one reference for the user.
     *Note Manipulating Keys::.

     This is the only way to get at `GpgmeKey' objects in GPGME.

     If the last key in the list has already been returned,
     `gpgme_op_keylist_next' returns `GPGME_EOF'.

     The function returns `GPGME_Invalid_Value' if CTX or R_KEY is not
     a valid pointer, `GPGME_No_Request' if there is no pending
     operation, `GPGME_Out_Of_Core' if there is not enough memory for
     the operation.

 - Function: GpgmeError gpgme_op_keylist_end (GpgmeCtx CTX)
     The function `gpgme_op_keylist_next' ends a pending key list
     operation in the context CTX.

     The function returns `GPGME_Invalid_Value' if CTX is not a valid
     pointer, `GPGME_No_Request' if there is no pending operation,
     `GPGME_Out_Of_Core' if at some time during the operation there was
     not enough memory available.

   The following example illustrates how all keys containing a certain
string (`g10code') can be listed with their key ID and the name and
e-mail address of the main user ID:

     GpgmeCtx ctx;
     GpgmeError err = gpgme_new (&ctx);
     
     if (!err)
       {
         err = gpgme_op_keylist_start (ctx, "g10code", 0);
         while (!err && (err = gpgme_op_keylist_next (ctx, &key)) != GPGME_EOF)
           {
             printf ("%s: %s <%s>\n",
                     gpgme_key_get_string_attr (key, GPGME_ATTR_KEYID, 0, 0),
     	        gpgme_key_get_string_attr (key, GPGME_ATTR_NAME, 0, 0),
     	        gpgme_key_get_string_attr (key, GPGME_ATTR_EMAIL, 0, 0));
             gpgme_key_release (key);
           }
         gpgme_release (ctx);
       }
     if (err)
       {
         fprintf (stderr, "%s: can not list keys: %s\n",
                  argv[0], gpgme_strerror (err));
         exit (1);
       }


File: gpgme.info,  Node: Information About Keys,  Next: Manipulating Keys,  Prev: Listing Keys,  Up: Key Management

Information About Keys
----------------------

 - Function: char * gpgme_key_get_as_xml (GpgmeKey KEY)
     The function `gpgme_key_get_as_xml' returns a string in XML format
     describing the key KEY.  The user has to release the string with
     `free'.

     The function returns `NULL' if KEY is not a valid pointer, or
     there is not enough memory available.

 - Data type: GpgmeAttr
     The `GpgmeAttr' type is used to specify a key or trust item
     attribute.  The following attributes are defined:

    `GPGME_ATTR_KEYID'
          This is the key ID of a sub key.  It is representable as a
          string.

          For trust items, the trust item refers to the key with this
          ID.

    `GPGME_ATTR_FPR'
          This is the fingerprint of a sub key.  It is representable as
          a string.

    `GPGME_ATTR_ALGO'
          This is the crypto algorithm for which the sub key can be
          used.  It is representable as a string and as a number.  The
          numbers correspond to the `enum gcry_pk_algos' values in the
          gcrypt library.

    `GPGME_ATTR_LEN'
          This is the key length of a sub key.  It is representable as a
          number.

    `GPGME_ATTR_CREATED'
          This is the timestamp at creation time of a sub key.  It is
          representable as a number.

    `GPGME_ATTR_EXPIRE'
          This is the expiration time of a sub key.  It is
          representable as a number.

    `GPGME_ATTR_OTRUST'
          XXX FIXME  (also for trust items)

    `GPGME_ATTR_USERID'
          This is a user ID.  There can be more than one user IDs in a
          GPGMEKEY object.  The first one (with index 0) is the primary
          user ID.  The user ID is representable as a number.

          For trust items, this is the user ID associated with this
          trust item.

    `GPGME_ATTR_NAME'
          This is the name belonging to a user ID.  It is representable
          as a string.

    `GPGME_ATTR_EMAIL'
          This is the email address belonging to a user ID.  It is
          representable as a string.

    `GPGME_ATTR_COMMENT'
          This is the comment belonging to a user ID.  It is
          representable as a string.

    `GPGME_ATTR_VALIDITY'
          This is the validity belonging to a user ID.  It is
          representable as a string and as a number.  See below for a
          list of available validities.

          For trust items, this is the validity that is associated with
          this trust item.

    `GPGME_ATTR_UID_REVOKED'
          This specifies if a user ID is revoked.  It is representable
          as a number, and is `1' if the user ID is revoked, and `0'
          otherwise.

    `GPGME_ATTR_UID_INVALID'
          This specifies if a user ID is invalid.  It is representable
          as a number, and is `1' if the user ID is invalid, and `0'
          otherwise.

    `GPGME_ATTR_LEVEL'
          This is the trust level of a trust item.

    `GPGME_ATTR_TYPE'
          This returns information about the type of key.  For the
          string function this will eother be "PGP" or "X.509".  The
          integer function returns 0 for PGP and 1 for X.509.  It is
          also used for the type of a trust item.

    `GPGME_ATTR_IS_SECRET'
          This specifies if the key is a secret key.  It is
          representable as a string or a number.  If the key is a
          secret key, the representation is "1" or `1', otherwise it is
          `NULL' or `0'.

    `GPGME_ATTR_KEY_REVOKED'
          This specifies if a sub key is revoked.  It is representable
          as a number, and is `1' if the key is revoked, and `0'
          otherwise.

    `GPGME_ATTR_KEY_INVALID'
          This specifies if a sub key is invalid.  It is representable
          as a number, and is `1' if the key is invalid, and `0'
          otherwise.

    `GPGME_ATTR_KEY_EXPIRED'
          This specifies if a sub key is expired.  It is representable
          as a number, and is `1' if the key is expired, and `0'
          otherwise.

    `GPGME_ATTR_KEY_DISABLED'
          This specifies if a sub key is disabled.  It is representable
          as a number, and is `1' if the key is disabled, and `0'
          otherwise.

    `GPGME_ATTR_KEY_CAPS'
          This is a description of the capabilities of a sub key.  It is
          representable as a string.  The string contains the letter
          "e" if the key can be used for encryption, "s" if the key can
          be used for signatures, and "c" if the key can be used for
          certifications.

    `GPGME_ATTR_CAN_ENCRYPT'
          This specifies if a sub key can be used for encryption.  It is
          representable as a number, and is `1' if the sub key can be
          used for encryption, and `0' otherwise.

    `GPGME_ATTR_CAN_SIGN'
          This specifies if a sub key can be used for signatures.  It is
          representable as a number, and is `1' if the sub key can be
          used for signatures, and `0' otherwise.

    `GPGME_ATTR_CAN_CERTIFY'
          This specifies if a sub key can be used for certifications.
          It is representable as a number, and is `1' if the sub key
          can be used for certifications, and `0' otherwise.

    `GPGME_ATTR_SERIAL'
          The X.509 issuer serial attribute of the key.  It is
          representable as a string.

    `GPGME_ATTR_ISSUE'
          The X.509 issuer name attribute of the key.  It is
          representable as a string.

    `GPGME_ATTR_CHAINID'
          The X.509 chain ID can be used to build the certification
          chain.  It is representable as a string.

 - Data type: GpgmeValidity
     The `GpgmeValidity' type is used to specify the validity of a user
     ID in a key.  The following validities are defined:

    `GPGME_VALIDITY_UNKNOWN'
          The user ID is of unknown validity.  The string
          representation of this validity is "?".

    `GPGME_VALIDITY_UNDEFINED'
          The validity of the user ID is undefined.  The string
          representation of this validity is "q".

    `GPGME_VALIDITY_NEVER'
          The user ID is never valid.  The string representation of this
          validity is "n".

    `GPGME_VALIDITY_MARGINAL'
          The user ID is marginally valid.  The string representation
          of this validity is "m".

    `GPGME_VALIDITY_FULL'
          The user ID is fully valid.  The string representation of this
          validity is "f".

    `GPGME_VALIDITY_ULTIMATE'
          The user ID is ultimately valid.  The string representation
          of this validity is "u".

 - Function: const char * gpgme_key_get_string_attr (GpgmeKey KEY,
          GpgmeAttr WHAT, const void *RESERVED, int IDX)
     The function `gpgme_key_get_string_attr' returns the value of the
     string-representable attribute WHAT of key KEY.  If the attribute
     is an attribute of a sub key or an user ID, IDX specifies the sub
     key or user ID of which the attribute value is returned.  The
     argument RESERVED is reserved for later use and should be `NULL'.

     The string returned is only valid as long as the key is valid.

     The function returns `0' if an attribute can't be returned as a
     string, KEY is not a valid pointer, IDX out of range, or RESERVED
     not `NULL'.

 - Function: unsigned long gpgme_key_get_ulong_attr (GpgmeKey KEY,
          GpgmeAttr WHAT, const void *RESERVED, int IDX)
     The function `gpgme_key_get_ulong_attr' returns the value of the
     number-representable attribute WHAT of key KEY.  If the attribute
     is an attribute of a sub key or an user ID, IDX specifies the sub
     key or user ID of which the attribute value is returned.  The
     argument RESERVED is reserved for later use and should be `NULL'.

     The function returns `0' if the attribute can't be returned as a
     number, KEY is not a valid pointer, IDX out of range, or RESERVED
     not `NULL'.


File: gpgme.info,  Node: Manipulating Keys,  Next: Generating Keys,  Prev: Information About Keys,  Up: Key Management

Manipulating Keys
-----------------

 - Function: void gpgme_key_ref (GpgmeKey KEY)
     The function `gpgme_key_ref' acquires an additional reference for
     the key KEY.

 - Function: void gpgme_key_unref (GpgmeKey KEY)
 - Function: void gpgme_key_release (GpgmeKey KEY)
     The function `gpgme_key_ref' releases a reference for the key KEY.
     If this was the last reference, the key will be destroyed and all
     resources associated to it will be released.

     The function `gpgme_key_release' is an alias for `gpgme_key_unref'.


File: gpgme.info,  Node: Generating Keys,  Next: Exporting Keys,  Prev: Manipulating Keys,  Up: Key Management

Generating Keys
---------------

 - Function: GpgmeError gpgme_op_genkey (GpgmeCtx CTX,
          const char *PARMS, GpgmeData PUBKEY, GpgmeData SECKEY)
     The function `gpgme_op_genkey' generates a new key pair in the
     context CTX and puts it into the standard key ring if both PUBKEY
     and SECKEY are `NULL'.  In this case the function returns
     immediately after starting the operation, and does not wait for it
     to complete.  If PUBKEY is not `NULL' it should be the handle for
     an empty (newly created) data object, and upon successful
     completion the data object will contain the public key.  If SECKEY
     is not `NULL' it should be the handle for an empty (newly created)
     data object, and upon successful completion the data object will
     contain the secret key.

     Note that not all crypto engines support this interface equally.
     GnuPG does not support PUBKEY and SUBKEY, they should be both
     `NULL', and the key pair will be added to the standard key ring.
     GpgSM does only support PUBKEY, the secret key will be stored by
     `gpg-agent'.  GpgSM expects PUBKEY being not `NULL'.

     The argument PARMS specifies parameters for the key in an XML
     string.  The details about the format of PARMS are specific to the
     crypto engine used by CTX.  Here is an example for GnuPG as the
     crypto engine:

          <GnupgKeyParms format="internal">
          Key-Type: DSA
          Key-Length: 1024
          Subkey-Type: ELG-E
          Subkey-Length: 1024
          Name-Real: Joe Tester
          Name-Comment: with stupid passphrase
          Name-Email: joe@foo.bar
          Expire-Date: 0
          Passphrase: abc
          </GnupgKeyParms>

     Here is an example for GpgSM as the crypto engine:
          <GnupgKeyParms format="internal">
          Key-Type: RSA
          Key-Length: 1024
          Name-DN: C=de,O=g10 code,OU=Testlab,CN=Joe 2 Tester
          Name-Email: joe@foo.bar
          </GnupgKeyParms>

     Strings should be given in UTF-8 encoding.  The only format
     supported for now is "internal".  The content of the
     `GnupgKeyParms' container is passed verbatim to GnuPG.  Control
     statements are not allowed.

     The function returns `GPGME_No_Error' if the operation could be
     started successfully, `GPGME_Invalid_Value' if PARMS is not a
     valid XML string, `GPGME_Not_Supported' if PUBKEY or SECKEY is not
     valid, and `GPGME_General_Error' if no key was created by the
     backend.

 - Function: GpgmeError gpgme_op_genkey_start (GpgmeCtx CTX,
          const char *PARMS, GpgmeData PUBKEY, GpgmeData SECKEY)
     The function `gpgme_op_genkey_start' initiates a `gpgme_op_genkey'
     operation.  It can be completed by calling `gpgme_wait' on the
     context.  *Note Waiting For Completion::.

     The function returns `GPGME_No_Error' if the operation could be
     started successfully, `GPGME_Invalid_Value' if PARMS is not a
     valid XML string, and `GPGME_Not_Supported' if PUBKEY or SECKEY is
     not `NULL'.


File: gpgme.info,  Node: Exporting Keys,  Next: Importing Keys,  Prev: Generating Keys,  Up: Key Management

Exporting Keys
--------------

 - Function: GpgmeError gpgme_op_export (GpgmeCtx CTX,
          GpgmeRecipients RECIPIENTS, GpgmeData KEYDATA)
     The function `gpgme_op_export' extracts the public keys of the
     user IDs in RECIPIENTS and returns them in the data buffer
     KEYDATA.  The type of the public keys returned is determined by
     the ASCII armor attribute set for the context CTX.

     The function returns `GPGME_No_Error' if the operation completed
     successfully, `GPGME_Invalid_Value' if RECIPIENTS is `NULL' or
     KEYDATA is not a valid empty data buffer, and passes through any
     errors that are reported by the crypto engine support routines.

 - Function: GpgmeError gpgme_op_export_start (GpgmeCtx CTX,
          GpgmeRecipients RECIPIENTS, GpgmeData KEYDATA)
     The function `gpgme_op_export_start' initiates a `gpgme_op_export'
     operation.  It can be completed by calling `gpgme_wait' on the
     context.  *Note Waiting For Completion::.

     The function returns `GPGME_No_Error' if the operation could be
     started successfully, and `GPGME_Invalid_Value' if RECIPIENTS is
     `NULL' or KEYDATA is not a valid empty data buffer.


File: gpgme.info,  Node: Importing Keys,  Next: Deleting Keys,  Prev: Exporting Keys,  Up: Key Management

Importing Keys
--------------

 - Function: GpgmeError gpgme_op_import (GpgmeCtx CTX,
          GpgmeData KEYDATA)
     The function `gpgme_op_import' adds the keys in the data buffer
     KEYDATA to the key ring of the crypto engine used by CTX.  The
     format of KEYDATA can be ASCII armored, for example, but the
     details are specific to the crypto engine.

     More information about the import is available with
     `gpgme_get_op_info'.  *Note Detailed Results::.

     The function returns `GPGME_No_Error' if the import was completed
     successfully, `GPGME_Invalid_Value' if KEYDATA if CTX or KEYDATA
     is not a valid pointer, and `GPGME_No_Data' if KEYDATA is an empty
     data buffer.

 - Function: GpgmeError gpgme_op_import_start (GpgmeCtx CTX,
          GpgmeData KEYDATA)
     The function `gpgme_op_import_start' initiates a `gpgme_op_import'
     operation.  It can be completed by calling `gpgme_wait' on the
     context.  *Note Waiting For Completion::.

     The function returns `GPGME_No_Error' if the import could be
     started successfully, `GPGME_Invalid_Value' if KEYDATA if CTX or
     KEYDATA is not a valid pointer, and `GPGME_No_Data' if KEYDATA is
     an empty data buffer.

 - Function: GpgmeError gpgme_op_import_ext (GpgmeCtx CTX,
          GpgmeData KEYDATA, int *NR)
     The function `gpgme_op_import_ext' is like `gpgme_op_import', but
     also returns the number of processed keys in NR.  This is the same
     as the `count' information in the detailed results available with
     `gpgme_get_op_info'.


File: gpgme.info,  Node: Deleting Keys,  Prev: Importing Keys,  Up: Key Management

Deleting Keys
-------------

 - Function: GpgmeError gpgme_op_delete (GpgmeCtx CTX,
          const GpgmeKey KEY, int ALLOW_SECRET)
     The function `gpgme_op_delete' deletes the key KEY from the key
     ring of the crypto engine used by CTX.  If ALLOW_SECRET is `0',
     only public keys are deleted, otherwise secret keys are deleted as
     well, if that is supported.

     The function returns `GPGME_No_Error' if the key was deleted
     successfully, `GPGME_Invalid_Value' if CTX or KEY is not a valid
     pointer, `GPGME_Invalid_Key' if KEY could not be found in the
     keyring, and `GPGME_Conflict' if the secret key for KEY is
     available, but ALLOW_SECRET is zero.

 - Function: GpgmeError gpgme_op_delete_start (GpgmeCtx CTX,
          const GpgmeKey KEY, int ALLOW_SECRET)
     The function `gpgme_op_delete_start' initiates a `gpgme_op_delete'
     operation.  It can be completed by calling `gpgme_wait' on the
     context.  *Note Waiting For Completion::.

     The function returns `GPGME_No_Error' if the operation was started
     successfully, and `GPGME_Invalid_Value' if CTX or KEY is not a
     valid pointer.


File: gpgme.info,  Node: Trust Item Management,  Next: Crypto Operations,  Prev: Key Management,  Up: Contexts

Trust Item Management
=====================

   *Caution:* The trust items interface is experimental.

 - Data type: GpgmeTrustItem
     The `GpgmeTrustItem' type is a handle for a trust item.

* Menu:

* Listing Trust Items::           Browsing the list of available trust items.
* Information About Trust Items:: Requesting detailed information about trust items.
* Manipulating Trust Items::      Operations on trust items.


File: gpgme.info,  Node: Listing Trust Items,  Next: Information About Trust Items,  Up: Trust Item Management

Listing Trust Items
-------------------

 - Function: GpgmeError gpgme_op_trustlist_start (GpgmeCtx CTX,
          const char *PATTERN, int MAX_LEVEL)
     The function `gpgme_op_trustlist_start' initiates a trust item
     listing operation inside the context CTX.  It sets everything up
     so that subsequent invocations of `gpgme_op_trustlist_next' return
     the trust items in the list.

     The string PATTERN contains an engine specific expression that is
     used to limit the list to all trust items matching the pattern.  It
     can not be the empty string.

     The argument MAX_LEVEL is currently ignored.

     The context will be busy until either all trust items are received
     (and `gpgme_op_trustlist_next' returns `GPGME_EOF'), or
     `gpgme_op_trustlist_end' is called to finish the operation.

     The function returns `GPGME_Invalid_Value' if CTX is not a valid
     pointer, and passes through any errors that are reported by the
     crypto engine support routines.

 - Function: GpgmeError gpgme_op_trustlist_next (GpgmeCtx CTX,
          GpgmeTrustItem *R_ITEM)
     The function `gpgme_op_trustlist_next' returns the next trust item
     in the list created by a previous `gpgme_op_trustlist_start'
     operation in the context CTX.  The trust item can be destroyed
     with `gpgme_trust_item_release'.  *Note Manipulating Trust Items::.

     This is the only way to get at `GpgmeTrustItem' objects in GPGME.

     If the last trust item in the list has already been returned,
     `gpgme_op_trustlist_next' returns `GPGME_EOF'.

     The function returns `GPGME_Invalid_Value' if CTX or R_ITEM is not
     a valid pointer, `GPGME_No_Request' if there is no pending
     operation, `GPGME_Out_Of_Core' if there is not enough memory for
     the operation.

 - Function: GpgmeError gpgme_op_trustlist_end (GpgmeCtx CTX)
     The function `gpgme_op_trustlist_next' ends a pending key list
     operation in the context CTX.

     The function returns `GPGME_Invalid_Value' if CTX is not a valid
     pointer, `GPGME_No_Request' if there is no pending operation,
     `GPGME_Out_Of_Core' if at some time during the operation there was
     not enough memory available.


File: gpgme.info,  Node: Information About Trust Items,  Next: Manipulating Trust Items,  Prev: Listing Trust Items,  Up: Trust Item Management

Information About Trust Items
-----------------------------

   Trust items have attributes which can be queried using the interfaces
below.  The attribute identifiers are shared with those for key
attributes.  *Note Information About Keys::.

 - Function: const char * gpgme_trust_item_get_string_attr
          (GpgmeTrustItem ITEM, GpgmeAttr WHAT, const void *RESERVED,
          int IDX)
     The function `gpgme_trust_item_get_string_attr' returns the value
     of the string-representable attribute WHAT of trust item ITEM.
     The arguments IDX and RESERVED are reserved for later use and
     should be `0' and `NULL' respectively.

     The string returned is only valid as long as the key is valid.

     The function returns `0' if an attribute can't be returned as a
     string, KEY is not a valid pointer, IDX out of range, or RESERVED
     not `NULL'.

 - Function: int gpgme_trust_item_get_int_attr (GpgmeTrustItem ITEM,
          GpgmeAttr WHAT, const void *RESERVED, int IDX)
     The function `gpgme_trust_item_get_int_attr' returns the value of
     the number-representable attribute WHAT of trust item ITEM.  If
     the attribute occurs more than once in the trust item, the index
     is specified by IDX.  However, currently no such attribute exists,
     so IDX should be `0'.  The argument RESERVED is reserved for later
     use and should be `NULL'.

     The function returns `0' if the attribute can't be returned as a
     number, KEY is not a valid pointer, IDX out of range, or RESERVED
     not `NULL'.


File: gpgme.info,  Node: Manipulating Trust Items,  Prev: Information About Trust Items,  Up: Trust Item Management

Manipulating Trust Items
------------------------

 - Function: void gpgme_trust_item_release (GpgmeTrustItem ITEM)
     The function `gpgme_trust_item_release' destroys a
     `GpgmeTrustItem' object and releases all associated resources.


File: gpgme.info,  Node: Crypto Operations,  Next: Run Control,  Prev: Trust Item Management,  Up: Contexts

Crypto Operations
=================

* Menu:

* Decrypt::                       Decrypting a ciphertext.
* Verify::                        Verifying a signature.
* Decrypt and Verify::            Decrypting a signed ciphertext.
* Sign::                          Creating a signature.
* Encrypt::                       Encrypting a plaintext.
* Detailed Results::              How to obtain more info about the operation.


File: gpgme.info,  Node: Decrypt,  Next: Verify,  Up: Crypto Operations

Decrypt
-------

 - Function: GpgmeError gpgme_op_decrypt (GpgmeCtx CTX,
          GpgmeData CIPHER, GpgmeData PLAIN)
     The function `gpgme_op_decrypt' decrypts the ciphertext in the
     data object CIPHER and stores it into the data object PLAIN.

     The function returns `GPGME_No_Error' if the ciphertext could be
     decrypted successfully, `GPGME_Invalid_Value' if CTX, CIPHER or
     PLAIN is not a valid pointer, `GPGME_No_Data' if CIPHER does not
     contain any data to decrypt, `GPGME_Decryption_Failed' if CIPHER
     is not a valid cipher text, `GPGME_No_Passphrase' if the
     passphrase for the secret key could not be retrieved, and passes
     through any errors that are reported by the crypto engine support
     routines.

 - Function: GpgmeError gpgme_op_decrypt_start (GpgmeCtx CTX,
          GpgmeData CIPHER, GpgmeData PLAIN)
     The function `gpgme_op_decrypt_start' initiates a
     `gpgme_op_decrypt' operation.  It can be completed by calling
     `gpgme_wait' on the context.  *Note Waiting For Completion::.

     The function returns `GPGME_No_Error' if the operation could be
     started successfully, and `GPGME_Invalid_Value' if CIPHER or PLAIN
     is not a valid pointer.


File: gpgme.info,  Node: Verify,  Next: Decrypt and Verify,  Prev: Decrypt,  Up: Crypto Operations

Verify
------

 - Data type: enum GpgmeSigStat
     The `GpgmeSigStat' type holds the result of a signature check, or
     the combined result of all signatures.  The following results are
     possible:

    `GPGME_SIG_STAT_NONE'
          This status should not occur in normal operation.

    `GPGME_SIG_STAT_GOOD'
          This status indicates that the signature is valid.  For the
          combined result this status means that all signatures are
          valid.

    `GPGME_SIG_STAT_GOOD_EXP'
          This status indicates that the signature is valid but
          expired.  For the combined result this status means that all
          signatures are valid and expired.

    `GPGME_SIG_STAT_GOOD_EXPKEY'
          This status indicates that the signature is valid but the key
          used to verify the signature has expired.  For the combined
          result this status means that all signatures are valid and
          all keys are expired.

    `GPGME_SIG_STAT_BAD'
          This status indicates that the signature is invalid.  For the
          combined result this status means that all signatures are
          invalid.

    `GPGME_SIG_STAT_NOKEY'
          This status indicates that the signature could not be
          verified due to a missing key.  For the combined result this
          status means that all signatures could not be checked due to
          missing keys.

    `GPGME_SIG_STAT_NOSIG'
          This status indicates that the signature data provided was
          not a real signature.

    `GPGME_SIG_STAT_ERROR'
          This status indicates that there was some other error which
          prevented the signature verification.

    `GPGME_SIG_STAT_DIFF'
          For the combined result this status means that at least two
          signatures have a different status.  You can get each key's
          status with `gpgme_get_sig_status'.

 - Function: GpgmeError gpgme_op_verify (GpgmeCtx CTX, GpgmeData SIG,
          GpgmeData PLAIN, GpgmeSigStat *R_STAT)
     The function `gpgme_op_verify' verifies that the signature in the
     data object SIG is a valid signature.  If PLAIN is initialized
     with plaintext data, it is assumed that SIG is a detached
     signature, and its validity for the plaintext given in PLAIN is
     verified.  If PLAIN is an uninitialized data object, it is assumed
     that SIG is a normal (or cleartext) signature, and the plaintext
     is available in PLAIN after successful verification.

     The combined status of all signatures is returned in R_STAT.  The
     results of the individual signature verifications can be retrieved
     with `gpgme_get_sig_status' and `gpgme_get_sig_key'.

     The function returns `GPGME_No_Error' if the operation could be
     completed successfully, `GPGME_Invalid_Value' if CTX, SIG, PLAIN
     or R_STAT is not a valid pointer, `GPGME_No_Data' if SIG does not
     contain any data to verify, and passes through any errors that are
     reported by the crypto engine support routines.

 - Function: GpgmeError gpgme_op_verify_start (GpgmeCtx CTX,
          GpgmeData SIG, GpgmeData PLAIN)
     The function `gpgme_op_verify_start' initiates a `gpgme_op_verify'
     operation.  It can be completed by calling `gpgme_wait' on the
     context.  *Note Waiting For Completion::.

     The function returns `GPGME_No_Error' if the operation could be
     started successfully, `GPGME_Invalid_Value' if CTX, SIG, PLAIN or
     R_STAT is not a valid pointer, and `GPGME_No_Data' if SIG or PLAIN
     does not contain any data to verify.

 - Function: const char * gpgme_get_sig_status (GpgmeCtx CTX, int IDX,
          GpgmeSigStat *R_STAT, time_t *R_CREATED)
     The function `gpgme_get_sig_status' receives information about a
     signature after the `gpgme_op_verify' or `gpgme_op_verify_decrypt'
     operation.  A single detached signature can contain signatures by
     more than one key.  The IDX specifies which signature's
     information should be retrieved, starting from 0.

     The status of the signature will be returned in R_STAT if it is
     not `NULL'.  The creation time stamp of the signature will be
     returned in R_CREATED if it is not NULL.

     The function returns a statically allocated string that contains
     the fingerprint of the key which signed the plaintext, or `NULL' if
     CTX is not a valid pointer, the operation is still pending, or no
     verification could be performed.

 - Function: const char * gpgme_get_sig_string_attr (GpgmeCtx CTX,
          int IDX, GpgmeAttr WHAT, int WHATIDX)
     This function is similar to `gpgme_get_sig_status' but may be used
     to retrieve more detailed information.  CTX should be the context
     used for the last signature verification, IDX is used to enumerate
     over all signatures starting with `0' and WHATIDX should be `0'
     unless otherwise stated.

     The following values may be used for WHAT:
    `GPGME_ATTR_FPR'
          Return the fingerprint of the key used to create the
          signature.

    `GPGME_ATTR_ERRTOK'
          Return a token with a more detailed error description.  A
          WHATIDX of `0' returns an error token associated with
          validity calculation, a value of `1' return an error token
          related to the certificate checking.


 - Function: const char * gpgme_get_sig_ulong_attr (GpgmeCtx CTX,
          int IDX, GpgmeAttr WAHT, int WHATIDX)
     This function is similar to `gpgme_get_sig_string_attr' but used
     for attributes which can be represented by an `unsigned long' data
     type.  CTX should be the context used for the last signature
     verification, IDX is used to enumerate over all signatures
     starting with `0' and WHATIDX should be `0' unless otherwise
     stated.

     The following values may be used for WHAT:
    `GPGME_ATTR_CREATED'
          Return the creation time of the signature in seconds since
          Epoch.  This is the same value as returned by
          `gpgme_get_sig_status'.

    `GPGME_ATTR_EXPIRE'
          Return the expiration time of the signature in seconds since
          Epoch.

    `GPGME_ATTR_VALIDITY'
          Returns the validity of the key used to create the signature.
          This is a shortcut function which avoids an extra key
          lookup.  The value returned is one of
          `GPGME_VALIDITY_UNKNOWN', `GPGME_VALIDITY_NEVER',
          `GPGME_VALIDITY_MARGINAL' or `GPGME_VALIDITY_FULL'.

    `GPGME_ATTR_SIG_STATUS'
          This is the same value as returned by `gpgme_get_sig_status'.

    `GPGME_ATTR_SIG_SUMMARY'
          This returns a bit vector giving a summary of the signature
          status.  Itprovides an easy interface to a defined semantic
          of the signature status.  Checking just one bit is sufficient
          to see whether a signature is valid without any restrictions.

          The defined bits are:
         `GPGME_SIGSUM_VALID'
               The signature is fully valid.

         `GPGME_SIGSUM_GREEN'
               The signature is good but one might want to display some
               extra   information.  Check the other bits.

         `GPGME_SIGSUM_RED'
               The signature is bad. It might be useful to checkother
               bits and   display moe information, i.e. a revoked
               certificate might not render a   signature invalid when
               the message was received prior to the cause for   the
               revocation.

         `GPGME_SIGSUM_KEY_REVOKED'
               The key or at least one certificate has been revoked.

         `GPGME_SIGSUM_KEY_EXPIRED'
               The key or one of the certificates has expired. It is
               probably a good   idea to display the date of the
               expiration.

         `GPGME_SIGSUM_SIG_EXPIRED'
               The signature has expired.

         `GPGME_SIGSUM_KEY_MISSING'
               Can't verifydue to a missing key o certificate.

         `GPGME_SIGSUM_CRL_MISSING'
               The CRL (or an equivalent mechanism) is not available.

         `GPGME_SIGSUM_CRL_TOO_OLD'
               Available CRL is too old.

         `GPGME_SIGSUM_BAD_POLICY'
               A policy requirement was not met.

         `GPGME_SIGSUM_SYS_ERROR'
               A system error occured.


 - Function: const char * gpgme_get_sig_key (GpgmeCtx CTX, int IDX,
          GpgmeKey *R_KEY)
     The function `gpgme_get_sig_status' receives a `GpgmeKey' object
     for the key which was used to verify the signature after the
     `gpgme_op_verify' or `gpgme_op_verify_decrypt' operation.  A
     single detached signature can contain signatures by more than one
     key.  The IDX specifies which signature's information should be
     retrieved, starting from 0.  The key will have on reference for
     the user.

     The function is a convenient way to retrieve the keys belonging to
     the fingerprints returned by `gpgme_get_sig_status'.

     The function returns `GPGME_No_Error' if the key could be
     returned, `GPGME_Invalid_Value' if R_KEY is not a valid pointer,
     `GPGME_Invalid_Key' if the fingerprint is not valid, `GPGME_EOF'
     if IDX is too large, or some other error value if a problem
     occurred requesting the key.

 - Function: char * gpgme_get_notation (GpgmeCtx CTX)
     The function `gpgme_get_notation' can be used to retrieve notation
     data from the last signature check in the context CTX.

     If there is notation data available from the last signature check,
     this function may be used to return this notation data as a string.
     The string is an XML representation of that data embedded in a
     <notation> container.  The user has to release the string with
     `free'.

     The function returns a string if the notation data is available or
     `NULL' if there is no such data available.


File: gpgme.info,  Node: Decrypt and Verify,  Next: Sign,  Prev: Verify,  Up: Crypto Operations

Decrypt and Verify
------------------

 - Function: GpgmeError gpgme_op_decrypt_verify (GpgmeCtx CTX,
          GpgmeData CIPHER, GpgmeData PLAIN, GpgmeSigStat *R_STAT)
     The function `gpgme_op_decrypt_verify' decrypts the ciphertext in
     the data object CIPHER and stores it into the data object PLAIN.
     If CIPHER contains signatures, they will be verified and their
     combined status will be returned in R_STAT.

     After the operation completed, `gpgme_op_get_sig_status' and
     `gpgme_op_get_sig_key' can be used to retrieve more information
     about the signatures.

     The function returns `GPGME_No_Error' if the ciphertext could be
     decrypted successfully, `GPGME_Invalid_Value' if CTX, CIPHER,
     PLAIN or R_STAT is not a valid pointer, `GPGME_No_Data' if CIPHER
     does not contain any data to decrypt, `GPGME_Decryption_Failed' if
     CIPHER is not a valid cipher text, `GPGME_No_Passphrase' if the
     passphrase for the secret key could not be retrieved, and passes
     through any errors that are reported by the crypto engine support
     routines.

 - Function: GpgmeError gpgme_op_decrypt_verify (GpgmeCtx CTX,
          GpgmeData CIPHER, GpgmeData PLAIN)
     The function `gpgme_op_decrypt_verify_start' initiates a
     `gpgme_op_decrypt_verify' operation.  It can be completed by
     calling `gpgme_wait' on the context.  *Note Waiting For
     Completion::.

     The function returns `GPGME_No_Error' if the operation could be
     started successfully, `GPGME_Invalid_Value' if CTX, CIPHER, PLAIN
     or R_STAT is not a valid pointer, and `GPGME_No_Data' if CIPHER
     does not contain any data to decrypt.


File: gpgme.info,  Node: Sign,  Next: Encrypt,  Prev: Decrypt and Verify,  Up: Crypto Operations

Sign
----

   A signature can contain signatures by one or more keys.  The set of
keys used to create a signatures is contained in a context, and is
applied to all following signing operations in this context (until the
set is changed).

* Menu:

* Selecting Signers::             How to choose the keys to sign with.
* Creating a Signature::          How to create a signature.


File: gpgme.info,  Node: Selecting Signers,  Next: Creating a Signature,  Up: Sign

Selecting Signers
.................

 - Function: void gpgme_signers_clear (GpgmeCtx CTX)
     The function `gpgme_signers_clear' releases a reference for each
     key on the signers list and removes the list of signers from the
     context CTX.

     Every context starts with an empty list.

 - Function: GpgmeError gpgme_signers_add (GpgmeCtx CTX,
          const GpgmeKey KEY)
     The function `gpgme_signers_add' adds the key KEY to the list of
     signers in the context CTX.

     Calling this function acquires an additional reference for the key.

 - Function: GpgmeKey gpgme_signers_enum (const GpgmeCtx CTX, int SEQ)
     The function `gpgme_signers_enum' returns the SEQth key in the
     list of signers in the context CTX.  An additional reference is
     acquired for the user.

     If SEQ is out of range, `NULL' is returned.


File: gpgme.info,  Node: Creating a Signature,  Prev: Selecting Signers,  Up: Sign

Creating a Signature
....................

 - Data type: enum GpgmeSigMode
     The `GpgmeSigMode' type is used to specify the desired type of a
     signature.  The following modes are available:

    `GPGME_SIG_MODE_NORMAL'
          A normal signature is made, the output includes the plaintext
          and the signature.

    `GPGME_SIG_MODE_DETACH'
          A detached signature is made.

    `GPGME_SIG_MODE_CLEAR'
          A clear text signature is made.  The ASCII armor and text
          mode settings of the context are ignored.

 - Function: GpgmeError gpgme_op_sign (GpgmeCtx CTX, GpgmeData PLAIN,
          GpgmeData SIG, GpgmeSigMode MODE)
     The function `gpgme_op_sign' creates a signature for the text in
     the data object PLAIN and returns it in the data object SIG.  The
     type of the signature created is determined by the ASCII armor and
     text mode attributes set for the context CTX and the requested
     signature mode MODE.

     More information about the signatures is available with
     `gpgme_get_op_info'.  *Note Detailed Results::.

     If an S/MIME signed message is created using the CMS crypto engine,
     the number of certificates to include in the message can be
     specified with `gpgme_set_include_certs'.  *Note Included
     Certificates::.

     The function returns `GPGME_No_Error' if the signature could be
     created successfully, `GPGME_Invalid_Value' if CTX, PLAIN or SIG
     is not a valid pointer, `GPGME_No_Data' if the signature could not
     be created, `GPGME_No_Passphrase' if the passphrase for the secret
     key could not be retrieved, and passes through any errors that are
     reported by the crypto engine support routines.

 - Function: GpgmeError gpgme_op_sign_start (GpgmeCtx CTX,
          GpgmeData PLAIN, GpgmeData SIG, GpgmeSigMode MODE)
     The function `gpgme_op_sign_start' initiates a `gpgme_op_sign'
     operation.  It can be completed by calling `gpgme_wait' on the
     context.  *Note Waiting For Completion::.

     The function returns `GPGME_No_Error' if the operation could be
     started successfully, and `GPGME_Invalid_Value' if CTX, PLAIN or
     SIG is not a valid pointer.


File: gpgme.info,  Node: Encrypt,  Next: Detailed Results,  Prev: Sign,  Up: Crypto Operations

Encrypt
-------

   One plaintext can be encrypted for several recipients at the same
time.  The list of recipients is created independently of any context,
and then passed to the encryption operation.

* Menu:

* Selecting Recipients::          How to choose the recipients.
* Encrypting a Plaintext::        How to encrypt a plaintext.


File: gpgme.info,  Node: Selecting Recipients,  Next: Encrypting a Plaintext,  Up: Encrypt

Selecting Recipients
....................

 - Data type: GpgmeRecipients
     The `GpgmeRecipients' type is a handle for a set of recipients
     that can be used in an encryption process.

 - Function: GpgmeError gpgme_recipients_new (GpgmeRecipients *R_RSET)
     The function `gpgme_recipients_new' creates a new, empty set of
     recipients and returns a handle for it in R_RSET.

     The function returns `GPGME_No_Error' if the recipient set could
     be created successfully, and `GPGME_Out_Of_Core' if not enough
     memory was available.

 - Function: void gpgme_recipients_release (GpgmeRecipients RSET)
     The function `gpgme_recipients_release' destroys the set of
     recipients RSET and releases all associated resources.

 - Function: GpgmeError gpgme_recipients_add_name
          (GpgmeRecipients RSET, const char *NAME)
     The function `gpgme_recipients_add_name' adds the recipient NAME
     to the set of recipients RSET.  This is equivalent to
     `gpgme_recipients_add_name_with_validity' with a validity of
     `GPGME_VALIDITY_UNKNOWN'.

     The function returns `GPGME_No_Error' if the recipient was added
     successfully, `GPGME_Invalid_Value' if RSET or NAME is not a valid
     pointer, and `GPGME_Out_Of_Core' if not enough memory is available.

 - Function: GpgmeError gpgme_recipients_add_name_with_validity
          (GpgmeRecipients RSET, const char *NAME, GpgmeValidity VAL)
     The function `gpgme_recipients_add_name_with_validity' adds the
     recipient NAME with the validity VAL to the set of recipients
     RSET.  If the validity is not known, the function
     `gpgme_recipients_add_name' can be used.  *Note Information About
     Keys::, for the possible values for VAL.

     The function returns `GPGME_No_Error' if the recipient was added
     successfully, `GPGME_Invalid_Value' if RSET or NAME is not a valid
     pointer, and `GPGME_Out_Of_Core' if not enough memory is available.

 - Function: unsigned int gpgme_recipients_count
          (const GPGMERECIPIENTS RSET)
     The function `gpgme_recipients_count' returns the number of
     recipients in the set RSET.

 - Function: GpgmeError gpgme_recipients_enum_open
          (const GpgmeRecipients RSET, void **ITER)
     The function `gpgme_recipients_enum_open' creates a new iterator
     ITER that can be used to walk through the set of recipients in
     RSET, using `gpgme_recipients_enum_read'.

     If the iterator is not needed anymore, it can be closed with
     `gpgme_recipients_enum_close'.

     The function returns `GPGME_No_Error' if the enumerator was
     successfully created and `GPGME_Invalid_Value' if RSET or ITER is
     not a valid pointer.

 - Function: const char * gpgme_recipients_enum_read
          (const GpgmeRecipients RSET, void **ITER)
     The function `gpgme_recipients_enum_read' returns a string
     containing the name of the next recipient in the set RSET for the
     iterator ITER.  The string is valid as long as RSET is valid or
     the function is called the next time with the same recipient set
     and iterator, whatever is earlier.

 - Function: GpgmeError gpgme_recipients_enum_close
          (const GpgmeRecipients RSET, void **ITER)
     The function `gpgme_recipients_enum_close' releases the iterator
     ITER for the recipient set RSET.


File: gpgme.info,  Node: Encrypting a Plaintext,  Prev: Selecting Recipients,  Up: Encrypt

Encrypting a Plaintext
......................

 - Function: GpgmeError gpgme_op_encrypt (GpgmeCtx CTX,
          GpgmeRecipients RSET, GpgmeData PLAIN, GpgmeData CIPHER)
     The function `gpgme_op_encrypt' encrypts the plaintext in the data
     object PLAIN for the recipients RSET and stores the ciphertext in
     the data object CIPHER.  The type of the ciphertext created is
     determined by the ASCII armor and text mode attributes set for the
     context CTX.

     If `GPGME_Invalid_Recipients' is returned, some recipients in RSET
     are invalid, but not all.  In this case the plaintext is encrypted
     for all valid recipients and returned in CIPHER.  More information
     about the invalid recipients is available with
     `gpgme_get_op_info'.  *Note Detailed Results::.

     If RECP is `NULL', symmetric rather than public key encryption is
     performed.  Symmetrically encrypted cipher text can be deciphered
     with `gpgme_op_decrypt'.  Note that in this case the crypto
     backend needs to retrieve a passphrase from the user.  Symmetric
     encryption is currently only supported for the OpenPGP crypto
     backend.

     The function returns `GPGME_No_Error' if the ciphertext could be
     created successfully, `GPGME_Invalid_Value' if CTX, RSET, PLAIN or
     CIPHER is not a valid pointer, `GPGME_No_Recipients' if RSET does
     not contain any valid recipients, `GPGME_Invalid_Recipients' if
     RSET contains some invalid recipients, `GPGME_No_Passphrase' if
     the passphrase for the secret key could not be retrieved, and
     passes through any errors that are reported by the crypto engine
     support routines.

 - Function: GpgmeError gpgme_op_encrypt_start (GpgmeCtx CTX,
          GpgmeRecipients RSET, GpgmeData PLAIN, GpgmeData CIPHER)
     The function `gpgme_op_encrypt_start' initiates a
     `gpgme_op_encrypt' operation.  It can be completed by calling
     `gpgme_wait' on the context.  *Note Waiting For Completion::.

     The function returns `GPGME_No_Error' if the operation could be
     started successfully, `GPGME_Invalid_Value' if CTX, RSET, PLAIN or
     CIPHER is not a valid pointer, and `GPGME_No_Recipients' if RSET
     does not contain any valid recipients.

 - Function: GpgmeError gpgme_op_encrypt_sign (GpgmeCtx CTX,
          GpgmeRecipients RSET, GpgmeData PLAIN, GpgmeData CIPHER)
     The function `gpgme_op_encrypt_sign' does a combined encrypt and
     sign operation.  It is used like `gpgme_op_encrypt', but the
     ciphertext also contains signatures for the signers listed in CTX.

     The combined encrypt and sign operation is currently only available
     for the OpenPGP crypto engine.

 - Function: GpgmeError gpgme_op_encrypt_sign_start (GpgmeCtx CTX,
          GpgmeRecipients RSET, GpgmeData PLAIN, GpgmeData CIPHER)
     The function `gpgme_op_encrypt_sign_start' initiates a
     `gpgme_op_encrypt_sign' operation.  It can be completed by calling
     `gpgme_wait' on the context.  *Note Waiting For Completion::.

     The function returns `GPGME_No_Error' if the operation could be
     started successfully, `GPGME_Invalid_Value' if CTX, RSET, PLAIN or
     CIPHER is not a valid pointer, and `GPGME_No_Recipients' if RSET
     does not contain any valid recipients.


File: gpgme.info,  Node: Detailed Results,  Prev: Encrypt,  Up: Crypto Operations

Detailed Results
----------------

 - Function: char * gpgme_get_op_info (GpgmeCtx CTX, int RESERVED)
     The function `gpgme_get_op_info' retrieves more information about
     the last crypto operation.

     The function returns a string in the XML format.  The user has to
     release the string with `free'.

     Here is a sample of the information that might be returned:
          <GnupgOperationInfo>
            <signature>
              <detached/> <!-- or cleartext or standard -->
              <algo>17</algo>
              <hashalgo>2</hashalgo>
              <micalg>pgp-sha1</micalg>
              <sigclass>01</sigclass>
              <created>9222222</created>
              <fpr>121212121212121212</fpr>
            </signature>
          </GnupgOperationInfo>

     Currently, the only operations that return additional information
     are encrypt, sign and import.  *Note Encrypt::, *Note Sign::,
     *Note Importing Keys::.

     The function returns a string or `NULL' if no such data is
     available.


File: gpgme.info,  Node: Run Control,  Prev: Crypto Operations,  Up: Contexts

Run Control
===========

   GPGME supports running operations synchronously and asynchronously.
You can use asynchronous operation to set up a context up to initiating
the desired operation, but delay performing it to a later point.

   Furthermore, you can use an external event loop to control exactly
when GPGME runs.  This ensures that GPGME only runs when necessary and
also prevents it from blocking for a long time.

* Menu:

* Waiting For Completion::        Waiting until an operation is completed.
* Cancelling an Operation::       Interrupting a running operation.
* Hooking Up Into Idle Time::     Doing something when nothing has to be done.
* Using External Event Loops::    Advanced control over what happens when.


File: gpgme.info,  Node: Waiting For Completion,  Next: Cancelling an Operation,  Up: Run Control

Waiting For Completion
----------------------

 - Function: GpgmeCtx gpgme_wait (GpgmeCtx CTX, GpgmeError *STATUS,
          int HANG)
     The function `gpgme_wait' continues the pending operation within
     the context CTX.  In particular, it ensures the data exchange
     between GPGME and the crypto backend and watches over the run time
     status of the backend process.

     If HANG is true, the function does not return until the operation
     is completed or cancelled.  Otherwise the function will not block
     for a long time.

     The error status of the finished operation is returned in STATUS
     if `gpgme_wait' does not return `NULL'.

     The CTX argument can be `NULL'.  In that case, `gpgme_wait' waits
     for any context to complete its operation.

     `gpgme_wait' can be used only in conjunction with any context that
     has a pending operation initiated with one of the
     `gpgme_op_*_start' functions except `gpgme_op_keylist_start' and
     `gpgme_op_trustlist_start' (for which you should use the
     corresponding `gpgme_op_*_next' functions).  If CTX is `NULL', all
     of such contexts are waited upon and possibly returned.
     Synchronous operations running in parallel, as well as key and
     trust item list operations, do not affect `gpgme_wait'.

     In a multi-threaded environment, only one thread should ever call
     `gpgme_wait' at any time, irregardless if CTX is specified or not.
     This means that all calls to this function should be fully
     synchronized by locking primitives.

     The function returns the CTX of the context which has finished the
     operation.


File: gpgme.info,  Node: Cancelling an Operation,  Next: Hooking Up Into Idle Time,  Prev: Waiting For Completion,  Up: Run Control

Cancelling an Operation
-----------------------

 - Function: void gpgme_cancel (GpgmeCtx CTX)
     The function `gpgme_cancel' tries to cancel the pending operation.
     A running synchronous operation in the context or the function
     `gpgme_wait' with this context as its CTX argument might notice
     the cancellation flag and return.  It is currently not guaranteed
     to work under all circumstances.  Its current primary purpose is
     to prevent asking for a passphrase again in the passphrase
     callback.


File: gpgme.info,  Node: Hooking Up Into Idle Time,  Next: Using External Event Loops,  Prev: Cancelling an Operation,  Up: Run Control

Hooking Up Into Idle Time
-------------------------

 - Data type: void (*GpgmeIdleFunc) (void)
     The `GpgmeIdleFunc' type is the type of functions usable as an
     idle function that can be registered with `gpgme_register_idle'.

 - Function: GpgmeIdleFunc gpgme_register_idle (GpgmeIdleFunc IDLE)
     The function `gpgme_register_idle' can be used to register IDLE as
     the idle function.

     IDLE will be called whenever GPGME thinks that it is idle and time
     can better be spent elsewhere.  Setting IDLE to `NULL' disables
     use of the idle function (this is the default).

     The function returns the old idle function, or `NULL' if none was
     registered yet.


File: gpgme.info,  Node: Using External Event Loops,  Prev: Hooking Up Into Idle Time,  Up: Run Control

Using External Event Loops
--------------------------

   GPGME hides the complexity of the communication between the library
and the crypto engine.  The price of this convenience is that the
calling thread can block arbitrary long waiting for the data returned
by the crypto engine.  In single-threaded programs, in particular if
they are interactive, this is an unwanted side-effect.  OTOH, if
`gpgme_wait' is used without the HANG option being enabled, it might be
called unnecessarily often, wasting CPU time that could be used
otherwise.

   The I/O callback interface described in this section lets the user
take control over what happens when.  GPGME will provide the user with
the file descriptors that should be monitored, and the callback
functions that should be invoked when a file descriptor is ready for
reading or writing.  It is then the user's responsibility to decide
when to check the file descriptors and when to invoke the callback
functions.  Usually this is done in an event loop, that also checks for
events in other parts of the program.  If the callback functions are
only called when the file descriptors are ready, GPGME will never
block.  This gives the user mroe control over the program flow, and
allows to perform other tasks when GPGME would block otherwise.

   By using this advanced mechanism, GPGME can be integrated smoothly
into GUI toolkits like GTK+ even for single-threaded programs.

* Menu:

* I/O Callback Interface::        How I/O callbacks are registered.
* Registering I/O Callbacks::     How to use I/O callbacks for a context.
* I/O Callback Example::          An example how to use I/O callbacks.
* I/O Callback Example GTK+::     How to use GPGME with GTK+.
* I/O Callback Example GDK::      How to use GPGME with GDK.


File: gpgme.info,  Node: I/O Callback Interface,  Next: Registering I/O Callbacks,  Up: Using External Event Loops

I/O Callback Interface
......................

 - Data type: void (*GpgmeIOCb) (void *DATA, int FD)
     The `GpgmeIOCb' type is the type of functions which GPGME wants to
     register as I/O callback handlers using the `GpgmeRegisterIOCb'
     functions provided by the user.

     DATA and FD are provided by GPGME when the I/O callback handler is
     registered, and should be passed through to the handler when it is
     invoked by the user because it noticed activity on the file
     descriptor FD.

 - Data type: GpgmeError (*GpgmeRegisterIOCb) (void *DATA, int FD,
int DIR, GpgmeIOCb FNC, void *FNC_DATA, void **TAG)
     The `GpgmeRegisterIOCb' type is the type of functions which can be
     called by GPGME to register an I/O callback funtion FNC for the
     file descriptor FD with the user.  FNC_DATA should be passed as
     the first argument to FNC when the handler is invoked (the second
     argument should be FD).  If DIR is 0, FNC should be called by the
     user when FD is ready for writing.  If DIR is 1, FNC should be
     called when FD is ready for reading.

     DATA was provided by the user when registering the
     `GpgmeRegisterIOCb' function with GPGME and will always be passed
     as the first argument when registering a callback function.  For
     example, the user can use this to determine the event loop to
     which the file descriptor should be added.

     GPGME will call this function when a crypto operation is initiated
     in a context for which the user has registered I/O callback
     handler functions with `gpgme_set_io_cbs'.  It can also call this
     function when it is in an I/O callback handler for a file
     descriptor associated to this context.

     The user should return a unique handle in TAG identifying this I/O
     callback registration, which will be passed to the
     `GpgmeRegisterIOCb' function without interpretation when the file
     descriptor should not be monitored anymore.

 - Data type: void (*GpgmeRemoveIOCb) (void *TAG)
     The `GpgmeRemoveIOCb' type is the type of functions which can be
     called by GPGME to remove an I/O callback handler that was
     registered before.  TAG is the handle that was returned by the
     `GpgmeRegisterIOCb' for this I/O callback.

     GPGME can call this function when a crypto operation is in an I/O
     callback.  It will also call this function when the context is
     destroyed while an operation is pending.

 - Data type: enum GpgmeEventIO
     The `GpgmeEventIO' type specifies the type of an event that is
     reported to the user by GPGME as a consequence of an I/O
     operation.  The following events are defined:

    `GPGME_EVENT_DONE'
          The operation is finished, the last I/O callback for this
          operation was removed.  The accompanying TYPE_DATA points to a
          `GpgmeError' variable that contains the status of the
          operation that finished.  This event is signalled after the
          last I/O callback has been removed.

    `GPGME_EVENT_NEXT_KEY'
          In a `gpgme_op_keylist_start' operation, the next key was
          received from the crypto engine.  The accompanying TYPE_DATA
          is a `GpgmeKey' variable that contains the key with one
          reference for the user.

    `GPGME_EVENT_NEXT_TRUSTITEM'
          In a `gpgme_op_trustlist_start' operation, the next trust item
          was received from the crypto engine.  The accompanying
          TYPE_DATA is a `GpgmeTrustItem' variable that contains the
          trust item with one reference for the user.

 - Data type: void (*GpgmeEventIOCb) (void *DATA, GpgmeEventIO TYPE,
void *TYPE_DATA)
     The `GpgmeEventIOCb' type is the type of functions which can be
     called by GPGME to signal an event for an operation running in a
     context which has I/O callback functions registered by the user.

     DATA was provided by the user when registering the
     `GpgmeEventIOCb' function with GPGME and will always be passed as
     the first argument when registering a callback function.  For
     example, the user can use this to determine the context in which
     this event has occured.

     TYPE will specify the type of event that has occured.  TYPE_DATA
     specifies the event further, as described in the above list of
     possible `GpgmeEventIO' types.

     GPGME can call this function in an I/O callback handler.


File: gpgme.info,  Node: Registering I/O Callbacks,  Next: I/O Callback Example,  Prev: I/O Callback Interface,  Up: Using External Event Loops

Registering I/O Callbacks
.........................

 - Data type: struct GpgmeIOCbs
     This structure is used to store the I/O callback interface
     functions described in the previous section.  It has the following
     members:

    `GpgmeRegisterIOCb add'
          This is the function called by GPGME to register an I/O
          callback handler.  It must be specified.

    `void *add_data'
          This is passed as the first argument to the `add' function
          when it is called by GPGME.  For example, it can be used to
          determine the event loop to which the file descriptor should
          be added.

    `GpgmeRemoveIOCb remove'
          This is the function called by GPGME to remove an I/O
          callback handler.  It must be specified.

    `GpgmeEventIOCb event'
          This is the function called by GPGME to signal an event for
          an operation.  It is optional, but if you don't specify it,
          you can not retrieve the return value of the operation.

    `void *event_data'
          This is passed as the first argument to the `event' function
          when it is called by GPGME.  For example, it can be used to
          determine the context in which the event has occured.

 - Function: void gpgme_set_io_cbs (GpgmeCtx CTX,
          struct GpgmeIOCbs *IO_CBS)
     The function `gpgme_set_io_cbs' enables the I/O callback interface
     for the context CTX.  The I/O callback functions are specified by
     IO_CBS.

     If IO_CBS->`add' is `NULL', the I/O callback interface is disabled
     for the context, and normal operation is restored.

 - Function: void gpgme_get_io_cbs (GpgmeCtx CTX,
          struct GpgmeIOCbs *IO_CBS)
     The function `gpgme_get_io_cbs' returns the I/O callback functions
     set with `gpgme_set_io_cbs' in IO_CBS.


File: gpgme.info,  Node: I/O Callback Example,  Next: I/O Callback Example GTK+,  Prev: Registering I/O Callbacks,  Up: Using External Event Loops

I/O Callback Example
....................

   To actually use an external event loop, you have to implement the I/O
callback functions that are used by GPGME to register and unregister
file descriptors.  Furthermore, you have to actually monitor these file
descriptors for activity and call the appropriate I/O callbacks.

   The following example illustrates how to do that.  The example uses
locking to show in which way the the callbacks and the event loop can
run concurrently.  For the event loop, we use a fixed array.  For a
real-world implementation, you should use a dynamically sized structure
because the number of file descriptors needed for a crypto operation in
GPGME is not predictable.

     #include <pthread.h>
     #include <sys/types.h>
     #include <gpgme.h>
     
     /* The following structure holds the result of a crypto operation.  */
     struct op_result
     {
       int done;
       GpgmeError err;
     };
     
     /* The following structure holds the data associated with one I/O
     callback.  */
     struct one_fd
     {
       int fd;
       int dir;
       GpgmeIOCb fnc;
       void *fnc_data;
     };
     
     struct event_loop
     {
       pthread_mutex_t lock;
     #define MAX_FDS 32
       /* Unused slots are marked with FD being -1.  */
       struct one_fd fds[MAX_FDS];
     };

   The following functions implement the I/O callback interface.

     GpgmeError
     add_io_cb (void *data, int fd, int dir, GpgmeIOCb fnc, void *fnc_data,
     	   void **r_tag)
     {
       struct event_loop *loop = data;
       struct one_fd *fds = loop->fds;
       int i;
     
       pthread_mutex_lock (&loop->lock);
       for (i = 0; i < MAX_FDS; i++)
         {
           if (fds[i].fd == -1)
     	{
     	  fds[i].fd = fd;
     	  fds[i].dir = dir;
     	  fds[i].fnc = fnc;
     	  fds[i].fnc_data = fnc_data;
     	  break;
     	}
         }
       pthread_mutex_unlock (&loop->lock);
       if (i == MAX_FDS)
         return GPGME_General_Error;
       *r_tag = &fds[i];
       return 0;
     }
     
     void
     remove_io_cb (void *tag)
     {
       struct one_fd *fd = tag;
     
       pthread_mutex_lock (&loop->lock);
       fd->fd = -1;
       pthread_mutex_unlock (&loop->lock);
     }
     
     void
     event_io_cb (void *data, GpgmeEventIO type, void *type_data)
     {
       struct op_result *result = data;
       GpgmeError *err = data;
     
       /* We don't support list operations here.  */
       if (type == GPGME_EVENT_DONE)
         {
           result->done = 1;
           result->err = *data;
         }
     }

   The final missing piece is the event loop, which will be presented
next.  We only support waiting for the success of a single operation.

     int
     do_select (struct event_loop *loop)
     {
       fd_set rfds;
       fd_set wfds;
       int i, n;
       int any = 0;
     
       pthread_mutex_lock (&loop->lock);
       FD_ZERO (&rfds);
       FD_ZERO (&wfds);
       for (i = 0; i < FDLIST_MAX; i++)
         if (fdlist[i].fd != -1)
           FD_SET (fdlist[i].fd, fdlist[i].dir ? &rfds : &wfds);
       pthread_mutex_unlock (&loop->unlock);
     
       do
         {
           n = select (FD_SETSIZE, &rfds, &wfds, NULL, 0);
         }
       while (n < 0 && errno == EINTR);
     
       if (n < 0)
         return n;	/* Error or timeout.  */
     
       pthread_mutex_lock (&loop->lock);
       for (i = 0; i < FDLIST_MAX && n; i++)
         {
           if (fdlist[i].fd != -1)
     	{
     	  if (FD_ISSET (fdlist[i].fd, fdlist[i].dir ? &rfds : &wfds))
     	    {
     	      assert (n);
     	      n--;
     	      any = 1;
                   /* The I/O callback handler can register/remove callbacks,
                      so we have to unlock the file descriptor list.  */
                   pthread_mutex_unlock (&loop->lock);
     	      (*fdlist[i].fnc) (fdlist[i].fnc_data, fdlist[i].fd);
                   pthread_mutex_lock (&loop->lock);
     	    }
     	}
         }
       pthread_mutex_unlock (&loop->lock);
       return any;
     }
     
     void
     wait_for_op (struct event_loop *loop, struct op_result *result)
     {
       int ret;
     
       do
         {
           ret = do_select (loop);
         }
       while (ret >= 0 && !result->done);
       return ret;
     }

   The main function shows how to put it all together.

     int
     main (int argc, char *argv[])
     {
       struct event_loop loop;
       struct op_result result;
       GpgmeCtx ctx;
       GpgmeError err;
       GpgmeData sig, text;
       GpgmeSigStat status;
       int i;
       struct GpgmeIOCbs io_cbs =
       {
         add_io_cb,
         &loop,
         remove_io_cb,
         event_io_cb,
         &result
       };
     
       /* Initialize the loop structure.  */
       loop.lock = PTHREAD_MUTEX_INITIALIZER;
       for (i = 0; i < MAX_FDS; i++)
         loop->fds[i].fd = -1;
     
       /* Initialize the result structure.  */
       result.done = 0;
     
       err = gpgme_data_new_from_file (&sig, "signature", 1);
       if (!err)
         err = gpgme_data_new_from_file (&text, "text", 1);
       if (!err)
         err = gpgme_new (&ctx);
       if (!err)
         {
            gpgme_set_io_cbs (ctx, &io_cbs);
            err = gpgme_op_verify_start (ctx, sig, text, &status);
         }
       if (err)
         {
           fprintf (stderr, "gpgme error: %s\n", gpgme_strerror (err));
           exit (1);
         }
     
       wait_for_op (&loop, &result);
       if (!result.done)
         {
           fprintf (stderr, "select error\n");
           exit (1);
         }
       if (!result.err)
         {
           fprintf (stderr, "verification failed: %s\n", gpgme_strerror (result.err));
           exit (1);
         }
       /* Evaluate STATUS.  */
       ...
       return 0;
     }


File: gpgme.info,  Node: I/O Callback Example GTK+,  Next: I/O Callback Example GDK,  Prev: I/O Callback Example,  Up: Using External Event Loops

I/O Callback Example GTK+
.........................

   The I/O callback interface can be used to integrate GPGME with the
GTK+ event loop.  The following code snippets shows 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 GTK+ specific setup.

     #include <gtk/gtk.h>
     
     struct my_gpgme_io_cb
     {
       GpgmeIOCb fnc;
       void *fnc_data;
       guint input_handler_id
     };
     
     void
     my_gpgme_io_cb (gpointer data, gint source, GdkInputCondition condition)
     {
       struct my_gpgme_io_cb *iocb = data;
       (*(iocb->fnc)) (iocb->data, source);
     }
     
     void
     my_gpgme_remove_io_cb (void *data)
     {
       struct my_gpgme_io_cb *iocb = data;
       gtk_input_remove (data->input_handler_id);
     }
     
     void
     my_gpgme_register_io_callback (void *data, int fd, int dir, GpgmeIOCb fnc,
                                    void *fnc_data, void **tag)
     {
       struct my_gpgme_io_cb *iocb = g_malloc (sizeof (struct my_gpgme_io_cb));
       iocb->fnc = fnc;
       iocb->data = fnc_data;
       iocb->input_handler_id = gtk_input_add_full (fd, dir
                                                        ? GDK_INPUT_READ
                                                        : GDK_INPUT_WRITE,
                                                    my_gpgme_io_callback,
                                                    0, iocb, NULL);
       *tag = iocb;
       return 0;
     }


File: gpgme.info,  Node: I/O Callback Example GDK,  Prev: I/O Callback Example GTK+,  Up: Using External Event Loops

I/O Callback Example GDK
........................

   The I/O callback interface can also be used to integrate GPGME with
the GDK event loop.  The following code snippets shows 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 GDK specific setup.

   It is very similar to the GTK+ example in the previous section.

     #include <gdk/gdk.h>
     
     struct my_gpgme_io_cb
     {
       GpgmeIOCb fnc;
       void *fnc_data;
       gint tag;
     };
     
     void
     my_gpgme_io_cb (gpointer data, gint source, GdkInputCondition condition)
     {
       struct my_gpgme_io_cb *iocb = data;
       (*(iocb->fnc)) (iocb->data, source);
     }
     
     void
     my_gpgme_remove_io_cb (void *data)
     {
       struct my_gpgme_io_cb *iocb = data;
       gdk_input_remove (data->tag);
     }
     
     void
     my_gpgme_register_io_callback (void *data, int fd, int dir, GpgmeIOCb fnc,
                                    void *fnc_data, void **tag)
     {
       struct my_gpgme_io_cb *iocb = g_malloc (sizeof (struct my_gpgme_io_cb));
       iocb->fnc = fnc;
       iocb->data = fnc_data;
       iocb->tag = gtk_input_add_full (fd, dir ? GDK_INPUT_READ : GDK_INPUT_WRITE,
                                       my_gpgme_io_callback, iocb, NULL);
       *tag = iocb;
       return 0;
     }


File: gpgme.info,  Node: Copying,  Next: Free Documentation License,  Prev: Contexts,  Up: Top

GNU GENERAL PUBLIC LICENSE
**************************

                         Version 2, June 1991

     Copyright (C) 1989, 1991 Free Software Foundation, Inc.
     59 Temple Place -- Suite 330, Boston, MA 02111-1307, USA
     
     Everyone is permitted to copy and distribute verbatim copies
     of this license document, but changing it is not allowed.

Preamble
--------

   The licenses for most software are designed to take away your
freedom to share and change it.  By contrast, the GNU General Public
License is intended to guarantee your freedom to share and change free
software--to make sure the software is free for all its users.  This
General Public License applies to most of the Free Software
Foundation's software and to any other program whose authors commit to
using it.  (Some other Free Software Foundation software is covered by
the GNU Library General Public License instead.)  You can apply it to
your programs, too.

   When we speak of free software, we are referring to freedom, not
price.  Our General Public Licenses are designed to make sure that you
have the freedom to distribute copies of free software (and charge for
this service if you wish), that you receive source code or can get it
if you want it, that you can change the software or use pieces of it in
new free programs; and that you know you can do these things.

   To protect your rights, we need to make restrictions that forbid
anyone to deny you these rights or to ask you to surrender the rights.
These restrictions translate to certain responsibilities for you if you
distribute copies of the software, or if you modify it.

   For example, if you distribute copies of such a program, whether
gratis or for a fee, you must give the recipients all the rights that
you have.  You must make sure that they, too, receive or can get the
source code.  And you must show them these terms so they know their
rights.

   We protect your rights with two steps: (1) copyright the software,
and (2) offer you this license which gives you legal permission to copy,
distribute and/or modify the software.

   Also, for each author's protection and ours, we want to make certain
that everyone understands that there is no warranty for this free
software.  If the software is modified by someone else and passed on, we
want its recipients to know that what they have is not the original, so
that any problems introduced by others will not reflect on the original
authors' reputations.

   Finally, any free program is threatened constantly by software
patents.  We wish to avoid the danger that redistributors of a free
program will individually obtain patent licenses, in effect making the
program proprietary.  To prevent this, we have made it clear that any
patent must be licensed for everyone's free use or not licensed at all.

   The precise terms and conditions for copying, distribution and
modification follow.

    TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION

  1. This License applies to any program or other work which contains a
     notice placed by the copyright holder saying it may be distributed
     under the terms of this General Public License.  The "Program",
     below, refers to any such program or work, and a "work based on
     the Program" means either the Program or any derivative work under
     copyright law: that is to say, a work containing the Program or a
     portion of it, either verbatim or with modifications and/or
     translated into another language.  (Hereinafter, translation is
     included without limitation in the term "modification".)  Each
     licensee is addressed as "you".

     Activities other than copying, distribution and modification are
     not covered by this License; they are outside its scope.  The act
     of running the Program is not restricted, and the output from the
     Program is covered only if its contents constitute a work based on
     the Program (independent of having been made by running the
     Program).  Whether that is true depends on what the Program does.

  2. You may copy and distribute verbatim copies of the Program's
     source code as you receive it, in any medium, provided that you
     conspicuously and appropriately publish on each copy an appropriate
     copyright notice and disclaimer of warranty; keep intact all the
     notices that refer to this License and to the absence of any
     warranty; and give any other recipients of the Program a copy of
     this License along with the Program.

     You may charge a fee for the physical act of transferring a copy,
     and you may at your option offer warranty protection in exchange
     for a fee.

  3. You may modify your copy or copies of the Program or any portion
     of it, thus forming a work based on the Program, and copy and
     distribute such modifications or work under the terms of Section 1
     above, provided that you also meet all of these conditions:

       a. You must cause the modified files to carry prominent notices
          stating that you changed the files and the date of any change.

       b. You must cause any work that you distribute or publish, that
          in whole or in part contains or is derived from the Program
          or any part thereof, to be licensed as a whole at no charge
          to all third parties under the terms of this License.

       c. If the modified program normally reads commands interactively
          when run, you must cause it, when started running for such
          interactive use in the most ordinary way, to print or display
          an announcement including an appropriate copyright notice and
          a notice that there is no warranty (or else, saying that you
          provide a warranty) and that users may redistribute the
          program under these conditions, and telling the user how to
          view a copy of this License.  (Exception: if the Program
          itself is interactive but does not normally print such an
          announcement, your work based on the Program is not required
          to print an announcement.)

     These requirements apply to the modified work as a whole.  If
     identifiable sections of that work are not derived from the
     Program, and can be reasonably considered independent and separate
     works in themselves, then this License, and its terms, do not
     apply to those sections when you distribute them as separate
     works.  But when you distribute the same sections as part of a
     whole which is a work based on the Program, the distribution of
     the whole must be on the terms of this License, whose permissions
     for other licensees extend to the entire whole, and thus to each
     and every part regardless of who wrote it.

     Thus, it is not the intent of this section to claim rights or
     contest your rights to work written entirely by you; rather, the
     intent is to exercise the right to control the distribution of
     derivative or collective works based on the Program.

     In addition, mere aggregation of another work not based on the
     Program with the Program (or with a work based on the Program) on
     a volume of a storage or distribution medium does not bring the
     other work under the scope of this License.

  4. You may copy and distribute the Program (or a work based on it,
     under Section 2) in object code or executable form under the terms
     of Sections 1 and 2 above provided that you also do one of the
     following:

       a. Accompany it with the complete corresponding machine-readable
          source code, which must be distributed under the terms of
          Sections 1 and 2 above on a medium customarily used for
          software interchange; or,

       b. Accompany it with a written offer, valid for at least three
          years, to give any third party, for a charge no more than your
          cost of physically performing source distribution, a complete
          machine-readable copy of the corresponding source code, to be
          distributed under the terms of Sections 1 and 2 above on a
          medium customarily used for software interchange; or,

       c. Accompany it with the information you received as to the offer
          to distribute corresponding source code.  (This alternative is
          allowed only for noncommercial distribution and only if you
          received the program in object code or executable form with
          such an offer, in accord with Subsection b above.)

     The source code for a work means the preferred form of the work for
     making modifications to it.  For an executable work, complete
     source code means all the source code for all modules it contains,
     plus any associated interface definition files, plus the scripts
     used to control compilation and installation of the executable.
     However, as a special exception, the source code distributed need
     not include anything that is normally distributed (in either
     source or binary form) with the major components (compiler,
     kernel, and so on) of the operating system on which the executable
     runs, unless that component itself accompanies the executable.

     If distribution of executable or object code is made by offering
     access to copy from a designated place, then offering equivalent
     access to copy the source code from the same place counts as
     distribution of the source code, even though third parties are not
     compelled to copy the source along with the object code.

  5. You may not copy, modify, sublicense, or distribute the Program
     except as expressly provided under this License.  Any attempt
     otherwise to copy, modify, sublicense or distribute the Program is
     void, and will automatically terminate your rights under this
     License.  However, parties who have received copies, or rights,
     from you under this License will not have their licenses
     terminated so long as such parties remain in full compliance.

  6. You are not required to accept this License, since you have not
     signed it.  However, nothing else grants you permission to modify
     or distribute the Program or its derivative works.  These actions
     are prohibited by law if you do not accept this License.
     Therefore, by modifying or distributing the Program (or any work
     based on the Program), you indicate your acceptance of this
     License to do so, and all its terms and conditions for copying,
     distributing or modifying the Program or works based on it.

  7. Each time you redistribute the Program (or any work based on the
     Program), the recipient automatically receives a license from the
     original licensor to copy, distribute or modify the Program
     subject to these terms and conditions.  You may not impose any
     further restrictions on the recipients' exercise of the rights
     granted herein.  You are not responsible for enforcing compliance
     by third parties to this License.

  8. If, as a consequence of a court judgment or allegation of patent
     infringement or for any other reason (not limited to patent
     issues), conditions are imposed on you (whether by court order,
     agreement or otherwise) that contradict the conditions of this
     License, they do not excuse you from the conditions of this
     License.  If you cannot distribute so as to satisfy simultaneously
     your obligations under this License and any other pertinent
     obligations, then as a consequence you may not distribute the
     Program at all.  For example, if a patent license would not permit
     royalty-free redistribution of the Program by all those who
     receive copies directly or indirectly through you, then the only
     way you could satisfy both it and this License would be to refrain
     entirely from distribution of the Program.

     If any portion of this section is held invalid or unenforceable
     under any particular circumstance, the balance of the section is
     intended to apply and the section as a whole is intended to apply
     in other circumstances.

     It is not the purpose of this section to induce you to infringe any
     patents or other property right claims or to contest validity of
     any such claims; this section has the sole purpose of protecting
     the integrity of the free software distribution system, which is
     implemented by public license practices.  Many people have made
     generous contributions to the wide range of software distributed
     through that system in reliance on consistent application of that
     system; it is up to the author/donor to decide if he or she is
     willing to distribute software through any other system and a
     licensee cannot impose that choice.

     This section is intended to make thoroughly clear what is believed
     to be a consequence of the rest of this License.

  9. If the distribution and/or use of the Program is restricted in
     certain countries either by patents or by copyrighted interfaces,
     the original copyright holder who places the Program under this
     License may add an explicit geographical distribution limitation
     excluding those countries, so that distribution is permitted only
     in or among countries not thus excluded.  In such case, this
     License incorporates the limitation as if written in the body of
     this License.

 10. The Free Software Foundation may publish revised and/or new
     versions of the General Public License from time to time.  Such
     new versions will be similar in spirit to the present version, but
     may differ in detail to address new problems or concerns.

     Each version is given a distinguishing version number.  If the
     Program specifies a version number of this License which applies
     to it and "any later version", you have the option of following
     the terms and conditions either of that version or of any later
     version published by the Free Software Foundation.  If the Program
     does not specify a version number of this License, you may choose
     any version ever published by the Free Software Foundation.

 11. If you wish to incorporate parts of the Program into other free
     programs whose distribution conditions are different, write to the
     author to ask for permission.  For software which is copyrighted
     by the Free Software Foundation, write to the Free Software
     Foundation; we sometimes make exceptions for this.  Our decision
     will be guided by the two goals of preserving the free status of
     all derivatives of our free software and of promoting the sharing
     and reuse of software generally.

                                NO WARRANTY

 12. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO
     WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE
     LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
     HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT
     WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT
     NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
     FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS TO THE
     QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE
     PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY
     SERVICING, REPAIR OR CORRECTION.

 13. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
     WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY
     MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE
     LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL,
     INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR
     INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
     DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU
     OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY
     OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN
     ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

                      END OF TERMS AND CONDITIONS

How to Apply These Terms to Your New Programs
=============================================

   If you develop a new program, and you want it to be of the greatest
possible use to the public, the best way to achieve this is to make it
free software which everyone can redistribute and change under these
terms.

   To do so, attach the following notices to the program.  It is safest
to attach them to the start of each source file to most effectively
convey the exclusion of warranty; and each file should have at least
the "copyright" line and a pointer to where the full notice is found.

     ONE LINE TO GIVE THE PROGRAM'S NAME AND AN IDEA OF WHAT IT DOES.
     Copyright (C) 19YY  NAME OF AUTHOR
     
     This program is free software; you can redistribute it and/or
     modify it under the terms of the GNU General Public License
     as published by the Free Software Foundation; either version 2
     of the License, or (at your option) any later version.
     
     This program is distributed in the hope that it will be useful,
     but WITHOUT ANY WARRANTY; without even the implied warranty of
     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
     GNU General Public License for more details.
     
     You should have received a copy of the GNU 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.

   Also add information on how to contact you by electronic and paper
mail.

   If the program is interactive, make it output a short notice like
this when it starts in an interactive mode:

     Gnomovision version 69, Copyright (C) 19YY NAME OF AUTHOR
     Gnomovision comes with ABSOLUTELY NO WARRANTY; for details
     type `show w'.  This is free software, and you are welcome
     to redistribute it under certain conditions; type `show c'
     for details.

   The hypothetical commands `show w' and `show c' should show the
appropriate parts of the General Public License.  Of course, the
commands you use may be called something other than `show w' and `show
c'; they could even be mouse-clicks or menu items--whatever suits your
program.

   You should also get your employer (if you work as a programmer) or
your school, if any, to sign a "copyright disclaimer" for the program,
if necessary.  Here is a sample; alter the names:

     Yoyodyne, Inc., hereby disclaims all copyright
     interest in the program `Gnomovision'
     (which makes passes at compilers) written
     by James Hacker.
     
     SIGNATURE OF TY COON, 1 April 1989
     Ty Coon, President of Vice

   This General Public License does not permit incorporating your
program into proprietary programs.  If your program is a subroutine
library, you may consider it more useful to permit linking proprietary
applications with the library.  If this is what you want to do, use the
GNU Library General Public License instead of this License.


File: gpgme.info,  Node: Free Documentation License,  Next: Concept Index,  Prev: Copying,  Up: Top

GNU Free Documentation License
******************************

                        Version 1.1, March 2000

     Copyright (C) 2000 Free Software Foundation, Inc.
     59 Temple Place, Suite 330, Boston, MA  02111-1307, USA
     
     Everyone is permitted to copy and distribute verbatim copies
     of this license document, but changing it is not allowed.

  0. PREAMBLE

     The purpose of this License is to make a manual, textbook, or other
     written document "free" in the sense of freedom: to assure everyone
     the effective freedom to copy and redistribute it, with or without
     modifying it, either commercially or noncommercially.  Secondarily,
     this License preserves for the author and publisher a way to get
     credit for their work, while not being considered responsible for
     modifications made by others.

     This License is a kind of "copyleft", which means that derivative
     works of the document must themselves be free in the same sense.
     It complements the GNU General Public License, which is a copyleft
     license designed for free software.

     We have designed this License in order to use it for manuals for
     free software, because free software needs free documentation: a
     free program should come with manuals providing the same freedoms
     that the software does.  But this License is not limited to
     software manuals; it can be used for any textual work, regardless
     of subject matter or whether it is published as a printed book.
     We recommend this License principally for works whose purpose is
     instruction or reference.

  1. APPLICABILITY AND DEFINITIONS

     This License applies to any manual or other work that contains a
     notice placed by the copyright holder saying it can be distributed
     under the terms of this License.  The "Document", below, refers to
     any such manual or work.  Any member of the public is a licensee,
     and is addressed as "you".

     A "Modified Version" of the Document means any work containing the
     Document or a portion of it, either copied verbatim, or with
     modifications and/or translated into another language.

     A "Secondary Section" is a named appendix or a front-matter
     section of the Document that deals exclusively with the
     relationship of the publishers or authors of the Document to the
     Document's overall subject (or to related matters) and contains
     nothing that could fall directly within that overall subject.
     (For example, if the Document is in part a textbook of
     mathematics, a Secondary Section may not explain any mathematics.)
     The relationship could be a matter of historical connection with
     the subject or with related matters, or of legal, commercial,
     philosophical, ethical or political position regarding them.

     The "Invariant Sections" are certain Secondary Sections whose
     titles are designated, as being those of Invariant Sections, in
     the notice that says that the Document is released under this
     License.

     The "Cover Texts" are certain short passages of text that are
     listed, as Front-Cover Texts or Back-Cover Texts, in the notice
     that says that the Document is released under this License.

     A "Transparent" copy of the Document means a machine-readable copy,
     represented in a format whose specification is available to the
     general public, whose contents can be viewed and edited directly
     and straightforwardly with generic text editors or (for images
     composed of pixels) generic paint programs or (for drawings) some
     widely available drawing editor, and that is suitable for input to
     text formatters or for automatic translation to a variety of
     formats suitable for input to text formatters.  A copy made in an
     otherwise Transparent file format whose markup has been designed
     to thwart or discourage subsequent modification by readers is not
     Transparent.  A copy that is not "Transparent" is called "Opaque".

     Examples of suitable formats for Transparent copies include plain
     ASCII without markup, Texinfo input format, LaTeX input format,
     SGML or XML using a publicly available DTD, and
     standard-conforming simple HTML designed for human modification.
     Opaque formats include PostScript, PDF, proprietary formats that
     can be read and edited only by proprietary word processors, SGML
     or XML for which the DTD and/or processing tools are not generally
     available, and the machine-generated HTML produced by some word
     processors for output purposes only.

     The "Title Page" means, for a printed book, the title page itself,
     plus such following pages as are needed to hold, legibly, the
     material this License requires to appear in the title page.  For
     works in formats which do not have any title page as such, "Title
     Page" means the text near the most prominent appearance of the
     work's title, preceding the beginning of the body of the text.

  2. VERBATIM COPYING

     You may copy and distribute the Document in any medium, either
     commercially or noncommercially, provided that this License, the
     copyright notices, and the license notice saying this License
     applies to the Document are reproduced in all copies, and that you
     add no other conditions whatsoever to those of this License.  You
     may not use technical measures to obstruct or control the reading
     or further copying of the copies you make or distribute.  However,
     you may accept compensation in exchange for copies.  If you
     distribute a large enough number of copies you must also follow
     the conditions in section 3.

     You may also lend copies, under the same conditions stated above,
     and you may publicly display copies.

  3. COPYING IN QUANTITY

     If you publish printed copies of the Document numbering more than
     100, and the Document's license notice requires Cover Texts, you
     must enclose the copies in covers that carry, clearly and legibly,
     all these Cover Texts: Front-Cover Texts on the front cover, and
     Back-Cover Texts on the back cover.  Both covers must also clearly
     and legibly identify you as the publisher of these copies.  The
     front cover must present the full title with all words of the
     title equally prominent and visible.  You may add other material
     on the covers in addition.  Copying with changes limited to the
     covers, as long as they preserve the title of the Document and
     satisfy these conditions, can be treated as verbatim copying in
     other respects.

     If the required texts for either cover are too voluminous to fit
     legibly, you should put the first ones listed (as many as fit
     reasonably) on the actual cover, and continue the rest onto
     adjacent pages.

     If you publish or distribute Opaque copies of the Document
     numbering more than 100, you must either include a
     machine-readable Transparent copy along with each Opaque copy, or
     state in or with each Opaque copy a publicly-accessible
     computer-network location containing a complete Transparent copy
     of the Document, free of added material, which the general
     network-using public has access to download anonymously at no
     charge using public-standard network protocols.  If you use the
     latter option, you must take reasonably prudent steps, when you
     begin distribution of Opaque copies in quantity, to ensure that
     this Transparent copy will remain thus accessible at the stated
     location until at least one year after the last time you
     distribute an Opaque copy (directly or through your agents or
     retailers) of that edition to the public.

     It is requested, but not required, that you contact the authors of
     the Document well before redistributing any large number of
     copies, to give them a chance to provide you with an updated
     version of the Document.

  4. MODIFICATIONS

     You may copy and distribute a Modified Version of the Document
     under the conditions of sections 2 and 3 above, provided that you
     release the Modified Version under precisely this License, with
     the Modified Version filling the role of the Document, thus
     licensing distribution and modification of the Modified Version to
     whoever possesses a copy of it.  In addition, you must do these
     things in the Modified Version:

       A. Use in the Title Page (and on the covers, if any) a title
          distinct from that of the Document, and from those of
          previous versions (which should, if there were any, be listed
          in the History section of the Document).  You may use the
          same title as a previous version if the original publisher of
          that version gives permission.

       B. List on the Title Page, as authors, one or more persons or
          entities responsible for authorship of the modifications in
          the Modified Version, together with at least five of the
          principal authors of the Document (all of its principal
          authors, if it has less than five).

       C. State on the Title page the name of the publisher of the
          Modified Version, as the publisher.

       D. Preserve all the copyright notices of the Document.

       E. Add an appropriate copyright notice for your modifications
          adjacent to the other copyright notices.

       F. Include, immediately after the copyright notices, a license
          notice giving the public permission to use the Modified
          Version under the terms of this License, in the form shown in
          the Addendum below.

       G. Preserve in that license notice the full lists of Invariant
          Sections and required Cover Texts given in the Document's
          license notice.

       H. Include an unaltered copy of this License.

       I. Preserve the section entitled "History", and its title, and
          add to it an item stating at least the title, year, new
          authors, and publisher of the Modified Version as given on
          the Title Page.  If there is no section entitled "History" in
          the Document, create one stating the title, year, authors,
          and publisher of the Document as given on its Title Page,
          then add an item describing the Modified Version as stated in
          the previous sentence.

       J. Preserve the network location, if any, given in the Document
          for public access to a Transparent copy of the Document, and
          likewise the network locations given in the Document for
          previous versions it was based on.  These may be placed in
          the "History" section.  You may omit a network location for a
          work that was published at least four years before the
          Document itself, or if the original publisher of the version
          it refers to gives permission.

       K. In any section entitled "Acknowledgments" or "Dedications",
          preserve the section's title, and preserve in the section all
          the substance and tone of each of the contributor
          acknowledgments and/or dedications given therein.

       L. Preserve all the Invariant Sections of the Document,
          unaltered in their text and in their titles.  Section numbers
          or the equivalent are not considered part of the section
          titles.

       M. Delete any section entitled "Endorsements".  Such a section
          may not be included in the Modified Version.

       N. Do not retitle any existing section as "Endorsements" or to
          conflict in title with any Invariant Section.

     If the Modified Version includes new front-matter sections or
     appendices that qualify as Secondary Sections and contain no
     material copied from the Document, you may at your option
     designate some or all of these sections as invariant.  To do this,
     add their titles to the list of Invariant Sections in the Modified
     Version's license notice.  These titles must be distinct from any
     other section titles.

     You may add a section entitled "Endorsements", provided it contains
     nothing but endorsements of your Modified Version by various
     parties--for example, statements of peer review or that the text
     has been approved by an organization as the authoritative
     definition of a standard.

     You may add a passage of up to five words as a Front-Cover Text,
     and a passage of up to 25 words as a Back-Cover Text, to the end
     of the list of Cover Texts in the Modified Version.  Only one
     passage of Front-Cover Text and one of Back-Cover Text may be
     added by (or through arrangements made by) any one entity.  If the
     Document already includes a cover text for the same cover,
     previously added by you or by arrangement made by the same entity
     you are acting on behalf of, you may not add another; but you may
     replace the old one, on explicit permission from the previous
     publisher that added the old one.

     The author(s) and publisher(s) of the Document do not by this
     License give permission to use their names for publicity for or to
     assert or imply endorsement of any Modified Version.

  5. COMBINING DOCUMENTS

     You may combine the Document with other documents released under
     this License, under the terms defined in section 4 above for
     modified versions, provided that you include in the combination
     all of the Invariant Sections of all of the original documents,
     unmodified, and list them all as Invariant Sections of your
     combined work in its license notice.

     The combined work need only contain one copy of this License, and
     multiple identical Invariant Sections may be replaced with a single
     copy.  If there are multiple Invariant Sections with the same name
     but different contents, make the title of each such section unique
     by adding at the end of it, in parentheses, the name of the
     original author or publisher of that section if known, or else a
     unique number.  Make the same adjustment to the section titles in
     the list of Invariant Sections in the license notice of the
     combined work.

     In the combination, you must combine any sections entitled
     "History" in the various original documents, forming one section
     entitled "History"; likewise combine any sections entitled
     "Acknowledgments", and any sections entitled "Dedications".  You
     must delete all sections entitled "Endorsements."

  6. COLLECTIONS OF DOCUMENTS

     You may make a collection consisting of the Document and other
     documents released under this License, and replace the individual
     copies of this License in the various documents with a single copy
     that is included in the collection, provided that you follow the
     rules of this License for verbatim copying of each of the
     documents in all other respects.

     You may extract a single document from such a collection, and
     distribute it individually under this License, provided you insert
     a copy of this License into the extracted document, and follow
     this License in all other respects regarding verbatim copying of
     that document.

  7. AGGREGATION WITH INDEPENDENT WORKS

     A compilation of the Document or its derivatives with other
     separate and independent documents or works, in or on a volume of
     a storage or distribution medium, does not as a whole count as a
     Modified Version of the Document, provided no compilation
     copyright is claimed for the compilation.  Such a compilation is
     called an "aggregate", and this License does not apply to the
     other self-contained works thus compiled with the Document, on
     account of their being thus compiled, if they are not themselves
     derivative works of the Document.

     If the Cover Text requirement of section 3 is applicable to these
     copies of the Document, then if the Document is less than one
     quarter of the entire aggregate, the Document's Cover Texts may be
     placed on covers that surround only the Document within the
     aggregate.  Otherwise they must appear on covers around the whole
     aggregate.

  8. TRANSLATION

     Translation is considered a kind of modification, so you may
     distribute translations of the Document under the terms of section
     4.  Replacing Invariant Sections with translations requires special
     permission from their copyright holders, but you may include
     translations of some or all Invariant Sections in addition to the
     original versions of these Invariant Sections.  You may include a
     translation of this License provided that you also include the
     original English version of this License.  In case of a
     disagreement between the translation and the original English
     version of this License, the original English version will prevail.

  9. TERMINATION

     You may not copy, modify, sublicense, or distribute the Document
     except as expressly provided for under this License.  Any other
     attempt to copy, modify, sublicense or distribute the Document is
     void, and will automatically terminate your rights under this
     License.  However, parties who have received copies, or rights,
     from you under this License will not have their licenses
     terminated so long as such parties remain in full compliance.

 10. FUTURE REVISIONS OF THIS LICENSE

     The Free Software Foundation may publish new, revised versions of
     the GNU Free Documentation License from time to time.  Such new
     versions will be similar in spirit to the present version, but may
     differ in detail to address new problems or concerns.  See
     `http://www.gnu.org/copyleft/'.

     Each version of the License is given a distinguishing version
     number.  If the Document specifies that a particular numbered
     version of this License "or any later version" applies to it, you
     have the option of following the terms and conditions either of
     that specified version or of any later version that has been
     published (not as a draft) by the Free Software Foundation.  If
     the Document does not specify a version number of this License,
     you may choose any version ever published (not as a draft) by the
     Free Software Foundation.

ADDENDUM: How to use this License for your documents
----------------------------------------------------

   To use this License in a document you have written, include a copy of
the License in the document and put the following copyright and license
notices just after the title page:

       Copyright (C)  YEAR  YOUR NAME.
       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 LIST THEIR TITLES, with the
       Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
       A copy of the license is included in the section entitled ``GNU
       Free Documentation License''.

   If you have no Invariant Sections, write "with no Invariant Sections"
instead of saying which ones are invariant.  If you have no Front-Cover
Texts, write "no Front-Cover Texts" instead of "Front-Cover Texts being
LIST"; likewise for Back-Cover Texts.

   If your document contains nontrivial examples of program code, we
recommend releasing these examples in parallel under your choice of
free software license, such as the GNU General Public License, to
permit their use in free software.


File: gpgme.info,  Node: Concept Index,  Next: Function and Data Index,  Prev: Free Documentation License,  Up: Top

Concept Index
*************

* Menu:

* armor mode:                            ASCII Armor.
* ASCII armor:                           ASCII Armor.
* attributes, of a key:                  Information About Keys.
* attributes, of a trust item:           Information About Trust Items.
* autoconf:                              Using Automake.
* automake:                              Using Automake.
* backend:                               Protocols and Engines.
* callback, passphrase:                  Passphrase Callback.
* callback, progress meter:              Progress Meter Callback.
* cancellation:                          Cancelling an Operation.
* canonical text mode:                   Text Mode.
* certificates, included:                Included Certificates.
* CMS:                                   Cryptographic Message Syntax.
* compiler flags:                        Building the Source.
* compiler options:                      Building the Source.
* context:                               Contexts.
* context, armor mode:                   ASCII Armor.
* context, attributes:                   Context Attributes.
* context, creation:                     Creating Contexts.
* context, destruction:                  Destroying Contexts.
* context, selecting protocol:           Protocol Selection.
* context, text mode:                    Text Mode.
* crypto backend:                        Protocols and Engines.
* crypto engine:                         Protocols and Engines.
* cryptographic message syntax:          Cryptographic Message Syntax.
* cryptographic operation:               Crypto Operations.
* cryptographic operation, cancel:       Cancelling an Operation.
* cryptographic operation, decryption:   Decrypt.
* cryptographic operation, decryption and verification: Decrypt and Verify.
* cryptographic operation, detailed results: Detailed Results.
* cryptographic operation, encryption:   Encrypt.
* cryptographic operation, running:      Run Control.
* cryptographic operation, signature check: Verify.
* cryptographic operation, signing:      Sign.
* cryptographic operation, verification: Verify.
* cryptographic operation, wait for:     Waiting For Completion.
* data buffer, creation:                 Creating Data Buffers.
* data buffer, destruction:              Destroying Data Buffers.
* data buffere, manipulation:            Manipulating Data Buffers.
* data, exchanging:                      Exchanging Data.
* decryption:                            Decrypt.
* decryption and verification:           Decrypt and Verify.
* encryption:                            Encrypt.
* encryption, selecting recipients:      Selecting Recipients.
* engine:                                Protocols and Engines.
* engine, GnuPG:                         OpenPGP.
* engine, GpgSM:                         Cryptographic Message Syntax.
* engine, information about:             Engine Information.
* error handling:                        Error Handling.
* error strings:                         Error Strings.
* error values, list of:                 Error Values.
* error values, printing of:             Error Strings.
* event loop, external:                  Using External Event Loops.
* FDL, GNU Free Documentation License:   Free Documentation License.
* GDK, using GPGME with:                 I/O Callback Example GDK.
* GnuPG:                                 OpenPGP.
* GpgSM:                                 Cryptographic Message Syntax.
* GPL, GNU General Public License:       Copying.
* GTK+, using GPGME with:                I/O Callback Example GTK+.
* header file:                           Header.
* idle function:                         Hooking Up Into Idle Time.
* idle time:                             Hooking Up Into Idle Time.
* include file:                          Header.
* key listing:                           Listing Keys.
* key listing mode:                      Key Listing Mode.
* key listing, mode of:                  Key Listing Mode.
* key listing, start:                    Listing Keys.
* key management:                        Key Management.
* key ring, add:                         Generating Keys.
* key ring, delete from:                 Deleting Keys.
* key ring, export from:                 Exporting Keys.
* key ring, import to:                   Importing Keys.
* key ring, list:                        Listing Keys.
* key ring, search:                      Listing Keys.
* key, attributes:                       Information About Keys.
* key, creation:                         Generating Keys.
* key, delete:                           Deleting Keys.
* key, export:                           Exporting Keys.
* key, import:                           Importing Keys.
* key, information about:                Information About Keys.
* key, manipulation:                     Manipulating Keys.
* listing keys:                          Listing Keys.
* multi-threading:                       Multi Threading.
* OpenPGP:                               OpenPGP.
* passphrase callback:                   Passphrase Callback.
* progress meter callback:               Progress Meter Callback.
* protocol:                              Protocols and Engines.
* protocol, CMS:                         Cryptographic Message Syntax.
* protocol, GnuPG:                       OpenPGP.
* protocol, S/MIME:                      Cryptographic Message Syntax.
* protocol, selecting:                   Protocol Selection.
* recipients:                            Selecting Recipients.
* run control:                           Run Control.
* S/MIME:                                Cryptographic Message Syntax.
* sign:                                  Sign.
* signature check:                       Decrypt and Verify.
* signature, creation:                   Sign.
* signature, selecting signers:          Selecting Signers.
* signature, status:                     Verify.
* signature, verification:               Verify.
* signers, selecting:                    Selecting Signers.
* text mode:                             Text Mode.
* thread-safeness:                       Multi Threading.
* trust item:                            Trust Item Management.
* trust item list:                       Listing Trust Items.
* trust item, attributes:                Information About Trust Items.
* trust item, information about:         Information About Trust Items.
* trust item, manipulation:              Manipulating Trust Items.
* verification:                          Verify.
* verification and decryption:           Decrypt and Verify.
* version check, of the engines:         Engine Version Check.
* version check, of the library:         Library Version Check.
* wait for completion:                   Waiting For Completion.


File: gpgme.info,  Node: Function and Data Index,  Prev: Concept Index,  Up: Top

Function and Data Index
***********************

* Menu:

* AM_PATH_GPGME:                         Using Automake.
* const char *(*GpgmePassphraseCb)(void *HOOK, const char *DESC, void **R_HD): Passphrase Callback.
* const char *(*GpgmeProgressCb)(void *HOOK, const char *WHAT, int TYPE, int CURRENT, int TOTAL): Progress Meter Callback.
* enum GpgmeDataEncoding:                Manipulating Data Buffers.
* enum GpgmeDataType:                    Manipulating Data Buffers.
* enum GpgmeError:                       Error Values.
* enum GpgmeEventIO:                     I/O Callback Interface.
* enum GpgmeProtocol:                    Protocols and Engines.
* enum GpgmeSigMode:                     Creating a Signature.
* enum GpgmeSigStat:                     Verify.
* gpgme_cancel:                          Cancelling an Operation.
* gpgme_check_engine:                    Engine Version Check.
* gpgme_check_version:                   Library Version Check.
* gpgme_data_get_encoding:               Manipulating Data Buffers.
* gpgme_data_get_type:                   Manipulating Data Buffers.
* gpgme_data_new:                        Creating Data Buffers.
* gpgme_data_new_from_file:              Creating Data Buffers.
* gpgme_data_new_from_filepart:          Creating Data Buffers.
* gpgme_data_new_from_mem:               Creating Data Buffers.
* gpgme_data_new_with_read_cb:           Creating Data Buffers.
* gpgme_data_read:                       Manipulating Data Buffers.
* gpgme_data_release:                    Destroying Data Buffers.
* gpgme_data_release_and_get_mem:        Destroying Data Buffers.
* gpgme_data_rewind:                     Manipulating Data Buffers.
* gpgme_data_set_encoding:               Manipulating Data Buffers.
* gpgme_data_write:                      Manipulating Data Buffers.
* gpgme_engine_check_version:            Engine Version Check.
* gpgme_get_armor:                       ASCII Armor.
* gpgme_get_engine_info:                 Engine Information.
* gpgme_get_include_certs:               Included Certificates.
* gpgme_get_io_cbs:                      Registering I/O Callbacks.
* gpgme_get_keylist_mode:                Key Listing Mode.
* gpgme_get_notation:                    Verify.
* gpgme_get_op_info:                     Detailed Results.
* gpgme_get_passphrase_cb:               Passphrase Callback.
* gpgme_get_progress_cb:                 Progress Meter Callback.
* gpgme_get_protocol:                    Protocol Selection.
* gpgme_get_sig_key:                     Verify.
* gpgme_get_sig_status:                  Verify.
* gpgme_get_sig_string_attr:             Verify.
* gpgme_get_sig_ulong_attr:              Verify.
* gpgme_get_textmode:                    Text Mode.
* gpgme_key_get_as_xml:                  Information About Keys.
* gpgme_key_get_string_attr:             Information About Keys.
* gpgme_key_get_ulong_attr:              Information About Keys.
* gpgme_key_ref:                         Manipulating Keys.
* gpgme_key_release:                     Manipulating Keys.
* gpgme_key_unref:                       Manipulating Keys.
* gpgme_new:                             Creating Contexts.
* gpgme_op_decrypt:                      Decrypt.
* gpgme_op_decrypt_start:                Decrypt.
* gpgme_op_decrypt_verify:               Decrypt and Verify.
* gpgme_op_delete:                       Deleting Keys.
* gpgme_op_delete_start:                 Deleting Keys.
* gpgme_op_encrypt:                      Encrypting a Plaintext.
* gpgme_op_encrypt_sign:                 Encrypting a Plaintext.
* gpgme_op_encrypt_sign_start:           Encrypting a Plaintext.
* gpgme_op_encrypt_start:                Encrypting a Plaintext.
* gpgme_op_export:                       Exporting Keys.
* gpgme_op_export_start:                 Exporting Keys.
* gpgme_op_genkey:                       Generating Keys.
* gpgme_op_genkey_start:                 Generating Keys.
* gpgme_op_import:                       Importing Keys.
* gpgme_op_import_ext:                   Importing Keys.
* gpgme_op_import_start:                 Importing Keys.
* gpgme_op_keylist_end:                  Listing Keys.
* gpgme_op_keylist_ext_start:            Listing Keys.
* gpgme_op_keylist_next:                 Listing Keys.
* gpgme_op_keylist_start:                Listing Keys.
* gpgme_op_sign:                         Creating a Signature.
* gpgme_op_sign_start:                   Creating a Signature.
* gpgme_op_trustlist_end:                Listing Trust Items.
* gpgme_op_trustlist_next:               Listing Trust Items.
* gpgme_op_trustlist_start:              Listing Trust Items.
* gpgme_op_verify:                       Verify.
* gpgme_op_verify_start:                 Verify.
* gpgme_recipients_add_name:             Selecting Recipients.
* gpgme_recipients_add_name_with_validity: Selecting Recipients.
* gpgme_recipients_count:                Selecting Recipients.
* gpgme_recipients_enum_close:           Selecting Recipients.
* gpgme_recipients_enum_open:            Selecting Recipients.
* gpgme_recipients_enum_read:            Selecting Recipients.
* gpgme_recipients_new:                  Selecting Recipients.
* gpgme_recipients_release:              Selecting Recipients.
* gpgme_register_idle:                   Hooking Up Into Idle Time.
* gpgme_release:                         Destroying Contexts.
* gpgme_set_armor:                       ASCII Armor.
* gpgme_set_include_certs:               Included Certificates.
* gpgme_set_io_cbs:                      Registering I/O Callbacks.
* gpgme_set_keylist_mode:                Key Listing Mode.
* gpgme_set_passphrase_cb:               Passphrase Callback.
* gpgme_set_progress_cb:                 Progress Meter Callback.
* gpgme_set_protocol:                    Protocol Selection.
* gpgme_set_textmode:                    Text Mode.
* gpgme_signers_add:                     Selecting Signers.
* gpgme_signers_clear:                   Selecting Signers.
* gpgme_signers_enum:                    Selecting Signers.
* gpgme_strerror:                        Error Strings.
* gpgme_trust_item_get_int_attr:         Information About Trust Items.
* gpgme_trust_item_get_string_attr:      Information About Trust Items.
* gpgme_trust_item_release:              Manipulating Trust Items.
* gpgme_wait:                            Waiting For Completion.
* GpgmeAttr:                             Information About Keys.
* GpgmeCtx:                              Contexts.
* GpgmeData:                             Exchanging Data.
* GpgmeDataEncoding:                     Manipulating Data Buffers.
* GpgmeDataType:                         Manipulating Data Buffers.
* GpgmeError:                            Error Values.
* GpgmeError (*GpgmeRegisterIOCb) (void *DATA, int FD, int DIR, GpgmeIOCb FNC, void *FNC_DATA, void **TAG): I/O Callback Interface.
* GpgmeEventIO <1>:                      Registering I/O Callbacks.
* GpgmeEventIO:                          I/O Callback Interface.
* GpgmeIdleFunc:                         Hooking Up Into Idle Time.
* GpgmeIOCb:                             I/O Callback Interface.
* GpgmeKey:                              Key Management.
* GpgmePassphraseCb:                     Passphrase Callback.
* GpgmeProgressCb:                       Progress Meter Callback.
* GpgmeProtocol:                         Protocols and Engines.
* GpgmeRecipients:                       Selecting Recipients.
* GpgmeRegisterIOCb:                     I/O Callback Interface.
* GpgmeSigMode:                          Creating a Signature.
* GpgmeSigStat:                          Verify.
* GpgmeTrustItem:                        Trust Item Management.
* GpgmeValidity:                         Information About Keys.
* struct GpgmeIOCbs:                     Registering I/O Callbacks.
* void (*GpgmeEventIOCb) (void *DATA, GpgmeEventIO TYPE, void *TYPE_DATA): I/O Callback Interface.
* void (*GpgmeIdleFunc) (void):          Hooking Up Into Idle Time.
* void (*GpgmeIOCb) (void *DATA, int FD): I/O Callback Interface.
* void (*GpgmeRemoveIOCb) (void *TAG):   I/O Callback Interface.



Tag Table:
Node: Top936
Node: Introduction6368
Node: Getting Started7143
Node: Features8264
Node: Overview9394
Node: Preparation10498
Node: Header11294
Node: Building the Source11941
Node: Using Automake13783
Node: Library Version Check14865
Node: Multi Threading16479
Ref: Multi Threading-Footnote-119579
Node: Protocols and Engines20051
Node: Engine Version Check21420
Node: Engine Information22279
Node: OpenPGP23411
Node: Cryptographic Message Syntax23740
Node: Error Handling24029
Node: Error Values25184
Node: Error Strings29283
Node: Exchanging Data30028
Node: Creating Data Buffers30909
Node: Destroying Data Buffers35163
Node: Manipulating Data Buffers36164
Node: Contexts40538
Node: Creating Contexts41566
Node: Destroying Contexts42058
Node: Context Attributes42382
Node: Protocol Selection43022
Node: ASCII Armor43988
Node: Text Mode44585
Node: Included Certificates45496
Node: Key Listing Mode46716
Node: Passphrase Callback48882
Node: Progress Meter Callback51166
Node: Key Management53045
Node: Listing Keys54138
Node: Information About Keys58398
Node: Manipulating Keys66471
Node: Generating Keys67135
Node: Exporting Keys70296
Node: Importing Keys71589
Node: Deleting Keys73259
Node: Trust Item Management74489
Node: Listing Trust Items75031
Node: Information About Trust Items77353
Node: Manipulating Trust Items79041
Node: Crypto Operations79401
Node: Decrypt79934
Node: Verify81228
Node: Decrypt and Verify91192
Node: Sign92958
Node: Selecting Signers93438
Node: Creating a Signature94372
Node: Encrypt96649
Node: Selecting Recipients97086
Node: Encrypting a Plaintext100502
Node: Detailed Results103873
Node: Run Control104990
Node: Waiting For Completion105802
Node: Cancelling an Operation107545
Node: Hooking Up Into Idle Time108205
Node: Using External Event Loops109032
Node: I/O Callback Interface110912
Node: Registering I/O Callbacks115435
Node: I/O Callback Example117401
Node: I/O Callback Example GTK+123403
Node: I/O Callback Example GDK125190
Node: Copying126798
Node: Free Documentation License146007
Node: Concept Index165891
Node: Function and Data Index172796

End Tag Table
