--- /dev/null
+@node Free Documentation License
+@appendix GNU Free Documentation License
+
+@cindex FDL, GNU Free Documentation License
+@center Version 1.1, March 2000
+
+@display
+Copyright @copyright{} 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.
+@end display
+
+@enumerate 0
+@item
+PREAMBLE
+
+The purpose of this License is to make a manual, textbook, or other
+written document @dfn{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.
+
+@item
+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
+@sc{ascii} without markup, Texinfo input format, La@TeX{} input format,
+@acronym{SGML} or @acronym{XML} using a publicly available
+@acronym{DTD}, and standard-conforming simple @acronym{HTML} designed
+for human modification. Opaque formats include PostScript,
+@acronym{PDF}, proprietary formats that can be read and edited only by
+proprietary word processors, @acronym{SGML} or @acronym{XML} for which
+the @acronym{DTD} and/or processing tools are not generally available,
+and the machine-generated @acronym{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.
+
+@item
+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.
+
+@item
+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.
+
+@item
+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:
+
+@enumerate A
+@item
+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.
+
+@item
+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).
+
+@item
+State on the Title page the name of the publisher of the
+Modified Version, as the publisher.
+
+@item
+Preserve all the copyright notices of the Document.
+
+@item
+Add an appropriate copyright notice for your modifications
+adjacent to the other copyright notices.
+
+@item
+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.
+
+@item
+Preserve in that license notice the full lists of Invariant Sections
+and required Cover Texts given in the Document's license notice.
+
+@item
+Include an unaltered copy of this License.
+
+@item
+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.
+
+@item
+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.
+
+@item
+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.
+
+@item
+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.
+
+@item
+Delete any section entitled ``Endorsements''. Such a section
+may not be included in the Modified Version.
+
+@item
+Do not retitle any existing section as ``Endorsements''
+or to conflict in title with any Invariant Section.
+@end enumerate
+
+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.
+
+@item
+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.''
+
+@item
+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.
+
+@item
+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.
+
+@item
+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.
+
+@item
+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.
+
+@item
+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
+@uref{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.
+@end enumerate
+
+@page
+@appendixsubsec 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:
+
+@smallexample
+@group
+ Copyright (C) @var{year} @var{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 @var{list their titles}, with the
+ Front-Cover Texts being @var{list}, and with the Back-Cover Texts being @var{list}.
+ A copy of the license is included in the section entitled ``GNU
+ Free Documentation License''.
+@end group
+@end smallexample
+
+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 @var{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.
+
+@c Local Variables:
+@c ispell-local-pdict: "ispell-dict"
+@c End:
+
--- /dev/null
+\input texinfo @c -*- Texinfo -*-
+@setfilename gpgme.info
+@settitle The `GnuPG Made Easy' Reference Manual
+
+@c TODO:
+@c GpgmeError gpgme_op_import ( GpgmeCtx c, GpgmeData keydata );
+@c GpgmeError gpgme_op_export ( GpgmeCtx c, GpgmeRecipients recp,
+@c GpgmeData keydata );
+@c GpgmeError gpgme_op_genkey ( GpgmeCtx c, const char *parms,
+@c GpgmeData pubkey, GpgmeData seckey );
+@c GpgmeError gpgme_op_delete ( GpgmeCtx c, const GpgmeKey key, int allow_secret);
+@c char *gpgme_get_op_info (GpgmeCtx c, int reserved);
+@c void gpgme_cancel (GpgmeCtx c);
+@c GpgmeCtx gpgme_wait (GpgmeCtx c, int hang);
+@c char *gpgme_get_notation (GpgmeCtx c);
+@c void gpgme_register_idle (void (*fnc)(void));
+
+@dircategory GNU Libraries
+@direntry
+* @acronym{GPGME}: (gpgme) Adding support for cryptography to your program.
+@end direntry
+
+@include version.texi
+
+@c Unify some of the indices.
+@syncodeindex tp fn
+@syncodeindex pg fn
+
+@ifinfo
+This file documents the @acronym{GPGME} library.
+
+This is Edition @value{EDITION}, last updated @value{UPDATED}, of
+@cite{The `GnuPG Made Easy' Reference Manual}, for Version
+@value{VERSION}.
+
+Copyright @copyright{} 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''.
+
+@end ifinfo
+
+@iftex
+@shorttitlepage The `GnuPG Made Easy' Reference Manual
+@end iftex
+@titlepage
+@center @titlefont{The `GnuPG Made Easy'}
+@sp 1
+@center @titlefont{Reference Manual}
+@sp 6
+@center Edition @value{EDITION}
+@sp 1
+@center last updated @value{UPDATED}
+@sp 1
+@center for version @value{VERSION}
+@page
+@vskip 0pt plus 1filll
+Copyright @copyright{} 2001 g10Code 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''.
+@end titlepage
+@page
+
+@ifnottex
+@node Top
+@top Main Menu
+This is Edition @value{EDITION}, last updated @value{UPDATED}, of
+@cite{The `GnuPG Made Easy' Reference Manual}, for Version
+@value{VERSION} of the GNU Mach microkernel.
+@end ifnottex
+
+@menu
+* Introduction:: How to use this manual.
+* Preperation:: 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 @acronym{GPGME}.
+* Contexts:: Handling @acronym{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.
+
+
+@detailmenu
+ --- The Detailed Node Listing ---
+
+Introduction
+
+* Getting Started:: Purpose of the manual, and how to use it.
+* Features:: Reasons to install and use @acronym{GPGME}.
+* Overview:: Basic architecture of the @acronym{GPGME} library.
+
+Preperation
+
+* Header:: What header file you need to include.
+* Building the source:: Compiler options to be used.
+* Library version check:: Getting and verifying the library version.
+
+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 @acronym{GPGME} contexts.
+* Destroying contexts:: Releasing @acronym{GPGME} contexts.
+* Context attributes:: Setting properties of a context.
+* Key Management:: Managing keys with @acronym{GPGME}.
+* Trust Item Management:: Managing trust items with @acronym{GPGME}.
+* Crypto Operations:: Using a context for cryptography.
+
+Context attributes
+
+* Protocol selection:: Selecting the protocol used by a context.
+* @acronym{ASCII} armor:: Requesting @acronym{ASCII} armored output.
+* Text mode:: Choosing canonical text mode.
+* 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.
+
+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.
+
+Sign
+
+* Selecting signers:: How to choose the keys to sign with.
+* Creating a signature:: How to create a signature.
+
+
+@end detailmenu
+@end menu
+
+@node Introduction
+@chapter Introduction
+
+`GnuPG Made Easy' (@acronym{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. @acronym{GPGME} provides a high-level crypto API for
+encryption, decryption, signing, signature verification and key
+management.
+
+@acronym{GPGME} uses GnuPG and GpgSM as its backends to support
+OpenPGP and the Cryptograhic Message Syntax (CMS).
+
+@menu
+* Getting Started:: Purpose of the manual, and how to use it.
+* Features:: Reasons to install and use @acronym{GPGME}.
+* Overview:: Basic architecture of the @acronym{GPGME} library.
+@end menu
+
+
+@node Getting Started
+@section Getting Started
+
+This library documents the @acronym{GPGME} library programming
+interface. All functions and data types provided by the library are
+explained.
+
+The reader is assumed to posess 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 @acronym{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.
+
+
+@node Features
+@section Features
+
+@acronym{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.
+
+@table @asis
+@item it's free software
+Anybody can use, modify, and redistribute it under the terms of the GNU
+General Public License (@pxref{Copying}).
+
+@item it's flexible
+@acronym{GPGME} provides transparent support for several cryptographic
+protocols by different engines. Currently, @acronym{GPGME} supports
+the OpenPGP protocol using GnuPG as the backend, and the Cryptographic
+Message Syntax using GpgSM as the backend.
+
+@item it's easy
+@acronym{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
+@acronym{GPGME} has been added to a program, it is easy to add support
+for other crypto protocols once @acronym{GPGME} backends provide them.
+@end table
+
+
+@node Overview
+@section Overview
+
+@acronym{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, @acronym{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.
+
+@strong{Caution:} The @acronym{GPGME} library is not thread-safe. It
+will be to some extent in the future, but currently great care has to
+be taken if @acronym{GPGME} is used in a multi-threaded environment.
+
+
+@node Preperation
+@chapter Preperation
+
+To use @acronym{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.
+* Library version check:: Getting and verifying the library version.
+@end menu
+
+
+@node Header
+@section 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:
+
+@example
+#include <gpgme.h>
+@end example
+
+The name space of @acronym{GPGME} is @code{gpgme_*} for function
+names, @code{Gpgme*} for data types and @code{GPGME_*} for other
+symbols.
+
+
+@node Building the source
+@section 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 @option{-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 @command{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 @option{--cflags} option to @command{gpgme-config}. The following
+example shows how it can be used at the command line:
+
+@example
+gcc -c foo.c `gpgme-config --cflags`
+@end example
+
+Adding the output of @samp{gpgme-config --cflags} to the compilers
+command line will ensure that the compiler can find the @acronym{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 @option{-L} option). For this, the option
+@option{--libs} to @command{gpgme-config} can be used. For
+convenience, this option also outputs all other options that are
+required to link the program with @acronym{GPGME} (in particular, the
+@samp{-lgpgme} option). The example shows how to link @file{foo.o}
+with the @acronym{GPGME} library to a program @command{foo}.
+
+@example
+gcc -o foo foo.o `gpgme-config --libs`
+@end example
+
+Of course you can also combine both examples to a single command by
+specifying both options to @command{gpgme-config}:
+
+@example
+gcc -o foo foo.c `gpgme-config --cflags --libs`
+@end example
+
+
+@node Library version check
+@section Library version check
+
+@deftypefun {const char *} gpgme_check_version (@w{const char *@var{required_version}})
+The function @code{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
+@acronym{GPGME}.
+
+If @var{required_version} is @code{NULL}, the function returns a
+pointer to a statically allocated string containing the version number
+of the library.
+
+If @var{required_version} is not @code{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 @var{REQUIRED_VERSION} is not a valid version number, or
+if the version requirement is not met, the function returns
+@code{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.
+@end deftypefun
+
+
+@node Protocols and Engines
+@chapter Protocols and Engines
+
+@acronym{GPGME} supports several cryptographic protocols, however, it
+does not implement them. Rather it uses backends (also called
+engines) which implement the protocol. @acronym{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 @acronym{GPGME}. Where an
+exchange of information between the application and the backend is
+necessary, @acronym{GPGME} provides the necessary callback function
+hooks and further interfaces.
+
+@deftp {Data type} {enum GpgmeProtocol}
+The @code{GpgmeProtocol} type specifies the set of possible protocol
+values that are supported by @acronym{GPGME}. The following protocols
+are supported:
+
+@table @code
+@item GPGME_PROTOCOL_OpenPGP
+This specifies the OpenPGP protocol.
+@item GPGME_PROTOCOL_CMS
+This specifies the Cryptographic Message Syntax.
+@end table
+@end deftp
+
+@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.
+@end menu
+
+
+@node Engine version check
+@section Engine version check
+
+@deftypefun GpgmeError gpgme_engine_check_version (@w{GpgmeProtocol @var{protocol}})
+The function @code{gpgme_engine_check_version} verifies that the
+engine implementing the protocol @var{PROTOCOL} is installed in the
+expected path and meets the version requirement of @acronym{GPGME}.
+
+This function returns @code{GPGME_No_Error} if the engine is available
+and @code{GPGME_Invalid_Engine} if it is not.
+@end deftypefun
+
+@deftypefun GpgmeError gpgme_check_engine (void)
+The function @code{gpgme_check_engine} is equivalent to
+
+@example
+gpgme_engine_check_version (GPGME_PROTOCOL_OpenPGP);
+@end example
+
+This function is deprecated and provided for backwards compatibility
+only. It is obsoleted by @code{gpgme_engine_check_version}.
+@end deftypefun
+
+
+@node Engine information
+@section Engine information
+
+@deftypefun {const char *} gpgme_get_engine_info (void)
+The function @code{gpgme_get_engine_info} returns an @acronym{XML}
+string containing information about the available protocols and the
+engine which implement them. The following information is returned
+for each engine:
+
+@table @samp
+@item <protocol>
+The name of the protocol.
+@item <version>
+The version of the engine.
+@item <path>
+The path to the engine binary.
+@end table
+
+A string is always returned. If an error occurs, the string will
+contain an @samp{<error>} tag with a description of the failure.
+@end deftypefun
+
+Here is the example output of what @code{gpgme_get_engine_info} might
+return on your system:
+
+@example
+<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>
+@end example
+
+
+@node OpenPGP
+@section OpenPGP
+
+OpenPGP is implemented by GnuPG, the @acronym{GNU} Privacy Guard.
+This is the first protocol that was supported by @acronym{GPGME}.
+
+The OpenPGP protocol is specified by @code{GPGME_PROTOCOL_OpenPGP}.
+
+
+@node Cryptographic Message Syntax
+@section Cryptographic Message Syntax
+
+@acronym{CMS} is implemented by GpgSM, the S/MIME implementation for
+GnuPG.
+
+The @acronym{CMS} protocol is specified by @code{GPGME_PROTOCOL_CMS}.
+
+
+@node Error Handling
+@chapter Error Handling
+
+Many functions in @acronym{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.
+@end menu
+
+
+@node Error values
+@section Error values
+
+@deftp {Data type} {enum GpgmeError}
+The @code{GpgmeError} type specifies the set of all error values that
+are used by @acronym{GPGME}. Possible values are:
+
+@table @code
+@item GPGME_EOF
+This value indicates the end of a list, buffer or file.
+
+@item GPGME_No_Error
+This value indicates success. The value of this error is @code{0}.
+
+@item 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 seperate error value for this type of problem.
+
+@item GPGME_Out_Of_Core
+This value means that an out-of-memory condition occured.
+
+@item 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 @code{GpgmeData}
+object was expected, but one containing data was provided, this error
+value is returned.
+
+@item 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
+canceled or finished yet.
+
+@item GPGME_No_Request
+This value is in some sense the opposite of @code{GPGME_Busy}. There
+is no pending operation, but it is required for the function to
+succeed.
+
+@item GPGME_Exec_Error
+This value means that an error occured when trying to spawn a child
+process.
+
+@item GPGME_Too_Many_Procs
+This value means that there are too many active backend processes.
+
+@item GPGME_Pipe_Error
+This value means that the creation of a pipe failed.
+
+@item GPGME_No_Recipients
+This value means that no recipients for a message have been set.
+
+@item GPGME_No_Data
+This value means that a @code{GpgmeData} object which was expected to
+have content was found empty.
+
+@item GPGME_Conflict
+This value means that a conflict of some sort occured.
+
+@item 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.
+
+@item GPGME_Read_Error
+This value means that an I/O read operation failed.
+
+@item GPGME_Write_Error
+This value means that an I/O write operation failed.
+
+@item 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
+@code{GpgmeData} object.
+
+@item GPGME_Invalid_Mode
+This value means that a @code{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).
+
+@item GPGME_File_Error
+This value means that a file I/O operation failed. The value of
+@code{errno} contains the system error value.
+
+@item GPGME_Decryption_Failed
+This value indicates that a decryption operation was unsuccessful.
+
+@item GPGME_No_Passphrase
+This value means that the user did not provide a passphrase when
+requested.
+
+@item GPGME_Canceled
+This value means that the operation was canceled.
+
+@item GPGME_Invalid_Key
+This value means that a key was invalid.
+
+@item 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.
+@end table
+@end deftp
+
+
+@node Error strings
+@section Error strings
+
+@deftypefun {const char *} gpgme_strerror (@w{GpgmeError @var{err}})
+The function @code{gpgme_strerror} returns a pointer to a statically
+allocated string containing a description of the error with the error
+value @var{err}. This string can be used to output a diagnostic
+message to the user.
+@end deftypefun
+
+
+@node Exchanging Data
+@chapter 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 @acronym{GPGME}.
+The user provides and receives the data via @code{GpgmeData} objects,
+regardless of the communication protocol between @acronym{GPGME} and
+the crypto engine in use.
+
+@deftp {Data type} {GpgmeData}
+The @code{GpgmeData} type is a handle for a container for generic
+data, which is used by @acronym{GPGME} to exchange data with the user.
+@end deftp
+
+@menu
+* Creating data buffers:: Creating new data buffers.
+* Destroying data buffers:: Releasing data buffers.
+* Manipulating data buffers:: Operations on data buffers.
+@end menu
+
+
+@node Creating data buffers
+@section Creating data buffers
+
+@deftypefun GpgmeError gpgme_data_new (@w{GpgmeData *@var{dh}})
+The function @code{gpgme_data_new} creates a new @code{GpgmeData}
+object and returns a handle for it in @var{dh}. The data object is
+initially empty.
+
+The function returns @code{GPGME_No_Error} if the data object was
+successfully created, @code{GPGME_Invalid_Value} if @var{dh} is not a
+valid pointer, and @code{GPGME_Out_Of_Core} if not enough memory is
+available.
+@end deftypefun
+
+@deftypefun GpgmeError gpgme_data_new_from_mem (@w{GpgmeData *@var{dh}}, @w{const char *@var{buffer}}, @w{size_t @var{size}}, @w{int @var{copy}})
+The function @code{gpgme_data_new_from_mem} creates a new
+@code{GpgmeData} object and fills it with @var{size} bytes starting
+from @var{buffer}.
+
+If @var{copy} is not zero, a private copy of the data is made. If
+@var{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 @code{GPGME_No_Error} if the data object was
+successfully created, @code{GPGME_Invalid_Value} if @var{dh} or
+@var{buffer} is not a valid pointer, and @code{GPGME_Out_Of_Core} if
+not enough memory is available.
+@end deftypefun
+
+@deftypefun GpgmeError gpgme_data_new_from_file (@w{GpgmeData *@var{dh}}, @w{const char *@var{filename}}, @w{int @var{copy}})
+The function @code{gpgme_data_new_from_file} creates a new
+@code{GpgmeData} object and fills it with the content of the file
+@var{filename}.
+
+If @var{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 @var{copy} might
+cause all reads to be delayed until the data is needed, but this is
+not yet implemented.
+
+The function returns @code{GPGME_No_Error} if the data object was
+successfully created, @code{GPGME_Invalid_Value} if @var{dh} or
+@var{filename} is not a valid pointer, @code{GPGME_File_Error} if an
+I/O operation fails, @code{GPGME_Not_Implemented} if @var{code} is
+zero, and @code{GPGME_Out_Of_Core} if not enough memory is available.
+@end deftypefun
+
+@deftypefun GpgmeError gpgme_data_new_from_filepart (@w{GpgmeData *@var{dh}}, @w{const char *@var{filename}}, @w{FILE *@var{fp}}, @w{off_t @var{offset}}, @w{off_t @var{length}})
+The function @code{gpgme_data_new_from_filepart} creates a new
+@code{GpgmeData} object and fills it with a part of the file specified
+by @var{filename} or @var{fp}.
+
+Exactly one of @var{filename} and @var{fp} must be non-zero, the other
+must be zero. The argument that is not zero specifies the file from
+which @var{length} bytes are read into the data object, starting from
+@var{offset}.
+
+The function returns @code{GPGME_No_Error} if the data object was
+successfully created, @code{GPGME_Invalid_Value} if @var{dh} and
+exactly one of @var{filename} and @var{fp} is not a valid pointer,
+@code{GPGME_File_Error} if an I/O operation fails, and
+@code{GPGME_Out_Of_Core} if not enough memory is available.
+@end deftypefun
+
+
+@deftypefun GpgmeError gpgme_data_new_with_read_cb (@w{GpgmeData *@var{dh}}, @w{int (*@var{readfunc})} (@w{void *@var{hook}}, @w{char *@var{buffer}}, @w{size_t @var{count}}, @w{size_t *@var{nread}}), @w{void *@var{hook_value}})
+The function @code{gpgme_data_new_with_read_cb} creates a new
+@code{GpgmeData} object and uses the callback function @var{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
+@acronym{GPGME} provides. However, it can not be used to write data.
+
+The callback function receives @var{hook_value} as its first argument
+whenever it is invoked. It should return up to @var{count} bytes in
+@var{buffer}, and return the number of bytes actually read in
+@var{nread}. It may return @code{0} in @var{nread} if no data is
+currently available. To indicate @code{EOF} the function should
+return with an error code of @code{-1} and set @var{nread} to
+@code{0}. The callback function may support to reset its internal
+read pointer if it is invoked with @var{buffer} and @var{nread} being
+@code{NULL} and @var{count} being @code{0}.
+
+The function returns @code{GPGME_No_Error} if the data object was
+successfully created, @code{GPGME_Invalid_Value} if @var{dh} or
+@var{readfunc} is not a valid pointer, and @code{GPGME_Out_Of_Core} if
+not enough memory is available.
+@end deftypefun
+
+
+@node Destroying data buffers
+@section Destroying data buffers
+
+@deftypefun void gpgme_data_release (@w{GpgmeData @var{dh}})
+The function @code{gpgme_data_release} destroys the data object with
+the handle @var{dh}. It releases all associated resources that were
+not provided by the user in the first place.
+@end deftypefun
+
+@deftypefun {char *} gpgme_data_release_and_get_mem (@w{GpgmeData @var{dh}}, @w{size_t *@var{length}})
+The function @code{gpgme_data_release_and_get_mem} is like
+@code{gpgme_data_release}, except that it returns the data buffer and
+its length that was provided by the object.
+
+The user has to release the buffer with @code{free}. In case the user
+provided the data buffer in non-copy mode, a copy will be made for
+this purpose.
+
+In case an error returns, or there is no suitable data buffer that can
+be returned to the user, the function will return @code{NULL}.
+@end deftypefun
+
+
+@node Manipulating data buffers
+@section Manipulating data buffers
+
+@deftypefun GpgmeError gpgme_data_read (@w{GpgmeData @var{dh}}, @w{char *@var{buffer}}, @w{size_t @var{length}}, @w{size_t *@var{nread}})
+The function @code{gpgme_data_read} reads up to @var{length} bytes
+from the data object with the handle @var{dh} into the space starting
+at @var{buffer}. The actual amount read is returned in @var{nread}.
+
+If @var{buffer} is @code{NULL}, the function returns the amount of
+bytes available in @var{nread} without changing the read pointer.
+This is not supported by all types of data objects. If this function
+is not supported, @code{GPGME_Invalid_Type} is returned.
+
+If the end of the data object is reached, the function returns
+@code{GPGME_EOF} and sets @var{nread} to zero.
+
+In all other cases, the function returns @code{GPGME_No_Error} if the
+operation was successfully performed and @code{GPGME_Invalid_Value} if
+@var{dh} is not a valid pointer.
+@end deftypefun
+
+@deftypefun GpgmeError gpgme_data_rewind (@w{GpgmeData @var{dh}})
+The function @code{gpgme_data_rewind} resets the read pointer of the
+data object with the handle @var{dh}, so that a subsequent
+@code{gpgme_data_read} operation starts at the beginning of the data.
+
+The function returns @code{GPGME_No_Error} if the operation was
+successfully performed, @code{GPGME_Not_Implemented} if the operation
+is not supported (for example, by a read callback function supplied by
+the user) and @code{GPGME_Invalid_Value} if @var{dh} is not a valid
+pointer.
+@end deftypefun
+
+@deftypefun GpgmeError gpgme_data_write (@w{GpgmeData @var{dh}}, @w{const char *@var{buffer}}, @w{size_t @var{length}})
+The function @code{gpgme_data_write} writes @var{length} bytes
+starting from @var{buffer} into the data object with the handle
+@var{dh} at the current write position.
+
+The function returns @code{GPGME_No_Error} if the operation was
+successfully performed, @code{GPGME_Invalid_Value} if @var{dh} or
+@var{buffer} is not a valid pointer, @code{GPGME_Invalid_Type} or
+@code{GPGME_Invalid_Mode} if the data object type does not support
+writing, and @code{GPGME_Out_Of_Core} if not enough memory is
+available.
+@end deftypefun
+
+@deftp {Data type} {enum GpgmeDataType}
+The @code{GpgmeDataType} type specifies the type of a @code{GpgmeData} object.
+The following data types are available:
+
+@table @code
+@item GPGME_DATA_TYPE_NONE
+This specifies that the type is not yet determined.
+
+@item GPGME_DATA_TYPE_MEM
+This specifies that the data is stored in memory.
+
+@item GPGME_DATA_TYPE_FD
+This type is not implemented.
+
+@item GPGME_DATA_TYPE_FILE
+This type is not implemented.
+
+@item GPGME_DATA_TYPE_CB
+This type specifies that the data is provided by a callback function
+implemented by the user.
+@end table
+@end deftp
+
+@deftypefun GpgmeDataType gpgme_data_get_type (@w{GpgmeData @var{dh}})
+The function @code{gpgme_data_get_type} returns the type of the data
+object with the handle @var{dh}. If @var{dh} is not a valid pointer,
+@code{GPGME_DATA_TYPE_NONE} is returned.
+@end deftypefun
+
+
+@node Contexts
+@chapter Contexts
+
+All cryptograhic operations in @acronym{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.
+
+@deftp {Data type} {GpgmeCtx}
+The @code{GpgmeCtx} type is a handle for a @acronym{GPGME} context,
+which is used to hold the configuration, status and result of
+cryptographic operations.
+@end deftp
+
+@menu
+* Creating contexts:: Creating new @acronym{GPGME} contexts.
+* Destroying contexts:: Releasing @acronym{GPGME} contexts.
+* Context attributes:: Setting properties of a context.
+* Key Management:: Managing keys with @acronym{GPGME}.
+* Trust Item Management:: Managing trust items with @acronym{GPGME}.
+* Crypto Operations:: Using a context for cryptography.
+@end menu
+
+
+@node Creating contexts
+@section Creating contexts
+
+@deftypefun GpgmeError gpgme_new (@w{GpgmeCtx *@var{ctx}})
+The function @code{gpgme_data_new} creates a new @code{GpgmeCtx}
+object and returns a handle for it in @var{ctx}.
+
+The function returns @code{GPGME_No_Error} if the context was
+successfully created, @code{GPGME_Invalid_Value} if @var{ctx} is not a
+valid pointer, and @code{GPGME_Out_Of_Core} if not enough memory is
+available.
+@end deftypefun
+
+
+
+@node Destroying contexts
+@section Destroying contexts
+
+@deftypefun void gpgme_release (@w{GpgmeCtx @var{ctx}})
+The function @code{gpgme_release} destroys the context with the handle
+@var{ctx} and releases all associated resources.
+@end deftypefun
+
+
+@node Context attributes
+@section Context attributes
+
+@menu
+* Protocol selection:: Selecting the protocol used by a context.
+* @acronym{ASCII} armor:: Requesting @acronym{ASCII} armored output.
+* Text mode:: Choosing canonical text mode.
+* Key listing mode:: Selecting key listing mode.
+* Passphrase callback:: Getting the passphrase from the user.
+* Progress meter callback:: Being informed about the progress.
+@end menu
+
+
+@node Protocol selection
+@subsection Protocol selection
+
+@deftypefun GpgmeError gpgme_set_protocol (@w{GpgmeCtx @var{ctx}}, @w{GpgmeProtocol @var{proto}})
+The function @code{gpgme_set_protocol} sets the protocol used within
+the context @var{ctx} to @var{proto}. All crypto operations will be
+performed by the crypto engine configured for that protocol.
+@xref{Protocols and Engines}.
+
+Setting the protocol with @code{gpgme_set_protocol} does not check if
+the crypto engine for that protocol is available and installed
+correctly. @xref{Engine version check}.
+
+The function returns @code{GPGME_No_Error} if the protocol could be
+set successfully, and @code{GPGME_Invalid_Value} if @var{protocol} is
+not a valid protocol.
+@end deftypefun
+
+
+@node @acronym{ASCII} armor
+@subsection @acronym{ASCII} armor
+
+@deftypefun void gpgme_set_armor (@w{GpgmeCtx @var{ctx}}, @w{int @var{yes}})
+The function @code{gpgme_set_armor} specifies if the output should be
+@acronym{ASCII} armoured. By default, output is not @acronym{ASCII}
+armoured.
+
+@acronym{ASCII} armoured output is disabled if @var{yes} is zero, and
+enabled otherwise.
+@end deftypefun
+
+@deftypefun int gpgme_get_armor (@w{GpgmeCtx @var{ctx}})
+The function @code{gpgme_get_armor} returns 1 if the output is
+@acronym{ASCII} armored, and @code{0} if it is not, or if @var{ctx} is
+not a valid pointer.
+@end deftypefun
+
+
+@node Text mode
+@subsection Text mode
+
+@deftypefun void gpgme_set_textmode (@w{GpgmeCtx @var{ctx}}, @w{int @var{yes}})
+The function @code{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.
+
+Canonical text mode is disabled if @var{yes} is zero, and enabled
+otherwise.
+@end deftypefun
+
+@deftypefun int gpgme_get_textmode (@w{GpgmeCtx @var{ctx}})
+The function @code{gpgme_get_textmode} returns 1 if canonical text
+mode is enabled, and @code{0} if it is not, or if @var{ctx} is not a
+valid pointer.
+@end deftypefun
+
+
+@node Key listing mode
+@subsection Key listing mode
+
+@deftypefun void gpgme_set_keylist_mode (@w{GpgmeCtx @var{ctx}}, @w{int @var{mode}})
+The function @code{gpgme_set_keylist_mode} changes the default
+behaviour of the key listing functions. Defined values for @var{mode}
+are:
+
+@table @code
+@item 0
+Normal listing.
+@item 1
+Fast listing without information about the key validity.
+@end table
+@end deftypefun
+
+
+@node Passphrase callback
+@subsection Passphrase callback
+
+@deftp {Data type} {const char *(*GpgmePassphraseCb)(void *@var{hook}, const char *@var{desc}, void *@var{r_hd})}
+The @code{GpgmePasshraseCb} type is the type of functions usable as
+passphrase callback function.
+
+The string @var{desc} contains a test usable to be displayed to the
+user of the application. The function should return a passphrase for
+the context when invoked with @var{desc} not being @code{NULL}.
+
+The user may store information about the resources associated with the
+returned passphrase in @var{*r_hd}. When the passphrase is no longer
+needed by @acronym{GPGME}, the passphrase callback function will be
+called with @var{desc} being @var{NULL}, and @var{r_hd} being the same
+as at the first invocation.
+@end deftp
+
+@deftypefun void gpgme_set_passphrase_cb (@w{GpgmeCtx @var{ctx}}, @w{GpgmePassphraseCb @var{passfunc}}, @w{void *@var{hook_value}})
+The function @code{gpgme_set_passphrase_cb} sets the function that is
+used when a passphrase needs to be provided by the user to
+@var{passfunc}. The function @var{passfunc} needs to implemented by
+the user, and whenever it is called, it is called with its first
+argument being @var{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 @code{gpgme_set_passphrase_cb} with @var{passfunc} being
+@code{NULL}.
+@end deftypefun
+
+
+@node Progress meter callback
+@subsection Progress meter callback
+
+@deftp {Data type} {const char *(*GpgmeProgressCb)(void *@var{hook}, const char *@var{what}, int @var{type}, int @var{current}, int @var{total})}
+The @code{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 @file{doc/DETAILS} in the
+section PROGRESS.
+@end deftp
+
+@deftypefun void gpgme_set_progress_cb (@w{GpgmeCtx @var{ctx}}, @w{GpgmeProgressCb @var{progfunc}}, @w{void *@var{hook_value}})
+The function @code{gpgme_set_progress_cb} sets the function that is
+used when progress information about a cryptographic operation is
+available. The function @var{progfunc} needs to implemented by the
+user, and whenever it is called, it is called with its first argument
+being @var{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 @code{gpgme_set_progress_cb} with @var{progfunc} being
+@code{NULL}.
+@end deftypefun
+
+
+@node Key Management
+@section 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.
+
+@deftp {Data type} GpgmeKey
+The @code{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.
+@end deftp
+
+@menu
+* Listing keys:: Browsing the list of available keys.
+* Information about keys:: Requesting detailed information about keys.
+* Manipulating keys:: Operations on keys.
+@end menu
+
+
+@node Listing keys
+@subsection Listing keys
+
+@deftypefun GpgmeError gpgme_op_keylist_start (@w{GpgmeCtx @var{ctx}}, @w{const char *@var{pattern}}, @w{int @var{secret_only}})
+The function @code{gpgme_op_keylist_start} initiates a key listing
+operation inside the context @var{ctx}. It sets everything up so that
+subsequent invocations of @code{gpgme_op_keylist_next} return the keys
+in the list.
+
+If @var{pattern} is @code{NULL}, all available keys are returned.
+Otherwise, @var{pattern} contains an engine specific expression that
+is used to limit the list to all keys matching the pattern.
+
+If @var{secret_only} is not @code{0}, the list is restricted to secret
+keys only.
+
+The context will be busy until either all keys are received (and
+@code{gpgme_op_keylist_next} returns @code{GPGME_EOF}), or
+@code{gpgme_op_keylist_end} is called to finish the operation.
+
+The function returns @code{GPGME_Invalid_Value} if @var{ctx} is not a
+valid pointer, and passes through any errors that are reported by the
+crypto engine support routines.
+@end deftypefun
+
+@deftypefun GpgmeError gpgme_op_keylist_next (@w{GpgmeCtx @var{ctx}}, @w{GpgmeKey *@var{r_key}})
+The function @code{gpgme_op_keylist_next} returns the next key in the
+list created by a previous @code{gpgme_op_keylist_start} operation in
+the context @var{ctx}. The key will have one reference for the user.
+@xref{Manipulating keys}.
+
+This is the only way to get at @code{GpgmeKey} objects in
+@acronym{GPGME}.
+
+If the last key in the list has already been returned,
+@code{gpgme_op_keylist_next} returns @code{GPGME_EOF}.
+
+The function returns @code{GPGME_Invalid_Value} if @var{ctx} or
+@var{r_key} is not a valid pointer, @code{GPGME_No_Request} if there
+is no pending operation, @code{GPGME_Out_Of_Core} if there is not
+enough memory for the operation.
+@end deftypefun
+
+@deftypefun GpgmeError gpgme_op_keylist_end (@w{GpgmeCtx @var{ctx}})
+The function @code{gpgme_op_keylist_next} ends a pending key list
+operation in the context @var{ctx}.
+
+The function returns @code{GPGME_Invalid_Value} if @var{ctx} is not a
+valid pointer, @code{GPGME_No_Request} if there is no pending
+operation, @code{GPGME_Out_Of_Core} if at some time during the
+operation there was not enough memory available.
+@end deftypefun
+
+
+@node Information about keys
+@subsection Information about keys
+
+@deftypefun {char *} gpgme_key_get_as_xml (@w{GpgmeKey @var{key}})
+The function @code{gpgme_key_get_as_xml} returns a string in
+@acronym{XML} format describing the key @var{key}. The user has to
+release the string with @code{free}.
+
+The function returns @code{NULL} if @var{key} is not a valid pointer,
+or there is not enough memory available.
+@end deftypefun
+
+@deftp {Data type} GpgmeAttr
+The @code{GpgmeAttr} type is used to specify a key or trust item
+attribute. The following attributes are defined:
+
+@table @code
+@item 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.
+
+@item GPGME_ATTR_FPR
+This is the fingerprint of a sub key. It is representable as a
+string.
+
+@item 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 @code{enum gcry_pk_algos} values in the gcrypt library.
+
+@item GPGME_ATTR_LEN
+This is the key length of a sub key. It is representable as a
+number.
+
+@item GPGME_ATTR_CREATED
+This is the timestamp at creation time of a sub key. It is
+representable as a number.
+
+@item GPGME_ATTR_EXPIRE
+XXX FIXME
+
+@item GPGME_ATTR_OTRUST
+XXX FIXME (also for trust items)
+
+@item GPGME_ATTR_USERID
+This is a user ID. There can be more than one user IDs in a
+@var{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.
+
+@item GPGME_ATTR_NAME
+This is the name belonging to a user ID. It is representable as a string.
+
+@item GPGME_ATTR_EMAIL
+This is the email address belonging to a user ID. It is representable
+as a string.
+
+@item GPGME_ATTR_COMMENT
+This is the comment belonging to a user ID. It is representable as a
+string.
+
+@item 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.
+
+@item GPGME_ATTR_UID_REVOKED
+This specifies if a user ID is revoked. It is representable as a
+number, and is @code{1} if the user ID is revoked, and @code{0}
+otherwise.
+
+@item GPGME_ATTR_UID_INVALID
+This specifies if a user ID is invalid. It is representable as a
+number, and is @code{1} if the user ID is invalid, and @code{0}
+otherwise.
+
+@item GPGME_ATTR_LEVEL
+This is the trust level of a trust item.
+
+@item GPGME_ATTR_TYPE
+This is the type of a trust item.
+
+@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 @code{1}, otherwise it is NULL or @code{0}.
+
+@item GPGME_ATTR_KEY_REVOKED
+This specifies if a sub key is revoked. It is representable as a
+number, and is @code{1} if the key is revoked, and @code{0} otherwise.
+
+@item GPGME_ATTR_KEY_INVALID
+This specifies if a sub key is invalid. It is representable as a
+number, and is @code{1} if the key is invalid, and @code{0} otherwise.
+
+@item GPGME_ATTR_KEY_EXPIRED
+This specifies if a sub key is expired. It is representable as a
+number, and is @code{1} if the key is expired, and @code{0} otherwise.
+
+@item GPGME_ATTR_KEY_DISABLED
+This specifies if a sub key is disabled. It is representable as a
+number, and is @code{1} if the key is disabled, and @code{0} otherwise.
+
+@item 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.
+
+@item GPGME_ATTR_CAN_ENCRYPT
+This specifies if a sub key can be used for encryption. It is
+representable as a number, and is @code{1} if the sub key can be used
+for encryption, and @code{0} otherwise.
+
+@item GPGME_ATTR_CAN_SIGN
+This specifies if a sub key can be used for signatures. It is
+representable as a number, and is @code{1} if the sub key can be used
+for signatures, and @code{0} otherwise.
+
+@item GPGME_ATTR_CAN_CERTIFY
+This specifies if a sub key can be used for certifications. It is
+representable as a number, and is @code{1} if the sub key can be used
+for certifications, and @code{0} otherwise.
+@end table
+@end deftp
+
+@deftp {Data type} GpgmeValidity
+The @code{GpgmeValidity} type is used to specify the validity of a user ID
+in a key. The following validities are defined:
+
+@table @code
+@item GPGME_VALIDITY_UNKNOWN
+The user ID is of unknown validity. The string representation of this
+validity is ``?''.
+
+@item GPGME_VALIDITY_UNDEFINED
+The validity of the user ID is undefined. The string representation of this
+validity is ``q''.
+
+@item GPGME_VALIDITY_NEVER
+The user ID is never valid. The string representation of this
+validity is ``n''.
+
+@item GPGME_VALIDITY_MARGINAL
+The user ID is marginally valid. The string representation of this
+validity is ``m''.
+
+@item GPGME_VALIDITY_FULL
+The user ID is fully valid. The string representation of this
+validity is ``f''.
+
+@item GPGME_VALIDITY_ULTIMATE
+The user ID is ultimately valid. The string representation of this
+validity is ``u''.
+@end table
+@end deftp
+
+@deftypefun {const char *} gpgme_key_get_string_attr (@w{GpgmeKey @var{key}}, @w{GpgmeAttr @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}})
+The function @code{gpgme_key_get_string_attr} returns the value of the
+string-representable attribute @var{what} of key @var{key}. If the
+attribute occurs more than once in the key, the index is specified by
+@var{idx}. This applies to attributes of sub keys and user IDs. The
+argument @var{reserved} is reserved for later use and should be
+@code{NULL}.
+
+The string returned is only valid as long as the key is valid.
+
+The function returns @code{0} if an attribute can't be returned as a
+string, @var{key} is not a valid pointer, @var{idx} out of range,
+or @var{reserved} not @code{NULL}.
+@end deftypefun
+
+@deftypefun {unsigned long} gpgme_key_get_ulong_attr (@w{GpgmeKey @var{key}}, @w{GpgmeAttr @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}})
+The function @code{gpgme_key_get_ulong_attr} returns the value of the
+number-representable attribute @var{what} of key @var{key}. If the
+attribute occurs more than once in the key, the index is specified by
+@var{idx}. This applies to attributes of sub keys and user IDs. The
+argument @var{reserved} is reserved for later use and should be
+@code{NULL}.
+
+The function returns @code{0} if the attribute can't be returned as a
+number, @var{key} is not a valid pointer, @var{idx} out of range,
+or @var{reserved} not @code{NULL}.
+@end deftypefun
+
+
+@node Manipulating keys
+@subsection Manipulating keys
+
+@deftypefun void gpgme_key_ref (@w{GpgmeKey @var{key}})
+The function @code{gpgme_key_ref} acquires an additional reference for
+the key @var{key}.
+@end deftypefun
+
+@deftypefun void gpgme_key_unref (@w{GpgmeKey @var{key}})
+@deftypefunx void gpgme_key_release (@w{GpgmeKey @var{key}})
+The function @code{gpgme_key_ref} releases a reference for the key
+@var{key}. If this was the last reference, the key will be destroyed
+and all resources associated to it will be released.
+
+The function @code{gpgme_key_release} is an alias for
+@code{gpgme_key_unref}.
+@end deftypefun
+
+
+@node Trust Item Management
+@section Trust Item Management
+
+@strong{Caution:} The trust items interface is experimental.
+
+@deftp {Data type} GpgmeTrustItem
+The @code{GpgmeTrustItem} type is a handle for a trust item.
+@end deftp
+
+@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.
+@end menu
+
+
+@node Listing trust items
+@subsection Listing trust items
+
+@deftypefun GpgmeError gpgme_op_trustlist_start (@w{GpgmeCtx @var{ctx}}, @w{const char *@var{pattern}}, @w{int @var{max_level}})
+The function @code{gpgme_op_trustlist_start} initiates a trust item
+listing operation inside the context @var{ctx}. It sets everything up
+so that subsequent invocations of @code{gpgme_op_trustlist_next} return
+the trsut items in the list.
+
+The string @var{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 @var{max_level} is currently ignored.
+
+The context will be busy until either all trust items are received
+(and @code{gpgme_op_trustlist_next} returns @code{GPGME_EOF}), or
+@code{gpgme_op_trustlist_end} is called to finish the operation.
+
+The function returns @code{GPGME_Invalid_Value} if @var{ctx} is not a
+valid pointer, and passes through any errors that are reported by the
+crypto engine support routines.
+@end deftypefun
+
+@deftypefun GpgmeError gpgme_op_trustlist_next (@w{GpgmeCtx @var{ctx}}, @w{GpgmeTrustItem *@var{r_item}})
+The function @code{gpgme_op_trustlist_next} returns the next trust
+item in the list created by a previous @code{gpgme_op_trustlist_start}
+operation in the context @var{ctx}. The trust item can be destroyed
+with @code{gpgme_trust_item_release}. @xref{Manipulating trust items}.
+
+This is the only way to get at @code{GpgmeTrustItem} objects in
+@acronym{GPGME}.
+
+If the last trust item in the list has already been returned,
+@code{gpgme_op_trustlist_next} returns @code{GPGME_EOF}.
+
+The function returns @code{GPGME_Invalid_Value} if @var{ctx} or
+@var{r_item} is not a valid pointer, @code{GPGME_No_Request} if there
+is no pending operation, @code{GPGME_Out_Of_Core} if there is not
+enough memory for the operation.
+@end deftypefun
+
+@deftypefun GpgmeError gpgme_op_trustlist_end (@w{GpgmeCtx @var{ctx}})
+The function @code{gpgme_op_trustlist_next} ends a pending key list
+operation in the context @var{ctx}.
+
+The function returns @code{GPGME_Invalid_Value} if @var{ctx} is not a
+valid pointer, @code{GPGME_No_Request} if there is no pending
+operation, @code{GPGME_Out_Of_Core} if at some time during the
+operation there was not enough memory available.
+@end deftypefun
+
+
+@node Information about trust items
+@subsection 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. @xref{Information about keys}.
+
+@deftypefun {const char *} gpgme_trust_item_get_string_attr (@w{GpgmeTrustItem @var{item}}, @w{GpgmeAttr @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}})
+The function @code{gpgme_trust_item_get_string_attr} returns the value
+of the string-representable attribute @var{what} of trust item
+@var{item}. If the attribute occurs more than once in the trust
+items, the index is specified by @var{idx}. However, currently no
+such attributes exists, so @var{idx} should be @code{0}. The argument
+@var{reserved} is reserved for later use and should be @code{NULL}.
+
+The string returned is only valid as long as the key is valid.
+
+The function returns @code{0} if an attribute can't be returned as a
+string, @var{key} is not a valid pointer, @var{idx} out of range,
+or @var{reserved} not @code{NULL}.
+@end deftypefun
+
+@deftypefun int gpgme_trust_item_get_int_attr (@w{GpgmeTrustItem @var{item}}, @w{GpgmeAttr @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}})
+The function @code{gpgme_trust_item_get_int_attr} returns the value of
+the number-representable attribute @var{what} of trust item
+@var{item}. If the attribute occurs more than once in the trust item,
+the index is specified by @var{idx}. However, currently no such
+attribute exists, so @var{idx} should be @code{0}. The argument
+@var{reserved} is reserved for later use and should be @code{NULL}.
+
+The function returns @code{0} if the attribute can't be returned as a
+number, @var{key} is not a valid pointer, @var{idx} out of range,
+or @var{reserved} not @code{NULL}.
+@end deftypefun
+
+
+@node Manipulating trust items
+@subsection Manipulating trust items
+
+@deftypefun void gpgme_trust_item_release (@w{GpgmeTrustItem @var{item}})
+The function @code{gpgme_trust_item_release} destroys a
+@code{GpgmeTrustItem} object and releases all associated resources.
+@end deftypefun
+
+@node Crypto Operations
+@section 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.
+@end menu
+
+
+@node Decrypt
+@subsection Decrypt
+
+@deftypefun GpgmeError gpgme_op_decrypt (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{cipher}}, @w{GpgmeData @var{plain}})
+The function @code{gpgme_op_decrypt} decrypts the ciphertext in the
+data object @var{cipher} and stores it into the data object
+@var{plain}.
+
+The function returns @code{GPGME_No_Error} if the ciphertext could be
+decrypted successfully, @code{GPGME_Invalid_Value} if @var{ctx},
+@var{cipher} or @var{plain} is not a valid pointer,
+@code{GPGME_No_Data} if @var{cipher} does not contain any data to
+decrypt, @code{GPGME_Decryption_Failed} if @var{cipher} is not a valid
+cipher text, @code{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.
+@end deftypefun
+
+@c @deftypefun GpgmeError gpgme_op_decrypt_start (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{cipher}}, @w{GpgmeData @var{plain}})
+@c The function @code{gpgme_op_decrypt_start} initiates a
+@c @code{gpgme_op_decrypt} operation. It can be completed by calling
+@c @code{gpgme_wait} on the context.
+
+@c The function returns @code{GPGME_No_Error} if the operation could be
+@c started, @code{GPGME_Invalid_Value} if @var{cipher} or @var{plain} is
+@c not a valid pointer, and passes through any errors that are reported
+@c by the crypto engine support routines.
+@c @end deftypefun
+
+
+@node Verify
+@subsection Verify
+
+@deftp {Data type} {enum GpgmeSigStat}
+The @code{GpgmeSigStat} type holds the result of a signature check, or
+the combined result of all signatures. The following results are
+possible:
+
+@table @code
+@item GPGME_SIG_STAT_NONE
+This status should not occur in normal operation.
+
+@item GPGME_SIG_STAT_GOOD
+This status indicates that the signature is valid. For the combined
+result this status means that all signatures are valid.
+
+@item GPGME_SIG_STAT_BAD
+This status indicates that the signature is invalid. For the combined
+result this status means that all signatures are invalid.
+
+@item 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.
+
+@item GPGME_SIG_STAT_NOSIG
+This status indicates that the signature data provided was not a real
+signature.
+
+@item GPGME_SIG_STAT_ERROR
+This status indicates that there was some other error which prevented
+the signature verification.
+
+@item 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
+@code{gpgme_get_sig_status}.
+@end table
+@end deftp
+
+@deftypefun GpgmeError gpgme_op_verify (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{sig}}, @w{GpgmeData @var{plain}}, @w{GpgmeSigStat *@var{r_stat}})
+The function @code{gpgme_op_verify} verifies that the detached
+signature in the data object @var{sig} is a valid signature for the
+plaintext in the data object @var{plain}.
+
+The combined status of all signatures is returned in @var{r_stat}.
+The results of the individual signature verifications can be retrieved
+with @code{gpgme_get_sig_status} and @code{gpgme_get_sig_key}.
+
+The function returns @code{GPGME_No_Error} if the operation could be
+completed successfully, @code{GPGME_Invalid_Value} if @var{ctx},
+@var{sig}, @var{plain} or @var{r_stat} is not a valid pointer,
+@code{GPGME_No_Data} if @var{sig} or @var{plain} does not contain any
+data to verify, and passes through any errors that are reported by the
+crypto engine support routines.
+@end deftypefun
+
+@c GpgmeError gpgme_op_verify_start (GpgmeCtx ctx, GpgmeData sig, GpgmeData plain);
+
+@deftypefun {const char *} gpgme_get_sig_status (@w{GpgmeCtx @var{ctx}}, @w{int @var{idx}}, @w{GpgmeSigStat *@var{r_stat}}, @w{time_t *@var{r_created}})
+The function @code{gpgme_get_sig_status} receives information about a
+signature after the @code{gpgme_op_verify} or
+@code{gpgme_op_verify_decrypt} operation. A single detached signature
+can contain signatures by more than one key. The @var{idx} specifies
+which signature's information should be retrieved, starting from
+@var{0}.
+
+The status of the signature will be returned in @var{r_stat} if it is
+not @code{NULL}. The creation time stamp of the signature will be
+returned in @var{r_created} if it is not @var{NULL}.
+
+The function returns a statically allocated string that contains the
+fingerprint of the key which signed the plaintext, or @code{NULL} if
+@var{ctx} is not a valid pointer, the operation is still pending, or
+no verification could be performed.
+@end deftypefun
+
+@deftypefun {const char *} gpgme_get_sig_key (@w{GpgmeCtx @var{ctx}}, @w{int @var{idx}}, @w{GpgmeSigKey *@var{r_stat}})
+The function @code{gpgme_get_sig_status} receives a @code{GpgmeKey}
+object for the key which was used to verify the signature after the
+@code{gpgme_op_verify} or @code{gpgme_op_verify_decrypt} operation. A
+single detached signature can contain signatures by more than one key.
+The @var{idx} specifies which signature's information should be
+retrieved, starting from @var{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 @code{gpgme_get_sig_status}.
+
+The function returns @code{GPGME_No_Error} if the key could be
+returned, @code{GPGME_Invalid_Value} if @var{r_key} is not a valid
+pointer, @code{GPGME_Invalid_Key} if the fingerprint is not valid,
+@code{GPGME_EOF} if @var{idx} is too large, or some other error value
+if a problem occured requesting the key.
+@end deftypefun
+
+
+@node Decrypt and verify
+@subsection Decrypt and verify
+
+@deftypefun GpgmeError gpgme_op_decrypt_verify (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{cipher}}, @w{GpgmeData @var{plain}}, @w{GpgmeSigStat *@var{r_stat}})
+The function @code{gpgme_op_decrypt_verify} decrypts the ciphertext in
+the data object @var{cipher} and stores it into the data object
+@var{plain}. If @var{cipher} contains signatures, they will be
+verified and their combined status will be returned in @var{r_stat}.
+
+After the operation completed, @code{gpgme_op_get_sig_status} and
+@code{gpgme_op_get_sig_key} can be used to retrieve more information
+about the signatures.
+
+The function returns @code{GPGME_No_Error} if the ciphertext could be
+decrypted successfully, @code{GPGME_Invalid_Value} if @var{ctx},
+@var{cipher}, @var{plain} or @var{r_stat} is not a valid pointer,
+@code{GPGME_No_Data} if @var{cipher} does not contain any data to
+decrypt, @code{GPGME_Decryption_Failed} if @var{cipher} is not a valid
+cipher text, @code{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.
+@end deftypefun
+
+@c GpgmeError gpgme_op_decrypt_verify (GpgmeCtx c, GpgmeData in, GpgmeData out, GpgmeSigStat *r_status);
+
+
+@node Sign
+@subsection 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.
+@end menu
+
+
+@node Selecting signers
+@subsubsection Selecting signers
+
+@deftypefun void gpgme_signers_clear (@w{GpgmeCtx @var{ctx}})
+The function @code{gpgme_signers_clear} releases a reference for each
+key on the signers list and removes the list of signers from the
+context @var{ctx}.
+
+Every context starts with an empty list.
+@end deftypefun
+
+
+@deftypefun GpgmeError gpgme_signers_add (@w{GpgmeCtx @var{ctx}}, @w{const GpgmeKey @var{key}})
+The function @code{gpgme_signers_add} adds the key @var{key} to the
+list of signers in the context @var{ctx}.
+
+One reference for the key is consumed.
+@end deftypefun
+
+@deftypefun GpgmeKey gpgme_signers_enum (@w{const GpgmeCtx @var{ctx}}, @w{int @var{seq}})
+The function @code{gpgme_signers_enum} returns the @var{seq}th key in
+the list of signers in the context @var{ctx}. An additional reference
+is acquired for the user.
+
+If @var{seq} is out of range, @code{NULL} is returned.
+@end deftypefun
+
+
+@node Creating a signature
+@subsubsection Creating a signature
+
+@deftp {Data type} {enum GpgmeSigMode}
+The @code{GpgmeSigMode} type is used to specify the desired type of a
+signature. The following modes are available:
+
+@table @code
+@item GPGME_SIG_MODE_NORMAL
+A normal signature is made, the output includes the plaintext and the
+signature.
+
+@item GPGME_SIG_MODE_DETACH
+A detached signature is made.
+
+@item GPGME_SIG_MODE_CLEAR
+A clear text signature is made. The @acronym{ASCII} armor and text
+mode settings of the context are ignored.
+@end table
+@end deftp
+
+@deftypefun GpgmeError gpgme_op_sign (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{plain}}, @w{GpgmeData @var{sig}}, @w{GpgmeSigMode @var{mode}})
+The function @code{gpgme_op_sign} creates a signature for the text in
+the data object @var{plain} and returns it in the data object
+@var{sig}. The type of the signature created is determined by the
+@acronym{ASCII} and text mode attributes set for the context @var{ctx}
+and the requested signature mode @var{mode}.
+
+The function returns @code{GPGME_No_Error} if the signature could be
+created successfully, @code{GPGME_Invalid_Value} if @var{ctx},
+@var{plain} or @var{sig} is not a valid pointer, @code{GPGME_No_Data}
+if the signature could not be created, @code{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.
+@end deftypefun
+
+
+@node Encrypt
+@subsection 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.
+@end menu
+
+
+@node Selecting recipients
+@subsubsection Selecting recipients
+
+@deftp {Data type} GpgmeRecipients
+The @code{GpgmeRecipients} type is a handle for a set of recipients
+that can be used in an encryption process.
+@end deftp
+
+@deftypefun GpgmeError gpgme_recipients_new (@w{GpgmeRecipients *@var{r_rset}})
+The function @code{gpgme_recipients_new} creates a new, empty set of
+recipients and returns a handle for it in @var{r_rset}.
+
+The function returns @code{GPGME_No_Error} if the recipient set could
+be created successfully, and @code{GPGME_Out_Of_Core} if not enough
+memory was available.
+@end deftypefun
+
+@deftypefun void gpgme_recipients_release (@w{GpgmeRecipients @var{rset}})
+The function @code{gpgme_recipients_release} destroys the set of
+recipients @var{rset} and releases all associated resources.
+@end deftypefun
+
+@deftypefun GpgmeError gpgme_recipients_add_name (@w{GpgmeRecipients @var{rset}}, @w{const char *@var{name}})
+The function @code{gpgme_recipients_add_name} adds the recipient
+@var{name} to the set of recipients @var{rset}. This is equivalent to
+@code{gpgme_recipients_add_name_with_validity} with a validity of
+@code{GPGME_VALIDITY_UNKNOWN}.
+
+The function returns @code{GPGME_No_Error} if the recipient was added
+successfully, @code{GPGME_Invalid_Value} if @var{rset} or @var{name}
+is not a valid pointer, and @code{GPGME_Out_Of_Core} if not enough
+memory is available.
+@end deftypefun
+
+@deftypefun GpgmeError gpgme_recipients_add_name_with_validity (@w{GpgmeRecipients @var{rset}}, @w{const char *@var{name}}, @w{GpgmeValidity @var{val}})
+The function @code{gpgme_recipients_add_name_with_validity} adds the
+recipient @var{name} with the validity @var{val} to the set of
+recipients @var{rset}. If the validity is not known, the function
+@code{gpgme_recipients_add_name} can be used.
+@xref{Information about keys}, for the possible values for @var{val}.
+
+The function returns @code{GPGME_No_Error} if the recipient was added
+successfully, @code{GPGME_Invalid_Value} if @var{rset} or @var{name}
+is not a valid pointer, and @code{GPGME_Out_Of_Core} if not enough
+memory is available.
+@end deftypefun
+
+@deftypefun {unsigned int} gpgme_recipients_count (@w{const @var{GpgmeRecipients rset}})
+The function @code{gpgme_recipients_count} returns the number of
+recipients in the set @var{rset}.
+@end deftypefun
+
+@deftypefun GpgmeError gpgme_recipients_enum_open (@w{const GpgmeRecipients @var{rset}}, @w{void **@var{iter}})
+The function @code{gpgme_recipients_enum_open} creates a new iterator
+@var{iter} that can be used to walk through the set of recipients in
+@var{rset}, using @code{gpgme_recipients_enum_read}.
+
+If the iterator is not needed anymore, it can be closed with
+@code{gpgme_recipients_enum_close}.
+
+The function returns @code{GPGME_No_Error} if the enumerator was
+successfully created and @code{GPGME_Invalid_Value} if @var{rset} or
+@var{iter} is not a valid pointer.
+@end deftypefun
+
+@deftypefun {const char *} gpgme_recipients_enum_read (@w{const GpgmeRecipients @var{rset}}, @w{void **@var{iter}})
+The function @code{gpgme_recipients_enum_read} returns a string
+containing the name of the next recipient in the set @var{rset} for
+the iterator @var{iter}. The string is valid as long as @var{rset} is
+valid or the function is called the next time with the same recipient
+set and iterator, whatever is earlier.
+@end deftypefun
+
+@deftypefun GpgmeError gpgme_recipients_enum_close (@w{const GpgmeRecipients @var{rset}}, @w{void **@var{iter}})
+The function @code{gpgme_recipients_enum_close} releases the iterator
+@var{iter} for the recipient set @var{rset}.
+@end deftypefun
+
+
+@node Encrypting a plaintext
+@subsubsection Encrypting a plaintext
+
+@deftypefun GpgmeError gpgme_op_encrypt (@w{GpgmeCtx @var{ctx}}, @w{GpgmeRecipients @var{rset}}, @w{GpgmeData @var{plain}}, @w{GpgmeData @var{cipher}})
+The function @code{gpgme_op_crypt} encrypts the plaintext in the data
+object @var{plain} for the recipients @var{rset} and stores the
+ciphertext in the data object @var{cipher}. The type of the
+ciphertext created is determined by the @acronym{ASCII} and text mode
+attributes set for the context @var{ctx}.
+
+The function returns @code{GPGME_No_Error} if the ciphertext could be
+created successfully, @code{GPGME_Invalid_Value} if @var{ctx},
+@var{rset}, @var{plain} or @var{cipher} is not a valid pointer,
+@code{GPGME_No_Recipient} if @var{rset} does not contain any
+valid recipients, @code{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.
+@end deftypefun
+
+
+@include gpl.texi
+
+
+@include fdl.texi
+
+
+@node Concept Index
+@unnumbered Concept Index
+
+@printindex cp
+
+
+@node Function and Data Index
+@unnumbered Function and Data Index
+
+@printindex fn
+
+
+@summarycontents
+@contents
+@bye
--- /dev/null
+@node Copying
+@appendix GNU GENERAL PUBLIC LICENSE
+
+@cindex GPL, GNU General Public License
+@center Version 2, June 1991
+
+@display
+Copyright @copyright{} 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.
+@end display
+
+@appendixsubsec 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.
+
+@iftex
+@appendixsubsec TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+@end iftex
+@ifinfo
+@center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+@end ifinfo
+
+@enumerate
+@item
+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.
+
+@item
+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.
+
+@item
+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:
+
+@enumerate a
+@item
+You must cause the modified files to carry prominent notices
+stating that you changed the files and the date of any change.
+
+@item
+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.
+
+@item
+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.)
+@end enumerate
+
+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.
+
+@item
+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:
+
+@enumerate a
+@item
+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,
+
+@item
+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,
+
+@item
+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.)
+@end enumerate
+
+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.
+
+@item
+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.
+
+@item
+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.
+
+@item
+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.
+
+@item
+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.
+
+@item
+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.
+
+@item
+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.
+
+@item
+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.
+
+@iftex
+@heading NO WARRANTY
+@end iftex
+@ifinfo
+@center NO WARRANTY
+@end ifinfo
+
+@item
+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.
+
+@item
+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 enumerate
+
+@iftex
+@heading END OF TERMS AND CONDITIONS
+@end iftex
+@ifinfo
+@center END OF TERMS AND CONDITIONS
+@end ifinfo
+
+@page
+@unnumberedsec 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.
+
+@smallexample
+@var{one line to give the program's name and an idea of what it does.}
+Copyright (C) 19@var{yy} @var{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.
+@end smallexample
+
+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:
+
+@smallexample
+Gnomovision version 69, Copyright (C) 19@var{yy} @var{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.
+@end smallexample
+
+The hypothetical commands @samp{show w} and @samp{show c} should show
+the appropriate parts of the General Public License. Of course, the
+commands you use may be called something other than @samp{show w} and
+@samp{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:
+
+@smallexample
+@group
+Yoyodyne, Inc., hereby disclaims all copyright
+interest in the program `Gnomovision'
+(which makes passes at compilers) written
+by James Hacker.
+
+@var{signature of Ty Coon}, 1 April 1989
+Ty Coon, President of Vice
+@end group
+@end smallexample
+
+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.
projects / gpgme.git / commitdiff