diff options
Diffstat (limited to 'branches/gpgme-0-3-branch/doc')
| -rw-r--r-- | branches/gpgme-0-3-branch/doc/ChangeLog | 258 | ||||
| -rw-r--r-- | branches/gpgme-0-3-branch/doc/Makefile.am | 27 | ||||
| -rw-r--r-- | branches/gpgme-0-3-branch/doc/fdl.texi | 402 | ||||
| -rwxr-xr-x | branches/gpgme-0-3-branch/doc/gdoc | 681 | ||||
| -rw-r--r-- | branches/gpgme-0-3-branch/doc/gpgme.texi | 3372 | ||||
| -rw-r--r-- | branches/gpgme-0-3-branch/doc/gpl.texi | 397 |
6 files changed, 5137 insertions, 0 deletions
diff --git a/branches/gpgme-0-3-branch/doc/ChangeLog b/branches/gpgme-0-3-branch/doc/ChangeLog new file mode 100644 index 00000000..3d798b75 --- /dev/null +++ b/branches/gpgme-0-3-branch/doc/ChangeLog @@ -0,0 +1,258 @@ +2002-08-30 Marcus Brinkmann <[email protected]> + + * gpgme.texi (Selecting Signers): Fix reference count. + +2002-08-21 Marcus Brinkmann <[email protected]> + + * gpgme.texi (Header): Document name space. + +2002-08-20 Marcus Brinkmann <[email protected]> + + * gpgme.texi (Importing Keys): Document gpgme_op_import_ext. + + * gpgme.texi (Importing Keys): Undocument EOF. + +2002-08-14 Werner Koch <[email protected]> + + * gpgme.texi (Information About Keys): Changed GPGME_ATTR_TYPE. + +2002-07-25 Marcus Brinkmann <[email protected]> + + * gpgme.texi (Deleting Keys): Say that secret keys might not be + deleted. + +2002-07-25 Marcus Brinkmann <[email protected]> + + * gpgme.texi (Information About Keys): Document (badly) the new + key attributes. + + * gpgme.texi (Manipulating Data Buffers): Mention that backend + tries to detect encoding automatically. + +2002-07-03 Marcus Brinkmann <[email protected]> + + * gpgme.texi (Run Control): Update this section. + (Waiting For Completion): Likewise for this subsection. + (Cancelling an Operation): Likewise for this subsection. + (Using External Event Loops): New subsection with several + subsubsections. + +2002-06-28 Marcus Brinkmann <[email protected]> + + * gpgme.texi (Multi Threading): Remove item about the need to + synchronize anything against gpgme_wait (except gpgme_wait + itself). + +2002-06-27 Marcus Brinkmann <[email protected]> + + * gpgme.texi (Information About Keys): Fix documentation for IDX. + (Information About Trust Items): Likewise. + +2002-06-26 Werner Koch <[email protected]> + + * gpgme.texi (Importing Keys): Document the return value -1 of + gpgme_op_import. + +2002-06-20 Werner Koch <[email protected]> + + * gpgme.texi (Verify): Explain the new whatidx variable. + +2002-06-10 Werner Koch <[email protected]> + + * gpgme.texi (Verify): Document attribute GPGME_ATTR_ERRTOK. + +2002-06-04 Marcus Brinkmann <[email protected]> + + * gpgme.texi (Multi Threading): Document new autodetection. + +2002-06-04 Marcus Brinkmann <[email protected]> + + * Makefile.am (DISTCLEANFILES): New variable. + +2002-05-26 Marcus Brinkmann <[email protected]> + + * gpgme.texi: Some typographical correctons throughout. + +2002-05-09 Marcus Brinkmann <[email protected]> + + * gpgme.texi (Using Automake): New section. + +2002-05-09 Marcus Brinkmann <[email protected]> + + * gpgme.texi (Multi Threading): Escape { and }. + +2002-05-09 Marcus Brinkmann <[email protected]> + + * gpgme.texi (Overview): Replace note about thread-safeness. + (Multi Threading): New section. + +2002-05-03 Werner Koch <[email protected]> + + * gpgme.texi (Manipulating Data Buffers): Changed some data types + to void*. + (Protocol Selection): Added gpgme_get_protocol. + (Verify): Updated to include the new attribute fucntions and + status codes. + +2002-04-27 Werner Koch <[email protected]> + + * gpgme.texi (Manipulating Data Buffers): New type GpgmeDataEncoding. + +2002-04-23 Marcus Brinkmann <[email protected]> + + * gpgme.texi (Passphrase Callback): Document that either return + argument can be NULL. + (Progress Meter Callback): Likewise. + +2002-04-22 Marcus Brinkmann <[email protected]> + + * gpgme.texi (Passphrase Callback): Fix small typo. Document the + new function gpgme_get_passphrase_cb. + (Progress Meter Callback): Document the new function + gpgme_get_progress_cb. + +2002-04-16 Marcus Brinkmann <[email protected]> + + * gpgme.texi (Creating a Signature): Fix function name. Reported + by Wichert Ackerman <[email protected]>. + +2002-03-29 Marcus Brinkmann <[email protected]> + + * gpgme.texi (direntry): End index entry with a full stop. + Patch submitted by Jose Carlos Garcia Sogo <[email protected]>. + +2002-03-17 Marcus Brinkmann <[email protected]> + + * gpgme.texi (Detailed Results): Fix syntax error in last change. + +2002-03-08 Werner Koch <[email protected]> + + * gpgme.texi (Detailed Results): Import does also return info. + +2002-03-06 Marcus Brinkmann <[email protected]> + + * gpgme.texi (Encrypting a Plaintext): Document symmetric + encryption. + +2002-03-06 Marcus Brinkmann <[email protected]> + + * gpgme.texi (Error Strings): Add example. + * gpgme.texi (Listing Keys): Likewise. + +2002-03-03 Marcus Brinkmann <[email protected]> + + * gpgme.texi (Information About Keys): Document GPGME_ATTR_EXPIRE. + +2002-03-03 Marcus Brinkmann <[email protected]> + + * gpgme.texi (Verify): Document verification of normal and + cleartext signatures. + +2002-02-27 Marcus Brinkmann <[email protected]> + + * gpgme.texi (Listing Keys): Document gpgme_op_keylist_ext_start. + +2002-02-27 Marcus Brinkmann <[email protected]> + + * gpgme.texi (Encrypting a Plaintext): Document + GPGME_Invalid_Recipients. + (Error Values): Likewise. + +2002-02-26 Marcus Brinkmann <[email protected]> + + * gpgme.texi (Encrypting a Plaintext): Document + gpgme_op_encrypt_sign and gpgme_op_encrypt_sign_start. + +2002-02-25 Marcus Brinkmann <[email protected]> + + * gpgme.texi (Creating a Signature): Add a note about + certificates to include. + (Included Certificates): New section. + +2002-02-09 Marcus Brinkmann <[email protected]> + + * gpgme.texi (Detailed Results): Remove literal tags. + (Generating Keys): Update documentation. + + * gpgme.texi (Generating Keys): Fix syntax error. + +2002-02-06 Marcus Brinkmann <[email protected]> + + * gpgme.texi (Waiting For Completion): Adjust doc to changes in + the code. + +2002-02-06 Marcus Brinkmann <[email protected]> + + * gpgme.texi (Key Listing Mode): Update documentation. + +2002-01-31 Marcus Brinkmann <[email protected]> + + * gpgme.texi (Generating Keys): Document error at creation + failure. + +2002-01-30 Marcus Brinkmann <[email protected]> + + * gpgme.texi (Deleting Keys): Document new error values. + +2002-01-30 Marcus Brinkmann <[email protected]> + + * gpgme.texi (Importing Keys): Add reference to gpgme_get_op_info. + +2002-01-30 Marcus Brinkmann <[email protected]> + + * gpgme.texi: Some spell checking. + +2002-01-30 Marcus Brinkmann <[email protected]> + + * gpgme.texi: Add all the gpgme_op_*_start functions. + Fill the concept index with many, many entries. + +2002-01-29 Marcus Brinkmann <[email protected]> + + * gpgme.texi (Run Control): New section. + (Verify): Docuent gpgme_get_notation. + (More Information): New section describing gpgme_get_op_info. + +2002-01-22 Marcus Brinkmann <[email protected]> + + * gpgme.texi (Passphrase callback): Change GpgmePassphraseCb's + R_HD type from void* to void**. + +2002-01-22 Marcus Brinkmann <[email protected]> + + * gpgme.texi (Creating data buffers): Change + gpgme_data_new_from_filepart's LENGTH type from off_t to size_t. + +2002-01-22 Marcus Brinkmann <[email protected]> + + * gpgme.texi (Generating keys): New subsection. + (Exporting keys): Likewise. + (Importing keys): Likewise. + (Deleting keys): Likewise. + +2002-01-16 Marcus Brinkmann <[email protected]> + + * gpgme.texi: g10Code -> g10 Code + + * gpgme.texi (Top): Complete detailmenu. + + * gpgme.texi: Convert embarassing cruft to the real thing. + +2002-01-16 Marcus Brinkmann <[email protected]> + + * ChangeLog: New file. + * gpgme.texi: Likewise. + * gpl.texi: Likewise. + * fdl.texi: Likewise. + * Makefile.am (info_TEXINFOS): New variable. + (gpgme_TEXINFOS): Likewise. + + Copyright 2002 g10 Code GmbH + + This file is free software; as a special exception the author gives + unlimited permission to copy and/or distribute it, with or without + modifications, as long as this notice is preserved. + + This file is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY, to the extent permitted by law; without even the + implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. diff --git a/branches/gpgme-0-3-branch/doc/Makefile.am b/branches/gpgme-0-3-branch/doc/Makefile.am new file mode 100644 index 00000000..bda8e373 --- /dev/null +++ b/branches/gpgme-0-3-branch/doc/Makefile.am @@ -0,0 +1,27 @@ +# doc - Automake template +# Copyright (C) 2001 g10 Code GmbH +# +# This file is part of GPGME. +# +# GPGME 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. +# +# GPGME 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 + +## Process this file with automake to produce Makefile.in + +EXTRA_DIST = gdoc + +DISTCLEANFILES = gpgme.tmp + +info_TEXINFOS = gpgme.texi +gpgme_TEXINFOS = gpl.texi fdl.texi diff --git a/branches/gpgme-0-3-branch/doc/fdl.texi b/branches/gpgme-0-3-branch/doc/fdl.texi new file mode 100644 index 00000000..50028ab5 --- /dev/null +++ b/branches/gpgme-0-3-branch/doc/fdl.texi @@ -0,0 +1,402 @@ +@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: + diff --git a/branches/gpgme-0-3-branch/doc/gdoc b/branches/gpgme-0-3-branch/doc/gdoc new file mode 100755 index 00000000..a1c314d8 --- /dev/null +++ b/branches/gpgme-0-3-branch/doc/gdoc @@ -0,0 +1,681 @@ +#!/usr/bin/perl + +## Copyright (c) 1998 Michael Zucchi, All Rights Reserved ## +## hacked to allow -tex option --nmav ## +## ## +## This software falls under the GNU Public License. Please read ## +## the COPYING file for more information ## + +# +# This will read a 'c' file and scan for embedded comments in the +# style of gnome comments (+minor extensions - see below). +# + +# Note: This only supports 'c'. + +# usage: +# gdoc [ -docbook | -html | -text | -man ] +# [ -function funcname [ -function funcname ...] ] c file(s)s > outputfile +# +# Set output format using one of -docbook -html -text or -man. Default is man. +# +# -function funcname +# If set, then only generate documentation for the given function(s). All +# other functions are ignored. +# +# c files - list of 'c' files to process +# +# All output goes to stdout, with errors to stderr. + +# +# format of comments. +# In the following table, (...)? signifies optional structure. +# (...)* signifies 0 or more structure elements +# /** +# * function_name(:)? (- short description)? +# (* @parameterx: (description of parameter x)?)* +# (* a blank line)? +# * (Description:)? (Description of function)? +# * (section header: (section description)? )* +# (*)?*/ +# +# So .. the trivial example would be: +# +# /** +# * my_function +# **/ +# +# If the Description: header tag is ommitted, then there must be a blank line +# after the last parameter specification. +# e.g. +# /** +# * my_function - does my stuff +# * @my_arg: its mine damnit +# * +# * Does my stuff explained. +# */ +# +# or, could also use: +# /** +# * my_function - does my stuff +# * @my_arg: its mine damnit +# * Description: Does my stuff explained. +# */ +# etc. +# +# All descriptions can be multiline, apart from the short function description. +# +# All descriptive text is further processed, scanning for the following special +# patterns, which are highlighted appropriately. +# +# 'funcname()' - function +# '$ENVVAR' - environmental variable +# '&struct_name' - name of a structure +# '@parameter' - name of a parameter +# '%CONST' - name of a constant. + +# match expressions used to find embedded type information +$type_constant = "\\\%(\\w+)"; +#$type_func = "(\\w+\\(\\))"; +$type_func = "(\\(w||\\\\)+\\(\\))"; +$type_param = "\\\@(\\w+)"; +$type_struct = "\\\&(\\w+)"; +$type_env = "(\\\$\\w+)"; + + +# Output conversion substitutions. +# One for each output format + +# these work fairly well +%highlights_html = ( $type_constant, "<i>\$1</i>", + $type_func, "<b>\$1</b>", + $type_struct, "<i>\$1</i>", + $type_param, "<tt><b>\$1</b></tt>" ); +$blankline_html = "<p>"; + +%highlights_tex = ( $type_constant, "{\\\\it \$1}", + $type_func, "{\\\\bf \$1}", + $type_struct, "{\\\\it \$1}", + $type_param, "{\\\\bf \$1}" ); +$blankline_tex = "\\par"; + +# sgml, docbook format +%highlights_sgml = ( $type_constant, "<replaceable class=\"option\">\$1</replaceable>", + $type_func, "<function>\$1</function>", + $type_struct, "<structname>\$1</structname>", + $type_env, "<envar>\$1</envar>", + $type_param, "<parameter>\$1</parameter>" ); +$blankline_sgml = "</para><para>\n"; + +# these are pretty rough +%highlights_man = ( $type_constant, "\\n.I \\\"\$1\\\"\\n", + $type_func, "\\n.B \\\"\$1\\\"\\n", + $type_struct, "\\n.I \\\"\$1\\\"\\n", + $type_param."([\.\, ]*)\n?", "\\n.I \\\"\$1\$2\\\"\\n" ); +$blankline_man = ""; + +# text-mode +%highlights_text = ( $type_constant, "\$1", + $type_func, "\$1", + $type_struct, "\$1", + $type_param, "\$1" ); +$blankline_text = ""; + + +sub usage { + print "Usage: $0 [ -v ] [ -docbook | -html | -text | -man | -tex ]\n"; + print " [ -function funcname [ -function funcname ...] ]\n"; + print " c source file(s) > outputfile\n"; + exit 1; +} + +# read arguments +if ($#ARGV==-1) { + usage(); +} + +$verbose = 0; +$output_mode = "man"; +%highlights = %highlights_man; +$blankline = $blankline_man; +$modulename = "API Documentation"; +$function_only = 0; +while ($ARGV[0] =~ m/^-(.*)/) { + $cmd = shift @ARGV; + if ($cmd eq "-html") { + $output_mode = "html"; + %highlights = %highlights_html; + $blankline = $blankline_html; + } elsif ($cmd eq "-man") { + $output_mode = "man"; + %highlights = %highlights_man; + $blankline = $blankline_man; + } elsif ($cmd eq "-tex") { + $output_mode = "tex"; + %highlights = %highlights_tex; + $blankline = $blankline_tex; + } elsif ($cmd eq "-text") { + $output_mode = "text"; + %highlights = %highlights_text; + $blankline = $blankline_text; + } elsif ($cmd eq "-docbook") { + $output_mode = "sgml"; + %highlights = %highlights_sgml; + $blankline = $blankline_sgml; + } elsif ($cmd eq "-module") { # not needed for sgml, inherits from calling document + $modulename = shift @ARGV; + } elsif ($cmd eq "-function") { # to only output specific functions + $function_only = 1; + $function = shift @ARGV; + $function_table{$function} = 1; + } elsif ($cmd eq "-v") { + $verbose = 1; + } elsif (($cmd eq "-h") || ($cmd eq "--help")) { + usage(); + } +} + + +# generate a sequence of code that will splice in highlighting information +# using the s// operator. +$dohighlight = ""; +foreach $pattern (keys %highlights) { +# print "scanning pattern $pattern ($highlights{$pattern})\n"; + $dohighlight .= "\$contents =~ s:$pattern:$highlights{$pattern}:gs;\n"; +} + +## +# dumps section contents to arrays/hashes intended for that purpose. +# +sub dump_section { + my $name = shift @_; + my $contents = join "\n", @_; + + if ($name =~ m/$type_constant/) { + $name = $1; +# print STDERR "constant section '$1' = '$contents'\n"; + $constants{$name} = $contents; + } elsif ($name =~ m/$type_param/) { +# print STDERR "parameter def '$1' = '$contents'\n"; + $name = $1; + $parameters{$name} = $contents; + } else { +# print STDERR "other section '$name' = '$contents'\n"; + $sections{$name} = $contents; + push @sectionlist, $name; + } +} + +## +# output function +# +# parameters, a hash. +# function => "function name" +# parameterlist => @list of parameters +# parameters => %parameter descriptions +# sectionlist => @list of sections +# sections => %descriont descriptions +# + +sub output_highlight { + my $contents = join "\n", @_; + my $line; + + eval $dohighlight; + foreach $line (split "\n", $contents) { + if ($line eq ""){ + print $lineprefix, $blankline; + } else { + print $lineprefix, $line; + } + print "\n"; + } +} + + +# output in html +sub output_html { + my %args = %{$_[0]}; + my ($parameter, $section); + my $count; + print "\n\n<a name=\"". $args{'function'} . "\"> </a><h2>Function</h2>\n"; + + print "<i>".$args{'functiontype'}."</i>\n"; + print "<b>".$args{'function'}."</b>\n"; + print "("; + $count = 0; + foreach $parameter (@{$args{'parameterlist'}}) { + print "<i>".$args{'parametertypes'}{$parameter}."</i> <b>".$parameter."</b>\n"; + if ($count != $#{$args{'parameterlist'}}) { + $count++; + print ", "; + } + } + print ")\n"; + + print "<h3>Arguments</h3>\n"; + print "<dl>\n"; + foreach $parameter (@{$args{'parameterlist'}}) { + print "<dt><i>".$args{'parametertypes'}{$parameter}."</i> <b>".$parameter."</b>\n"; + print "<dd>"; + output_highlight($args{'parameters'}{$parameter}); + } + print "</dl>\n"; + foreach $section (@{$args{'sectionlist'}}) { + print "<h3>$section</h3>\n"; + print "<ul>\n"; + output_highlight($args{'sections'}{$section}); + print "</ul>\n"; + } + print "<hr>\n"; +} + +# output in tex +sub output_tex { + my %args = %{$_[0]}; + my ($parameter, $section); + my $count; + my $func = $args{'function'}; + my $param; + my $param2; + my $sec; + my $check; + my $type; + + $func =~ s/_/\\_/g; + + print "\n\n\\subsection{". $func . "}\n\\label{" . $args{'function'} . "}\n"; + + $type = $args{'functiontype'}; + $type =~ s/_/\\_/g; + + print "{\\it ".$type."}\n"; + print "{\\bf ".$func."}\n"; + print "(\n"; + $count = 0; + foreach $parameter (@{$args{'parameterlist'}}) { + $param = $args{'parametertypes'}{$parameter}; + $param2 = $parameter; + $param =~ s/_/\\_/g; + $param2 =~ s/_/\\_/g; + + print "{\\it ".$param."} {\\bf ".$param2."}\n"; + if ($count != $#{$args{'parameterlist'}}) { + $count++; + print ", "; + } + } + print ")\n"; + + print "\n{\\large{Arguments}}\n"; + + print "\\begin{itemize}\n"; + $check=0; + foreach $parameter (@{$args{'parameterlist'}}) { + $param = $args{'parametertypes'}{$parameter}; + $param =~ s/_/\\_/g; + $param2 = $parameter; + $param2 =~ s/_/\\_/g; + + $check = 1; + print "\\item {\\it ".$param."} {\\bf ".$param2."}\n"; + print "\n"; + + output_highlight($param{$parameter}); + } + if ($check==0) { + print "\\item void\n"; + } + print "\\end{itemize}\n"; + + foreach $section (@{$args{'sectionlist'}}) { + print "\n\\par{\\large{$section}}\\par\n"; + print "\\begin{rmfamily}\n"; + + $sec = $args{'sections'}{$section}; + $sec =~ s/_/\\_/g; + $sec =~ s/&/\\&/g; + output_highlight($sec); + print "\\end{rmfamily}\n"; + } + print "\n"; +} + + +# output in sgml DocBook +sub output_sgml { + my %args = %{$_[0]}; + my ($parameter, $section); + my $count; + my $id; + + $id = $args{'module'}."-".$args{'function'}; + $id =~ s/[^A-Za-z0-9]/-/g; + + print "<refentry>\n"; + print "<refmeta>\n"; + print "<refentrytitle><phrase id=\"$id\">".$args{'function'}."</phrase></refentrytitle>\n"; + print "</refmeta>\n"; + print "<refnamediv>\n"; + print " <refname>".$args{'function'}."</refname>\n"; + print " <refpurpose>\n"; + print " ".$args{'purpose'}."\n"; + print " </refpurpose>\n"; + print "</refnamediv>\n"; + + print "<refsynopsisdiv>\n"; + print " <title>Synopsis</title>\n"; + print " <funcsynopsis>\n"; + print " <funcdef>".$args{'functiontype'}." "; + print "<function>".$args{'function'}." "; + print "</function></funcdef>\n"; + +# print "<refsect1>\n"; +# print " <title>Synopsis</title>\n"; +# print " <funcsynopsis>\n"; +# print " <funcdef>".$args{'functiontype'}." "; +# print "<function>".$args{'function'}." "; +# print "</function></funcdef>\n"; + + $count = 0; + if ($#{$args{'parameterlist'}} >= 0) { + foreach $parameter (@{$args{'parameterlist'}}) { + print " <paramdef>".$args{'parametertypes'}{$parameter}; + print " <parameter>$parameter</parameter></paramdef>\n"; + } + } else { + print " <void>\n"; + } + print " </funcsynopsis>\n"; + print "</refsynopsisdiv>\n"; +# print "</refsect1>\n"; + + # print parameters + print "<refsect1>\n <title>Arguments</title>\n"; +# print "<para>\nArguments\n"; + if ($#{$args{'parameterlist'}} >= 0) { + print " <variablelist>\n"; + foreach $parameter (@{$args{'parameterlist'}}) { + print " <varlistentry>\n <term><parameter>$parameter</parameter></term>\n"; + print " <listitem>\n <para>\n"; + $lineprefix=" "; + output_highlight($args{'parameters'}{$parameter}); + print " </para>\n </listitem>\n </varlistentry>\n"; + } + print " </variablelist>\n"; + } else { + print " <para>\n None\n </para>\n"; + } + print "</refsect1>\n"; + + # print out each section + $lineprefix=" "; + foreach $section (@{$args{'sectionlist'}}) { + print "<refsect1>\n <title>$section</title>\n <para>\n"; +# print "<para>\n$section\n"; + if ($section =~ m/EXAMPLE/i) { + print "<example><para>\n"; + } + output_highlight($args{'sections'}{$section}); +# print "</para>"; + if ($section =~ m/EXAMPLE/i) { + print "</para></example>\n"; + } + print " </para>\n</refsect1>\n"; + } + + print "\n\n"; +} + +## +# output in man +sub output_man { + my %args = %{$_[0]}; + my ($parameter, $section); + my $count; + + print ".TH \"$args{'module'}\" \"$args{'function'}\" \"25 May 1998\" \"API Manual\" GNOME\n"; + + print ".SH Function\n"; + + print ".I \"".$args{'functiontype'}."\"\n"; + print ".B \"".$args{'function'}."\"\n"; + print "(\n"; + $count = 0; + foreach $parameter (@{$args{'parameterlist'}}) { + print ".I \"".$args{'parametertypes'}{$parameter}."\"\n.B \"".$parameter."\"\n"; + if ($count != $#{$args{'parameterlist'}}) { + $count++; + print ",\n"; + } + } + print ")\n"; + + print ".SH Arguments\n"; + foreach $parameter (@{$args{'parameterlist'}}) { + print ".IP \"".$args{'parametertypes'}{$parameter}." ".$parameter."\" 12\n"; + output_highlight($args{'parameters'}{$parameter}); + } + foreach $section (@{$args{'sectionlist'}}) { + print ".SH \"$section\"\n"; + output_highlight($args{'sections'}{$section}); + } +} + +## +# output in text +sub output_text { + my %args = %{$_[0]}; + my ($parameter, $section); + + print "Function = ".$args{'function'}."\n"; + print " return type: ".$args{'functiontype'}."\n\n"; + foreach $parameter (@{$args{'parameterlist'}}) { + print " ".$args{'parametertypes'}{$parameter}." ".$parameter."\n"; + print " -> ".$args{'parameters'}{$parameter}."\n"; + } + foreach $section (@{$args{'sectionlist'}}) { + print " $section:\n"; + print " -> "; + output_highlight($args{'sections'}{$section}); + } +} + +## +# generic output function - calls the right one based +# on current output mode. +sub output_function { +# output_html(@_); + eval "output_".$output_mode."(\@_);"; +} + + +## +# takes a function prototype and spits out all the details +# stored in the global arrays/hsahes. +sub dump_function { + my $prototype = shift @_; + + if ($prototype =~ m/^()([a-zA-Z0-9_~:]+)\s*\(([^\)]*)\)/ || + $prototype =~ m/^(\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\)]*)\)/ || + $prototype =~ m/^(\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\)]*)\)/ || + $prototype =~ m/^(\w+\s+\w+)\s+([a-zA-Z0-9_~:]+)\s*\(([^\)]*)\)/ || + $prototype =~ m/^(\w+\s+\w+\s*\*)\s*([a-zA-Z0-9_~:]+)\s*\(([^\)]*)\)/) { + $return_type = $1; + $function_name = $2; + $args = $3; + +# print STDERR "ARGS = '$args'\n"; + + foreach $arg (split ',', $args) { + # strip leading/trailing spaces + $arg =~ s/^\s*//; + $arg =~ s/\s*$//; +# print STDERR "SCAN ARG: '$arg'\n"; + @args = split('\s', $arg); + +# print STDERR " -> @args\n"; + $param = pop @args; +# print STDERR " -> @args\n"; + if ($param =~ m/^(\*+)(.*)/) { + $param = $2; + push @args, $1; + } + $type = join " ", @args; + + if ($parameters{$param} eq "") { + $parameters{$param} = "-- undescribed --"; + print STDERR "Warning($lineno): Function parameter '$param' not described in '$function_name'\n"; + } + + push @parameterlist, $param; + $parametertypes{$param} = $type; + +# print STDERR "param = '$param', type = '$type'\n"; + } + } else { + print STDERR "Error($lineno): cannot understand prototype: '$prototype'\n"; + return; + } + + if ($function_only==0 || defined($function_table{$function_name})) { + output_function({'function' => $function_name, + 'module' => $modulename, + 'functiontype' => $return_type, + 'parameterlist' => \@parameterlist, + 'parameters' => \%parameters, + 'parametertypes' => \%parametertypes, + 'sectionlist' => \@sectionlist, + 'sections' => \%sections, + 'purpose' => $function_purpose + }); + } +} + +###################################################################### +# main +# states +# 0 - normal code +# 1 - looking for function name +# 2 - scanning field start. +# 3 - scanning prototype. +$state = 0; +$section = ""; + +$doc_special = "\@\%\$\&"; + +$doc_start = "^/\\*\\*\$"; +$doc_end = "\\*/"; +$doc_com = "\\s*\\*\\s*"; +$doc_func = $doc_com."(\\w+):?"; +$doc_sect = $doc_com."([".$doc_special."]?[\\w ]+):(.*)"; +$doc_content = $doc_com."(.*)"; + +%constants = (); +%parameters = (); +@parameterlist = (); +%sections = (); +@sectionlist = (); + +$contents = ""; +$section_default = "Description"; # default section +$section = $section_default; + +$lineno = 0; +foreach $file (@ARGV) { + if (!open(IN,"<$file")) { + print STDERR "Error: Cannot open file $file\n"; + next; + } + while (<IN>) { + $lineno++; + + if ($state == 0) { + if (/$doc_start/o) { + $state = 1; # next line is always the function name + } + } elsif ($state == 1) { # this line is the function name (always) + if (/$doc_func/o) { + $function = $1; + $state = 2; + if (/-(.*)/) { + $function_purpose = $1; + } else { + $function_purpose = ""; + } + if ($verbose) { + print STDERR "Info($lineno): Scanning doc for $function\n"; + } + } else { + print STDERR "WARN($lineno): Cannot understand $_ on line $lineno", + " - I thought it was a doc line\n"; + $state = 0; + } + } elsif ($state == 2) { # look for head: lines, and include content + if (/$doc_sect/o) { + $newsection = $1; + $newcontents = $2; + + if ($contents ne "") { + dump_section($section, $contents); + $section = $section_default; + } + + $contents = $newcontents; + if ($contents ne "") { + $contents .= "\n"; + } + $section = $newsection; + } elsif (/$doc_end/) { + + if ($contents ne "") { + dump_section($section, $contents); + $section = $section_default; + $contents = ""; + } + +# print STDERR "end of doc comment, looking for prototype\n"; + $prototype = ""; + $state = 3; + } elsif (/$doc_content/) { + # miguel-style comment kludge, look for blank lines after + # @parameter line to signify start of description + if ($1 eq "" && $section =~ m/^@/) { + dump_section($section, $contents); + $section = $section_default; + $contents = ""; + } else { + $contents .= $1."\n"; + } + } else { + # i dont know - bad line? ignore. + print STDERR "WARNING($lineno): bad line: $_"; + } + } elsif ($state == 3) { # scanning for function { (end of prototype) + if (m#\s*/\*\s+MACDOC\s*#io) { + # do nothing + } + elsif (/([^\{]*)/) { + $prototype .= $1; + } + if (/\{/) { + $prototype =~ s@/\*.*?\*/@@gos; # strip comments. + $prototype =~ s@[\r\n]+@ @gos; # strip newlines/cr's. + $prototype =~ s@^ +@@gos; # strip leading spaces + dump_function($prototype); + + $function = ""; + %constants = (); + %parameters = (); + %parametertypes = (); + @parameterlist = (); + %sections = (); + @sectionlist = (); + $prototype = ""; + + $state = 0; + } + } + } +} + diff --git a/branches/gpgme-0-3-branch/doc/gpgme.texi b/branches/gpgme-0-3-branch/doc/gpgme.texi new file mode 100644 index 00000000..51b5d492 --- /dev/null +++ b/branches/gpgme-0-3-branch/doc/gpgme.texi @@ -0,0 +1,3372 @@ +\input texinfo @c -*- Texinfo -*- +@setfilename gpgme.info +@settitle The `GnuPG Made Easy' Reference Manual + +@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{} 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 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 @acronym{GPGME} library. +@end ifnottex + +@menu +* Introduction:: How to use this manual. +* Preparation:: What you should do before using the library. +* Protocols and Engines:: Supported crypto protocols. +* Error Handling:: Error numbers and their meanings. +* Exchanging Data:: Passing data to and from @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. + +Preparation + +* Header:: What header file you need to include. +* Building the Source:: Compiler options to be used. +* Using Automake:: Compiler options to be used the easy way. +* Library Version Check:: Getting and verifying the library version. +* Multi Threading:: How GPGME can be used in an MT environment. + +Protocols and Engines + +* Engine Version Check:: Verifying the engine version. +* Engine Information:: Obtaining more information about the engines. +* OpenPGP:: Support for the OpenPGP protocol. +* Cryptographic Message Syntax:: Support for the CMS. + +Error Handling + +* Error Values:: A list of all error values used. +* Error Strings:: How to get a descriptive string from a value. + +Exchanging Data + +* Creating Data Buffers:: Creating new data buffers. +* Destroying Data Buffers:: Releasing data buffers. +* Manipulating Data Buffers:: Operations on data buffers. + +Contexts + +* Creating Contexts:: Creating new @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. +* Run Control:: Controlling how operations are run. + +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. +* Included Certificates:: Including a number of certificates. +* Key Listing Mode:: Selecting key listing mode. +* Passphrase Callback:: Getting the passphrase from the user. +* Progress Meter Callback:: Being informed about the progress. + +Key Management + +* Listing Keys:: Browsing the list of available keys. +* Information About Keys:: Requesting detailed information about keys. +* Manipulating Keys:: Operations on keys. +* Generating Keys:: Creating new key pairs. +* Exporting Keys:: Retrieving key data from the key ring. +* Importing Keys:: Adding keys to the key ring. +* Deleting Keys:: Removing keys from the key ring. + +Trust Item Management + +* Listing Trust Items:: Browsing the list of available trust items. +* Information About Trust Items:: Requesting detailed information about trust items. +* Manipulating Trust Items:: Operations on trust items. + +Crypto Operations + +* Decrypt:: Decrypting a ciphertext. +* Verify:: Verifying a signature. +* Decrypt and Verify:: Decrypting a signed ciphertext. +* Sign:: Creating a signature. +* Encrypt:: Encrypting a plaintext. +* Detailed Results:: How to obtain more info about the operation. + +Sign + +* Selecting Signers:: How to choose the keys to sign with. +* Creating a Signature:: How to create a signature. + +Encrypt + +* Selecting Recipients:: How to choose the recipients. +* Encrypting a Plaintext:: How to encrypt a plaintext. + +Run Control + +* Waiting For Completion:: Waiting until an operation is completed. +* Cancelling an Operation:: Interrupting a running operation. +* Hooking Up Into Idle Time:: Doing something when nothing has to be done. +* Using External Event Loops:: Advanced control over what happens when. + +Using External Event Loops + +* I/O Callback Interface:: How I/O callbacks are registered. +* Registering I/O Callbacks:: How to use I/O callbacks for a context. +* I/O Callback Example:: An example how to use I/O callbacks. +* I/O Callback Example GTK+:: How to integrate @acronym{GPGME} in GTK+. +* I/O Callback Example GDK:: How to integrate @acronym{GPGME} in GDK. + +@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 Cryptographic 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 possess basic knowledge about cryptography in +general, and public key cryptography in particular. The underlying +cryptographic engines that are used by the library are not explained, +but where necessary, special features or requirements by an engine are +mentioned as far as they are relevant to @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. + +With some precautions, @acronym{GPGME} can be used in a multi-threaded +environment, although it is not completely thread safe and thus needs +the support of the application. + + +@node Preparation +@chapter Preparation + +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. +* Using Automake:: Compiler options to be used the easy way. +* Library Version Check:: Getting and verifying the library version. +* Multi Threading:: How GPGME can be used in an MT environment. +@end menu + + +@node Header +@section Header +@cindex header file +@cindex include file + +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. Symbols internal to @acronym{GPGME} take the form +@code{_gpgme_*}. + +Because @acronym{GPGME} links to the Assuan library, linking to +@acronym{GPGME} will also use the @code{assuan_*} and @code{_assuan_*} +name space indirectly. + + +@node Building the Source +@section Building the Source +@cindex compiler options +@cindex compiler flags + +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 Using Automake +@section Using Automake +@cindex automake +@cindex autoconf + +It is much easier if you use GNU Automake instead writing your own +Makefiles. If you do that you don't have to worry about finding and +invoking the @command{gpgme-config} script at all. @acronym{GPGME} +provides an extension to Automake that does all the work for you. + +@c A simple macro for optional variables. +@macro ovar{varname} +@r{[}@var{\varname\}@r{]} +@end macro +@defmac AM_PATH_GPGME (@ovar{minimum-version}, @ovar{action-if-found}, @ovar{action-if-not-found}) +Check whether @acronym{GPGME} (at least version @var{minimum-version}, +if given) exists on the host system. If it is found, execute +@var{action-if-found}, otherwise do @var{action-if-not-found}, if +given. + +Additionally, the function defines @code{GPGME_CFLAGS} to the flags +needed for compilation of the program to find the @file{gpgme.h} +header file, and @code{GPGME_LIBS} to the linker flags needed to link +the program to the @acronym{GPGME} library. +@end defmac + +You can use the defined Autoconf variables like this in your +@file{Makefile.am}: + +@example +AM_CPPFLAGS = $(GPGME_CFLAGS) +LDADD = $(GPGME_LIBS) +@end example + + +@node Library Version Check +@section Library Version Check +@cindex version check, of the library + +@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 Multi Threading +@section Multi Threading +@cindex thread-safeness +@cindex multi-threading + +The @acronym{GPGME} library is not entirely thread-safe, but it can +still be used in a multi-threaded environment if some care is taken. +If the following requirements are met, there should be no race +conditions to worry about: + +@itemize @bullet +@item +@acronym{GPGME} supports the thread libraries pthread and GNU Pth. +The support for this has to be enabled at compile time. +@acronym{GPGME} will automatically detect the location in which the +thread libraries are installed and activate the support for them. + +Support for other thread libraries is very easy to add. Please +contact us if you have the need. + +@item +If you link your program dynamically to @acronym{GPGME} and your +supported thread library, @acronym{GPGME} will automatically detect +the presence of this library and activate its use. If you link to +both pthread and GNU Pth, @acronym{GPGME} will use the pthread +support. This feature requires weak symbol support. + +@item +If you link your program statically to @acronym{GPGME}, there is +currently no easy way to make sure that @acronym{GPGME} detects the +presence of the thread library. This will be solved in a future +version. + +@item +The function @code{gpgme_check_version} must be called before any +other function in the library, because it initializes the thread +support subsystem in @acronym{GPGME}. To achieve this in all +generality, it is necessary to synchronize the call to this function +with all other calls to functions in the library, using the +synchronization mechanisms available in your thread library. +Otherwise, specific compiler or CPU memory cache optimizations could +lead to the situation where a thread is started and uses +@acronym{GPGME} before the effects of the initialization are visible +for this thread. It doesn't even suffice to call +@code{gpgme_check_version} before creating this other +thread@footnote{In SMP systems the new thread could be started on +another CPU before the effects of the initialization are seen by that +CPU's memory cache. Not doing proper synchronization here leads to +the same problems the double-checked locking idiom has. You might +find that if you don't do proper synchronization, it still works in +most configurations. Don't let this fool you. Someday it might lead +to subtle bugs when someone tries it on a DEC Alpha or an SMP +machine.}. + +For example, if you are using POSIX threads, each thread that wants to +call functions in @acronym{GPGME} could call the following function +before any function in the library: + +@example +#include <pthread.h> + +void +initialize_gpgme (void) +@{ + static int gpgme_init; + static pthread_mutext_t gpgme_init_lock = PTHREAD_MUTEX_INITIALIZER; + + pthread_mutex_lock (&gpgme_init_lock); + if (!gpgme_init) + @{ + gpgme_check_version (); + gpgme_init = 1; + @} + pthread_mutex_unlock (&gpgme_init_lock); +@} +@end example + +@item +Any @code{GpgmeData}, @code{GpgmeCtx} and @code{GpgmeRecipients} +object must only be accessed by one thread at a time. If multiple +threads want to deal with the same object, the caller has to make sure +that operations on this object are fully synchronized. + +@item +Only one thread at any time is allowed to call @code{gpgme_wait}. If +multiple threads call this function, the caller must make sure that +all invocations are fully synchronized. +@end itemize + + +@node Protocols and Engines +@chapter Protocols and Engines +@cindex protocol +@cindex engine +@cindex crypto engine +@cindex backend +@cindex crypto backend + +@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} +@tindex 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 +@cindex version check, of the engines + +@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 +@cindex engine, information about + +@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 +@cindex OpenPGP +@cindex GnuPG +@cindex protocol, GnuPG +@cindex engine, GnuPG + +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 +@cindex CMS +@cindex cryptographic message syntax +@cindex GpgSM +@cindex protocol, CMS +@cindex engine, GpgSM +@cindex S/MIME +@cindex protocol, S/MIME + +@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 +@cindex 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 +@cindex error values, list of + +@deftp {Data type} {enum GpgmeError} +@tindex 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 separate error value for this type of problem. + +@item GPGME_Out_Of_Core +This value means that an out-of-memory condition occurred. + +@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 +cancelled 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 occurred 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 valid recipients for a message have been set. + +@item GPGME_Invalid_Recipients +This value means that some, but not all, recipients for a message have +been invalid. + +@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 occurred. + +@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 +@cindex error values, printing of +@cindex 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. + +The following example illustrates the use of @code{gpgme_strerror}: + +@example +GpgmeCtx ctx; +GpgmeError err = gpgme_new (&ctx); +if (err) + @{ + fprintf (stderr, "%s: creating GpgME context failed: %s\n", + argv[0], gpgme_strerror (err)); + exit (1); + @} +@end example +@end deftypefun + + +@node Exchanging Data +@chapter Exchanging Data +@cindex data, exchanging + +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 +@cindex data buffer, creation + +@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{size_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 +@cindex data buffer, destruction + +@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 +@cindex data buffere, manipulation + +@deftypefun GpgmeError gpgme_data_read (@w{GpgmeData @var{dh}}, @w{void *@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 void *@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 + +@c +@c GpgmeDataType +@c +@deftp {Data type} {enum GpgmeDataType} +@tindex 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 + +@c +@c GpgmeDataEncoding +@c +@deftp {Data type} {enum GpgmeDataEncoding} +@tindex GpgmeDataEncoding +The @code{GpgmeDataEncoding} type specifies the encoding of a +@code{GpgmeData} object. This encoding is useful to give the backend +a hint on the type of data. The following data types are available: + +@table @code +@item GPGME_DATA_ENCODING_NONE +This specifies that the encoding is not known. This is the default +for a new data object. The backend will try its best to detect the +encoding automatically. + +@item GPGME_DATA_ENCODING_BINARY +This specifies that the data is encoding in binary form; i.e. there is +no special encoding. + +@item GPGME_DATA_ENCODING_BASE64 +This specifies that the data is encoded using the Base-64 encoding +scheme as used by @acronym{MIME} and other protocols. + +@item GPGME_DATA_ENCODING_ARMOR +This specifies that the data is encoded in an armored form as used by +OpenPGP and PEM. +@end table +@end deftp + +@deftypefun GpgmeDataEncoding gpgme_data_get_encoding (@w{GpgmeData @var{dh}}) +The function @code{gpgme_data_get_encoding} returns the encoding of +the data object with the handle @var{dh}. If @var{dh} is not a valid +pointer (e.g. @code{NULL}) @code{GPGME_DATA_ENCODING_NONE} is +returned. +@end deftypefun + +@deftypefun GpgmeError gpgme_data_set_encoding (@w{GpgmeData @var{dh}, GpgmeDataEncoding @var{enc}}) +The function @code{gpgme_data_set_encoding} changes the encoding of +the data object with the handle @var{dh} to @var{enc}. +@end deftypefun + + +@c +@c Chapter Contexts +@c +@node Contexts +@chapter Contexts +@cindex context + +All cryptographic 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. +* Run Control:: Controlling how operations are run. +@end menu + + +@node Creating Contexts +@section Creating Contexts +@cindex context, creation + +@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 +@cindex context, destruction + +@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 +@cindex 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. +* Included Certificates:: Including a number of certificates. +* Key Listing Mode:: Selecting key listing mode. +* Passphrase Callback:: Getting the passphrase from the user. +* Progress Meter Callback:: Being informed about the progress. +@end menu + + +@node Protocol Selection +@subsection Protocol Selection +@cindex context, selecting protocol +@cindex protocol, selecting + +@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 + +@deftypefun GpgmeProtocol gpgme_get_protocol (@w{GpgmeCtx @var{ctx}}) +The function @code{gpgme_get_protocol} retrieves the protocol currently +use with the context @var{ctx}. +@end deftypefun + +@node @acronym{ASCII} Armor +@subsection @acronym{ASCII} Armor +@cindex context, armor mode +@cindex @acronym{ASCII} armor +@cindex armor mode + +@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} armored. By default, output is not @acronym{ASCII} +armored. + +@acronym{ASCII} armored 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 +@cindex context, text mode +@cindex text mode +@cindex canonical 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. + +This option is only relevant to the OpenPGP crypto engine, and ignored +by all other engines. + +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 Included Certificates +@subsection Included Certificates +@cindex certificates, included + +@deftypefun void gpgme_set_include_certs (@w{GpgmeCtx @var{ctx}}, @w{int @var{nr_of_certs}}) +The function @code{gpgme_set_include_certs} specifies how many +certificates should be included in an S/MIME signed message. By +default, only the sender's certificate is included. The possible +values of @var{nr_of_certs} are: + +@table @code +@item -2 +Include all certificates except the root certificate. +@item -1 +Include all certificates. +@item 0 +Include no certificates. +@item 1 +Include the sender's certificate only. +@item n +Include the first n certificates of the certificates path, starting +from the sender's certificate. The number @code{n} must be positive. +@end table + +Values of @var{nr_of_certs} smaller than -2 are undefined. + +This option is only relevant to the CMS crypto engine, and ignored +by all other engines. +@end deftypefun + +@deftypefun int gpgme_get_include_certs (@w{GpgmeCtx @var{ctx}}) +The function @code{gpgme_get_include_certs} returns the number of +certificates to include into an S/MIME signed message. +@end deftypefun + + +@node Key Listing Mode +@subsection Key Listing Mode +@cindex key listing mode +@cindex key listing, mode of + +@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. The value in @var{mode} is a +bitwise-or combination of one or multiple of the following bit values: + +@table @code +@item GPGME_KEYLIST_MODE_LOCAL +The @code{GPGME_KEYLIST_MODE_LOCAL} symbol specifies that the local +keyring should be searched for keys in the keylisting operation. This +is the default. + +@item GPGME_KEYLIST_MODE_EXTERN +The @code{GPGME_KEYLIST_MODE_EXTERN} symbol specifies that an external +source should be should be searched for keys in the keylisting +operation. The type of external source is dependant on the crypto +engine used. For example, it can be a remote keyserver or LDAP +certificate server. +@end table + +At least one of @code{GPGME_KEYLIST_MODE_LOCAL} and +@code{GPGME_KEYLIST_MODE_EXTERN} must be specified. For future binary +compatibility, you should get the current mode with +@code{gpgme_get_keylist_mode} and modify it by setting or clearing the +appropriate bits, and then using that calulcated value in the +@code{gpgme_set_keylisting_mode} operation. This will leave all other +bits in the mode value intact (in particular those that are not used +in the current version of the library). + +The function returns @code{GPGME_No_Error} if the mode could be set +correctly, and @code{GPGME_Invalid_Value} if @var{ctx} is not a valid +pointer or @var{mode} is not a valid mode. +@end deftypefun + + +@deftypefun int gpgme_get_keylist_mode (@w{GpgmeCtx @var{ctx}}) +The function @code{gpgme_get_keylist_mode} returns the current key +listing mode of the context @var{ctx}. This value can then be +modified and used in a subsequent @code{gpgme_set_keylist_mode} +operation to only affect the desired bits (and leave all others +intact). + +The function returns 0 if @var{ctx} is not a valid pointer, and the +current mode otherwise. Note that 0 is not a valid mode value. +@end deftypefun + + +@node Passphrase Callback +@subsection Passphrase Callback +@cindex callback, passphrase +@cindex passphrase callback + +@deftp {Data type} {const char *(*GpgmePassphraseCb)(void *@var{hook}, const char *@var{desc}, void **@var{r_hd})} +@tindex GpgmePassphraseCb +The @code{GpgmePassphraseCb} type is the type of functions usable as +passphrase callback function. + +The string @var{desc} contains a text usable to be displayed to the +user of the application. The function should return a passphrase for +the context when invoked with @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 + +@deftypefun void gpgme_get_passphrase_cb (@w{GpgmeCtx @var{ctx}}, @w{GpgmePassphraseCb *@var{passfunc}}, @w{void **@var{hook_value}}) +The function @code{gpgme_get_passphrase_cb} returns the function that +is used when a passphrase needs to be provided by the user in +@var{*passfunc}, and the first argument for this function in +@var{*hook_value}. If no passphrase callback is set, or @var{ctx} is +not a valid pointer, @code{NULL} is returned in both variables. + +@var{passfunc} or @var{hook_value} can be @code{NULL}. In this case, +the corresponding value will not be returned. +@end deftypefun + + +@node Progress Meter Callback +@subsection Progress Meter Callback +@cindex callback, progress meter +@cindex 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})} +@tindex GpgmeProgressCb +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 + +@deftypefun void gpgme_get_progress_cb (@w{GpgmeCtx @var{ctx}}, @w{GpgmeProgressCb *@var{progfunc}}, @w{void **@var{hook_value}}) +The function @code{gpgme_get_progress_cb} returns the function that is +used to inform the user about the progress made in @var{*progfunc}, +and the first argument for this function in @var{*hook_value}. If no +progress callback is set, or @var{ctx} is not a valid pointer, +@code{NULL} is returned in both variables. + +@var{progfunc} or @var{hook_value} can be @code{NULL}. In this case, +the corresponding value will not be returned. +@end deftypefun + + +@node Key Management +@section Key Management +@cindex 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. +* Generating Keys:: Creating new key pairs. +* Exporting Keys:: Retrieving key data from the key ring. +* Importing Keys:: Adding keys to the key ring. +* Deleting Keys:: Removing keys from the key ring. +@end menu + + +@node Listing Keys +@subsection Listing Keys +@cindex listing keys +@cindex key listing +@cindex key listing, start +@cindex key ring, list +@cindex key ring, search + +@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_ext_start (@w{GpgmeCtx @var{ctx}}, @w{const char *@var{pattern}[]}, @w{int @var{secret_only}}, @w{int @var{reserved}}) +The function @code{gpgme_op_keylist_ext_start} initiates an extended +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} or @var{*pattern} is @code{NULL}, all available keys +are returned. Otherwise, @var{pattern} is a @code{NULL} terminated +array of strings that are used to limit the list to all keys matching +at least one of the patterns verbatim. + +If @var{secret_only} is not @code{0}, the list is restricted to secret +keys only. + +The value of @var{reserved} must be @code{0}. + +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 + +The following example illustrates how all keys containing a certain +string (@code{g10code}) can be listed with their key ID and the name +and e-mail address of the main user ID: + +@example +GpgmeCtx ctx; +GpgmeError err = gpgme_new (&ctx); + +if (!err) + @{ + err = gpgme_op_keylist_start (ctx, "g10code", 0); + while (!err && (err = gpgme_op_keylist_next (ctx, &key)) != GPGME_EOF) + @{ + printf ("%s: %s <%s>\n", + gpgme_key_get_string_attr (key, GPGME_ATTR_KEYID, 0, 0), + gpgme_key_get_string_attr (key, GPGME_ATTR_NAME, 0, 0), + gpgme_key_get_string_attr (key, GPGME_ATTR_EMAIL, 0, 0)); + gpgme_key_release (key); + @} + gpgme_release (ctx); + @} +if (err) + @{ + fprintf (stderr, "%s: can not list keys: %s\n", + argv[0], gpgme_strerror (err)); + exit (1); + @} +@end example + + +@node Information About Keys +@subsection Information About Keys +@cindex key, information about +@cindex key, attributes +@cindex attributes, of a key + +@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 +This is the expiration time of a sub key. It is representable as a +number. + +@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 returns information about the type of key. For the string function +this will eother be "PGP" or "X.509". The integer function returns 0 +for PGP and 1 for X.509. It is also used for the type of a trust item. + +@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 @code{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. + +@item GPGME_ATTR_SERIAL +The X.509 issuer serial attribute of the key. It is representable as +a string. + +@item GPGME_ATTR_ISSUE +The X.509 issuer name attribute of the key. It is representable as a +string. + +@item GPGME_ATTR_CHAINID +The X.509 chain ID can be used to build the certification chain. It +is representable as a string. +@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 is an attribute of a sub key or an user ID, @var{idx} +specifies the sub key or user ID of which the attribute value is +returned. 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 is an attribute of a sub key or an user ID, @var{idx} +specifies the sub key or user ID of which the attribute value is +returned. 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 +@cindex key, manipulation + +@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 Generating Keys +@subsection Generating Keys +@cindex key, creation +@cindex key ring, add + +@deftypefun GpgmeError gpgme_op_genkey (@w{GpgmeCtx @var{ctx}}, @w{const char *@var{parms}}, @w{GpgmeData @var{pubkey}}, @w{GpgmeData @var{seckey}}) +The function @code{gpgme_op_genkey} generates a new key pair in the +context @var{ctx} and puts it into the standard key ring if both +@var{pubkey} and @var{seckey} are @code{NULL}. In this case the +function returns immediately after starting the operation, and does +not wait for it to complete. If @var{pubkey} is not @code{NULL} it +should be the handle for an empty (newly created) data object, and +upon successful completion the data object will contain the public +key. If @var{seckey} is not @code{NULL} it should be the handle for +an empty (newly created) data object, and upon successful completion +the data object will contain the secret key. + +Note that not all crypto engines support this interface equally. +GnuPG does not support @var{pubkey} and @var{subkey}, they should be +both @code{NULL}, and the key pair will be added to the standard key +ring. GpgSM does only support @var{pubkey}, the secret key will be +stored by @command{gpg-agent}. GpgSM expects @var{pubkey} being not +@code{NULL}. + +The argument @var{parms} specifies parameters for the key in an XML +string. The details about the format of @var{parms} are specific to +the crypto engine used by @var{ctx}. Here is an example for GnuPG as +the crypto engine: + +@example +<GnupgKeyParms format="internal"> +Key-Type: DSA +Key-Length: 1024 +Subkey-Type: ELG-E +Subkey-Length: 1024 +Name-Real: Joe Tester +Name-Comment: with stupid passphrase +Name-Email: joe@@foo.bar +Expire-Date: 0 +Passphrase: abc +</GnupgKeyParms> +@end example + +Here is an example for GpgSM as the crypto engine: +@example +<GnupgKeyParms format="internal"> +Key-Type: RSA +Key-Length: 1024 +Name-DN: C=de,O=g10 code,OU=Testlab,CN=Joe 2 Tester +Name-Email: joe@@foo.bar +</GnupgKeyParms> +@end example + +Strings should be given in UTF-8 encoding. The only format supported +for now is ``internal''. The content of the @code{GnupgKeyParms} +container is passed verbatim to GnuPG. Control statements are not +allowed. + +The function returns @code{GPGME_No_Error} if the operation could be +started successfully, @code{GPGME_Invalid_Value} if @var{parms} is not +a valid XML string, @code{GPGME_Not_Supported} if @var{pubkey} or +@var{seckey} is not valid, and @code{GPGME_General_Error} if no key +was created by the backend. +@end deftypefun + +@deftypefun GpgmeError gpgme_op_genkey_start (@w{GpgmeCtx @var{ctx}}, @w{const char *@var{parms}}, @w{GpgmeData @var{pubkey}}, @w{GpgmeData @var{seckey}}) +The function @code{gpgme_op_genkey_start} initiates a +@code{gpgme_op_genkey} operation. It can be completed by calling +@code{gpgme_wait} on the context. @xref{Waiting For Completion}. + +The function returns @code{GPGME_No_Error} if the operation could be +started successfully, @code{GPGME_Invalid_Value} if @var{parms} is not +a valid XML string, and @code{GPGME_Not_Supported} if @var{pubkey} or +@var{seckey} is not @code{NULL}. +@end deftypefun + + +@node Exporting Keys +@subsection Exporting Keys +@cindex key, export +@cindex key ring, export from + +@deftypefun GpgmeError gpgme_op_export (@w{GpgmeCtx @var{ctx}}, @w{GpgmeRecipients @var{recipients}}, @w{GpgmeData @var{keydata}}) +The function @code{gpgme_op_export} extracts the public keys of the +user IDs in @var{recipients} and returns them in the data buffer +@var{keydata}. The type of the public keys returned is determined by +the @acronym{ASCII} armor attribute set for the context @var{ctx}. + +The function returns @code{GPGME_No_Error} if the operation completed +successfully, @code{GPGME_Invalid_Value} if @var{recipients} is +@code{NULL} or @var{keydata} is not a valid empty data buffer, and +passes through any errors that are reported by the crypto engine +support routines. +@end deftypefun + +@deftypefun GpgmeError gpgme_op_export_start (@w{GpgmeCtx @var{ctx}}, @w{GpgmeRecipients @var{recipients}}, @w{GpgmeData @var{keydata}}) +The function @code{gpgme_op_export_start} initiates a +@code{gpgme_op_export} operation. It can be completed by calling +@code{gpgme_wait} on the context. @xref{Waiting For Completion}. + +The function returns @code{GPGME_No_Error} if the operation could be +started successfully, and @code{GPGME_Invalid_Value} if +@var{recipients} is @code{NULL} or @var{keydata} is not a valid empty +data buffer. +@end deftypefun + + +@node Importing Keys +@subsection Importing Keys +@cindex key, import +@cindex key ring, import to + +@deftypefun GpgmeError gpgme_op_import (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{keydata}}) +The function @code{gpgme_op_import} adds the keys in the data buffer +@var{keydata} to the key ring of the crypto engine used by @var{ctx}. +The format of @var{keydata} can be @var{ASCII} armored, for example, +but the details are specific to the crypto engine. + +More information about the import is available with +@code{gpgme_get_op_info}. @xref{Detailed Results}. + +The function returns @code{GPGME_No_Error} if the import was completed +successfully, @code{GPGME_Invalid_Value} if @var{keydata} if @var{ctx} +or @var{keydata} is not a valid pointer, and @code{GPGME_No_Data} if +@var{keydata} is an empty data buffer. +@end deftypefun + +@deftypefun GpgmeError gpgme_op_import_start (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{keydata}}) +The function @code{gpgme_op_import_start} initiates a +@code{gpgme_op_import} operation. It can be completed by calling +@code{gpgme_wait} on the context. @xref{Waiting For Completion}. + +The function returns @code{GPGME_No_Error} if the import could be +started successfully, @code{GPGME_Invalid_Value} if @var{keydata} if +@var{ctx} or @var{keydata} is not a valid pointer, and +@code{GPGME_No_Data} if @var{keydata} is an empty data buffer. +@end deftypefun + +@deftypefun GpgmeError gpgme_op_import_ext (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{keydata}}, @w{int *@var{nr}}) +The function @code{gpgme_op_import_ext} is like +@code{gpgme_op_import}, but also returns the number of processed keys +in @var{nr}. This is the same as the @code{count} information in the +detailed results available with @code{gpgme_get_op_info}. +@end deftypefun + + +@node Deleting Keys +@subsection Deleting Keys +@cindex key, delete +@cindex key ring, delete from + +@deftypefun GpgmeError gpgme_op_delete (@w{GpgmeCtx @var{ctx}}, @w{const GpgmeKey @var{key}}, @w{int @var{allow_secret}}) +The function @code{gpgme_op_delete} deletes the key @var{key} from the +key ring of the crypto engine used by @var{ctx}. If +@var{allow_secret} is @code{0}, only public keys are deleted, +otherwise secret keys are deleted as well, if that is supported. + +The function returns @code{GPGME_No_Error} if the key was deleted +successfully, @code{GPGME_Invalid_Value} if @var{ctx} or @var{key} is +not a valid pointer, @code{GPGME_Invalid_Key} if @var{key} could not +be found in the keyring, and @code{GPGME_Conflict} if the secret key +for @var{key} is available, but @var{allow_secret} is zero. +@end deftypefun + +@deftypefun GpgmeError gpgme_op_delete_start (@w{GpgmeCtx @var{ctx}}, @w{const GpgmeKey @var{key}}, @w{int @var{allow_secret}}) +The function @code{gpgme_op_delete_start} initiates a +@code{gpgme_op_delete} operation. It can be completed by calling +@code{gpgme_wait} on the context. @xref{Waiting For Completion}. + +The function returns @code{GPGME_No_Error} if the operation was +started successfully, and @code{GPGME_Invalid_Value} if @var{ctx} or +@var{key} is not a valid pointer. +@end deftypefun + + +@node Trust Item Management +@section Trust Item Management +@cindex trust item + +@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 +@cindex trust item list + +@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 trust 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 +@cindex trust item, information about +@cindex trust item, attributes +@cindex attributes, of a trust item + +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}. The arguments @var{idx} and @var{reserved} are reserved +for later use and should be @code{0} and @code{NULL} respectively. + +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 +@cindex trust item, manipulation + +@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 +@cindex cryptographic operation + +@menu +* Decrypt:: Decrypting a ciphertext. +* Verify:: Verifying a signature. +* Decrypt and Verify:: Decrypting a signed ciphertext. +* Sign:: Creating a signature. +* Encrypt:: Encrypting a plaintext. +* Detailed Results:: How to obtain more info about the operation. +@end menu + + +@node Decrypt +@subsection Decrypt +@cindex decryption +@cindex cryptographic operation, decryption + +@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 + +@deftypefun GpgmeError gpgme_op_decrypt_start (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{cipher}}, @w{GpgmeData @var{plain}}) +The function @code{gpgme_op_decrypt_start} initiates a +@code{gpgme_op_decrypt} operation. It can be completed by calling +@code{gpgme_wait} on the context. @xref{Waiting For Completion}. + +The function returns @code{GPGME_No_Error} if the operation could be +started successfully, and @code{GPGME_Invalid_Value} if @var{cipher} +or @var{plain} is not a valid pointer. +@end deftypefun + + +@node Verify +@subsection Verify +@cindex verification +@cindex signature, verification +@cindex cryptographic operation, verification +@cindex cryptographic operation, signature check +@cindex signature, status + +@deftp {Data type} {enum GpgmeSigStat} +@tindex 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_GOOD_EXP +This status indicates that the signature is valid but expired. For +the combined result this status means that all signatures are valid +and expired. + +@item GPGME_SIG_STAT_GOOD_EXPKEY +This status indicates that the signature is valid but the key used to +verify the signature has expired. For the combined result this status +means that all signatures are valid and all keys are expired. + +@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 signature in the +data object @var{sig} is a valid signature. If @var{plain} is +initialized with plaintext data, it is assumed that @var{sig} is a +detached signature, and its validity for the plaintext given in +@var{plain} is verified. If @var{plain} is an uninitialized data +object, it is assumed that @var{sig} is a normal (or cleartext) +signature, and the plaintext is available in @var{plain} after +successful verification. + +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} does not contain any data to verify, +and passes through any errors that are reported by the crypto engine +support routines. +@end deftypefun + +@deftypefun GpgmeError gpgme_op_verify_start (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{sig}}, @w{GpgmeData @var{plain}}) +The function @code{gpgme_op_verify_start} initiates a +@code{gpgme_op_verify} operation. It can be completed by calling +@code{gpgme_wait} on the context. @xref{Waiting For Completion}. + +The function returns @code{GPGME_No_Error} if the operation could be +started successfully, @code{GPGME_Invalid_Value} if @var{ctx}, +@var{sig}, @var{plain} or @var{r_stat} is not a valid pointer, and +@code{GPGME_No_Data} if @var{sig} or @var{plain} does not contain any +data to verify. +@end deftypefun + +@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_string_attr (@w{GpgmeCtx @var{ctx}}, @w{int @var{idx}}, @w{GpgmeAttr @var{what}}, @w{int @var{whatidx}}) +This function is similar to @code{gpgme_get_sig_status} but may be used +to retrieve more detailed information. @var{ctx} should be the context +used for the last signature verification, @var{idx} is used to enumerate +over all signatures starting with @code{0} and @var{whatidx} should be +@code{0} unless otherwise stated. + +The following values may be used for @var{what}: +@table @code +@item GPGME_ATTR_FPR +Return the fingerprint of the key used to create the signature. + +@item GPGME_ATTR_ERRTOK +Return a token with a more detailed error description. A @var{whatidx} +of @code{0} returns an error token associated with validity calculation, +a value of @code{1} return an error token related to the certificate +checking. + +@end table +@end deftypefun + +@deftypefun {const char *} gpgme_get_sig_ulong_attr (@w{GpgmeCtx @var{ctx}}, @w{int @var{idx}}, @w{GpgmeAttr @var{waht}}, @w{int @var{whatidx}}) +This function is similar to @code{gpgme_get_sig_string_attr} but used +for attributes which can be represented by an @code{unsigned long} data +type. @var{ctx} should be the context used for the last signature +verification, @var{idx} is used to enumerate over all signatures +starting with @code{0} and @var{whatidx} should be @code{0} unless +otherwise stated. + +The following values may be used for @var{what}: +@table @code +@item GPGME_ATTR_CREATED +Return the creation time of the signature in seconds since Epoch. This +is the same value as returned by @code{gpgme_get_sig_status}. + +@item GPGME_ATTR_EXPIRE +Return the expiration time of the signature in seconds since Epoch. + +@item GPGME_ATTR_VALIDITY +Returns the validity of the key used to create the signature. This is a +shortcut function which avoids an extra key lookup. The value returned +is one of @code{GPGME_VALIDITY_UNKNOWN}, @code{GPGME_VALIDITY_NEVER}, +@code{GPGME_VALIDITY_MARGINAL} or @code{GPGME_VALIDITY_FULL}. + +@item GPGME_ATTR_SIG_STATUS +This is the same value as returned by @code{gpgme_get_sig_status}. + +@item GPGME_ATTR_SIG_SUMMARY +This returns a bit vector giving a summary of the signature status. +Itprovides an easy interface to a defined semantic of the signature +status. Checking just one bit is sufficient to see whether a signature +is valid without any restrictions. + +The defined bits are: + @table @code + @item GPGME_SIGSUM_VALID + The signature is fully valid. + + @item GPGME_SIGSUM_GREEN + The signature is good but one might want to display some extra + information. Check the other bits. + + @item GPGME_SIGSUM_RED + The signature is bad. It might be useful to checkother bits and + display moe information, i.e. a revoked certificate might not render a + signature invalid when the message was received prior to the cause for + the revocation. + + @item GPGME_SIGSUM_KEY_REVOKED + The key or at least one certificate has been revoked. + + @item GPGME_SIGSUM_KEY_EXPIRED + The key or one of the certificates has expired. It is probably a good + idea to display the date of the expiration. + + @item GPGME_SIGSUM_SIG_EXPIRED + The signature has expired. + + @item GPGME_SIGSUM_KEY_MISSING + Can't verifydue to a missing key o certificate. + + @item GPGME_SIGSUM_CRL_MISSING + The CRL (or an equivalent mechanism) is not available. + + @item GPGME_SIGSUM_CRL_TOO_OLD + Available CRL is too old. + + @item GPGME_SIGSUM_BAD_POLICY + A policy requirement was not met. + + @item GPGME_SIGSUM_SYS_ERROR + A system error occured. + + @end table + +@end table +@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 occurred requesting the key. +@end deftypefun + +@deftypefun {char *} gpgme_get_notation (@w{GpgmeCtx @var{ctx}}) +The function @code{gpgme_get_notation} can be used to retrieve +notation data from the last signature check in the context @var{ctx}. + +If there is notation data available from the last signature check, +this function may be used to return this notation data as a string. +The string is an XML representation of that data embedded in a +<notation> container. The user has to release the string with +@code{free}. + +The function returns a string if the notation data is available or +@code{NULL} if there is no such data available. +@end deftypefun + + +@node Decrypt and Verify +@subsection Decrypt and Verify +@cindex decryption and verification +@cindex verification and decryption +@cindex signature check +@cindex cryptographic operation, decryption and verification + +@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 + +@deftypefun GpgmeError gpgme_op_decrypt_verify (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{cipher}}, @w{GpgmeData @var{plain}}) +The function @code{gpgme_op_decrypt_verify_start} initiates a +@code{gpgme_op_decrypt_verify} operation. It can be completed by +calling @code{gpgme_wait} on the context. @xref{Waiting For +Completion}. + +The function returns @code{GPGME_No_Error} if the operation could be +started successfully, @code{GPGME_Invalid_Value} if @var{ctx}, +@var{cipher}, @var{plain} or @var{r_stat} is not a valid pointer, and +@code{GPGME_No_Data} if @var{cipher} does not contain any data to +decrypt. +@end deftypefun + + +@node Sign +@subsection Sign +@cindex signature, creation +@cindex sign +@cindex cryptographic operation, signing + +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 +@cindex signature, selecting signers +@cindex signers, selecting + +@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}. + +Calling this function acquires an additional reference for the key. +@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} +@tindex 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} armor and text mode attributes set for the context +@var{ctx} and the requested signature mode @var{mode}. + +More information about the signatures is available with +@code{gpgme_get_op_info}. @xref{Detailed Results}. + +If an S/MIME signed message is created using the CMS crypto engine, +the number of certificates to include in the message can be specified +with @code{gpgme_set_include_certs}. @xref{Included Certificates}. + +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 + +@deftypefun GpgmeError gpgme_op_sign_start (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{plain}}, @w{GpgmeData @var{sig}}, @w{GpgmeSigMode @var{mode}}) +The function @code{gpgme_op_sign_start} initiates a +@code{gpgme_op_sign} operation. It can be completed by calling +@code{gpgme_wait} on the context. @xref{Waiting For Completion}. + +The function returns @code{GPGME_No_Error} if the operation could be +started successfully, and @code{GPGME_Invalid_Value} if @var{ctx}, +@var{plain} or @var{sig} is not a valid pointer. +@end deftypefun + + +@node Encrypt +@subsection Encrypt +@cindex encryption +@cindex cryptographic operation, encryption + +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 +@cindex encryption, selecting recipients +@cindex 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_encrypt} 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} armor and text +mode attributes set for the context @var{ctx}. + +If @code{GPGME_Invalid_Recipients} is returned, some recipients in +@var{rset} are invalid, but not all. In this case the plaintext is +encrypted for all valid recipients and returned in @var{cipher}. More +information about the invalid recipients is available with +@code{gpgme_get_op_info}. @xref{Detailed Results}. + +If @var{recp} is @code{NULL}, symmetric rather than public key +encryption is performed. Symmetrically encrypted cipher text can be +deciphered with @code{gpgme_op_decrypt}. Note that in this case the +crypto backend needs to retrieve a passphrase from the user. +Symmetric encryption is currently only supported for the OpenPGP +crypto backend. + +The function returns @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_Recipients} if @var{rset} does not contain any valid +recipients, @code{GPGME_Invalid_Recipients} if @var{rset} contains +some invalid 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 + +@deftypefun GpgmeError gpgme_op_encrypt_start (@w{GpgmeCtx @var{ctx}}, @w{GpgmeRecipients @var{rset}}, @w{GpgmeData @var{plain}}, @w{GpgmeData @var{cipher}}) +The function @code{gpgme_op_encrypt_start} initiates a +@code{gpgme_op_encrypt} operation. It can be completed by calling +@code{gpgme_wait} on the context. @xref{Waiting For Completion}. + +The function returns @code{GPGME_No_Error} if the operation could be +started successfully, @code{GPGME_Invalid_Value} if @var{ctx}, +@var{rset}, @var{plain} or @var{cipher} is not a valid pointer, and +@code{GPGME_No_Recipients} if @var{rset} does not contain any valid +recipients. +@end deftypefun + + +@deftypefun GpgmeError gpgme_op_encrypt_sign (@w{GpgmeCtx @var{ctx}}, @w{GpgmeRecipients @var{rset}}, @w{GpgmeData @var{plain}}, @w{GpgmeData @var{cipher}}) +The function @code{gpgme_op_encrypt_sign} does a combined encrypt and +sign operation. It is used like @code{gpgme_op_encrypt}, but the +ciphertext also contains signatures for the signers listed in +@var{ctx}. + +The combined encrypt and sign operation is currently only available +for the OpenPGP crypto engine. +@end deftypefun + +@deftypefun GpgmeError gpgme_op_encrypt_sign_start (@w{GpgmeCtx @var{ctx}}, @w{GpgmeRecipients @var{rset}}, @w{GpgmeData @var{plain}}, @w{GpgmeData @var{cipher}}) +The function @code{gpgme_op_encrypt_sign_start} initiates a +@code{gpgme_op_encrypt_sign} operation. It can be completed by +calling @code{gpgme_wait} on the context. @xref{Waiting For +Completion}. + +The function returns @code{GPGME_No_Error} if the operation could be +started successfully, @code{GPGME_Invalid_Value} if @var{ctx}, +@var{rset}, @var{plain} or @var{cipher} is not a valid pointer, and +@code{GPGME_No_Recipients} if @var{rset} does not contain any valid +recipients. +@end deftypefun + + +@node Detailed Results +@subsection Detailed Results +@cindex cryptographic operation, detailed results + +@deftypefun {char *} gpgme_get_op_info (@w{GpgmeCtx @var{ctx}}, @w{int @var{reserved}}) +The function @code{gpgme_get_op_info} retrieves more information about +the last crypto operation. + +The function returns a string in the XML format. The user has to +release the string with @code{free}. + +Here is a sample of the information that might be returned: +@example +<GnupgOperationInfo> + <signature> + <detached/> <!-- or cleartext or standard --> + <algo>17</algo> + <hashalgo>2</hashalgo> + <micalg>pgp-sha1</micalg> + <sigclass>01</sigclass> + <created>9222222</created> + <fpr>121212121212121212</fpr> + </signature> +</GnupgOperationInfo> +@end example + +Currently, the only operations that return additional information are +encrypt, sign and import. @xref{Encrypt}, @xref{Sign}, +@xref{Importing Keys}. + +The function returns a string or @code{NULL} if no such data is +available. +@end deftypefun + + +@node Run Control +@section Run Control +@cindex run control +@cindex cryptographic operation, running + +@acronym{GPGME} supports running operations synchronously and +asynchronously. You can use asynchronous operation to set up a +context up to initiating the desired operation, but delay performing +it to a later point. + +Furthermore, you can use an external event loop to control exactly +when @acronym{GPGME} runs. This ensures that @acronym{GPGME} only +runs when necessary and also prevents it from blocking for a long +time. + +@menu +* Waiting For Completion:: Waiting until an operation is completed. +* Cancelling an Operation:: Interrupting a running operation. +* Hooking Up Into Idle Time:: Doing something when nothing has to be done. +* Using External Event Loops:: Advanced control over what happens when. +@end menu + + +@node Waiting For Completion +@subsection Waiting For Completion +@cindex cryptographic operation, wait for +@cindex wait for completion + +@deftypefun GpgmeCtx gpgme_wait (@w{GpgmeCtx @var{ctx}}, @w{GpgmeError *@var{status}}, @w{int @var{hang}}) +The function @code{gpgme_wait} continues the pending operation within +the context @var{ctx}. In particular, it ensures the data exchange +between @acronym{GPGME} and the crypto backend and watches over the +run time status of the backend process. + +If @var{hang} is true, the function does not return until the +operation is completed or cancelled. Otherwise the function will not +block for a long time. + +The error status of the finished operation is returned in @var{status} +if @code{gpgme_wait} does not return @code{NULL}. + +The @var{ctx} argument can be @code{NULL}. In that case, +@code{gpgme_wait} waits for any context to complete its operation. + +@code{gpgme_wait} can be used only in conjunction with any context +that has a pending operation initiated with one of the +@code{gpgme_op_*_start} functions except @code{gpgme_op_keylist_start} +and @code{gpgme_op_trustlist_start} (for which you should use the +corresponding @code{gpgme_op_*_next} functions). If @var{ctx} is +@code{NULL}, all of such contexts are waited upon and possibly +returned. Synchronous operations running in parallel, as well as key +and trust item list operations, do not affect @code{gpgme_wait}. + +In a multi-threaded environment, only one thread should ever call +@code{gpgme_wait} at any time, irregardless if @var{ctx} is specified +or not. This means that all calls to this function should be fully +synchronized by locking primitives. + +The function returns the @var{ctx} of the context which has finished +the operation. +@end deftypefun + + +@node Cancelling an Operation +@subsection Cancelling an Operation +@cindex cancellation +@cindex cryptographic operation, cancel + +@deftypefun void gpgme_cancel (@w{GpgmeCtx @var{ctx}}) +The function @code{gpgme_cancel} tries to cancel the pending +operation. A running synchronous operation in the context or the +function @code{gpgme_wait} with this context as its @var{ctx} argument +might notice the cancellation flag and return. It is currently not +guaranteed to work under all circumstances. Its current primary +purpose is to prevent asking for a passphrase again in the passphrase +callback. +@end deftypefun + + +@node Hooking Up Into Idle Time +@subsection Hooking Up Into Idle Time +@cindex idle time +@cindex idle function + +@deftp {Data type} {void (*GpgmeIdleFunc) (void)} +@tindex GpgmeIdleFunc +The @code{GpgmeIdleFunc} type is the type of functions usable as +an idle function that can be registered with @code{gpgme_register_idle}. +@end deftp + +@deftypefun GpgmeIdleFunc gpgme_register_idle (@w{GpgmeIdleFunc @var{idle}}) +The function @code{gpgme_register_idle} can be used to register +@var{idle} as the idle function. + +@var{idle} will be called whenever @acronym{GPGME} thinks that it is +idle and time can better be spent elsewhere. Setting @var{idle} to +@code{NULL} disables use of the idle function (this is the default). + +The function returns the old idle function, or @code{NULL} if none was +registered yet. +@end deftypefun + + +@node Using External Event Loops +@subsection Using External Event Loops +@cindex event loop, external + +@acronym{GPGME} hides the complexity of the communication between the +library and the crypto engine. The price of this convenience is that +the calling thread can block arbitrary long waiting for the data +returned by the crypto engine. In single-threaded programs, in +particular if they are interactive, this is an unwanted side-effect. +OTOH, if @code{gpgme_wait} is used without the @var{hang} option being +enabled, it might be called unnecessarily often, wasting CPU time that +could be used otherwise. + +The I/O callback interface described in this section lets the user +take control over what happens when. @acronym{GPGME} will provide the +user with the file descriptors that should be monitored, and the +callback functions that should be invoked when a file descriptor is +ready for reading or writing. It is then the user's responsibility to +decide when to check the file descriptors and when to invoke the +callback functions. Usually this is done in an event loop, that also +checks for events in other parts of the program. If the callback +functions are only called when the file descriptors are ready, +@acronym{GPGME} will never block. This gives the user mroe control +over the program flow, and allows to perform other tasks when +@acronym{GPGME} would block otherwise. + +By using this advanced mechanism, @acronym{GPGME} can be integrated +smoothly into GUI toolkits like GTK+ even for single-threaded +programs. + +@menu +* I/O Callback Interface:: How I/O callbacks are registered. +* Registering I/O Callbacks:: How to use I/O callbacks for a context. +* I/O Callback Example:: An example how to use I/O callbacks. +* I/O Callback Example GTK+:: How to use @acronym{GPGME} with GTK+. +* I/O Callback Example GDK:: How to use @acronym{GPGME} with GDK. +@end menu + + +@node I/O Callback Interface +@subsubsection I/O Callback Interface + +@deftp {Data type} {void (*GpgmeIOCb) (@w{void *@var{data}}, @w{int @var{fd}})} +@tindex GpgmeIOCb +The @code{GpgmeIOCb} type is the type of functions which +@acronym{GPGME} wants to register as I/O callback handlers using the +@code{GpgmeRegisterIOCb} functions provided by the user. + +@var{data} and @var{fd} are provided by @acronym{GPGME} when the I/O +callback handler is registered, and should be passed through to the +handler when it is invoked by the user because it noticed activity on +the file descriptor @var{fd}. +@end deftp + +@deftp {Data type} {GpgmeError (*GpgmeRegisterIOCb) (@w{void *@var{data}}, @w{int @var{fd}}, @w{int @var{dir}}, @w{GpgmeIOCb @var{fnc}}, @w{void *@var{fnc_data}}, @w{void **@var{tag}})} +@tindex GpgmeRegisterIOCb +The @code{GpgmeRegisterIOCb} type is the type of functions which can +be called by @acronym{GPGME} to register an I/O callback funtion +@var{fnc} for the file descriptor @var{fd} with the user. +@var{fnc_data} should be passed as the first argument to @var{fnc} +when the handler is invoked (the second argument should be @var{fd}). +If @var{dir} is 0, @var{fnc} should be called by the user when +@var{fd} is ready for writing. If @var{dir} is 1, @var{fnc} should be +called when @var{fd} is ready for reading. + +@var{data} was provided by the user when registering the +@code{GpgmeRegisterIOCb} function with @acronym{GPGME} and will always +be passed as the first argument when registering a callback function. +For example, the user can use this to determine the event loop to +which the file descriptor should be added. + +@acronym{GPGME} will call this function when a crypto operation is +initiated in a context for which the user has registered I/O callback +handler functions with @code{gpgme_set_io_cbs}. It can also call this +function when it is in an I/O callback handler for a file descriptor +associated to this context. + +The user should return a unique handle in @var{tag} identifying this +I/O callback registration, which will be passed to the +@code{GpgmeRegisterIOCb} function without interpretation when the file +descriptor should not be monitored anymore. +@end deftp + +@deftp {Data type} {void (*GpgmeRemoveIOCb) (@w{void *@var{tag}})} +The @code{GpgmeRemoveIOCb} type is the type of functions which can be +called by @acronym{GPGME} to remove an I/O callback handler that was +registered before. @var{tag} is the handle that was returned by the +@code{GpgmeRegisterIOCb} for this I/O callback. + +@acronym{GPGME} can call this function when a crypto operation is in +an I/O callback. It will also call this function when the context is +destroyed while an operation is pending. +@end deftp + +@deftp {Data type} {enum GpgmeEventIO} +@tindex GpgmeEventIO +The @code{GpgmeEventIO} type specifies the type of an event that is +reported to the user by @acronym{GPGME} as a consequence of an I/O +operation. The following events are defined: + +@table @code +@item GPGME_EVENT_DONE +The operation is finished, the last I/O callback for this operation +was removed. The accompanying @var{type_data} points to a +@code{GpgmeError} variable that contains the status of the operation +that finished. This event is signalled after the last I/O callback +has been removed. + +@item GPGME_EVENT_NEXT_KEY +In a @code{gpgme_op_keylist_start} operation, the next key was +received from the crypto engine. The accompanying @var{type_data} is +a @code{GpgmeKey} variable that contains the key with one reference +for the user. + +@item GPGME_EVENT_NEXT_TRUSTITEM +In a @code{gpgme_op_trustlist_start} operation, the next trust item +was received from the crypto engine. The accompanying @var{type_data} +is a @code{GpgmeTrustItem} variable that contains the trust item with +one reference for the user. +@end table +@end deftp + +@deftp {Data type} {void (*GpgmeEventIOCb) (@w{void *@var{data}}, @w{GpgmeEventIO @var{type}}, @w{void *@var{type_data}})} +The @code{GpgmeEventIOCb} type is the type of functions which can be +called by @acronym{GPGME} to signal an event for an operation running +in a context which has I/O callback functions registered by the user. + +@var{data} was provided by the user when registering the +@code{GpgmeEventIOCb} function with @acronym{GPGME} and will always be +passed as the first argument when registering a callback function. +For example, the user can use this to determine the context in which +this event has occured. + +@var{type} will specify the type of event that has occured. +@var{type_data} specifies the event further, as described in the above +list of possible @code{GpgmeEventIO} types. + +@acronym{GPGME} can call this function in an I/O callback handler. +@end deftp + + +@node Registering I/O Callbacks +@subsubsection Registering I/O Callbacks + +@deftp {Data type} {struct GpgmeIOCbs} +@tindex GpgmeEventIO +This structure is used to store the I/O callback interface functions +described in the previous section. It has the following members: + +@table @code +@item GpgmeRegisterIOCb add +This is the function called by @acronym{GPGME} to register an I/O +callback handler. It must be specified. + +@item void *add_data +This is passed as the first argument to the @code{add} function when +it is called by @acronym{GPGME}. For example, it can be used to +determine the event loop to which the file descriptor should be added. + +@item GpgmeRemoveIOCb remove +This is the function called by @acronym{GPGME} to remove an I/O +callback handler. It must be specified. + +@item GpgmeEventIOCb event +This is the function called by @acronym{GPGME} to signal an event for +an operation. It is optional, but if you don't specify it, you can +not retrieve the return value of the operation. + +@item void *event_data +This is passed as the first argument to the @code{event} function when +it is called by @acronym{GPGME}. For example, it can be used to +determine the context in which the event has occured. +@end table +@end deftp + +@deftypefun void gpgme_set_io_cbs (@w{GpgmeCtx @var{ctx}}, @w{struct GpgmeIOCbs *@var{io_cbs}}) +The function @code{gpgme_set_io_cbs} enables the I/O callback +interface for the context @var{ctx}. The I/O callback functions are +specified by @var{io_cbs}. + +If @var{io_cbs}->@code{add} is @code{NULL}, the I/O callback interface +is disabled for the context, and normal operation is restored. +@end deftypefun + +@deftypefun void gpgme_get_io_cbs (@w{GpgmeCtx @var{ctx}}, @w{struct GpgmeIOCbs *@var{io_cbs}}) +The function @code{gpgme_get_io_cbs} returns the I/O callback +functions set with @code{gpgme_set_io_cbs} in @var{io_cbs}. +@end deftypefun + + +@node I/O Callback Example +@subsubsection I/O Callback Example + +To actually use an external event loop, you have to implement the I/O +callback functions that are used by @acronym{GPGME} to register and +unregister file descriptors. Furthermore, you have to actually +monitor these file descriptors for activity and call the appropriate +I/O callbacks. + +The following example illustrates how to do that. The example uses +locking to show in which way the the callbacks and the event loop can +run concurrently. For the event loop, we use a fixed array. For a +real-world implementation, you should use a dynamically sized +structure because the number of file descriptors needed for a crypto +operation in @acronym{GPGME} is not predictable. + +@example +#include <pthread.h> +#include <sys/types.h> +#include <gpgme.h> + +/* The following structure holds the result of a crypto operation. */ +struct op_result +@{ + int done; + GpgmeError err; +@}; + +/* The following structure holds the data associated with one I/O +callback. */ +struct one_fd +@{ + int fd; + int dir; + GpgmeIOCb fnc; + void *fnc_data; +@}; + +struct event_loop +@{ + pthread_mutex_t lock; +#define MAX_FDS 32 + /* Unused slots are marked with FD being -1. */ + struct one_fd fds[MAX_FDS]; +@}; +@end example + +The following functions implement the I/O callback interface. + +@example +GpgmeError +add_io_cb (void *data, int fd, int dir, GpgmeIOCb fnc, void *fnc_data, + void **r_tag) +@{ + struct event_loop *loop = data; + struct one_fd *fds = loop->fds; + int i; + + pthread_mutex_lock (&loop->lock); + for (i = 0; i < MAX_FDS; i++) + @{ + if (fds[i].fd == -1) + @{ + fds[i].fd = fd; + fds[i].dir = dir; + fds[i].fnc = fnc; + fds[i].fnc_data = fnc_data; + break; + @} + @} + pthread_mutex_unlock (&loop->lock); + if (i == MAX_FDS) + return GPGME_General_Error; + *r_tag = &fds[i]; + return 0; +@} + +void +remove_io_cb (void *tag) +@{ + struct one_fd *fd = tag; + + pthread_mutex_lock (&loop->lock); + fd->fd = -1; + pthread_mutex_unlock (&loop->lock); +@} + +void +event_io_cb (void *data, GpgmeEventIO type, void *type_data) +@{ + struct op_result *result = data; + GpgmeError *err = data; + + /* We don't support list operations here. */ + if (type == GPGME_EVENT_DONE) + @{ + result->done = 1; + result->err = *data; + @} +@} +@end example + +The final missing piece is the event loop, which will be presented +next. We only support waiting for the success of a single operation. + +@example +int +do_select (struct event_loop *loop) +@{ + fd_set rfds; + fd_set wfds; + int i, n; + int any = 0; + + pthread_mutex_lock (&loop->lock); + FD_ZERO (&rfds); + FD_ZERO (&wfds); + for (i = 0; i < FDLIST_MAX; i++) + if (fdlist[i].fd != -1) + FD_SET (fdlist[i].fd, fdlist[i].dir ? &rfds : &wfds); + pthread_mutex_unlock (&loop->unlock); + + do + @{ + n = select (FD_SETSIZE, &rfds, &wfds, NULL, 0); + @} + while (n < 0 && errno == EINTR); + + if (n < 0) + return n; /* Error or timeout. */ + + pthread_mutex_lock (&loop->lock); + for (i = 0; i < FDLIST_MAX && n; i++) + @{ + if (fdlist[i].fd != -1) + @{ + if (FD_ISSET (fdlist[i].fd, fdlist[i].dir ? &rfds : &wfds)) + @{ + assert (n); + n--; + any = 1; + /* The I/O callback handler can register/remove callbacks, + so we have to unlock the file descriptor list. */ + pthread_mutex_unlock (&loop->lock); + (*fdlist[i].fnc) (fdlist[i].fnc_data, fdlist[i].fd); + pthread_mutex_lock (&loop->lock); + @} + @} + @} + pthread_mutex_unlock (&loop->lock); + return any; +@} + +void +wait_for_op (struct event_loop *loop, struct op_result *result) +@{ + int ret; + + do + @{ + ret = do_select (loop); + @} + while (ret >= 0 && !result->done); + return ret; +@} +@end example + +The main function shows how to put it all together. + +@example +int +main (int argc, char *argv[]) +@{ + struct event_loop loop; + struct op_result result; + GpgmeCtx ctx; + GpgmeError err; + GpgmeData sig, text; + GpgmeSigStat status; + int i; + struct GpgmeIOCbs io_cbs = + @{ + add_io_cb, + &loop, + remove_io_cb, + event_io_cb, + &result + @}; + + /* Initialize the loop structure. */ + loop.lock = PTHREAD_MUTEX_INITIALIZER; + for (i = 0; i < MAX_FDS; i++) + loop->fds[i].fd = -1; + + /* Initialize the result structure. */ + result.done = 0; + + err = gpgme_data_new_from_file (&sig, "signature", 1); + if (!err) + err = gpgme_data_new_from_file (&text, "text", 1); + if (!err) + err = gpgme_new (&ctx); + if (!err) + @{ + gpgme_set_io_cbs (ctx, &io_cbs); + err = gpgme_op_verify_start (ctx, sig, text, &status); + @} + if (err) + @{ + fprintf (stderr, "gpgme error: %s\n", gpgme_strerror (err)); + exit (1); + @} + + wait_for_op (&loop, &result); + if (!result.done) + @{ + fprintf (stderr, "select error\n"); + exit (1); + @} + if (!result.err) + @{ + fprintf (stderr, "verification failed: %s\n", gpgme_strerror (result.err)); + exit (1); + @} + /* Evaluate STATUS. */ + @dots{} + return 0; +@} +@end example + + +@node I/O Callback Example GTK+ +@subsubsection I/O Callback Example GTK+ +@cindex GTK+, using @acronym{GPGME} with + +The I/O callback interface can be used to integrate @acronym{GPGME} +with the GTK+ event loop. The following code snippets shows how this +can be done using the appropriate register and remove I/O callback +functions. In this example, the private data of the register I/O +callback function is unused. The event notifications is missing +because it does not require any GTK+ specific setup. + +@example +#include <gtk/gtk.h> + +struct my_gpgme_io_cb +@{ + GpgmeIOCb fnc; + void *fnc_data; + guint input_handler_id +@}; + +void +my_gpgme_io_cb (gpointer data, gint source, GdkInputCondition condition) +@{ + struct my_gpgme_io_cb *iocb = data; + (*(iocb->fnc)) (iocb->data, source); +@} + +void +my_gpgme_remove_io_cb (void *data) +@{ + struct my_gpgme_io_cb *iocb = data; + gtk_input_remove (data->input_handler_id); +@} + +void +my_gpgme_register_io_callback (void *data, int fd, int dir, GpgmeIOCb fnc, + void *fnc_data, void **tag) +@{ + struct my_gpgme_io_cb *iocb = g_malloc (sizeof (struct my_gpgme_io_cb)); + iocb->fnc = fnc; + iocb->data = fnc_data; + iocb->input_handler_id = gtk_input_add_full (fd, dir + ? GDK_INPUT_READ + : GDK_INPUT_WRITE, + my_gpgme_io_callback, + 0, iocb, NULL); + *tag = iocb; + return 0; +@} +@end example + + +@node I/O Callback Example GDK +@subsubsection I/O Callback Example GDK +@cindex GDK, using @acronym{GPGME} with + +The I/O callback interface can also be used to integrate +@acronym{GPGME} with the GDK event loop. The following code snippets +shows how this can be done using the appropriate register and remove +I/O callback functions. In this example, the private data of the +register I/O callback function is unused. The event notifications is +missing because it does not require any GDK specific setup. + +It is very similar to the GTK+ example in the previous section. + +@example +#include <gdk/gdk.h> + +struct my_gpgme_io_cb +@{ + GpgmeIOCb fnc; + void *fnc_data; + gint tag; +@}; + +void +my_gpgme_io_cb (gpointer data, gint source, GdkInputCondition condition) +@{ + struct my_gpgme_io_cb *iocb = data; + (*(iocb->fnc)) (iocb->data, source); +@} + +void +my_gpgme_remove_io_cb (void *data) +@{ + struct my_gpgme_io_cb *iocb = data; + gdk_input_remove (data->tag); +@} + +void +my_gpgme_register_io_callback (void *data, int fd, int dir, GpgmeIOCb fnc, + void *fnc_data, void **tag) +@{ + struct my_gpgme_io_cb *iocb = g_malloc (sizeof (struct my_gpgme_io_cb)); + iocb->fnc = fnc; + iocb->data = fnc_data; + iocb->tag = gtk_input_add_full (fd, dir ? GDK_INPUT_READ : GDK_INPUT_WRITE, + my_gpgme_io_callback, iocb, NULL); + *tag = iocb; + return 0; +@} +@end example + + +@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 diff --git a/branches/gpgme-0-3-branch/doc/gpl.texi b/branches/gpgme-0-3-branch/doc/gpl.texi new file mode 100644 index 00000000..ca0508fa --- /dev/null +++ b/branches/gpgme-0-3-branch/doc/gpl.texi @@ -0,0 +1,397 @@ +@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. |