doc/
[gpgme.git] / doc / gpgme.texi
1 \input texinfo                  @c -*- Texinfo -*-
2 @setfilename gpgme.info
3 @settitle The `GnuPG Made Easy' Reference Manual
4
5 @dircategory GNU Libraries
6 @direntry
7 * @acronym{GPGME}: (gpgme).          Adding support for cryptography to your program.
8 @end direntry
9
10 @include version.texi
11
12 @c Unify some of the indices.
13 @syncodeindex tp fn
14 @syncodeindex pg fn
15
16 @ifinfo
17 This file documents the @acronym{GPGME} library.
18
19 This is Edition @value{EDITION}, last updated @value{UPDATED}, of
20 @cite{The `GnuPG Made Easy' Reference Manual}, for Version
21 @value{VERSION}.
22
23 Copyright @copyright{} 2002 g10 Code GmbH.
24
25 Permission is granted to copy, distribute and/or modify this document
26 under the terms of the GNU Free Documentation License, Version 1.1 or
27 any later version published by the Free Software Foundation; with the
28 Invariant Sections being ``Free Software Needs Free Documentation'' and
29 ``GNU Lesser General Public License'', the Front-Cover texts being (a)
30 (see below), and with the Back-Cover Texts being (b) (see below).  A
31 copy of the license is included in the section entitled ``GNU Free
32 Documentation License''.
33
34 @end ifinfo
35
36 @iftex
37 @shorttitlepage The `GnuPG Made Easy' Reference Manual
38 @end iftex
39 @titlepage
40 @center @titlefont{The `GnuPG Made Easy'}
41 @sp 1
42 @center @titlefont{Reference Manual}
43 @sp 6
44 @center Edition @value{EDITION}
45 @sp 1
46 @center last updated @value{UPDATED}
47 @sp 1
48 @center for version @value{VERSION}
49 @page
50 @vskip 0pt plus 1filll
51 Copyright @copyright{} 2002 g10 Code GmbH.
52
53 Permission is granted to copy, distribute and/or modify this document
54 under the terms of the GNU Free Documentation License, Version 1.1 or
55 any later version published by the Free Software Foundation; with the
56 Invariant Sections being ``Free Software Needs Free Documentation'' and
57 ``GNU Lesser General Public License'', the Front-Cover texts being (a)
58 (see below), and with the Back-Cover Texts being (b) (see below).  A
59 copy of the license is included in the section entitled ``GNU Free
60 Documentation License''.
61 @end titlepage
62 @page
63
64 @ifnottex
65 @node Top
66 @top Main Menu
67 This is Edition @value{EDITION}, last updated @value{UPDATED}, of
68 @cite{The `GnuPG Made Easy' Reference Manual}, for Version
69 @value{VERSION} of the @acronym{GPGME} library.
70 @end ifnottex
71
72 @menu
73 * Introduction::                  How to use this manual.
74 * Preparation::                   What you should do before using the library.
75 * Protocols and Engines::         Supported crypto protocols.
76 * Error Handling::                Error numbers and their meanings.
77 * Exchanging Data::               Passing data to and from @acronym{GPGME}.
78 * Contexts::                      Handling @acronym{GPGME} contexts.
79
80 Appendices
81
82 * Copying::                       The GNU General Public License says how you
83                                   can copy and share `GnuPG Made Easy'.
84 * Free Documentation License::    This manual is under the GNU Free
85                                   Documentation License.
86
87 Indices
88
89 * Concept Index::                 Index of concepts and programs.
90 * Function and Data Index::       Index of functions, variables and data types.
91
92
93 @detailmenu
94  --- The Detailed Node Listing ---
95
96 Introduction
97
98 * Getting Started::               Purpose of the manual, and how to use it.
99 * Features::                      Reasons to install and use @acronym{GPGME}.
100 * Overview::                      Basic architecture of the @acronym{GPGME} library.
101
102 Preparation
103
104 * Header::                        What header file you need to include.
105 * Building the Source::           Compiler options to be used.
106 * Using Automake::                Compiler options to be used the easy way.
107 * Library Version Check::         Getting and verifying the library version.
108 * Multi Threading::               How @acronym{GPGME} can be used in an MT environment.
109
110 Protocols and Engines
111
112 * Engine Version Check::          Verifying the engine version.
113 * Engine Information::            Obtaining more information about the engines.
114 * OpenPGP::                       Support for the OpenPGP protocol.
115 * Cryptographic Message Syntax::  Support for the CMS.
116
117 Error Handling
118
119 * Error Values::                  A list of all error values used.
120 * Error Strings::                 How to get a descriptive string from a value.
121
122 Exchanging Data 
123
124 * Creating Data Buffers::         Creating new data buffers.
125 * Destroying Data Buffers::       Releasing data buffers.
126 * Manipulating Data Buffers::     Operations on data buffers.
127
128 Creating Data Buffers
129
130 * Memory Based Data Buffers::     Creating memory based data buffers.
131 * File Based Data Buffers::       Creating file based data buffers.
132 * Callback Based Data Buffers::   Creating callback based data buffers.
133
134 Contexts
135
136 * Creating Contexts::             Creating new @acronym{GPGME} contexts.
137 * Destroying Contexts::           Releasing @acronym{GPGME} contexts.
138 * Context Attributes::            Setting properties of a context.
139 * Key Management::                Managing keys with @acronym{GPGME}.
140 * Trust Item Management::         Managing trust items with @acronym{GPGME}.
141 * Crypto Operations::             Using a context for cryptography.
142 * Run Control::                   Controlling how operations are run.
143
144 Context Attributes
145
146 * Protocol Selection::            Selecting the protocol used by a context.
147 * @acronym{ASCII} Armor::                   Requesting @acronym{ASCII} armored output.
148 * Text Mode::                     Choosing canonical text mode.
149 * Included Certificates::         Including a number of certificates.
150 * Key Listing Mode::              Selecting key listing mode.
151 * Passphrase Callback::           Getting the passphrase from the user.
152 * Progress Meter Callback::       Being informed about the progress.
153
154 Key Management
155
156 * Listing Keys::                  Browsing the list of available keys.
157 * Information About Keys::        Requesting detailed information about keys.
158 * Key Signatures::                Listing the signatures on a key.
159 * Manipulating Keys::             Operations on keys.
160 * Generating Keys::               Creating new key pairs.
161 * Exporting Keys::                Retrieving key data from the key ring.
162 * Importing Keys::                Adding keys to the key ring.
163 * Deleting Keys::                 Removing keys from the key ring.
164
165 Trust Item Management
166
167 * Listing Trust Items::           Browsing the list of available trust items.
168 * Information About Trust Items:: Requesting detailed information about trust items.
169 * Manipulating Trust Items::      Operations on trust items.
170
171 Crypto Operations
172
173 * Decrypt::                       Decrypting a ciphertext.
174 * Verify::                        Verifying a signature.
175 * Decrypt and Verify::            Decrypting a signed ciphertext.
176 * Sign::                          Creating a signature.
177 * Encrypt::                       Encrypting a plaintext.
178 * Detailed Results::              How to obtain more info about the operation.
179
180 Sign
181
182 * Selecting Signers::             How to choose the keys to sign with.
183 * Creating a Signature::          How to create a signature.
184
185 Encrypt
186
187 * Selecting Recipients::          How to choose the recipients.
188 * Encrypting a Plaintext::        How to encrypt a plaintext.
189
190 Run Control
191
192 * Waiting For Completion::        Waiting until an operation is completed.
193 * Using External Event Loops::    Advanced control over what happens when.
194
195 Using External Event Loops
196
197 * I/O Callback Interface::        How I/O callbacks are registered.
198 * Registering I/O Callbacks::     How to use I/O callbacks for a context.
199 * I/O Callback Example::          An example how to use I/O callbacks.
200 * I/O Callback Example GTK+::     How to integrate @acronym{GPGME} in GTK+.
201 * I/O Callback Example GDK::      How to integrate @acronym{GPGME} in GDK.
202
203 @end detailmenu
204 @end menu
205
206 @node Introduction
207 @chapter Introduction
208
209 `GnuPG Made Easy' (@acronym{GPGME}) is a C language library that
210 allows to add support for cryptography to a program.  It is designed
211 to make access to crypto engines like GnuPG or GpgSM easier for
212 applications.  @acronym{GPGME} provides a high-level crypto API for
213 encryption, decryption, signing, signature verification and key
214 management.
215
216 @acronym{GPGME} uses GnuPG and GpgSM as its backends to support
217 OpenPGP and the Cryptographic Message Syntax (CMS).
218
219 @menu
220 * Getting Started::               Purpose of the manual, and how to use it.
221 * Features::                      Reasons to install and use @acronym{GPGME}.
222 * Overview::                      Basic architecture of the @acronym{GPGME} library.
223 @end menu
224
225
226 @node Getting Started
227 @section Getting Started
228
229 This manual documents the @acronym{GPGME} library programming
230 interface.  All functions and data types provided by the library are
231 explained.
232
233 The reader is assumed to possess basic knowledge about cryptography in
234 general, and public key cryptography in particular.  The underlying
235 cryptographic engines that are used by the library are not explained,
236 but where necessary, special features or requirements by an engine are
237 mentioned as far as they are relevant to @acronym{GPGME} or its users.
238
239 This manual can be used in several ways.  If read from the beginning
240 to the end, it gives a good introduction into the library and how it
241 can be used in an application.  Forward references are included where
242 necessary.  Later on, the manual can be used as a reference manual to
243 get just the information needed about any particular interface of the
244 library.  Experienced programmers might want to start looking at the
245 examples at the end of the manual, and then only read up those parts
246 of the interface which are unclear.
247
248
249 @node Features
250 @section Features
251
252 @acronym{GPGME} has a couple of advantages over other libraries doing
253 a similar job, and over implementing support for GnuPG or other crypto
254 engines into your application directly.
255
256 @table @asis
257 @item it's free software
258 Anybody can use, modify, and redistribute it under the terms of the GNU
259 General Public License (@pxref{Copying}).
260
261 @item it's flexible
262 @acronym{GPGME} provides transparent support for several cryptographic
263 protocols by different engines.  Currently, @acronym{GPGME} supports
264 the OpenPGP protocol using GnuPG as the backend, and the Cryptographic
265 Message Syntax using GpgSM as the backend.
266
267 @item it's easy
268 @acronym{GPGME} hides the differences between the protocols and
269 engines from the programmer behind an easy-to-use interface.  This way
270 the programmer can focus on the other parts of the program, and still
271 integrate strong cryptography in his application.  Once support for
272 @acronym{GPGME} has been added to a program, it is easy to add support
273 for other crypto protocols once @acronym{GPGME} backends provide them.
274 @end table
275
276
277 @node Overview
278 @section Overview
279
280 @acronym{GPGME} provides a data abstraction that is used to pass data
281 to the crypto engine, and receive returned data from it.  Data can be
282 read from memory or from files, but it can also be provided by a
283 callback function.
284
285 The actual cryptographic operations are always set within a context.
286 A context provides configuration parameters that define the behaviour
287 of all operations performed within it.  Only one operation per context
288 is allowed at any time, but when one operation is finished, you can
289 run the next operation in the same context.  There can be more than
290 one context, and all can run different operations at the same time.
291
292 Furthermore, @acronym{GPGME} has rich key management facilities
293 including listing keys, querying their attributes, generating,
294 importing, exporting and deleting keys, and acquiring information
295 about the trust path.
296
297 With some precautions, @acronym{GPGME} can be used in a multi-threaded
298 environment, although it is not completely thread safe and thus needs
299 the support of the application.
300
301
302 @node Preparation
303 @chapter Preparation
304
305 To use @acronym{GPGME}, you have to perform some changes to your
306 sources and the build system.  The necessary changes are small and
307 explained in the following sections.  At the end of this chapter, it
308 is described how the library is initialized, and how the requirements
309 of the library are verified.
310
311 @menu
312 * Header::                        What header file you need to include.
313 * Building the Source::           Compiler options to be used.
314 * Using Automake::                Compiler options to be used the easy way.
315 * Library Version Check::         Getting and verifying the library version.
316 * Multi Threading::               How @acronym{GPGME} can be used in an MT environment.
317 @end menu
318
319
320 @node Header
321 @section Header
322 @cindex header file
323 @cindex include file
324
325 All interfaces (data types and functions) of the library are defined
326 in the header file `gpgme.h'.  You must include this in all programs
327 using the library, either directly or through some other header file,
328 like this:
329
330 @example
331 #include <gpgme.h>
332 @end example
333
334 The name space of @acronym{GPGME} is @code{gpgme_*} for function
335 names, @code{Gpgme*} for data types and @code{GPGME_*} for other
336 symbols.  Symbols internal to @acronym{GPGME} take the form
337 @code{_gpgme_*}.
338
339 Because @acronym{GPGME} links to the Assuan library, linking to
340 @acronym{GPGME} will also use the @code{assuan_*} and @code{_assuan_*}
341 name space indirectly.
342
343
344 @node Building the Source
345 @section Building the Source
346 @cindex compiler options
347 @cindex compiler flags
348
349 If you want to compile a source file including the `gpgme.h' header
350 file, you must make sure that the compiler can find it in the
351 directory hierarchy.  This is accomplished by adding the path to the
352 directory in which the header file is located to the compilers include
353 file search path (via the @option{-I} option).
354
355 However, the path to the include file is determined at the time the
356 source is configured.  To solve this problem, gpgme ships with a small
357 helper program @command{gpgme-config} that knows about the path to the
358 include file and other configuration options.  The options that need
359 to be added to the compiler invocation at compile time are output by
360 the @option{--cflags} option to @command{gpgme-config}.  The following
361 example shows how it can be used at the command line:
362
363 @example
364 gcc -c foo.c `gpgme-config --cflags`
365 @end example
366
367 Adding the output of @samp{gpgme-config --cflags} to the compilers
368 command line will ensure that the compiler can find the @acronym{GPGME} header
369 file.
370
371 A similar problem occurs when linking the program with the library.
372 Again, the compiler has to find the library files.  For this to work,
373 the path to the library files has to be added to the library search
374 path (via the @option{-L} option).  For this, the option
375 @option{--libs} to @command{gpgme-config} can be used.  For
376 convenience, this option also outputs all other options that are
377 required to link the program with @acronym{GPGME} (in particular, the
378 @samp{-lgpgme} option).  The example shows how to link @file{foo.o}
379 with the @acronym{GPGME} library to a program @command{foo}.
380
381 @example
382 gcc -o foo foo.o `gpgme-config --libs`
383 @end example
384
385 Of course you can also combine both examples to a single command by
386 specifying both options to @command{gpgme-config}:
387
388 @example
389 gcc -o foo foo.c `gpgme-config --cflags --libs`
390 @end example
391
392
393 @node Using Automake
394 @section Using Automake
395 @cindex automake
396 @cindex autoconf
397
398 It is much easier if you use GNU Automake instead writing your own
399 Makefiles.  If you do that you don't have to worry about finding and
400 invoking the @command{gpgme-config} script at all.  @acronym{GPGME}
401 provides an extension to Automake that does all the work for you.
402
403 @c A simple macro for optional variables.
404 @macro ovar{varname}
405 @r{[}@var{\varname\}@r{]}
406 @end macro
407 @defmac AM_PATH_GPGME (@ovar{minimum-version}, @ovar{action-if-found}, @ovar{action-if-not-found})
408 Check whether @acronym{GPGME} (at least version @var{minimum-version},
409 if given) exists on the host system.  If it is found, execute
410 @var{action-if-found}, otherwise do @var{action-if-not-found}, if
411 given.
412
413 Additionally, the function defines @code{GPGME_CFLAGS} to the flags
414 needed for compilation of the program to find the @file{gpgme.h}
415 header file, and @code{GPGME_LIBS} to the linker flags needed to link
416 the program to the @acronym{GPGME} library.
417 @end defmac
418
419 You can use the defined Autoconf variables like this in your
420 @file{Makefile.am}:
421
422 @example
423 AM_CPPFLAGS = $(GPGME_CFLAGS)
424 LDADD = $(GPGME_LIBS)
425 @end example
426
427
428 @node Library Version Check
429 @section Library Version Check
430 @cindex version check, of the library
431
432 @deftypefun {const char *} gpgme_check_version (@w{const char *@var{required_version}})
433 The function @code{gpgme_check_version} has three purposes.  It can be
434 used to retrieve the version number of the library.  In addition it
435 can verify that the version number is higher than a certain required
436 version number.  In either case, the function initializes some
437 sub-systems, and for this reason alone it must be invoked early in
438 your program, before you make use of the other functions in
439 @acronym{GPGME}.
440
441 If @var{required_version} is @code{NULL}, the function returns a
442 pointer to a statically allocated string containing the version number
443 of the library.
444
445 If @var{required_version} is not @code{NULL}, it should point to a
446 string containing a version number, and the function checks that the
447 version of the library is at least as high as the version number
448 provided.  In this case, the function returns a pointer to a
449 statically allocated string containing the version number of the
450 library.  If @var{REQUIRED_VERSION} is not a valid version number, or
451 if the version requirement is not met, the function returns
452 @code{NULL}.
453
454 If you use a version of a library that is backwards compatible with
455 older releases, but contains additional interfaces which your program
456 uses, this function provides a run-time check if the necessary
457 features are provided by the installed version of the library.
458 @end deftypefun
459
460
461 @node Multi Threading
462 @section Multi Threading
463 @cindex thread-safeness
464 @cindex multi-threading
465
466 The @acronym{GPGME} library is not entirely thread-safe, but it can
467 still be used in a multi-threaded environment if some care is taken.
468 If the following requirements are met, there should be no race
469 conditions to worry about:
470
471 @itemize @bullet
472 @item
473 @acronym{GPGME} supports the thread libraries pthread and GNU Pth.
474 The support for this has to be enabled at compile time.
475 @acronym{GPGME} will automatically detect the location in which the
476 thread libraries are installed and activate the support for them.
477
478 Support for other thread libraries is very easy to add.  Please
479 contact us if you have the need.
480
481 @item
482 If you link your program dynamically to @acronym{GPGME} and your
483 supported thread library, @acronym{GPGME} will automatically detect
484 the presence of this library and activate its use.  If you link to
485 both pthread and GNU Pth, @acronym{GPGME} will use the pthread
486 support.  This feature requires weak symbol support.
487
488 @item
489 If you link your program statically to @acronym{GPGME}, there is
490 currently no easy way to make sure that @acronym{GPGME} detects the
491 presence of the thread library.  This will be solved in a future
492 version.
493
494 @item
495 The function @code{gpgme_check_version} must be called before any
496 other function in the library, because it initializes the thread
497 support subsystem in @acronym{GPGME}.  To achieve this in all
498 generality, it is necessary to synchronize the call to this function
499 with all other calls to functions in the library, using the
500 synchronization mechanisms available in your thread library.
501 Otherwise, specific compiler or CPU memory cache optimizations could
502 lead to the situation where a thread is started and uses
503 @acronym{GPGME} before the effects of the initialization are visible
504 for this thread.  It doesn't even suffice to call
505 @code{gpgme_check_version} before creating this other
506 thread@footnote{In SMP systems the new thread could be started on
507 another CPU before the effects of the initialization are seen by that
508 CPU's memory cache.  Not doing proper synchronization here leads to
509 the same problems the double-checked locking idiom has.  You might
510 find that if you don't do proper synchronization, it still works in
511 most configurations.  Don't let this fool you.  Someday it might lead
512 to subtle bugs when someone tries it on a DEC Alpha or an SMP
513 machine.}.
514
515 For example, if you are using POSIX threads, each thread that wants to
516 call functions in @acronym{GPGME} could call the following function
517 before any function in the library:
518
519 @example
520 #include <pthread.h>
521
522 void
523 initialize_gpgme (void)
524 @{
525   static int gpgme_init;
526   static pthread_mutext_t gpgme_init_lock = PTHREAD_MUTEX_INITIALIZER;
527
528   pthread_mutex_lock (&gpgme_init_lock);
529   if (!gpgme_init)
530     @{
531       gpgme_check_version ();
532       gpgme_init = 1;
533     @}
534   pthread_mutex_unlock (&gpgme_init_lock);
535 @}
536 @end example
537
538 @item
539 Any @code{GpgmeData}, @code{GpgmeCtx} and @code{GpgmeRecipients}
540 object must only be accessed by one thread at a time.  If multiple
541 threads want to deal with the same object, the caller has to make sure
542 that operations on that object are fully synchronized.
543
544 @item
545 Only one thread at any time is allowed to call @code{gpgme_wait}.  If
546 multiple threads call this function, the caller must make sure that
547 all invocations are fully synchronized.  It is safe to start
548 asynchronous operations while a thread is running in gpgme_wait.
549 @end itemize
550
551
552 @node Protocols and Engines
553 @chapter Protocols and Engines
554 @cindex protocol
555 @cindex engine
556 @cindex crypto engine
557 @cindex backend
558 @cindex crypto backend
559
560 @acronym{GPGME} supports several cryptographic protocols, however, it
561 does not implement them.  Rather it uses backends (also called
562 engines) which implement the protocol.  @acronym{GPGME} uses
563 inter-process communication to pass data back and forth between the
564 application and the backend, but the details of the communication
565 protocol and invocation of the backends is completely hidden by the
566 interface.  All complexity is handled by @acronym{GPGME}.  Where an
567 exchange of information between the application and the backend is
568 necessary, @acronym{GPGME} provides the necessary callback function
569 hooks and further interfaces.
570
571 @deftp {Data type} {enum GpgmeProtocol}
572 @tindex GpgmeProtocol
573 The @code{GpgmeProtocol} type specifies the set of possible protocol
574 values that are supported by @acronym{GPGME}.  The following protocols
575 are supported:
576
577 @table @code
578 @item GPGME_PROTOCOL_OpenPGP
579 This specifies the OpenPGP protocol.
580 @item GPGME_PROTOCOL_CMS
581 This specifies the Cryptographic Message Syntax.
582 @end table
583 @end deftp
584
585
586 @deftypefun const char *gpgme_get_protocol_name (@w{GpgmeProtocol @var{protocol}})
587 The function @code{gpgme_get_protocol_name} returns a statically
588 allocated string describing the protocol @var{protocol}, or
589 @code{NULL} if the protocol number is not valid.
590 @end deftypefun
591
592 @menu
593 * Engine Version Check::          Verifying the engine version.
594 * Engine Information::            Obtaining more information about the engines.
595 * OpenPGP::                       Support for the OpenPGP protocol.
596 * Cryptographic Message Syntax::  Support for the CMS.
597 @end menu
598
599
600 @node Engine Version Check
601 @section Engine Version Check
602 @cindex version check, of the engines
603
604 @deftypefun GpgmeError gpgme_engine_check_version (@w{GpgmeProtocol @var{protocol}})
605 The function @code{gpgme_engine_check_version} verifies that the
606 engine implementing the protocol @var{PROTOCOL} is installed in the
607 expected path and meets the version requirement of @acronym{GPGME}.
608
609 This function returns @code{GPGME_No_Error} if the engine is available
610 and @code{GPGME_Invalid_Engine} if it is not.
611 @end deftypefun
612
613
614 @node Engine Information
615 @section Engine Information
616 @cindex engine, information about
617
618 @deftp {Data type} {GpgmeEngineInfo}
619 @tindex GpgmeProtocol
620 The @code{GpgmeEngineInfo} type specifies a pointer to a structure
621 describing a crypto backend engine.  The structure contains the
622 following elements:
623
624 @table @code
625 @item GpgmeEngineInfo next
626 This is a pointer to the next engine info structure in the linked
627 list, or @code{NULL} if this is the last element.
628
629 @item GpgmeProtocol protocol
630 This is the protocol for which the crypo engine is used.  You can
631 convert this to a string with @code{gpgme_get_protocol_name} for
632 printing.
633
634 @item const char *file_name
635 This is a string holding the file name of the executable of the crypto
636 engine.  Currently, it is never @code{NULL}, but using @code{NULL} is
637 reserved for future use, so always check before you use it.
638
639 @item const char *version
640 This is a string containing the version number of the crypto engine.
641 It might be @code{NULL} if the version number can not be determined,
642 for example because the executable doesn't exist or is invalid.
643
644 @item const char *req_version
645 This is a string containing the minimum required version number of the
646 crypto engine for @acronym{GPGME} to work correctly.  This is the
647 version number that @code{gpgme_engine_check_version} verifies
648 against.  Currently, it is never @code{NULL}, but using @code{NULL} is
649 reserved for future use, so always check before you use it.
650 @end table
651 @end deftp
652
653 @deftypefun GpgmeError gpgme_get_engine_info (GpgmeEngineInfo *info)
654 The function @code{gpgme_get_engine_info} returns a linked list of
655 engine info structures in @var{info}.  Each info structure describes
656 one configured crypto backend engine.
657
658 The memory for the info structures is allocated the first time this
659 function is invoked, and must not be freed by the caller.
660
661 This function returns @code{GPGME_No_Error} if successful, and
662 @code{GPGME_Out_Of_Core} if not enough memory is available for the
663 operation.
664 @end deftypefun
665
666 Here is the example how you can provide more diagnostics if you
667 receive an error message which indicates that the crypto engine is
668 invalid.
669
670 @example
671 GpgmeCtx ctx;
672 GpgmeError err;
673
674 [...]
675
676 if (err == GPGME_Invalid_Engine)
677   @{
678     GpgmeEngineInfo info;
679     err = gpgme_get_engine_info (&info);
680     if (!err)
681       @{
682         while (info && info->protocol != gpgme_get_protocol (ctx))
683           info = info->next;
684         if (!info)
685           fprintf (stderr, "GPGME compiled without support for protocol %s",
686                    gpgme_get_protocol_name (info->protocol));
687         else if (info->path && !info->version)
688           fprintf (stderr, "Engine %s not installed properly",
689                    info->path);
690         else if (info->path && info->version && info->req_version)
691           fprintf (stderr, "Engine %s version %s installed, "
692                    "but at least version %s required", info->path,
693                    info->version, info->req_version);
694         else
695           fprintf (stderr, "Unknown problem with engine for protocol %s",
696                    gpgme_get_protocol_name (info->protocol));
697       @}
698   @}
699 @end example
700
701
702 @node OpenPGP
703 @section OpenPGP
704 @cindex OpenPGP
705 @cindex GnuPG
706 @cindex protocol, GnuPG
707 @cindex engine, GnuPG
708
709 OpenPGP is implemented by GnuPG, the @acronym{GNU} Privacy Guard.
710 This is the first protocol that was supported by @acronym{GPGME}.
711
712 The OpenPGP protocol is specified by @code{GPGME_PROTOCOL_OpenPGP}.
713
714
715 @node Cryptographic Message Syntax
716 @section Cryptographic Message Syntax
717 @cindex CMS
718 @cindex cryptographic message syntax
719 @cindex GpgSM
720 @cindex protocol, CMS
721 @cindex engine, GpgSM
722 @cindex S/MIME
723 @cindex protocol, S/MIME
724
725 @acronym{CMS} is implemented by GpgSM, the S/MIME implementation for
726 GnuPG.
727
728 The @acronym{CMS} protocol is specified by @code{GPGME_PROTOCOL_CMS}.
729
730
731 @node Error Handling
732 @chapter Error Handling
733 @cindex error handling
734
735 Many functions in @acronym{GPGME} can return an error if they fail.
736 For this reason, the application should always catch the error
737 condition and take appropriate measures, for example by releasing the
738 resources and passing the error up to the caller, or by displaying a
739 descriptive message to the user and cancelling the operation.
740
741 Some error values do not indicate a system error or an error in the
742 operation, but the result of an operation that failed properly.  For
743 example, if you try to decrypt a tempered message, the decryption will
744 fail.  Another error value actually means that the end of a data
745 buffer or list has been reached.  The following descriptions explain
746 what each error message means in general.  Some error values have
747 specific meanings if returned by a specific function.  Such cases are
748 described in the documentation of those functions.
749
750 @menu
751 * Error Values::                  A list of all error values used.
752 * Error Strings::                 How to get a descriptive string from a value.
753 @end menu
754
755
756 @node Error Values
757 @section Error Values
758 @cindex error values, list of
759
760 @deftp {Data type} {enum GpgmeError}
761 @tindex GpgmeError
762 The @code{GpgmeError} type specifies the set of all error values that
763 are used by @acronym{GPGME}.  Possible values are:
764
765 @table @code
766 @item GPGME_EOF
767 This value indicates the end of a list, buffer or file.
768
769 @item GPGME_No_Error
770 This value indicates success.  The value of this error is @code{0}.
771
772 @item GPGME_General_Error
773 This value means that something went wrong, but either there is not
774 enough information about the problem to return a more useful error
775 value, or there is no separate error value for this type of problem.
776
777 @item GPGME_Out_Of_Core
778 This value means that an out-of-memory condition occurred.
779
780 @item GPGME_Invalid_Value
781 This value means that some user provided data was out of range.  This
782 can also refer to objects.  For example, if an empty @code{GpgmeData}
783 object was expected, but one containing data was provided, this error
784 value is returned.
785
786 @item GPGME_Exec_Error
787 This value means that an error occurred when trying to spawn a child
788 process.
789
790 @item GPGME_Too_Many_Procs
791 This value means that there are too many active backend processes.
792
793 @item GPGME_Pipe_Error
794 This value means that the creation of a pipe failed.
795
796 @item GPGME_No_UserID 
797 This value means that no valid recipients for a message have been set.
798
799 @item GPGME_Invalid_UserID
800 This value means that some, but not all, recipients for a message have
801 been invalid.
802
803 @item GPGME_No_Data
804 This value means that a @code{GpgmeData} object which was expected to
805 have content was found empty.
806
807 @item GPGME_Conflict
808 This value means that a conflict of some sort occurred.
809
810 @item GPGME_Not_Implemented
811 This value indicates that the specific function (or operation) is not
812 implemented.  This error should never happen.  It can only occur if
813 you use certain values or configuration options which do not work,
814 but for which we think that they should work at some later time.
815
816 @item GPGME_Read_Error
817 This value means that an I/O read operation failed.
818
819 @item GPGME_Write_Error
820 This value means that an I/O write operation failed.
821
822 @item GPGME_Invalid_Type
823 This value means that a user provided object was of a wrong or
824 incompatible type.  Usually this refers to the type of a
825 @code{GpgmeData} object.
826
827 @item GPGME_Invalid_Mode
828 This value means that a @code{GpgmeData} object has an incorrect mode
829 of operation (for example, doesn't support output although it is
830 attempted to use it as an output buffer).
831
832 @item GPGME_File_Error
833 This value means that a file I/O operation failed.  The value of
834 @var{errno} contains the system error value.
835
836 @item GPGME_Decryption_Failed
837 This value indicates that a decryption operation was unsuccessful.
838
839 @item GPGME_Bad_Passphrase
840 This value means that the user did not provide a correct passphrase
841 when requested.
842
843 @item GPGME_Canceled
844 This value means that the operation was canceled.
845
846 @item GPGME_Invalid_Key
847 This value means that a key was invalid.
848
849 @item GPGME_Invalid_Engine
850 This value means that the engine that implements the desired protocol
851 is currently not available.  This can either be because the sources
852 were configured to exclude support for this engine, or because the
853 engine is not installed properly.
854 @end table
855 @end deftp
856
857
858 @node Error Strings
859 @section Error Strings
860 @cindex error values, printing of
861 @cindex error strings
862
863 @deftypefun {const char *} gpgme_strerror (@w{GpgmeError @var{err}})
864 The function @code{gpgme_strerror} returns a pointer to a statically
865 allocated string containing a description of the error with the error
866 value @var{err}.  This string can be used to output a diagnostic
867 message to the user.
868
869 The following example illustrates the use of @code{gpgme_strerror}:
870
871 @example
872 GpgmeCtx ctx;
873 GpgmeError err = gpgme_new (&ctx);
874 if (err)
875   @{
876     fprintf (stderr, "%s: creating GpgME context failed: %s\n",
877              argv[0], gpgme_strerror (err));
878     exit (1);
879   @}
880 @end example
881 @end deftypefun
882
883
884 @node Exchanging Data
885 @chapter Exchanging Data
886 @cindex data, exchanging
887
888 A lot of data has to be exchanged between the user and the crypto
889 engine, like plaintext messages, ciphertext, signatures and
890 information about the keys.  The technical details about exchanging
891 the data information are completely abstracted by @acronym{GPGME}.
892 The user provides and receives the data via @code{GpgmeData} objects,
893 regardless of the communication protocol between @acronym{GPGME} and
894 the crypto engine in use.
895
896 @deftp {Data type} {GpgmeData}
897 The @code{GpgmeData} type is a handle for a container for generic
898 data, which is used by @acronym{GPGME} to exchange data with the user.
899 @end deftp
900
901 @menu
902 * Creating Data Buffers::         Creating new data buffers.
903 * Destroying Data Buffers::       Releasing data buffers.
904 * Manipulating Data Buffers::     Operations on data buffers.
905 @end menu
906
907
908 @node Creating Data Buffers
909 @section Creating Data Buffers
910 @cindex data buffer, creation
911
912 Data objects can be based on memory, files, or callback functions
913 provided by the user.  Not all operations are supported by all
914 objects.
915
916
917 @menu
918 * Memory Based Data Buffers::     Creating memory based data buffers.
919 * File Based Data Buffers::       Creating file based data buffers.
920 * Callback Based Data Buffers::   Creating callback based data buffers.
921 @end menu
922
923
924 @node Memory Based Data Buffers
925 @subsection Memory Based Data Buffers
926
927 Memory based data objects store all data in allocated memory.  This is
928 convenient, but only practical for an amount of data that is a
929 fraction of the available physical memory.  The data has to be copied
930 from its source and to its destination, which can often be avoided by
931 using one of the other data object 
932
933 @deftypefun GpgmeError gpgme_data_new (@w{GpgmeData *@var{dh}})
934 The function @code{gpgme_data_new} creates a new @code{GpgmeData}
935 object and returns a handle for it in @var{dh}.  The data object is
936 memory based and initially empty.
937
938 The function returns @code{GPGME_No_Error} if the data object was
939 successfully created, @code{GPGME_Invalid_Value} if @var{dh} is not a
940 valid pointer, and @code{GPGME_Out_Of_Core} if not enough memory is
941 available.
942 @end deftypefun
943
944 @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}})
945 The function @code{gpgme_data_new_from_mem} creates a new
946 @code{GpgmeData} object and fills it with @var{size} bytes starting
947 from @var{buffer}.
948
949 If @var{copy} is not zero, a private copy of the data is made.  If
950 @var{copy} is zero, the data is taken from the specified buffer as
951 needed, and the user has to ensure that the buffer remains valid for
952 the whole life span of the data object.
953
954 The function returns @code{GPGME_No_Error} if the data object was
955 successfully created, @code{GPGME_Invalid_Value} if @var{dh} or
956 @var{buffer} is not a valid pointer, and @code{GPGME_Out_Of_Core} if
957 not enough memory is available.
958 @end deftypefun
959
960 @deftypefun GpgmeError gpgme_data_new_from_file (@w{GpgmeData *@var{dh}}, @w{const char *@var{filename}}, @w{int @var{copy}})
961 The function @code{gpgme_data_new_from_file} creates a new
962 @code{GpgmeData} object and fills it with the content of the file
963 @var{filename}.
964
965 If @var{copy} is not zero, the whole file is read in at initialization
966 time and the file is not used anymore after that.  This is the only
967 mode supported currently.  Later, a value of zero for @var{copy} might
968 cause all reads to be delayed until the data is needed, but this is
969 not yet implemented.
970
971 The function returns @code{GPGME_No_Error} if the data object was
972 successfully created, @code{GPGME_Invalid_Value} if @var{dh} or
973 @var{filename} is not a valid pointer, @code{GPGME_File_Error} if an
974 I/O operation fails, @code{GPGME_Not_Implemented} if @var{code} is
975 zero, and @code{GPGME_Out_Of_Core} if not enough memory is available.
976 @end deftypefun
977
978 @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}})
979 The function @code{gpgme_data_new_from_filepart} creates a new
980 @code{GpgmeData} object and fills it with a part of the file specified
981 by @var{filename} or @var{fp}.
982
983 Exactly one of @var{filename} and @var{fp} must be non-zero, the other
984 must be zero.  The argument that is not zero specifies the file from
985 which @var{length} bytes are read into the data object, starting from
986 @var{offset}.
987
988 The function returns @code{GPGME_No_Error} if the data object was
989 successfully created, @code{GPGME_Invalid_Value} if @var{dh} and
990 exactly one of @var{filename} and @var{fp} is not a valid pointer,
991 @code{GPGME_File_Error} if an I/O operation fails, and
992 @code{GPGME_Out_Of_Core} if not enough memory is available.
993 @end deftypefun
994
995
996 @node File Based Data Buffers
997 @subsection File Based Data Buffers
998
999 File based data objects operate directly on file descriptors or
1000 streams.  Only a small amount of data is stored in core at any time,
1001 so the size of the data objects is not limited by @acronym{GPGME}.
1002
1003 @deftypefun GpgmeError gpgme_data_new_from_fd (@w{GpgmeData *@var{dh}}, @w{int @var{fd}})
1004 The function @code{gpgme_data_new_from_fd} creates a new
1005 @code{GpgmeData} object and uses the file descriptor @var{fd} to read
1006 from (if used as an input data object) and write to (if used as an
1007 output data object).
1008
1009 When using the data object as an input buffer, the function might read
1010 a bit more from the file descriptor than is actually needed by the
1011 crypto engine in the desired operation because of internal buffering.
1012
1013 The function returns @code{GPGME_No_Error} if the data object was
1014 successfully created, and @code{GPGME_Out_Of_Core} if not enough
1015 memory is available.
1016 @end deftypefun
1017
1018 @deftypefun GpgmeError gpgme_data_new_from_stream (@w{GpgmeData *@var{dh}}, @w{FILE *@var{stream}})
1019 The function @code{gpgme_data_new_from_stream} creates a new
1020 @code{GpgmeData} object and uses the I/O stream @var{stream} to read
1021 from (if used as an input data object) and write to (if used as an
1022 output data object).
1023
1024 When using the data object as an input buffer, the function might read
1025 a bit more from the stream than is actually needed by the crypto
1026 engine in the desired operation because of internal buffering.
1027
1028 The function returns @code{GPGME_No_Error} if the data object was
1029 successfully created, and @code{GPGME_Out_Of_Core} if not enough
1030 memory is available.
1031 @end deftypefun
1032
1033
1034 @node Callback Based Data Buffers
1035 @subsection Callback Based Data Buffers
1036
1037 If neither memory nor file based data objects are a good fit for your
1038 application, you can implement the functions a data object provides
1039 yourself and create a data object from these callback functions.
1040
1041 @deftp {Data type} {ssize_t (*GpgmeDataReadCb) (@w{void *@var{handle}}, @w{void @var{*buffer}}, @w{size_t @var{size}})}
1042 @tindex GpgmeDataReadCb
1043 The @code{GpgmeDataReadCb} type is the type of functions which
1044 @acronym{GPGME} calls if it wants to read data from a user-implemented
1045 data object.  The function should read up to @var{size} bytes from the
1046 current read position into the space starting at @var{buffer}.  The
1047 @var{handle} is provided by the user at data object creation time.
1048
1049 The function should return the number of bytes read, 0 on EOF, and -1
1050 on error.  If an error occurs, @var{errno} should be set to describe
1051 the type of the error.
1052 @end deftp
1053
1054 @deftp {Data type} {ssize_t (*GpgmeDataWriteCb) (@w{void *@var{handle}}, @w{const void @var{*buffer}}, @w{size_t @var{size}})}
1055 @tindex GpgmeDataWriteCb
1056 The @code{GpgmeDataWriteCb} type is the type of functions which
1057 @acronym{GPGME} calls if it wants to write data to a user-implemented
1058 data object.  The function should write up to @var{size} bytes to the
1059 current write position from the space starting at @var{buffer}.  The
1060 @var{handle} is provided by the user at data object creation time.
1061
1062 The function should return the number of bytes written, and -1 on
1063 error.  If an error occurs, @var{errno} should be set to describe the
1064 type of the error.
1065 @end deftp
1066
1067 @deftp {Data type} {off_t (*GpgmeDataSeekCb) (@w{void *@var{handle}}, @w{off_t @var{offset}}, @w{int @var{whence}})}
1068 @tindex GpgmeDataSeekCb
1069 The @code{GpgmeDataSeekCb} type is the type of functions which
1070 @acronym{GPGME} calls if it wants to change the current read/write
1071 position in a user-implemented data object, just like the @code{lseek}
1072 function.
1073
1074 The function should return the new read/write position, and -1 on
1075 error.  If an error occurs, @var{errno} should be set to describe the
1076 type of the error.
1077 @end deftp
1078
1079 @deftp {Data type} {void (*GpgmeDataReleaseCb) (@w{void *@var{handle}})}
1080 @tindex GpgmeDataReleaseCb
1081 The @code{GpgmeDataReleaseCb} type is the type of functions which
1082 @acronym{GPGME} calls if it wants to destroy a user-implemented data
1083 object.  The @var{handle} is provided by the user at data object
1084 creation time.
1085 @end deftp
1086
1087 @deftp {Data type} {struct GpgmeDataCbs}
1088 This structure is used to store the data callback interface functions
1089 described above.  It has the following members:
1090
1091 @table @code
1092 @item GpgmeDataReadCb read
1093 This is the function called by @acronym{GPGME} to read data from the
1094 data object.  It is only required for input data object.
1095
1096 @item GpgmeDataWriteCb write
1097 This is the function called by @acronym{GPGME} to write data to the
1098 data object.  It is only required for output data object.
1099
1100 @item GpgmeDataSeekCb seek
1101 This is the function called by @acronym{GPGME} to change the current
1102 read/write pointer in the data object (if available).  It is optional.
1103
1104 @item GpgmeDataReleaseCb release
1105 This is the function called by @acronym{GPGME} to release a data
1106 object.  It is optional.
1107 @end table
1108 @end deftp
1109
1110 @deftypefun GpgmeError gpgme_data_new_from_cbs (@w{GpgmeData *@var{dh}}, @w{struct GpgmeDataCbs *@var{cbs}}, @w{void *@var{handle}})
1111 The function @code{gpgme_data_new_from_cbs} creates a new
1112 @code{GpgmeData} object and uses the user-provided callback functions
1113 to operate on the data object.
1114
1115 The handle @var{handle} is passed as first argument to the callback
1116 functions.  This can be used to identify this data object.
1117
1118 The function returns @code{GPGME_No_Error} if the data object was
1119 successfully created, and @code{GPGME_Out_Of_Core} if not enough
1120 memory is available.
1121 @end deftypefun
1122
1123 The following interface is deprecated and only provided for backward
1124 compatibility.  Don't use it.  It will be removed in a future version
1125 of @acronym{GPGME}.
1126
1127 @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}})
1128 The function @code{gpgme_data_new_with_read_cb} creates a new
1129 @code{GpgmeData} object and uses the callback function @var{readfunc}
1130 to retrieve the data on demand.  As the callback function can supply
1131 the data in any way it wants, this is the most flexible data type
1132 @acronym{GPGME} provides.  However, it can not be used to write data.
1133
1134 The callback function receives @var{hook_value} as its first argument
1135 whenever it is invoked.  It should return up to @var{count} bytes in
1136 @var{buffer}, and return the number of bytes actually read in
1137 @var{nread}.  It may return @code{0} in @var{nread} if no data is
1138 currently available.  To indicate @code{EOF} the function should
1139 return with an error code of @code{-1} and set @var{nread} to
1140 @code{0}.  The callback function may support to reset its internal
1141 read pointer if it is invoked with @var{buffer} and @var{nread} being
1142 @code{NULL} and @var{count} being @code{0}.
1143
1144 The function returns @code{GPGME_No_Error} if the data object was
1145 successfully created, @code{GPGME_Invalid_Value} if @var{dh} or
1146 @var{readfunc} is not a valid pointer, and @code{GPGME_Out_Of_Core} if
1147 not enough memory is available.
1148 @end deftypefun
1149
1150
1151 @node Destroying Data Buffers
1152 @section Destroying Data Buffers
1153 @cindex data buffer, destruction
1154
1155 @deftypefun void gpgme_data_release (@w{GpgmeData @var{dh}})
1156 The function @code{gpgme_data_release} destroys the data object with
1157 the handle @var{dh}.  It releases all associated resources that were
1158 not provided by the user in the first place.
1159 @end deftypefun
1160
1161 @deftypefun {char *} gpgme_data_release_and_get_mem (@w{GpgmeData @var{dh}}, @w{size_t *@var{length}})
1162 The function @code{gpgme_data_release_and_get_mem} is like
1163 @code{gpgme_data_release}, except that it returns the data buffer and
1164 its length that was provided by the object.
1165
1166 The user has to release the buffer with @code{free}.  In case the user
1167 provided the data buffer in non-copy mode, a copy will be made for
1168 this purpose.
1169
1170 In case an error returns, or there is no suitable data buffer that can
1171 be returned to the user, the function will return @code{NULL}.
1172 @end deftypefun
1173
1174
1175 @node Manipulating Data Buffers
1176 @section Manipulating Data Buffers
1177 @cindex data buffere, manipulation
1178
1179 @deftypefun ssize_t gpgme_data_read (@w{GpgmeData @var{dh}}, @w{void *@var{buffer}}, @w{size_t @var{length}})
1180 The function @code{gpgme_data_read} reads up to @var{length} bytes
1181 from the data object with the handle @var{dh} into the space starting
1182 at @var{buffer}.
1183
1184 If no error occurs, the actual amount read is returned.  If the end of
1185 the data object is reached, the function returns @code{GPGME_EOF} and
1186 sets @var{nread} to zero.
1187
1188 In all other cases, the function returns -1 and sets @var{errno}.
1189 @end deftypefun
1190
1191 @deftypefun ssize_t gpgme_data_write (@w{GpgmeData @var{dh}}, @w{const void *@var{buffer}}, @w{size_t @var{size}})
1192 The function @code{gpgme_data_write} writes up to @var{size} bytes
1193 starting from @var{buffer} into the data object with the handle
1194 @var{dh} at the current write position.
1195
1196 The function returns the number of bytes actually written, or -1 if an
1197 error occurs.  If an error occurs, @var{errno} is set.
1198 @end deftypefun
1199
1200 /* Set the current position from where the next read or write starts
1201    in the data object with the handle DH to OFFSET, relativ to
1202    WHENCE.  */
1203 off_t gpgme_data_seek (GpgmeData dh, off_t offset, int whence);
1204
1205 @deftypefun off_t gpgme_data_seek (@w{GpgmeData @var{dh}}, @w{off_t *@var{offset}}, @w{int @var{whence}})
1206 The function @code{gpgme_data_seek} changes the current read/write
1207 position.
1208
1209 The @var{whence} argument specifies how the @var{offset} should be
1210 interpreted.  It must be one of the following symbolic constants:
1211
1212 @table @code
1213 @item SEEK_SET
1214 Specifies that @var{whence} is a count of characters from the
1215 beginning of the data object.
1216
1217 @item SEEK_CUR
1218 Specifies that @var{whence} is a count of characters from the current
1219 file position.  This count may be positive or negative.
1220
1221 @item SEEK_END
1222 Specifies that @var{whence} is a count of characters from the end of
1223 the data object.  A negative count specifies a position within the
1224 current extent of the data object; a positive count specifies a
1225 position past the current end.  If you set the position past the
1226 current end, and actually write data, you will extend the data object
1227 with zeros up to that position.
1228 @end table
1229
1230 If successful, the function returns the resulting file position,
1231 measured in bytes from the beginning of the data object.  You can use
1232 this feature together with @code{SEEK_CUR} to read the current
1233 read/write position.
1234
1235 If the function fails, -1 is returned and @var{errno} is set.
1236 @end deftypefun
1237
1238 The following function is deprecated and should not be used.  It will
1239 be removed in a future version of @acronym{GPGME}.
1240
1241 @deftypefun GpgmeError gpgme_data_rewind (@w{GpgmeData @var{dh}})
1242 The function @code{gpgme_data_rewind} is equivalent to:
1243
1244 @example
1245   return (gpgme_data_seek (dh, 0, SEEK_SET) == -1)
1246     ? mk_error (File_Error) : 0;
1247 @end example
1248 @end deftypefun
1249
1250 @c
1251 @c  GpgmeDataEncoding
1252 @c
1253 @deftp {Data type} {enum GpgmeDataEncoding}
1254 @tindex GpgmeDataEncoding
1255 The @code{GpgmeDataEncoding} type specifies the encoding of a
1256 @code{GpgmeData} object.  This encoding is useful to give the backend
1257 a hint on the type of data.  The following data types are available:
1258
1259 @table @code
1260 @item GPGME_DATA_ENCODING_NONE
1261 This specifies that the encoding is not known.  This is the default
1262 for a new data object.  The backend will try its best to detect the
1263 encoding automatically.
1264
1265 @item GPGME_DATA_ENCODING_BINARY
1266 This specifies that the data is encoding in binary form; i.e. there is
1267 no special encoding.
1268
1269 @item GPGME_DATA_ENCODING_BASE64
1270 This specifies that the data is encoded using the Base-64 encoding
1271 scheme as used by @acronym{MIME} and other protocols.
1272
1273 @item GPGME_DATA_ENCODING_ARMOR
1274 This specifies that the data is encoded in an armored form as used by
1275 OpenPGP and PEM.
1276 @end table
1277 @end deftp
1278
1279 @deftypefun GpgmeDataEncoding gpgme_data_get_encoding (@w{GpgmeData @var{dh}})
1280 The function @code{gpgme_data_get_encoding} returns the encoding of
1281 the data object with the handle @var{dh}.  If @var{dh} is not a valid
1282 pointer (e.g. @code{NULL}) @code{GPGME_DATA_ENCODING_NONE} is
1283 returned.
1284 @end deftypefun
1285
1286 @deftypefun GpgmeError gpgme_data_set_encoding (@w{GpgmeData @var{dh}, GpgmeDataEncoding @var{enc}})
1287 The function @code{gpgme_data_set_encoding} changes the encoding of
1288 the data object with the handle @var{dh} to @var{enc}.
1289 @end deftypefun
1290
1291
1292 @c
1293 @c    Chapter Contexts
1294 @c 
1295 @node Contexts
1296 @chapter Contexts
1297 @cindex context
1298
1299 All cryptographic operations in @acronym{GPGME} are performed within a
1300 context, which contains the internal state of the operation as well as
1301 configuration parameters.  By using several contexts you can run
1302 several cryptographic operations in parallel, with different
1303 configuration.
1304
1305 @deftp {Data type} {GpgmeCtx}
1306 The @code{GpgmeCtx} type is a handle for a @acronym{GPGME} context,
1307 which is used to hold the configuration, status and result of
1308 cryptographic operations.
1309 @end deftp
1310
1311 @menu
1312 * Creating Contexts::             Creating new @acronym{GPGME} contexts.
1313 * Destroying Contexts::           Releasing @acronym{GPGME} contexts.
1314 * Context Attributes::            Setting properties of a context.
1315 * Key Management::                Managing keys with @acronym{GPGME}.
1316 * Trust Item Management::         Managing trust items with @acronym{GPGME}.
1317 * Crypto Operations::             Using a context for cryptography.
1318 * Run Control::                   Controlling how operations are run.
1319 @end menu
1320
1321
1322 @node Creating Contexts
1323 @section Creating Contexts
1324 @cindex context, creation
1325
1326 @deftypefun GpgmeError gpgme_new (@w{GpgmeCtx *@var{ctx}})
1327 The function @code{gpgme_data_new} creates a new @code{GpgmeCtx}
1328 object and returns a handle for it in @var{ctx}.
1329
1330 The function returns @code{GPGME_No_Error} if the context was
1331 successfully created, @code{GPGME_Invalid_Value} if @var{ctx} is not a
1332 valid pointer, and @code{GPGME_Out_Of_Core} if not enough memory is
1333 available.
1334 @end deftypefun
1335
1336
1337 @node Destroying Contexts
1338 @section Destroying Contexts
1339 @cindex context, destruction
1340
1341 @deftypefun void gpgme_release (@w{GpgmeCtx @var{ctx}})
1342 The function @code{gpgme_release} destroys the context with the handle
1343 @var{ctx} and releases all associated resources.
1344 @end deftypefun
1345
1346
1347 @node Context Attributes
1348 @section Context Attributes
1349 @cindex context, attributes
1350
1351 @menu
1352 * Protocol Selection::            Selecting the protocol used by a context.
1353 * @acronym{ASCII} Armor::                   Requesting @acronym{ASCII} armored output.
1354 * Text Mode::                     Choosing canonical text mode.
1355 * Included Certificates::       Including a number of certificates.
1356 * Key Listing Mode::              Selecting key listing mode.
1357 * Passphrase Callback::           Getting the passphrase from the user.
1358 * Progress Meter Callback::       Being informed about the progress.
1359 @end menu
1360
1361
1362 @node Protocol Selection
1363 @subsection Protocol Selection
1364 @cindex context, selecting protocol
1365 @cindex protocol, selecting
1366
1367 @deftypefun GpgmeError gpgme_set_protocol (@w{GpgmeCtx @var{ctx}}, @w{GpgmeProtocol @var{proto}})
1368 The function @code{gpgme_set_protocol} sets the protocol used within
1369 the context @var{ctx} to @var{proto}.  All crypto operations will be
1370 performed by the crypto engine configured for that protocol.
1371 @xref{Protocols and Engines}.
1372
1373 Setting the protocol with @code{gpgme_set_protocol} does not check if
1374 the crypto engine for that protocol is available and installed
1375 correctly.  @xref{Engine Version Check}.
1376
1377 The function returns @code{GPGME_No_Error} if the protocol could be
1378 set successfully, and @code{GPGME_Invalid_Value} if @var{protocol} is
1379 not a valid protocol.
1380 @end deftypefun
1381
1382 @deftypefun GpgmeProtocol gpgme_get_protocol (@w{GpgmeCtx @var{ctx}})
1383 The function @code{gpgme_get_protocol} retrieves the protocol currently
1384 use with the context @var{ctx}.
1385 @end deftypefun
1386
1387 @node @acronym{ASCII} Armor
1388 @subsection @acronym{ASCII} Armor
1389 @cindex context, armor mode
1390 @cindex @acronym{ASCII} armor
1391 @cindex armor mode
1392
1393 @deftypefun void gpgme_set_armor (@w{GpgmeCtx @var{ctx}}, @w{int @var{yes}})
1394 The function @code{gpgme_set_armor} specifies if the output should be
1395 @acronym{ASCII} armored.  By default, output is not @acronym{ASCII}
1396 armored.
1397
1398 @acronym{ASCII} armored output is disabled if @var{yes} is zero, and
1399 enabled otherwise.
1400 @end deftypefun
1401
1402 @deftypefun int gpgme_get_armor (@w{GpgmeCtx @var{ctx}})
1403 The function @code{gpgme_get_armor} returns 1 if the output is
1404 @acronym{ASCII} armored, and @code{0} if it is not, or if @var{ctx} is
1405 not a valid pointer.
1406 @end deftypefun
1407
1408
1409 @node Text Mode
1410 @subsection Text Mode
1411 @cindex context, text mode
1412 @cindex text mode
1413 @cindex canonical text mode
1414
1415 @deftypefun void gpgme_set_textmode (@w{GpgmeCtx @var{ctx}}, @w{int @var{yes}})
1416 The function @code{gpgme_set_textmode} specifies if canonical text mode
1417 should be used.  By default, text mode is not used.
1418
1419 Text mode is for example used for the RFC2015 signatures; note that
1420 the updated RFC 3156 mandates that the mail user agent does some
1421 preparations so that text mode is not needed anymore.
1422
1423 This option is only relevant to the OpenPGP crypto engine, and ignored
1424 by all other engines.
1425
1426 Canonical text mode is disabled if @var{yes} is zero, and enabled
1427 otherwise.
1428 @end deftypefun
1429
1430 @deftypefun int gpgme_get_textmode (@w{GpgmeCtx @var{ctx}})
1431 The function @code{gpgme_get_textmode} returns 1 if canonical text
1432 mode is enabled, and @code{0} if it is not, or if @var{ctx} is not a
1433 valid pointer.
1434 @end deftypefun
1435
1436
1437 @node Included Certificates
1438 @subsection Included Certificates
1439 @cindex certificates, included
1440
1441 @deftypefun void gpgme_set_include_certs (@w{GpgmeCtx @var{ctx}}, @w{int @var{nr_of_certs}})
1442 The function @code{gpgme_set_include_certs} specifies how many
1443 certificates should be included in an S/MIME signed message.  By
1444 default, only the sender's certificate is included.  The possible
1445 values of @var{nr_of_certs} are:
1446
1447 @table @code
1448 @item -2
1449 Include all certificates except the root certificate.
1450 @item -1
1451 Include all certificates.
1452 @item 0
1453 Include no certificates.
1454 @item 1
1455 Include the sender's certificate only.
1456 @item n
1457 Include the first n certificates of the certificates path, starting
1458 from the sender's certificate.  The number @code{n} must be positive.
1459 @end table
1460
1461 Values of @var{nr_of_certs} smaller than -2 are undefined.
1462
1463 This option is only relevant to the CMS crypto engine, and ignored
1464 by all other engines.
1465 @end deftypefun
1466
1467 @deftypefun int gpgme_get_include_certs (@w{GpgmeCtx @var{ctx}})
1468 The function @code{gpgme_get_include_certs} returns the number of
1469 certificates to include into an S/MIME signed message.
1470 @end deftypefun
1471
1472
1473 @node Key Listing Mode
1474 @subsection Key Listing Mode
1475 @cindex key listing mode
1476 @cindex key listing, mode of
1477
1478 @deftypefun void gpgme_set_keylist_mode (@w{GpgmeCtx @var{ctx}}, @w{int @var{mode}})
1479 The function @code{gpgme_set_keylist_mode} changes the default
1480 behaviour of the key listing functions.  The value in @var{mode} is a
1481 bitwise-or combination of one or multiple of the following bit values:
1482
1483 @table @code
1484 @item GPGME_KEYLIST_MODE_LOCAL
1485 The @code{GPGME_KEYLIST_MODE_LOCAL} symbol specifies that the local
1486 keyring should be searched for keys in the keylisting operation.  This
1487 is the default.
1488
1489 @item GPGME_KEYLIST_MODE_EXTERN
1490 The @code{GPGME_KEYLIST_MODE_EXTERN} symbol specifies that an external
1491 source should be should be searched for keys in the keylisting
1492 operation.  The type of external source is dependant on the crypto
1493 engine used.  For example, it can be a remote keyserver or LDAP
1494 certificate server.
1495 @end table
1496
1497 At least one of @code{GPGME_KEYLIST_MODE_LOCAL} and
1498 @code{GPGME_KEYLIST_MODE_EXTERN} must be specified.  For future binary
1499 compatibility, you should get the current mode with
1500 @code{gpgme_get_keylist_mode} and modify it by setting or clearing the
1501 appropriate bits, and then using that calulcated value in the
1502 @code{gpgme_set_keylisting_mode} operation.  This will leave all other
1503 bits in the mode value intact (in particular those that are not used
1504 in the current version of the library).
1505
1506 The function returns @code{GPGME_No_Error} if the mode could be set
1507 correctly, and @code{GPGME_Invalid_Value} if @var{ctx} is not a valid
1508 pointer or @var{mode} is not a valid mode.
1509 @end deftypefun
1510
1511
1512 @deftypefun int gpgme_get_keylist_mode (@w{GpgmeCtx @var{ctx}})
1513 The function @code{gpgme_get_keylist_mode} returns the current key
1514 listing mode of the context @var{ctx}.  This value can then be
1515 modified and used in a subsequent @code{gpgme_set_keylist_mode}
1516 operation to only affect the desired bits (and leave all others
1517 intact).
1518
1519 The function returns 0 if @var{ctx} is not a valid pointer, and the
1520 current mode otherwise.  Note that 0 is not a valid mode value.
1521 @end deftypefun
1522
1523
1524 @node Passphrase Callback
1525 @subsection Passphrase Callback
1526 @cindex callback, passphrase
1527 @cindex passphrase callback
1528
1529 @deftp {Data type} {GpgmeError (*GpgmePassphraseCb)(void *@var{hook}, const char *@var{desc}, void **@var{r_hd}, const char **@var{result})}
1530 @tindex GpgmePassphraseCb
1531 The @code{GpgmePassphraseCb} type is the type of functions usable as
1532 passphrase callback function.
1533
1534 The string @var{desc} contains a text usable to be displayed to the
1535 user of the application.  The function should return a passphrase for
1536 the context when invoked with @var{desc} not being @code{NULL} in
1537 *@var{result}.
1538
1539 The user may store information about the resources associated with the
1540 returned passphrase in @var{*r_hd}.  When the passphrase is no longer
1541 needed by @acronym{GPGME}, the passphrase callback function will be
1542 called with @var{desc} being @var{NULL}, and @var{r_hd} being the same
1543 as at the first invocation.
1544
1545 If an error occurs, return the corresponding @code{GpgmeError} value.
1546 You can use @code{GPGME_Canceled} to abort the operation.  Otherwise,
1547 return @code{0}.
1548 @end deftp
1549
1550 @deftypefun void gpgme_set_passphrase_cb (@w{GpgmeCtx @var{ctx}}, @w{GpgmePassphraseCb @var{passfunc}}, @w{void *@var{hook_value}})
1551 The function @code{gpgme_set_passphrase_cb} sets the function that is
1552 used when a passphrase needs to be provided by the user to
1553 @var{passfunc}.  The function @var{passfunc} needs to implemented by
1554 the user, and whenever it is called, it is called with its first
1555 argument being @var{hook_value}.  By default, no passphrase callback
1556 function is set.
1557
1558 Not all crypto engines require this callback to retrieve the
1559 passphrase.  It is better if the engine retrieves the passphrase from
1560 a trusted agent (a daemon process), rather than having each user to
1561 implement their own passphrase query.
1562
1563 The user can disable the use of a passphrase callback function by
1564 calling @code{gpgme_set_passphrase_cb} with @var{passfunc} being
1565 @code{NULL}.
1566 @end deftypefun
1567
1568 @deftypefun void gpgme_get_passphrase_cb (@w{GpgmeCtx @var{ctx}}, @w{GpgmePassphraseCb *@var{passfunc}}, @w{void **@var{hook_value}})
1569 The function @code{gpgme_get_passphrase_cb} returns the function that
1570 is used when a passphrase needs to be provided by the user in
1571 @var{*passfunc}, and the first argument for this function in
1572 @var{*hook_value}.  If no passphrase callback is set, or @var{ctx} is
1573 not a valid pointer, @code{NULL} is returned in both variables.
1574
1575 @var{passfunc} or @var{hook_value} can be @code{NULL}.  In this case,
1576 the corresponding value will not be returned.
1577 @end deftypefun
1578
1579
1580 @node Progress Meter Callback
1581 @subsection Progress Meter Callback
1582 @cindex callback, progress meter
1583 @cindex progress meter callback
1584
1585 @deftp {Data type} {const char *(*GpgmeProgressCb)(void *@var{hook}, const char *@var{what}, int @var{type}, int @var{current}, int @var{total})}
1586 @tindex GpgmeProgressCb
1587 The @code{GpgmeProgressCb} type is the type of functions usable as
1588 progress callback function.
1589
1590 The arguments are specific to the crypto engine.  More information
1591 about the progress information returned from the GnuPG engine can be
1592 found in the GnuPG source code in the file @file{doc/DETAILS} in the
1593 section PROGRESS.
1594 @end deftp
1595
1596 @deftypefun void gpgme_set_progress_cb (@w{GpgmeCtx @var{ctx}}, @w{GpgmeProgressCb @var{progfunc}}, @w{void *@var{hook_value}})
1597 The function @code{gpgme_set_progress_cb} sets the function that is
1598 used when progress information about a cryptographic operation is
1599 available.  The function @var{progfunc} needs to implemented by the
1600 user, and whenever it is called, it is called with its first argument
1601 being @var{hook_value}.  By default, no progress callback function
1602 is set.
1603
1604 Setting a callback function allows an interactive program to display
1605 progress information about a long operation to the user.
1606
1607 The user can disable the use of a progress callback function by
1608 calling @code{gpgme_set_progress_cb} with @var{progfunc} being
1609 @code{NULL}.
1610 @end deftypefun
1611
1612 @deftypefun void gpgme_get_progress_cb (@w{GpgmeCtx @var{ctx}}, @w{GpgmeProgressCb *@var{progfunc}}, @w{void **@var{hook_value}})
1613 The function @code{gpgme_get_progress_cb} returns the function that is
1614 used to inform the user about the progress made in @var{*progfunc},
1615 and the first argument for this function in @var{*hook_value}.  If no
1616 progress callback is set, or @var{ctx} is not a valid pointer,
1617 @code{NULL} is returned in both variables.
1618
1619 @var{progfunc} or @var{hook_value} can be @code{NULL}.  In this case,
1620 the corresponding value will not be returned.
1621 @end deftypefun
1622
1623
1624 @node Key Management
1625 @section Key Management
1626 @cindex key management
1627
1628 Some of the cryptographic operations require that recipients or
1629 signers are specified.  This is always done by specifying the
1630 respective keys that should be used for the operation.  The following
1631 section describes how such keys can be selected and manipulated.
1632
1633 @deftp {Data type} GpgmeKey
1634 The @code{GpgmeKey} type is a handle for a public or secret key, and
1635 is used to select the key for operations involving it.
1636
1637 A key can contain several user IDs and sub keys.
1638 @end deftp
1639
1640 @menu
1641 * Listing Keys::                  Browsing the list of available keys.
1642 * Information About Keys::        Requesting detailed information about keys.
1643 * Key Signatures::                Listing the signatures on a key.
1644 * Manipulating Keys::             Operations on keys.
1645 * Generating Keys::               Creating new key pairs.
1646 * Exporting Keys::                Retrieving key data from the key ring.
1647 * Importing Keys::                Adding keys to the key ring.
1648 * Deleting Keys::                 Removing keys from the key ring.
1649 @end menu
1650
1651
1652 @node Listing Keys
1653 @subsection Listing Keys
1654 @cindex listing keys
1655 @cindex key listing
1656 @cindex key listing, start
1657 @cindex key ring, list
1658 @cindex key ring, search
1659
1660 @deftypefun GpgmeError gpgme_op_keylist_start (@w{GpgmeCtx @var{ctx}}, @w{const char *@var{pattern}}, @w{int @var{secret_only}})
1661 The function @code{gpgme_op_keylist_start} initiates a key listing
1662 operation inside the context @var{ctx}.  It sets everything up so that
1663 subsequent invocations of @code{gpgme_op_keylist_next} return the keys
1664 in the list.
1665
1666 If @var{pattern} is @code{NULL}, all available keys are returned.
1667 Otherwise, @var{pattern} contains an engine specific expression that
1668 is used to limit the list to all keys matching the pattern.
1669
1670 If @var{secret_only} is not @code{0}, the list is restricted to secret
1671 keys only.
1672
1673 The context will be busy until either all keys are received (and
1674 @code{gpgme_op_keylist_next} returns @code{GPGME_EOF}), or
1675 @code{gpgme_op_keylist_end} is called to finish the operation.
1676
1677 The function returns @code{GPGME_Invalid_Value} if @var{ctx} is not a
1678 valid pointer, and passes through any errors that are reported by the
1679 crypto engine support routines.
1680 @end deftypefun
1681
1682 @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}})
1683 The function @code{gpgme_op_keylist_ext_start} initiates an extended
1684 key listing operation inside the context @var{ctx}.  It sets
1685 everything up so that subsequent invocations of
1686 @code{gpgme_op_keylist_next} return the keys in the list.
1687
1688 If @var{pattern} or @var{*pattern} is @code{NULL}, all available keys
1689 are returned.  Otherwise, @var{pattern} is a @code{NULL} terminated
1690 array of strings that are used to limit the list to all keys matching
1691 at least one of the patterns verbatim.
1692
1693 If @var{secret_only} is not @code{0}, the list is restricted to secret
1694 keys only.
1695
1696 The value of @var{reserved} must be @code{0}.
1697
1698 The context will be busy until either all keys are received (and
1699 @code{gpgme_op_keylist_next} returns @code{GPGME_EOF}), or
1700 @code{gpgme_op_keylist_end} is called to finish the operation.
1701
1702 The function returns @code{GPGME_Invalid_Value} if @var{ctx} is not a
1703 valid pointer, and passes through any errors that are reported by the
1704 crypto engine support routines.
1705 @end deftypefun
1706
1707 @deftypefun GpgmeError gpgme_op_keylist_next (@w{GpgmeCtx @var{ctx}}, @w{GpgmeKey *@var{r_key}})
1708 The function @code{gpgme_op_keylist_next} returns the next key in the
1709 list created by a previous @code{gpgme_op_keylist_start} operation in
1710 the context @var{ctx}.  The key will have one reference for the user.
1711 @xref{Manipulating Keys}.
1712
1713 This is the only way to get at @code{GpgmeKey} objects in
1714 @acronym{GPGME}.
1715
1716 If the last key in the list has already been returned,
1717 @code{gpgme_op_keylist_next} returns @code{GPGME_EOF}.
1718
1719 The function returns @code{GPGME_Invalid_Value} if @var{ctx} or
1720 @var{r_key} is not a valid pointer, and @code{GPGME_Out_Of_Core} if
1721 there is not enough memory for the operation.
1722 @end deftypefun
1723
1724 @deftypefun GpgmeError gpgme_op_keylist_end (@w{GpgmeCtx @var{ctx}})
1725 The function @code{gpgme_op_keylist_next} ends a pending key list
1726 operation in the context @var{ctx}.
1727
1728 The function returns @code{GPGME_Invalid_Value} if @var{ctx} is not a
1729 valid pointer, and @code{GPGME_Out_Of_Core} if at some time during the
1730 operation there was not enough memory available.
1731 @end deftypefun
1732
1733 The following example illustrates how all keys containing a certain
1734 string (@code{g10code}) can be listed with their key ID and the name
1735 and e-mail address of the main user ID:
1736
1737 @example
1738 GpgmeCtx ctx;
1739 GpgmeError err = gpgme_new (&ctx);
1740
1741 if (!err)
1742   @{
1743     err = gpgme_op_keylist_start (ctx, "g10code", 0);
1744     while (!err && (err = gpgme_op_keylist_next (ctx, &key)) != GPGME_EOF)
1745       @{
1746         printf ("%s: %s <%s>\n",
1747                 gpgme_key_get_string_attr (key, GPGME_ATTR_KEYID, 0, 0),
1748                 gpgme_key_get_string_attr (key, GPGME_ATTR_NAME, 0, 0),
1749                 gpgme_key_get_string_attr (key, GPGME_ATTR_EMAIL, 0, 0));
1750         gpgme_key_release (key);
1751       @}
1752     gpgme_release (ctx);
1753   @}
1754 if (err)
1755   @{
1756     fprintf (stderr, "%s: can not list keys: %s\n",
1757              argv[0], gpgme_strerror (err));
1758     exit (1);
1759   @}
1760 @end example
1761
1762 In a simple program, for which a blocking operation is acceptable, the
1763 following function can be used to retrieve a single key.
1764
1765 @deftypefun GpgmeError gpgme_get_key (@w{GpgmeCtx @var{ctx}}, @w{const char *@var{fpr}}, @w{GpgmeKey *@var{r_key}}, @w{int @var{secret}}, @w{int @var{force_update}})
1766 The function @code{gpgme_get_key} gets the key with the fingerprint
1767 (or key ID) @var{fpr} from the key cache or from the crypto backend
1768 and return it in @var{r_key}.  If @var{force_update} is true, force a
1769 refresh of the key from the crypto backend and replace the key in the
1770 cache, if any.  If @var{secret} is true, get the secret key.
1771
1772 If the @code{GPGME_KEYLIST_MODE_SIGS} mode is active, the key will be
1773 retrieved with the key signatures (and updated if necessary).
1774
1775 The function returns @code{GPGME_Invalid_Value} if @var{ctx} or
1776 @var{r_key} is not a valid pointer, @code{GPGME_Invalid_Key} if
1777 @var{fpr} is not a fingerprint or key ID, @code{GPGME_Out_Of_Core} if
1778 at some time during the operation there was not enough memory
1779 available.
1780 @end deftypefun
1781
1782
1783 @node Information About Keys
1784 @subsection Information About Keys
1785 @cindex key, information about
1786 @cindex key, attributes
1787 @cindex attributes, of a key
1788
1789 @deftypefun {char *} gpgme_key_get_as_xml (@w{GpgmeKey @var{key}})
1790 The function @code{gpgme_key_get_as_xml} returns a string in
1791 @acronym{XML} format describing the key @var{key}.  The user has to
1792 release the string with @code{free}.
1793
1794 The function returns @code{NULL} if @var{key} is not a valid pointer,
1795 or there is not enough memory available.
1796 @end deftypefun
1797
1798 @deftp {Data type} GpgmeAttr
1799 The @code{GpgmeAttr} type is used to specify a key or trust item
1800 attribute.  The following attributes are defined:
1801
1802 @table @code
1803 @item GPGME_ATTR_KEYID
1804 This is the key ID of a sub key.  It is representable as a string.
1805
1806 For trust items, the trust item refers to the key with this ID.
1807
1808 @item GPGME_ATTR_FPR
1809 This is the fingerprint of a sub key.  It is representable as a
1810 string.
1811
1812 @item GPGME_ATTR_ALGO
1813 This is the crypto algorithm for which the sub key can be used.  It
1814 is representable as a string and as a number.  The numbers correspond
1815 to the @code{enum gcry_pk_algos} values in the gcrypt library.
1816
1817 @item GPGME_ATTR_LEN
1818 This is the key length of a sub key.  It is representable as a
1819 number.
1820
1821 @item GPGME_ATTR_CREATED
1822 This is the timestamp at creation time of a sub key.  It is
1823 representable as a number.
1824
1825 @item GPGME_ATTR_EXPIRE
1826 This is the expiration time of a sub key.  It is representable as a
1827 number.
1828
1829 @item GPGME_ATTR_OTRUST
1830 XXX FIXME  (also for trust items)
1831
1832 @item GPGME_ATTR_USERID
1833 This is a user ID.  There can be more than one user IDs in a
1834 @var{GpgmeKey} object.  The first one (with index 0) is the primary
1835 user ID.  The user ID is representable as a number.
1836
1837 For trust items, this is the user ID associated with this trust item.
1838
1839 @item GPGME_ATTR_NAME
1840 This is the name belonging to a user ID.  It is representable as a string.
1841
1842 @item GPGME_ATTR_EMAIL
1843 This is the email address belonging to a user ID.  It is representable
1844 as a string.
1845
1846 @item GPGME_ATTR_COMMENT
1847 This is the comment belonging to a user ID.  It is representable as a
1848 string.
1849
1850 @item GPGME_ATTR_VALIDITY
1851 This is the validity belonging to a user ID.  It is representable as a
1852 string and as a number.  See below for a list of available validities.
1853
1854 For trust items, this is the validity that is associated with this
1855 trust item.
1856
1857 @item GPGME_ATTR_UID_REVOKED
1858 This specifies if a user ID is revoked.  It is representable as a
1859 number, and is @code{1} if the user ID is revoked, and @code{0}
1860 otherwise.
1861
1862 @item GPGME_ATTR_UID_INVALID
1863 This specifies if a user ID is invalid.  It is representable as a
1864 number, and is @code{1} if the user ID is invalid, and @code{0}
1865 otherwise.
1866
1867 @item GPGME_ATTR_LEVEL
1868 This is the trust level of a trust item.
1869
1870 @item GPGME_ATTR_TYPE
1871 This returns information about the type of key.  For the string function
1872 this will eother be "PGP" or "X.509".  The integer function returns 0
1873 for PGP and 1 for X.509.  It is also used for the type of a trust item.
1874
1875 @item GPGME_ATTR_IS_SECRET
1876 This specifies if the key is a secret key.  It is representable as a
1877 number, and is @code{1} if the key is revoked, and @code{0} otherwise.
1878
1879 @item GPGME_ATTR_KEY_REVOKED
1880 This specifies if a sub key is revoked.  It is representable as a
1881 number, and is @code{1} if the key is revoked, and @code{0} otherwise.
1882
1883 @item GPGME_ATTR_KEY_INVALID
1884 This specifies if a sub key is invalid.  It is representable as a
1885 number, and is @code{1} if the key is invalid, and @code{0} otherwise.
1886
1887 @item GPGME_ATTR_KEY_EXPIRED
1888 This specifies if a sub key is expired.  It is representable as a
1889 number, and is @code{1} if the key is expired, and @code{0} otherwise.
1890
1891 @item GPGME_ATTR_KEY_DISABLED
1892 This specifies if a sub key is disabled.  It is representable as a
1893 number, and is @code{1} if the key is disabled, and @code{0} otherwise.
1894
1895 @item GPGME_ATTR_KEY_CAPS
1896 This is a description of the capabilities of a sub key.  It is
1897 representable as a string.  The string contains the letter ``e'' if
1898 the key can be used for encryption, ``s'' if the key can be used for
1899 signatures, and ``c'' if the key can be used for certifications.
1900
1901 @item GPGME_ATTR_CAN_ENCRYPT
1902 This specifies if a sub key can be used for encryption.  It is
1903 representable as a number, and is @code{1} if the sub key can be used
1904 for encryption, and @code{0} otherwise.
1905
1906 @item GPGME_ATTR_CAN_SIGN
1907 This specifies if a sub key can be used for signatures.  It is
1908 representable as a number, and is @code{1} if the sub key can be used
1909 for signatures, and @code{0} otherwise.
1910
1911 @item GPGME_ATTR_CAN_CERTIFY
1912 This specifies if a sub key can be used for certifications.  It is
1913 representable as a number, and is @code{1} if the sub key can be used
1914 for certifications, and @code{0} otherwise.
1915
1916 @item GPGME_ATTR_SERIAL
1917 The X.509 issuer serial attribute of the key.  It is representable as
1918 a string.
1919
1920 @item GPGME_ATTR_ISSUE
1921 The X.509 issuer name attribute of the key.  It is representable as a
1922 string.
1923
1924 @item GPGME_ATTR_CHAINID
1925 The X.509 chain ID can be used to build the certification chain.  It
1926 is representable as a string.
1927 @end table
1928 @end deftp
1929
1930 @deftp {Data type} GpgmeValidity
1931 The @code{GpgmeValidity} type is used to specify the validity of a user ID
1932 in a key.  The following validities are defined:
1933
1934 @table @code
1935 @item GPGME_VALIDITY_UNKNOWN
1936 The user ID is of unknown validity.  The string representation of this
1937 validity is ``?''.
1938
1939 @item GPGME_VALIDITY_UNDEFINED
1940 The validity of the user ID is undefined.  The string representation of this
1941 validity is ``q''.
1942
1943 @item GPGME_VALIDITY_NEVER
1944 The user ID is never valid.  The string representation of this
1945 validity is ``n''.
1946
1947 @item GPGME_VALIDITY_MARGINAL
1948 The user ID is marginally valid.  The string representation of this
1949 validity is ``m''.
1950
1951 @item GPGME_VALIDITY_FULL
1952 The user ID is fully valid.  The string representation of this
1953 validity is ``f''.
1954
1955 @item GPGME_VALIDITY_ULTIMATE
1956 The user ID is ultimately valid.  The string representation of this
1957 validity is ``u''.
1958 @end table
1959 @end deftp
1960
1961 @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}})
1962 The function @code{gpgme_key_get_string_attr} returns the value of the
1963 string-representable attribute @var{what} of key @var{key}.  If the
1964 attribute is an attribute of a sub key or an user ID, @var{idx}
1965 specifies the sub key or user ID of which the attribute value is
1966 returned.  The argument @var{reserved} is reserved for later use and
1967 should be @code{NULL}.
1968
1969 The string returned is only valid as long as the key is valid.
1970
1971 The function returns @code{0} if an attribute can't be returned as a
1972 string, @var{key} is not a valid pointer, @var{idx} out of range,
1973 or @var{reserved} not @code{NULL}.
1974 @end deftypefun
1975
1976 @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}})
1977 The function @code{gpgme_key_get_ulong_attr} returns the value of the
1978 number-representable attribute @var{what} of key @var{key}.  If the
1979 attribute is an attribute of a sub key or an user ID, @var{idx}
1980 specifies the sub key or user ID of which the attribute value is
1981 returned.  The argument @var{reserved} is reserved for later use and
1982 should be @code{NULL}.
1983
1984 The function returns @code{0} if the attribute can't be returned as a
1985 number, @var{key} is not a valid pointer, @var{idx} out of range,
1986 or @var{reserved} not @code{NULL}.
1987 @end deftypefun
1988
1989
1990 @node Key Signatures
1991 @subsection Key Signatures
1992 @cindex key, signatures
1993 @cindex signatures, on a key
1994
1995 The signatures on a key are only available if the key was retrieved
1996 via a listing operation with the @code{GPGME_KEYLIST_MODE_SIGS} mode
1997 enabled, because it is expensive to retrieve all signatures of a key.
1998
1999 So, before using the below interfaces to retrieve the signatures on a
2000 key, you have to make sure that the key was listed with signatures
2001 enabled.  One convenient, but blocking, way to do this is to use the
2002 function @code{gpgme_get_key}.
2003
2004 @deftp {Data type} GpgmeAttr
2005 The @code{GpgmeAttr} type is used to specify a key signature
2006 attribute.  The following attributes are defined:
2007
2008 @table @code
2009 @item GPGME_ATTR_KEYID
2010 This is the key ID of the key which was used for the signature.  It is
2011 representable as a string.
2012
2013 @item GPGME_ATTR_ALGO
2014 This is the crypto algorithm used to create the signature.  It is
2015 representable as a string and as a number.  The numbers correspond to
2016 the @code{enum gcry_pk_algos} values in the gcrypt library.
2017
2018 @item GPGME_ATTR_CREATED
2019 This is the timestamp at creation time of the signature.  It is
2020 representable as a number.
2021
2022 @item GPGME_ATTR_EXPIRE
2023 This is the expiration time of the signature.  It is representable as
2024 a number.
2025
2026 @item GPGME_ATTR_USERID
2027 This is the user ID associated with the signing key.  The user ID is
2028 representable as a number.
2029
2030 @item GPGME_ATTR_NAME
2031 This is the name belonging to a user ID.  It is representable as a string.
2032
2033 @item GPGME_ATTR_EMAIL
2034 This is the email address belonging to a user ID.  It is representable
2035 as a string.
2036
2037 @item GPGME_ATTR_COMMENT
2038 This is the comment belonging to a user ID.  It is representable as a
2039 string.
2040
2041 @item GPGME_ATTR_KEY_REVOKED
2042 This specifies if a key signature is a revocation signature.  It is
2043 representable as a number, and is @code{1} if the key is revoked, and
2044 @code{0} otherwise.
2045
2046 @c @item GPGME_ATTR_KEY_EXPIRED
2047 @c This specifies if a key signature is expired.  It is representable as
2048 @c a number, and is @code{1} if the key is revoked, and @code{0}
2049 @c otherwise.
2050 @c
2051 @item GPGME_ATTR_SIG_CLASS
2052 This specifies the signature class of a key signature.  It is
2053 representable as a number.  The meaning is specific to the crypto
2054 engine.
2055
2056 @item GPGME_ATTR_SIG_CLASS
2057 This specifies the signature class of a key signature.  It is
2058 representable as a number.  The meaning is specific to the crypto
2059 engine.
2060
2061 @item GPGME_ATTR_SIG_STATUS
2062 This is the same value as returned by @code{gpgme_get_sig_status}.
2063 @end table
2064 @end deftp
2065
2066 @deftypefun {const char *} gpgme_key_sig_get_string_attr (@w{GpgmeKey @var{key}}, @w{int @var{uid_idx}}, @w{GpgmeAttr @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}})
2067 The function @code{gpgme_key_sig_get_string_attr} returns the value of
2068 the string-representable attribute @var{what} of the signature
2069 @var{idx} on the user ID @var{uid_idx} in the key @var{key}.  The
2070 argument @var{reserved} is reserved for later use and should be
2071 @code{NULL}.
2072
2073 The string returned is only valid as long as the key is valid.
2074
2075 The function returns @code{0} if an attribute can't be returned as a
2076 string, @var{key} is not a valid pointer, @var{uid_idx} or @var{idx}
2077 out of range, or @var{reserved} not @code{NULL}.
2078 @end deftypefun
2079
2080 @deftypefun {unsigned long} gpgme_key_sig_get_ulong_attr (@w{GpgmeKey @var{key}}, @w{int @var{uid_idx}}, @w{GpgmeAttr @var{what}}, @w{const void *@var{reserved}}, @w{int @var{idx}})
2081 The function @code{gpgme_key_sig_get_ulong_attr} returns the value of
2082 the number-representable attribute @var{what} of the signature
2083 @var{idx} on the user ID @var{uid_idx} in the key @var{key}.  The
2084 argument @var{reserved} is reserved for later use and should be
2085 @code{NULL}.
2086
2087 The function returns @code{0} if an attribute can't be returned as a
2088 string, @var{key} is not a valid pointer, @var{uid_idx} or @var{idx}
2089 out of range, or @var{reserved} not @code{NULL}.
2090 @end deftypefun
2091
2092
2093 @node Manipulating Keys
2094 @subsection Manipulating Keys
2095 @cindex key, manipulation
2096
2097 @deftypefun void gpgme_key_ref (@w{GpgmeKey @var{key}})
2098 The function @code{gpgme_key_ref} acquires an additional reference for
2099 the key @var{key}.
2100 @end deftypefun
2101
2102 @deftypefun void gpgme_key_unref (@w{GpgmeKey @var{key}})
2103 @deftypefunx void gpgme_key_release (@w{GpgmeKey @var{key}})
2104 The function @code{gpgme_key_ref} releases a reference for the key
2105 @var{key}.  If this was the last reference, the key will be destroyed
2106 and all resources associated to it will be released.
2107
2108 The function @code{gpgme_key_release} is an alias for
2109 @code{gpgme_key_unref}.
2110 @end deftypefun
2111
2112
2113 @node Generating Keys
2114 @subsection Generating Keys
2115 @cindex key, creation
2116 @cindex key ring, add
2117
2118 @deftypefun GpgmeError gpgme_op_genkey (@w{GpgmeCtx @var{ctx}}, @w{const char *@var{parms}}, @w{GpgmeData @var{public}}, @w{GpgmeData @var{secret}})
2119 The function @code{gpgme_op_genkey} generates a new key pair in the
2120 context @var{ctx}.  The meaning of @var{public} and @var{secret}
2121 depends on the crypto backend.
2122
2123 GnuPG does not support @var{public} and @var{secret}, they should be
2124 @code{NULL}.  GnuPG will generate a key pair and add it to the
2125 standard key ring.  The fingerprint of the generated key is available
2126 with @code{gpgme_op_genkey_result}.
2127
2128 GpgSM requires @var{public} to be a writable data object.  GpgSM will
2129 generate a secret key (which will be stored by @command{gpg-agent},
2130 and return a certificate request in @var{public}, which then needs to
2131 be signed by the certification authority and imported before it can be
2132 used.  GpgSM does not make the fingerprint available.
2133
2134 The argument @var{parms} specifies parameters for the key in an XML
2135 string.  The details about the format of @var{parms} are specific to
2136 the crypto engine used by @var{ctx}.  Here is an example for GnuPG as
2137 the crypto engine:
2138
2139 @example
2140 <GnupgKeyParms format="internal">
2141 Key-Type: DSA
2142 Key-Length: 1024
2143 Subkey-Type: ELG-E
2144 Subkey-Length: 1024
2145 Name-Real: Joe Tester
2146 Name-Comment: with stupid passphrase
2147 Name-Email: joe@@foo.bar
2148 Expire-Date: 0
2149 Passphrase: abc
2150 </GnupgKeyParms>
2151 @end example
2152
2153 Here is an example for GpgSM as the crypto engine:
2154
2155 @example
2156 <GnupgKeyParms format="internal">
2157 Key-Type: RSA
2158 Key-Length: 1024
2159 Name-DN: C=de,O=g10 code,OU=Testlab,CN=Joe 2 Tester
2160 Name-Email: joe@@foo.bar
2161 </GnupgKeyParms>
2162 @end example
2163
2164 Strings should be given in UTF-8 encoding.  The only format supported
2165 for now is ``internal''.  The content of the @code{GnupgKeyParms}
2166 container is passed verbatim to the crypto backend.  Control
2167 statements are not allowed.
2168
2169 After the operation completed successfully, the result can be
2170 retrieved with @code{gpgme_op_genkey_result}.
2171
2172 The function returns @code{GPGME_No_Error} if the operation could be
2173 started successfully, @code{GPGME_Invalid_Value} if @var{parms} is not
2174 a valid XML string, @code{GPGME_Not_Supported} if @var{public} or
2175 @var{secret} is not valid, and @code{GPGME_General_Error} if no key
2176 was created by the backend.
2177 @end deftypefun
2178
2179 @deftypefun GpgmeError gpgme_op_genkey_start (@w{GpgmeCtx @var{ctx}}, @w{const char *@var{parms}}, @w{GpgmeData @var{public}}, @w{GpgmeData @var{secret}})
2180 The function @code{gpgme_op_genkey_start} initiates a
2181 @code{gpgme_op_genkey} operation.  It can be completed by calling
2182 @code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
2183
2184 The function returns @code{GPGME_No_Error} if the operation could be
2185 started successfully, @code{GPGME_Invalid_Value} if @var{parms} is not
2186 a valid XML string, and @code{GPGME_Not_Supported} if @var{public} or
2187 @var{secret} is not @code{NULL}.
2188 @end deftypefun
2189
2190 @deftp {Data type} {GpgmeGenKeyResult}
2191 This is a pointer to a structure used to store the result of a
2192 @code{gpgme_op_genkey} operation.  After successfully generating a
2193 key, you can retrieve the pointer to the result with
2194 @code{gpgme_op_genkey_result}.  The structure contains the following
2195 members:
2196
2197 @table @code
2198 @item unsigned int primary : 1
2199 This is a flag that is set to 1 if a primary key was created and to 0
2200 if not.
2201
2202 @item unsigned int sub : 1
2203 This is a flag that is set to 1 if a subkey was created and to 0
2204 if not.
2205
2206 @item char *fpr
2207 This is the fingerprint of the key that was created.  If both a
2208 primary and a sub key were generated, the fingerprint of the primary
2209 key will be returned.  If the crypto engine does not provide the
2210 fingerprint, @code{fpr} will be a null pointer.
2211 @end table
2212 @end deftp
2213
2214 @deftypefun GpgmeGenKeyResult gpgme_op_genkey_result (@w{GpgmeCtx @var{ctx}})
2215 The function @code{gpgme_op_genkey_result} returns a
2216 @code{GpgmeGenKeyResult} pointer to a structure holding the result of
2217 a @code{gpgme_op_genkey} operation.  The pointer is only valid if the
2218 last operation on the context was a @code{gpgme_op_genkey} or
2219 @code{gpgme_op_genkey_start} operation, and if this operation finished
2220 successfully.  The returned pointer is only valid until the next
2221 operation is started on the context.
2222 @end deftypefun
2223
2224
2225 @node Exporting Keys
2226 @subsection Exporting Keys
2227 @cindex key, export
2228 @cindex key ring, export from
2229
2230 @deftypefun GpgmeError gpgme_op_export (@w{GpgmeCtx @var{ctx}}, @w{GpgmeRecipients @var{recipients}}, @w{GpgmeData @var{keydata}})
2231 The function @code{gpgme_op_export} extracts the public keys of the
2232 user IDs in @var{recipients} and returns them in the data buffer
2233 @var{keydata}.  The type of the public keys returned is determined by
2234 the @acronym{ASCII} armor attribute set for the context @var{ctx}.
2235
2236 The function returns @code{GPGME_No_Error} if the operation completed
2237 successfully, @code{GPGME_Invalid_Value} if @var{recipients} is
2238 @code{NULL} or @var{keydata} is not a valid empty data buffer, and
2239 passes through any errors that are reported by the crypto engine
2240 support routines.
2241 @end deftypefun
2242
2243 @deftypefun GpgmeError gpgme_op_export_start (@w{GpgmeCtx @var{ctx}}, @w{GpgmeRecipients @var{recipients}}, @w{GpgmeData @var{keydata}})
2244 The function @code{gpgme_op_export_start} initiates a
2245 @code{gpgme_op_export} operation.  It can be completed by calling
2246 @code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
2247
2248 The function returns @code{GPGME_No_Error} if the operation could be
2249 started successfully, and @code{GPGME_Invalid_Value} if
2250 @var{recipients} is @code{NULL} or @var{keydata} is not a valid empty
2251 data buffer.
2252 @end deftypefun
2253
2254
2255 @node Importing Keys
2256 @subsection Importing Keys
2257 @cindex key, import
2258 @cindex key ring, import to
2259
2260 @deftypefun GpgmeError gpgme_op_import (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{keydata}})
2261 The function @code{gpgme_op_import} adds the keys in the data buffer
2262 @var{keydata} to the key ring of the crypto engine used by @var{ctx}.
2263 The format of @var{keydata} can be @var{ASCII} armored, for example,
2264 but the details are specific to the crypto engine.
2265
2266 More information about the import is available with
2267 @code{gpgme_get_op_info}.  @xref{Detailed Results}.
2268
2269 The function returns @code{GPGME_No_Error} if the import was completed
2270 successfully, @code{GPGME_Invalid_Value} if @var{keydata} if @var{ctx}
2271 or @var{keydata} is not a valid pointer, and @code{GPGME_No_Data} if
2272 @var{keydata} is an empty data buffer.
2273 @end deftypefun
2274
2275 @deftypefun GpgmeError gpgme_op_import_start (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{keydata}})
2276 The function @code{gpgme_op_import_start} initiates a
2277 @code{gpgme_op_import} operation.  It can be completed by calling
2278 @code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
2279
2280 The function returns @code{GPGME_No_Error} if the import could be
2281 started successfully, @code{GPGME_Invalid_Value} if @var{keydata} if
2282 @var{ctx} or @var{keydata} is not a valid pointer, and
2283 @code{GPGME_No_Data} if @var{keydata} is an empty data buffer.
2284 @end deftypefun
2285
2286 @deftp {Data type} {GpgmeImportStatus}
2287 This is a pointer to a structure used to store a part of the result of
2288 a @code{gpgme_op_genkey} operation.  For each considered key one
2289 status is added that contains information about the result of the
2290 import.  The structure contains the following members:
2291
2292 @table @code
2293 @item GpgmeImportStatus next
2294 This is a pointer to the next status object in the list.
2295
2296 @item char *fpr
2297 This is the fingerprint of the key that was considered.
2298
2299 @item GpgmeError result
2300 If the import was not successful, this is the error value that caused
2301 the import to fail.  Otherwise it is @code{GPGME_No_Error}.
2302
2303 @item unsigned int status
2304 This is a bit-wise OR of the following flags that give more
2305 information about what part of the key was imported.  If the key was
2306 already known, this might be 0.
2307
2308 @table @code
2309 @item GPGME_IMPORT_NEW
2310 The key was new.
2311
2312 @item GPGME_IMPORT_UID
2313 The key contained new user IDs.
2314
2315 @item GPGME_IMPORT_SIG
2316 The key contained new signatures.
2317
2318 @item GPGME_IMPORT_SUBKEY
2319 The key contained new sub keys.
2320
2321 @item GPGME_IMPORT_PRIVATE
2322 The key contained a private key.
2323 @end table
2324 @end table
2325 @end deftp
2326
2327 @deftp {Data type} {GpgmeImportResult}
2328 This is a pointer to a structure used to store the result of a
2329 @code{gpgme_op_genkey} operation.  After a successful import
2330 operation, you can retrieve the pointer to the result with
2331 @code{gpgme_op_import_result}.  The structure contains the following
2332 members:
2333
2334 @table @code
2335 @item int considered
2336 The total number of considered keys.
2337
2338 @item int no_user_id
2339 The number of keys without user ID.
2340
2341 @item int imported
2342 The total number of imported keys.
2343
2344 @item imported_rsa
2345 The number of imported RSA keys.
2346
2347 @item unchanged
2348 The number of unchanged keys.
2349
2350 @item new_user_ids
2351 The number of new user IDs.
2352
2353 @item new_sub_keys
2354 The number of new sub keys.
2355
2356 @item new_signatures
2357 The number of new signatures.
2358
2359 @item new_revocations
2360 The number of new revocations.
2361
2362 @item secret_read
2363 The total number of secret keys read.
2364
2365 @item secret_imported
2366 The number of imported secret keys.
2367
2368 @item secret_unchanged
2369 The number of unchanged secret keys.
2370
2371 @item not_imported
2372 The number of keys not imported.
2373
2374 @item GpgmeImportStatus imports
2375 A list of GpgmeImportStatus objects which contain more information
2376 about the keys for which an import was attempted.
2377 @end table
2378 @end deftp
2379
2380 @deftypefun GpgmeImportResult gpgme_op_import_result (@w{GpgmeCtx @var{ctx}})
2381 The function @code{gpgme_op_import_result} returns a
2382 @code{GpgmeImportResult} pointer to a structure holding the result of
2383 a @code{gpgme_op_import} operation.  The pointer is only valid if the
2384 last operation on the context was a @code{gpgme_op_import} or
2385 @code{gpgme_op_import_start} operation, and if this operation finished
2386 successfully.  The returned pointer is only valid until the next
2387 operation is started on the context.
2388 @end deftypefun
2389
2390 The following interface is deprecated and only provided for backward
2391 compatibility.  Don't use it.  It will be removed in a future version
2392 of @acronym{GPGME}.
2393
2394 @deftypefun GpgmeError gpgme_op_import_ext (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{keydata}}, @w{int *@var{nr}})
2395 The function @code{gpgme_op_import_ext} is equivalent to:
2396
2397 @example
2398   GpgmeError err = gpgme_op_import (ctx, keydata);
2399   if (!err)
2400     @{
2401       GpgmeImportResult result = gpgme_op_import_result (ctx);
2402       *nr = result->considered;
2403     @}
2404 @end example
2405 @end deftypefun
2406
2407
2408 @node Deleting Keys
2409 @subsection Deleting Keys
2410 @cindex key, delete
2411 @cindex key ring, delete from
2412
2413 @deftypefun GpgmeError gpgme_op_delete (@w{GpgmeCtx @var{ctx}}, @w{const GpgmeKey @var{key}}, @w{int @var{allow_secret}})
2414 The function @code{gpgme_op_delete} deletes the key @var{key} from the
2415 key ring of the crypto engine used by @var{ctx}.  If
2416 @var{allow_secret} is @code{0}, only public keys are deleted,
2417 otherwise secret keys are deleted as well, if that is supported.
2418
2419 The function returns @code{GPGME_No_Error} if the key was deleted
2420 successfully, @code{GPGME_Invalid_Value} if @var{ctx} or @var{key} is
2421 not a valid pointer, @code{GPGME_Invalid_Key} if @var{key} could not
2422 be found in the keyring, and @code{GPGME_Conflict} if the secret key
2423 for @var{key} is available, but @var{allow_secret} is zero.
2424 @end deftypefun
2425
2426 @deftypefun GpgmeError gpgme_op_delete_start (@w{GpgmeCtx @var{ctx}}, @w{const GpgmeKey @var{key}}, @w{int @var{allow_secret}})
2427 The function @code{gpgme_op_delete_start} initiates a
2428 @code{gpgme_op_delete} operation.  It can be completed by calling
2429 @code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
2430
2431 The function returns @code{GPGME_No_Error} if the operation was
2432 started successfully, and @code{GPGME_Invalid_Value} if @var{ctx} or
2433 @var{key} is not a valid pointer.
2434 @end deftypefun
2435
2436
2437 @node Trust Item Management
2438 @section Trust Item Management
2439 @cindex trust item
2440
2441 @strong{Caution:} The trust items interface is experimental.
2442
2443 @deftp {Data type} GpgmeTrustItem
2444 The @code{GpgmeTrustItem} type is a handle for a trust item.
2445 @end deftp
2446
2447 @menu
2448 * Listing Trust Items::           Browsing the list of available trust items.
2449 * Information About Trust Items:: Requesting detailed information about trust items.
2450 * Manipulating Trust Items::      Operations on trust items.
2451 @end menu
2452
2453
2454 @node Listing Trust Items
2455 @subsection Listing Trust Items
2456 @cindex trust item list
2457
2458 @deftypefun GpgmeError gpgme_op_trustlist_start (@w{GpgmeCtx @var{ctx}}, @w{const char *@var{pattern}}, @w{int @var{max_level}})
2459 The function @code{gpgme_op_trustlist_start} initiates a trust item
2460 listing operation inside the context @var{ctx}.  It sets everything up
2461 so that subsequent invocations of @code{gpgme_op_trustlist_next} return
2462 the trust items in the list.
2463
2464 The string @var{pattern} contains an engine specific expression that
2465 is used to limit the list to all trust items matching the pattern.  It
2466 can not be the empty string.
2467
2468 The argument @var{max_level} is currently ignored.
2469
2470 The context will be busy until either all trust items are received
2471 (and @code{gpgme_op_trustlist_next} returns @code{GPGME_EOF}), or
2472 @code{gpgme_op_trustlist_end} is called to finish the operation.
2473
2474 The function returns @code{GPGME_Invalid_Value} if @var{ctx} is not a
2475 valid pointer, and passes through any errors that are reported by the
2476 crypto engine support routines.
2477 @end deftypefun
2478
2479 @deftypefun GpgmeError gpgme_op_trustlist_next (@w{GpgmeCtx @var{ctx}}, @w{GpgmeTrustItem *@var{r_item}})
2480 The function @code{gpgme_op_trustlist_next} returns the next trust
2481 item in the list created by a previous @code{gpgme_op_trustlist_start}
2482 operation in the context @var{ctx}.  The trust item can be destroyed
2483 with @code{gpgme_trust_item_release}.  @xref{Manipulating Trust Items}.
2484
2485 This is the only way to get at @code{GpgmeTrustItem} objects in
2486 @acronym{GPGME}.
2487
2488 If the last trust item in the list has already been returned,
2489 @code{gpgme_op_trustlist_next} returns @code{GPGME_EOF}.
2490
2491 The function returns @code{GPGME_Invalid_Value} if @var{ctx} or
2492 @var{r_item} is not a valid pointer, and @code{GPGME_Out_Of_Core} if
2493 there is not enough memory for the operation.
2494 @end deftypefun
2495
2496 @deftypefun GpgmeError gpgme_op_trustlist_end (@w{GpgmeCtx @var{ctx}})
2497 The function @code{gpgme_op_trustlist_next} ends a pending key list
2498 operation in the context @var{ctx}.
2499
2500 The function returns @code{GPGME_Invalid_Value} if @var{ctx} is not a
2501 valid pointer, and @code{GPGME_Out_Of_Core} if at some time during the
2502 operation there was not enough memory available.
2503 @end deftypefun
2504
2505
2506 @node Information About Trust Items
2507 @subsection Information About Trust Items
2508 @cindex trust item, information about
2509 @cindex trust item, attributes
2510 @cindex attributes, of a trust item
2511
2512 Trust items have attributes which can be queried using the interfaces
2513 below.  The attribute identifiers are shared with those for key
2514 attributes.  @xref{Information About Keys}.
2515
2516 @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}})
2517 The function @code{gpgme_trust_item_get_string_attr} returns the value
2518 of the string-representable attribute @var{what} of trust item
2519 @var{item}.  The arguments @var{idx} and @var{reserved} are reserved
2520 for later use and should be @code{0} and @code{NULL} respectively.
2521
2522 The string returned is only valid as long as the key is valid.
2523
2524 The function returns @code{0} if an attribute can't be returned as a
2525 string, @var{key} is not a valid pointer, @var{idx} out of range,
2526 or @var{reserved} not @code{NULL}.
2527 @end deftypefun
2528
2529 @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}})
2530 The function @code{gpgme_trust_item_get_int_attr} returns the value of
2531 the number-representable attribute @var{what} of trust item
2532 @var{item}.  If the attribute occurs more than once in the trust item,
2533 the index is specified by @var{idx}.  However, currently no such
2534 attribute exists, so @var{idx} should be @code{0}.  The argument
2535 @var{reserved} is reserved for later use and should be @code{NULL}.
2536
2537 The function returns @code{0} if the attribute can't be returned as a
2538 number, @var{key} is not a valid pointer, @var{idx} out of range,
2539 or @var{reserved} not @code{NULL}.
2540 @end deftypefun
2541
2542
2543 @node Manipulating Trust Items
2544 @subsection Manipulating Trust Items
2545 @cindex trust item, manipulation
2546
2547 @deftypefun void gpgme_trust_item_release (@w{GpgmeTrustItem @var{item}})
2548 The function @code{gpgme_trust_item_release} destroys a
2549 @code{GpgmeTrustItem} object and releases all associated resources.
2550 @end deftypefun
2551
2552 @node Crypto Operations
2553 @section Crypto Operations
2554 @cindex cryptographic operation
2555
2556 @menu
2557 * Decrypt::                       Decrypting a ciphertext.
2558 * Verify::                        Verifying a signature.
2559 * Decrypt and Verify::            Decrypting a signed ciphertext.
2560 * Sign::                          Creating a signature.
2561 * Encrypt::                       Encrypting a plaintext.
2562 * Detailed Results::              How to obtain more info about the operation.
2563 @end menu
2564
2565
2566 @node Decrypt
2567 @subsection Decrypt
2568 @cindex decryption
2569 @cindex cryptographic operation, decryption
2570
2571 @deftypefun GpgmeError gpgme_op_decrypt (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{cipher}}, @w{GpgmeData @var{plain}})
2572 The function @code{gpgme_op_decrypt} decrypts the ciphertext in the
2573 data object @var{cipher} and stores it into the data object
2574 @var{plain}.
2575
2576 The function returns @code{GPGME_No_Error} if the ciphertext could be
2577 decrypted successfully, @code{GPGME_Invalid_Value} if @var{ctx},
2578 @var{cipher} or @var{plain} is not a valid pointer,
2579 @code{GPGME_No_Data} if @var{cipher} does not contain any data to
2580 decrypt, @code{GPGME_Decryption_Failed} if @var{cipher} is not a valid
2581 cipher text, @code{GPGME_Bad_Passphrase} if the passphrase for the
2582 secret key could not be retrieved, and passes through any errors that
2583 are reported by the crypto engine support routines.
2584 @end deftypefun
2585
2586 @deftypefun GpgmeError gpgme_op_decrypt_start (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{cipher}}, @w{GpgmeData @var{plain}})
2587 The function @code{gpgme_op_decrypt_start} initiates a
2588 @code{gpgme_op_decrypt} operation.  It can be completed by calling
2589 @code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
2590
2591 The function returns @code{GPGME_No_Error} if the operation could be
2592 started successfully, and @code{GPGME_Invalid_Value} if @var{cipher}
2593 or @var{plain} is not a valid pointer.
2594 @end deftypefun
2595
2596
2597 @node Verify
2598 @subsection Verify
2599 @cindex verification
2600 @cindex signature, verification
2601 @cindex cryptographic operation, verification
2602 @cindex cryptographic operation, signature check
2603 @cindex signature, status
2604
2605 @deftp {Data type} {enum GpgmeSigStat}
2606 @tindex GpgmeSigStat
2607 The @code{GpgmeSigStat} type holds the result of a signature check, or
2608 the combined result of all signatures.  The following results are
2609 possible:
2610
2611 @table @code
2612 @item GPGME_SIG_STAT_NONE
2613 This status should not occur in normal operation.
2614
2615 @item GPGME_SIG_STAT_GOOD
2616 This status indicates that the signature is valid.  For the combined
2617 result this status means that all signatures are valid.
2618
2619 @item GPGME_SIG_STAT_GOOD_EXP
2620 This status indicates that the signature is valid but expired.  For
2621 the combined result this status means that all signatures are valid
2622 and expired.
2623
2624 @item GPGME_SIG_STAT_GOOD_EXPKEY
2625 This status indicates that the signature is valid but the key used to
2626 verify the signature has expired.  For the combined result this status
2627 means that all signatures are valid and all keys are expired.
2628
2629 @item GPGME_SIG_STAT_BAD
2630 This status indicates that the signature is invalid.  For the combined
2631 result this status means that all signatures are invalid.
2632
2633 @item GPGME_SIG_STAT_NOKEY
2634 This status indicates that the signature could not be verified due to
2635 a missing key.  For the combined result this status means that all
2636 signatures could not be checked due to missing keys.
2637
2638 @item GPGME_SIG_STAT_NOSIG
2639 This status indicates that the signature data provided was not a real
2640 signature.
2641
2642 @item GPGME_SIG_STAT_ERROR
2643 This status indicates that there was some other error which prevented
2644 the signature verification.
2645
2646 @item GPGME_SIG_STAT_DIFF
2647 For the combined result this status means that at least two signatures
2648 have a different status.  You can get each key's status with
2649 @code{gpgme_get_sig_status}.
2650 @end table
2651 @end deftp
2652
2653
2654 @deftypefun GpgmeError gpgme_op_verify (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{sig}}, @w{GpgmeData @var{signed_text}}, @w{GpgmeData @var{plain}})
2655 The function @code{gpgme_op_verify} verifies that the signature in the
2656 data object @var{sig} is a valid signature.  If @var{sig} is a
2657 detached signature, then the signed text should be provided in
2658 @var{signed_text} and @var{plain} should be a null pointer.
2659 Otherwise, if @var{sig} is a normal (or cleartext) signature,
2660 @var{signed_text} should be a null pointer and @var{plain} should be a
2661 writable data object that will contain the plaintext after successful
2662 verification.
2663
2664 The results of the individual signature verifications can be retrieved
2665 with @code{gpgme_get_sig_status} and @code{gpgme_get_sig_key}.
2666
2667 The function returns @code{GPGME_No_Error} if the operation could be
2668 completed successfully, @code{GPGME_Invalid_Value} if @var{ctx},
2669 @var{sig}, @var{plain} or @var{r_stat} is not a valid pointer,
2670 @code{GPGME_No_Data} if @var{sig} does not contain any data to verify,
2671 and passes through any errors that are reported by the crypto engine
2672 support routines.
2673 @end deftypefun
2674
2675 @deftypefun GpgmeError gpgme_op_verify_start (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{sig}}, @w{GpgmeData @var{signed_text}}, @w{GpgmeData @var{plain}})
2676 The function @code{gpgme_op_verify_start} initiates a
2677 @code{gpgme_op_verify} operation.  It can be completed by calling
2678 @code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
2679
2680 The function returns @code{GPGME_No_Error} if the operation could be
2681 started successfully, @code{GPGME_Invalid_Value} if @var{ctx},
2682 @var{sig}, @var{plain} or @var{r_stat} is not a valid pointer, and
2683 @code{GPGME_No_Data} if @var{sig} or @var{plain} does not contain any
2684 data to verify.
2685 @end deftypefun
2686
2687 @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}})
2688 The function @code{gpgme_get_sig_status} receives information about a
2689 signature after the @code{gpgme_op_verify} or
2690 @code{gpgme_op_verify_decrypt} operation.  A single detached signature
2691 can contain signatures by more than one key.  The @var{idx} specifies
2692 which signature's information should be retrieved, starting from
2693 @var{0}.
2694
2695 The status of the signature will be returned in @var{r_stat} if it is
2696 not @code{NULL}.  The creation time stamp of the signature will be
2697 returned in @var{r_created} if it is not @var{NULL}.
2698
2699 The function returns a statically allocated string that contains the
2700 fingerprint of the key which signed the plaintext, or @code{NULL} if
2701 @var{ctx} is not a valid pointer, the operation is still pending, or
2702 no verification could be performed.
2703 @end deftypefun
2704
2705 @deftypefun {const char *} gpgme_get_sig_string_attr (@w{GpgmeCtx @var{ctx}}, @w{int @var{idx}}, @w{GpgmeAttr @var{what}}, @w{int @var{whatidx}})
2706 This function is similar to @code{gpgme_get_sig_status} but may be used
2707 to retrieve more detailed information.  @var{ctx} should be the context
2708 used for the last signature verification, @var{idx} is used to enumerate
2709 over all signatures starting with @code{0} and @var{whatidx} should be
2710 @code{0} unless otherwise stated.
2711
2712 The following values may be used for @var{what}:
2713 @table @code
2714 @item GPGME_ATTR_FPR
2715 Return the fingerprint of the key used to create the signature.
2716
2717 @item GPGME_ATTR_ERRTOK
2718 Return a token with a more detailed error description.  A @var{whatidx}
2719 of @code{0} returns an error token associated with validity calculation,
2720 a value of @code{1} return an error token related to the certificate
2721 checking.
2722
2723 @end table
2724 @end deftypefun
2725
2726 @deftypefun {const char *} gpgme_get_sig_ulong_attr (@w{GpgmeCtx @var{ctx}}, @w{int @var{idx}}, @w{GpgmeAttr @var{waht}}, @w{int @var{whatidx}})
2727 This function is similar to @code{gpgme_get_sig_string_attr} but used
2728 for attributes which can be represented by an @code{unsigned long} data
2729 type.  @var{ctx} should be the context used for the last signature
2730 verification, @var{idx} is used to enumerate over all signatures
2731 starting with @code{0} and @var{whatidx} should be @code{0} unless
2732 otherwise stated.
2733
2734 The following values may be used for @var{what}:
2735 @table @code
2736 @item GPGME_ATTR_CREATED
2737 Return the creation time of the signature in seconds since Epoch.  This
2738 is the same value as returned by @code{gpgme_get_sig_status}.
2739
2740 @item GPGME_ATTR_EXPIRE
2741 Return the expiration time of the signature in seconds since Epoch. 
2742
2743 @item GPGME_ATTR_VALIDITY
2744 Returns the validity of the key used to create the signature.  This is a
2745 shortcut function which avoids an extra key lookup.  The value returned
2746 is one of @code{GPGME_VALIDITY_UNKNOWN}, @code{GPGME_VALIDITY_NEVER},
2747 @code{GPGME_VALIDITY_MARGINAL} or @code{GPGME_VALIDITY_FULL}.
2748
2749 @item GPGME_ATTR_SIG_STATUS
2750 This is the same value as returned by @code{gpgme_get_sig_status}.
2751
2752 @item GPGME_ATTR_SIG_SUMMARY
2753 This returns a bit vector giving a summary of the signature status.
2754 Itprovides an easy interface to a defined semantic of the signature
2755 status.  Checking just one bit is sufficient to see whether a signature
2756 is valid without any restrictions.
2757
2758 The defined bits are:
2759   @table @code
2760   @item GPGME_SIGSUM_VALID
2761   The signature is fully valid.
2762
2763   @item GPGME_SIGSUM_GREEN
2764   The signature is good but one might want to display some extra
2765   information.  Check the other bits.
2766
2767   @item GPGME_SIGSUM_RED
2768   The signature is bad. It might be useful to checkother bits and
2769   display moe information, i.e. a revoked certificate might not render a
2770   signature invalid when the message was received prior to the cause for
2771   the revocation.
2772
2773   @item GPGME_SIGSUM_KEY_REVOKED
2774   The key or at least one certificate has been revoked.
2775
2776   @item GPGME_SIGSUM_KEY_EXPIRED
2777   The key or one of the certificates has expired. It is probably a good
2778   idea to display the date of the expiration.
2779
2780   @item GPGME_SIGSUM_SIG_EXPIRED
2781   The signature has expired.
2782
2783   @item GPGME_SIGSUM_KEY_MISSING
2784   Can't verifydue to a missing key o certificate.
2785
2786   @item GPGME_SIGSUM_CRL_MISSING
2787   The CRL (or an equivalent mechanism) is not available. 
2788
2789   @item GPGME_SIGSUM_CRL_TOO_OLD
2790   Available CRL is too old.
2791
2792   @item GPGME_SIGSUM_BAD_POLICY
2793   A policy requirement was not met. 
2794
2795   @item GPGME_SIGSUM_SYS_ERROR
2796   A system error occured. 
2797
2798   @end table
2799
2800 @end table
2801 @end deftypefun
2802
2803
2804 @deftypefun {const char *} gpgme_get_sig_key (@w{GpgmeCtx @var{ctx}}, @w{int @var{idx}}, @w{GpgmeKey *@var{r_key}})
2805 The function @code{gpgme_get_sig_status} receives a @code{GpgmeKey}
2806 object for the key which was used to verify the signature after the
2807 @code{gpgme_op_verify} or @code{gpgme_op_verify_decrypt} operation.  A
2808 single detached signature can contain signatures by more than one key.
2809 The @var{idx} specifies which signature's information should be
2810 retrieved, starting from @var{0}.  The key will have on reference for
2811 the user.
2812
2813 The function is a convenient way to retrieve the keys belonging to the
2814 fingerprints returned by @code{gpgme_get_sig_status}.
2815
2816 The function returns @code{GPGME_No_Error} if the key could be
2817 returned, @code{GPGME_Invalid_Value} if @var{r_key} is not a valid
2818 pointer, @code{GPGME_Invalid_Key} if the fingerprint is not valid,
2819 @code{GPGME_EOF} if @var{idx} is too large, or some other error value
2820 if a problem occurred requesting the key.
2821 @end deftypefun
2822
2823 @deftypefun {char *} gpgme_get_notation (@w{GpgmeCtx @var{ctx}})
2824 The function @code{gpgme_get_notation} can be used to retrieve
2825 notation data from the last signature check in the context @var{ctx}.
2826
2827 If there is notation data available from the last signature check,
2828 this function may be used to return this notation data as a string.
2829 The string is an XML representation of that data embedded in a
2830 <notation> container.  The user has to release the string with
2831 @code{free}.
2832
2833 The function returns a string if the notation data is available or
2834 @code{NULL} if there is no such data available.
2835 @end deftypefun
2836
2837
2838 @node Decrypt and Verify
2839 @subsection Decrypt and Verify
2840 @cindex decryption and verification
2841 @cindex verification and decryption
2842 @cindex signature check
2843 @cindex cryptographic operation, decryption and verification
2844
2845 @deftypefun GpgmeError gpgme_op_decrypt_verify (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{cipher}}, @w{GpgmeData @var{plain}})
2846 The function @code{gpgme_op_decrypt_verify} decrypts the ciphertext in
2847 the data object @var{cipher} and stores it into the data object
2848 @var{plain}.  If @var{cipher} contains signatures, they will be
2849 verified.
2850
2851 After the operation completed, @code{gpgme_op_get_sig_status} and
2852 @code{gpgme_op_get_sig_key} can be used to retrieve more information
2853 about the signatures.
2854
2855 The function returns @code{GPGME_No_Error} if the ciphertext could be
2856 decrypted successfully, @code{GPGME_Invalid_Value} if @var{ctx},
2857 @var{cipher}, @var{plain} or @var{r_stat} is not a valid pointer,
2858 @code{GPGME_No_Data} if @var{cipher} does not contain any data to
2859 decrypt, @code{GPGME_Decryption_Failed} if @var{cipher} is not a valid
2860 cipher text, @code{GPGME_Bad_Passphrase} if the passphrase for the
2861 secret key could not be retrieved, and passes through any errors that
2862 are reported by the crypto engine support routines.
2863 @end deftypefun
2864
2865 @deftypefun GpgmeError gpgme_op_decrypt_verify (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{cipher}}, @w{GpgmeData @var{plain}})
2866 The function @code{gpgme_op_decrypt_verify_start} initiates a
2867 @code{gpgme_op_decrypt_verify} operation.  It can be completed by
2868 calling @code{gpgme_wait} on the context.  @xref{Waiting For
2869 Completion}.
2870
2871 The function returns @code{GPGME_No_Error} if the operation could be
2872 started successfully, @code{GPGME_Invalid_Value} if @var{ctx},
2873 @var{cipher}, @var{plain} or @var{r_stat} is not a valid pointer, and
2874 @code{GPGME_No_Data} if @var{cipher} does not contain any data to
2875 decrypt.
2876 @end deftypefun
2877
2878
2879 @node Sign
2880 @subsection Sign
2881 @cindex signature, creation
2882 @cindex sign
2883 @cindex cryptographic operation, signing
2884
2885 A signature can contain signatures by one or more keys.  The set of
2886 keys used to create a signatures is contained in a context, and is
2887 applied to all following signing operations in this context (until the
2888 set is changed).
2889
2890 @menu
2891 * Selecting Signers::             How to choose the keys to sign with.
2892 * Creating a Signature::          How to create a signature.
2893 @end menu
2894
2895
2896 @node Selecting Signers
2897 @subsubsection Selecting Signers
2898 @cindex signature, selecting signers
2899 @cindex signers, selecting
2900
2901 @deftypefun void gpgme_signers_clear (@w{GpgmeCtx @var{ctx}})
2902 The function @code{gpgme_signers_clear} releases a reference for each
2903 key on the signers list and removes the list of signers from the
2904 context @var{ctx}.
2905
2906 Every context starts with an empty list.
2907 @end deftypefun
2908
2909 @deftypefun GpgmeError gpgme_signers_add (@w{GpgmeCtx @var{ctx}}, @w{const GpgmeKey @var{key}})
2910 The function @code{gpgme_signers_add} adds the key @var{key} to the
2911 list of signers in the context @var{ctx}.
2912
2913 Calling this function acquires an additional reference for the key.
2914 @end deftypefun
2915
2916 @deftypefun GpgmeKey gpgme_signers_enum (@w{const GpgmeCtx @var{ctx}}, @w{int @var{seq}})
2917 The function @code{gpgme_signers_enum} returns the @var{seq}th key in
2918 the list of signers in the context @var{ctx}.  An additional reference
2919 is acquired for the user.
2920
2921 If @var{seq} is out of range, @code{NULL} is returned.
2922 @end deftypefun
2923
2924
2925 @node Creating a Signature
2926 @subsubsection Creating a Signature
2927
2928 @deftp {Data type} {enum GpgmeSigMode}
2929 @tindex GpgmeSigMode
2930 The @code{GpgmeSigMode} type is used to specify the desired type of a
2931 signature.  The following modes are available:
2932
2933 @table @code
2934 @item GPGME_SIG_MODE_NORMAL
2935 A normal signature is made, the output includes the plaintext and the
2936 signature.
2937
2938 @item GPGME_SIG_MODE_DETACH
2939 A detached signature is made.
2940
2941 @item GPGME_SIG_MODE_CLEAR
2942 A clear text signature is made.  The @acronym{ASCII} armor and text
2943 mode settings of the context are ignored.
2944 @end table
2945 @end deftp
2946
2947 @deftypefun GpgmeError gpgme_op_sign (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{plain}}, @w{GpgmeData @var{sig}}, @w{GpgmeSigMode @var{mode}})
2948 The function @code{gpgme_op_sign} creates a signature for the text in
2949 the data object @var{plain} and returns it in the data object
2950 @var{sig}.  The type of the signature created is determined by the
2951 @acronym{ASCII} armor and text mode attributes set for the context
2952 @var{ctx} and the requested signature mode @var{mode}.
2953
2954 More information about the signatures is available with
2955 @code{gpgme_get_op_info}.  @xref{Detailed Results}.
2956
2957 If an S/MIME signed message is created using the CMS crypto engine,
2958 the number of certificates to include in the message can be specified
2959 with @code{gpgme_set_include_certs}.  @xref{Included Certificates}.
2960
2961 The function returns @code{GPGME_No_Error} if the signature could be
2962 created successfully, @code{GPGME_Invalid_Value} if @var{ctx},
2963 @var{plain} or @var{sig} is not a valid pointer, @code{GPGME_No_Data}
2964 if the signature could not be created, @code{GPGME_Bad_Passphrase} if
2965 the passphrase for the secret key could not be retrieved, and passes
2966 through any errors that are reported by the crypto engine support
2967 routines.
2968 @end deftypefun
2969
2970 @deftypefun GpgmeError gpgme_op_sign_start (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{plain}}, @w{GpgmeData @var{sig}}, @w{GpgmeSigMode @var{mode}})
2971 The function @code{gpgme_op_sign_start} initiates a
2972 @code{gpgme_op_sign} operation.  It can be completed by calling
2973 @code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
2974
2975 The function returns @code{GPGME_No_Error} if the operation could be
2976 started successfully, and @code{GPGME_Invalid_Value} if @var{ctx},
2977 @var{plain} or @var{sig} is not a valid pointer.
2978 @end deftypefun
2979
2980
2981 @node Encrypt
2982 @subsection Encrypt
2983 @cindex encryption
2984 @cindex cryptographic operation, encryption
2985
2986 One plaintext can be encrypted for several recipients at the same
2987 time.  The list of recipients is created independently of any context,
2988 and then passed to the encryption operation.
2989
2990 @menu
2991 * Selecting Recipients::          How to choose the recipients.
2992 * Encrypting a Plaintext::        How to encrypt a plaintext.
2993 @end menu
2994
2995
2996 @node Selecting Recipients
2997 @subsubsection Selecting Recipients
2998 @cindex encryption, selecting recipients
2999 @cindex recipients
3000
3001 @deftp {Data type} GpgmeRecipients
3002 The @code{GpgmeRecipients} type is a handle for a set of recipients
3003 that can be used in an encryption process.
3004 @end deftp
3005
3006 @deftypefun GpgmeError gpgme_recipients_new (@w{GpgmeRecipients *@var{r_rset}})
3007 The function @code{gpgme_recipients_new} creates a new, empty set of
3008 recipients and returns a handle for it in @var{r_rset}.
3009
3010 The function returns @code{GPGME_No_Error} if the recipient set could
3011 be created successfully, and @code{GPGME_Out_Of_Core} if not enough
3012 memory was available.
3013 @end deftypefun
3014
3015 @deftypefun void gpgme_recipients_release (@w{GpgmeRecipients @var{rset}})
3016 The function @code{gpgme_recipients_release} destroys the set of
3017 recipients @var{rset} and releases all associated resources.
3018 @end deftypefun
3019
3020 @deftypefun GpgmeError gpgme_recipients_add_name (@w{GpgmeRecipients @var{rset}}, @w{const char *@var{name}})
3021 The function @code{gpgme_recipients_add_name} adds the recipient
3022 @var{name} to the set of recipients @var{rset}.  This is equivalent to
3023 @code{gpgme_recipients_add_name_with_validity} with a validity of
3024 @code{GPGME_VALIDITY_UNKNOWN}.
3025
3026 The function returns @code{GPGME_No_Error} if the recipient was added
3027 successfully, @code{GPGME_Invalid_Value} if @var{rset} or @var{name}
3028 is not a valid pointer, and @code{GPGME_Out_Of_Core} if not enough
3029 memory is available.
3030 @end deftypefun
3031
3032 @deftypefun GpgmeError gpgme_recipients_add_name_with_validity (@w{GpgmeRecipients @var{rset}}, @w{const char *@var{name}}, @w{GpgmeValidity @var{val}})
3033 The function @code{gpgme_recipients_add_name_with_validity} adds the
3034 recipient @var{name} with the validity @var{val} to the set of
3035 recipients @var{rset}.  If the validity is not known, the function
3036 @code{gpgme_recipients_add_name} can be used.
3037 @xref{Information About Keys}, for the possible values for @var{val}.
3038
3039 The function returns @code{GPGME_No_Error} if the recipient was added
3040 successfully, @code{GPGME_Invalid_Value} if @var{rset} or @var{name}
3041 is not a valid pointer, and @code{GPGME_Out_Of_Core} if not enough
3042 memory is available.
3043 @end deftypefun
3044
3045 @deftypefun {unsigned int} gpgme_recipients_count (@w{const @var{GpgmeRecipients rset}})
3046 The function @code{gpgme_recipients_count} returns the number of
3047 recipients in the set @var{rset}.
3048 @end deftypefun
3049
3050 @deftypefun GpgmeError gpgme_recipients_enum_open (@w{const GpgmeRecipients @var{rset}}, @w{void **@var{iter}})
3051 The function @code{gpgme_recipients_enum_open} creates a new iterator
3052 @var{iter} that can be used to walk through the set of recipients in
3053 @var{rset}, using @code{gpgme_recipients_enum_read}.
3054
3055 If the iterator is not needed anymore, it can be closed with
3056 @code{gpgme_recipients_enum_close}.
3057
3058 The function returns @code{GPGME_No_Error} if the enumerator was
3059 successfully created and @code{GPGME_Invalid_Value} if @var{rset} or
3060 @var{iter} is not a valid pointer.
3061 @end deftypefun
3062
3063 @deftypefun {const char *} gpgme_recipients_enum_read (@w{const GpgmeRecipients @var{rset}}, @w{void **@var{iter}})
3064 The function @code{gpgme_recipients_enum_read} returns a string
3065 containing the name of the next recipient in the set @var{rset} for
3066 the iterator @var{iter}.  The string is valid as long as @var{rset} is
3067 valid or the function is called the next time with the same recipient
3068 set and iterator, whatever is earlier.
3069 @end deftypefun
3070
3071 @deftypefun GpgmeError gpgme_recipients_enum_close (@w{const GpgmeRecipients @var{rset}}, @w{void **@var{iter}})
3072 The function @code{gpgme_recipients_enum_close} releases the iterator
3073 @var{iter} for the recipient set @var{rset}.
3074 @end deftypefun
3075
3076
3077 @node Encrypting a Plaintext
3078 @subsubsection Encrypting a Plaintext
3079
3080 @deftypefun GpgmeError gpgme_op_encrypt (@w{GpgmeCtx @var{ctx}}, @w{GpgmeRecipients @var{rset}}, @w{GpgmeData @var{plain}}, @w{GpgmeData @var{cipher}})
3081 The function @code{gpgme_op_encrypt} encrypts the plaintext in the data
3082 object @var{plain} for the recipients @var{rset} and stores the
3083 ciphertext in the data object @var{cipher}.  The type of the
3084 ciphertext created is determined by the @acronym{ASCII} armor and text
3085 mode attributes set for the context @var{ctx}.
3086
3087 If @code{GPGME_Invalid_UserID} is returned, some recipients in
3088 @var{rset} are invalid, but not all.  In this case the plaintext is
3089 encrypted for all valid recipients and returned in @var{cipher}.  More
3090 information about the invalid recipients is available with
3091 @code{gpgme_get_op_info}.  @xref{Detailed Results}.
3092
3093 If @var{recp} is @code{NULL}, symmetric rather than public key
3094 encryption is performed.  Symmetrically encrypted cipher text can be
3095 deciphered with @code{gpgme_op_decrypt}.  Note that in this case the
3096 crypto backend needs to retrieve a passphrase from the user.
3097 Symmetric encryption is currently only supported for the OpenPGP
3098 crypto backend.
3099
3100 The function returns @code{GPGME_No_Error} if the ciphertext could be
3101 created successfully, @code{GPGME_Invalid_Value} if @var{ctx},
3102 @var{rset}, @var{plain} or @var{cipher} is not a valid pointer,
3103 @code{GPGME_No_UserID} if @var{rset} does not contain any valid
3104 recipients, @code{GPGME_Invalid_UserID} if @var{rset} contains some
3105 invalid recipients, @code{GPGME_Bad_Passphrase} if the passphrase for
3106 the secret key could not be retrieved, and passes through any errors
3107 that are reported by the crypto engine support routines.
3108 @end deftypefun
3109
3110 @deftypefun GpgmeError gpgme_op_encrypt_start (@w{GpgmeCtx @var{ctx}}, @w{GpgmeRecipients @var{rset}}, @w{GpgmeData @var{plain}}, @w{GpgmeData @var{cipher}})
3111 The function @code{gpgme_op_encrypt_start} initiates a
3112 @code{gpgme_op_encrypt} operation.  It can be completed by calling
3113 @code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
3114
3115 The function returns @code{GPGME_No_Error} if the operation could be
3116 started successfully, @code{GPGME_Invalid_Value} if @var{ctx},
3117 @var{rset}, @var{plain} or @var{cipher} is not a valid pointer, and
3118 @code{GPGME_No_UserID} if @var{rset} does not contain any valid
3119 recipients.
3120 @end deftypefun
3121
3122
3123 @deftypefun GpgmeError gpgme_op_encrypt_sign (@w{GpgmeCtx @var{ctx}}, @w{GpgmeRecipients @var{rset}}, @w{GpgmeData @var{plain}}, @w{GpgmeData @var{cipher}})
3124 The function @code{gpgme_op_encrypt_sign} does a combined encrypt and
3125 sign operation.  It is used like @code{gpgme_op_encrypt}, but the
3126 ciphertext also contains signatures for the signers listed in
3127 @var{ctx}.
3128
3129 The combined encrypt and sign operation is currently only available
3130 for the OpenPGP crypto engine.
3131 @end deftypefun
3132
3133 @deftypefun GpgmeError gpgme_op_encrypt_sign_start (@w{GpgmeCtx @var{ctx}}, @w{GpgmeRecipients @var{rset}}, @w{GpgmeData @var{plain}}, @w{GpgmeData @var{cipher}})
3134 The function @code{gpgme_op_encrypt_sign_start} initiates a
3135 @code{gpgme_op_encrypt_sign} operation.  It can be completed by
3136 calling @code{gpgme_wait} on the context.  @xref{Waiting For
3137 Completion}.
3138
3139 The function returns @code{GPGME_No_Error} if the operation could be
3140 started successfully, @code{GPGME_Invalid_Value} if @var{ctx},
3141 @var{rset}, @var{plain} or @var{cipher} is not a valid pointer, and
3142 @code{GPGME_No_UserID} if @var{rset} does not contain any valid
3143 recipients.
3144 @end deftypefun
3145
3146
3147 @node Detailed Results
3148 @subsection Detailed Results
3149 @cindex cryptographic operation, detailed results
3150
3151 @deftypefun {char *} gpgme_get_op_info (@w{GpgmeCtx @var{ctx}}, @w{int @var{reserved}})
3152 The function @code{gpgme_get_op_info} retrieves more information about
3153 the last crypto operation.
3154
3155 The function returns a string in the XML format.  The user has to
3156 release the string with @code{free}.
3157
3158 Here is a sample of the information that might be returned:
3159 @example
3160 <GnupgOperationInfo>
3161   <signature>
3162     <detached/> <!-- or cleartext or standard -->
3163     <algo>17</algo>
3164     <hashalgo>2</hashalgo>
3165     <micalg>pgp-sha1</micalg>
3166     <sigclass>01</sigclass>
3167     <created>9222222</created>
3168     <fpr>121212121212121212</fpr>
3169   </signature>
3170 </GnupgOperationInfo>
3171 @end example
3172
3173 Currently, the only operations that return additional information are
3174 encrypt, sign and import.  @xref{Encrypt}, @xref{Sign},
3175 @xref{Importing Keys}.
3176
3177 The function returns a string or @code{NULL} if no such data is
3178 available.
3179 @end deftypefun
3180
3181
3182 @node Run Control
3183 @section Run Control
3184 @cindex run control
3185 @cindex cryptographic operation, running
3186
3187 @acronym{GPGME} supports running operations synchronously and
3188 asynchronously.  You can use asynchronous operation to set up a
3189 context up to initiating the desired operation, but delay performing
3190 it to a later point.
3191
3192 Furthermore, you can use an external event loop to control exactly
3193 when @acronym{GPGME} runs.  This ensures that @acronym{GPGME} only
3194 runs when necessary and also prevents it from blocking for a long
3195 time.
3196
3197 @menu
3198 * Waiting For Completion::        Waiting until an operation is completed.
3199 * Using External Event Loops::    Advanced control over what happens when.
3200 @end menu
3201
3202
3203 @node Waiting For Completion
3204 @subsection Waiting For Completion
3205 @cindex cryptographic operation, wait for
3206 @cindex wait for completion
3207
3208 @deftypefun GpgmeCtx gpgme_wait (@w{GpgmeCtx @var{ctx}}, @w{GpgmeError *@var{status}}, @w{int @var{hang}})
3209 The function @code{gpgme_wait} continues the pending operation within
3210 the context @var{ctx}.  In particular, it ensures the data exchange
3211 between @acronym{GPGME} and the crypto backend and watches over the
3212 run time status of the backend process.
3213
3214 If @var{hang} is true, the function does not return until the
3215 operation is completed or cancelled.  Otherwise the function will not
3216 block for a long time.
3217
3218 The error status of the finished operation is returned in @var{status}
3219 if @code{gpgme_wait} does not return @code{NULL}.
3220
3221 The @var{ctx} argument can be @code{NULL}.  In that case,
3222 @code{gpgme_wait} waits for any context to complete its operation.
3223
3224 @code{gpgme_wait} can be used only in conjunction with any context
3225 that has a pending operation initiated with one of the
3226 @code{gpgme_op_*_start} functions except @code{gpgme_op_keylist_start}
3227 and @code{gpgme_op_trustlist_start} (for which you should use the
3228 corresponding @code{gpgme_op_*_next} functions).  If @var{ctx} is
3229 @code{NULL}, all of such contexts are waited upon and possibly
3230 returned.  Synchronous operations running in parallel, as well as key
3231 and trust item list operations, do not affect @code{gpgme_wait}.
3232
3233 In a multi-threaded environment, only one thread should ever call
3234 @code{gpgme_wait} at any time, irregardless if @var{ctx} is specified
3235 or not.  This means that all calls to this function should be fully
3236 synchronized by locking primitives.  It is safe to start asynchronous
3237 operations while a thread is running in @code{gpgme_wait}.
3238
3239 The function returns the @var{ctx} of the context which has finished
3240 the operation.  If @var{hang} is false, and the timeout expires,
3241 @code{NULL} is returned and @code{*status} will be set to 0.  If an
3242 error occurs, @code{NULL} is returned and the error is returned in
3243 @code{*status}.
3244 @end deftypefun
3245
3246
3247 @node Using External Event Loops
3248 @subsection Using External Event Loops
3249 @cindex event loop, external
3250
3251 @acronym{GPGME} hides the complexity of the communication between the
3252 library and the crypto engine.  The price of this convenience is that
3253 the calling thread can block arbitrary long waiting for the data
3254 returned by the crypto engine.  In single-threaded programs, in
3255 particular if they are interactive, this is an unwanted side-effect.
3256 OTOH, if @code{gpgme_wait} is used without the @var{hang} option being
3257 enabled, it might be called unnecessarily often, wasting CPU time that
3258 could be used otherwise.
3259
3260 The I/O callback interface described in this section lets the user
3261 take control over what happens when.  @acronym{GPGME} will provide the
3262 user with the file descriptors that should be monitored, and the
3263 callback functions that should be invoked when a file descriptor is
3264 ready for reading or writing.  It is then the user's responsibility to
3265 decide when to check the file descriptors and when to invoke the
3266 callback functions.  Usually this is done in an event loop, that also
3267 checks for events in other parts of the program.  If the callback
3268 functions are only called when the file descriptors are ready,
3269 @acronym{GPGME} will never block.  This gives the user mroe control
3270 over the program flow, and allows to perform other tasks when
3271 @acronym{GPGME} would block otherwise.
3272
3273 By using this advanced mechanism, @acronym{GPGME} can be integrated
3274 smoothly into GUI toolkits like GTK+ even for single-threaded
3275 programs.
3276
3277 @menu
3278 * I/O Callback Interface::        How I/O callbacks are registered.
3279 * Registering I/O Callbacks::     How to use I/O callbacks for a context.
3280 * I/O Callback Example::          An example how to use I/O callbacks.
3281 * I/O Callback Example GTK+::     How to use @acronym{GPGME} with GTK+.
3282 * I/O Callback Example GDK::      How to use @acronym{GPGME} with GDK.
3283 @end menu
3284
3285
3286 @node I/O Callback Interface
3287 @subsubsection I/O Callback Interface
3288
3289 @deftp {Data type} {GpgmeError (*GpgmeIOCb) (@w{void *@var{data}}, @w{int @var{fd}})}
3290 @tindex GpgmeIOCb
3291 The @code{GpgmeIOCb} type is the type of functions which
3292 @acronym{GPGME} wants to register as I/O callback handlers using the
3293 @code{GpgmeRegisterIOCb} functions provided by the user.
3294
3295 @var{data} and @var{fd} are provided by @acronym{GPGME} when the I/O
3296 callback handler is registered, and should be passed through to the
3297 handler when it is invoked by the user because it noticed activity on
3298 the file descriptor @var{fd}.
3299
3300 The callback handler always returns @code{0}, but you should consider
3301 the return value to be reserved for later use.
3302 @end deftp
3303
3304 @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}})}
3305 @tindex GpgmeRegisterIOCb
3306 The @code{GpgmeRegisterIOCb} type is the type of functions which can
3307 be called by @acronym{GPGME} to register an I/O callback funtion
3308 @var{fnc} for the file descriptor @var{fd} with the user.
3309 @var{fnc_data} should be passed as the first argument to @var{fnc}
3310 when the handler is invoked (the second argument should be @var{fd}).
3311 If @var{dir} is 0, @var{fnc} should be called by the user when
3312 @var{fd} is ready for writing.  If @var{dir} is 1, @var{fnc} should be
3313 called when @var{fd} is ready for reading.
3314
3315 @var{data} was provided by the user when registering the
3316 @code{GpgmeRegisterIOCb} function with @acronym{GPGME} and will always
3317 be passed as the first argument when registering a callback function.
3318 For example, the user can use this to determine the event loop to
3319 which the file descriptor should be added.
3320
3321 @acronym{GPGME} will call this function when a crypto operation is
3322 initiated in a context for which the user has registered I/O callback
3323 handler functions with @code{gpgme_set_io_cbs}.  It can also call this
3324 function when it is in an I/O callback handler for a file descriptor
3325 associated to this context.
3326
3327 The user should return a unique handle in @var{tag} identifying this
3328 I/O callback registration, which will be passed to the
3329 @code{GpgmeRegisterIOCb} function without interpretation when the file
3330 descriptor should not be monitored anymore.
3331 @end deftp
3332
3333 @deftp {Data type} {void (*GpgmeRemoveIOCb) (@w{void *@var{tag}})}
3334 The @code{GpgmeRemoveIOCb} type is the type of functions which can be
3335 called by @acronym{GPGME} to remove an I/O callback handler that was
3336 registered before.  @var{tag} is the handle that was returned by the
3337 @code{GpgmeRegisterIOCb} for this I/O callback.
3338
3339 @acronym{GPGME} can call this function when a crypto operation is in
3340 an I/O callback.  It will also call this function when the context is
3341 destroyed while an operation is pending.
3342 @end deftp
3343
3344 @deftp {Data type} {enum GpgmeEventIO}
3345 @tindex GpgmeEventIO
3346 The @code{GpgmeEventIO} type specifies the type of an event that is
3347 reported to the user by @acronym{GPGME} as a consequence of an I/O
3348 operation.  The following events are defined:
3349
3350 @table @code
3351 @item GPGME_EVENT_START
3352 The operation is fully initialized now, and you can start to run the
3353 registered I/O callback handlers now.  Note that registered I/O
3354 callback handlers must not be run before this event is signalled.
3355 @var{type_data} is @code{NULL} and reserved for later use.
3356
3357 @item GPGME_EVENT_DONE
3358 The operation is finished, the last I/O callback for this operation
3359 was removed.  The accompanying @var{type_data} points to a
3360 @code{GpgmeError} variable that contains the status of the operation
3361 that finished.  This event is signalled after the last I/O callback
3362 has been removed.
3363
3364 @item GPGME_EVENT_NEXT_KEY
3365 In a @code{gpgme_op_keylist_start} operation, the next key was
3366 received from the crypto engine.  The accompanying @var{type_data} is
3367 a @code{GpgmeKey} variable that contains the key with one reference
3368 for the user.
3369
3370 @item GPGME_EVENT_NEXT_TRUSTITEM
3371 In a @code{gpgme_op_trustlist_start} operation, the next trust item
3372 was received from the crypto engine.  The accompanying @var{type_data}
3373 is a @code{GpgmeTrustItem} variable that contains the trust item with
3374 one reference for the user.
3375 @end table
3376 @end deftp
3377
3378 @deftp {Data type} {void (*GpgmeEventIOCb) (@w{void *@var{data}}, @w{GpgmeEventIO @var{type}}, @w{void *@var{type_data}})}
3379 The @code{GpgmeEventIOCb} type is the type of functions which can be
3380 called by @acronym{GPGME} to signal an event for an operation running
3381 in a context which has I/O callback functions registered by the user.
3382
3383 @var{data} was provided by the user when registering the
3384 @code{GpgmeEventIOCb} function with @acronym{GPGME} and will always be
3385 passed as the first argument when registering a callback function.
3386 For example, the user can use this to determine the context in which
3387 this event has occured.
3388
3389 @var{type} will specify the type of event that has occured.
3390 @var{type_data} specifies the event further, as described in the above
3391 list of possible @code{GpgmeEventIO} types.
3392
3393 @acronym{GPGME} can call this function in an I/O callback handler.
3394 @end deftp
3395
3396
3397 @node Registering I/O Callbacks
3398 @subsubsection Registering I/O Callbacks
3399
3400 @deftp {Data type} {struct GpgmeIOCbs}
3401 @tindex GpgmeEventIO
3402 This structure is used to store the I/O callback interface functions
3403 described in the previous section.  It has the following members:
3404
3405 @table @code
3406 @item GpgmeRegisterIOCb add
3407 This is the function called by @acronym{GPGME} to register an I/O
3408 callback handler.  It must be specified.
3409
3410 @item void *add_data
3411 This is passed as the first argument to the @code{add} function when
3412 it is called by @acronym{GPGME}.  For example, it can be used to
3413 determine the event loop to which the file descriptor should be added.
3414
3415 @item GpgmeRemoveIOCb remove
3416 This is the function called by @acronym{GPGME} to remove an I/O
3417 callback handler.  It must be specified.
3418
3419 @item GpgmeEventIOCb event
3420 This is the function called by @acronym{GPGME} to signal an event for
3421 an operation.  It is optional, but if you don't specify it, you can
3422 not retrieve the return value of the operation.
3423
3424 @item void *event_data
3425 This is passed as the first argument to the @code{event} function when
3426 it is called by @acronym{GPGME}.  For example, it can be used to
3427 determine the context in which the event has occured.
3428 @end table
3429 @end deftp
3430
3431 @deftypefun void gpgme_set_io_cbs (@w{GpgmeCtx @var{ctx}}, @w{struct GpgmeIOCbs *@var{io_cbs}})
3432 The function @code{gpgme_set_io_cbs} enables the I/O callback
3433 interface for the context @var{ctx}.  The I/O callback functions are
3434 specified by @var{io_cbs}.
3435
3436 If @var{io_cbs}->@code{add} is @code{NULL}, the I/O callback interface
3437 is disabled for the context, and normal operation is restored.
3438 @end deftypefun
3439
3440 @deftypefun void gpgme_get_io_cbs (@w{GpgmeCtx @var{ctx}}, @w{struct GpgmeIOCbs *@var{io_cbs}})
3441 The function @code{gpgme_get_io_cbs} returns the I/O callback
3442 functions set with @code{gpgme_set_io_cbs} in @var{io_cbs}.
3443 @end deftypefun
3444
3445
3446 @node I/O Callback Example
3447 @subsubsection I/O Callback Example
3448
3449 To actually use an external event loop, you have to implement the I/O
3450 callback functions that are used by @acronym{GPGME} to register and
3451 unregister file descriptors.  Furthermore, you have to actually
3452 monitor these file descriptors for activity and call the appropriate
3453 I/O callbacks.
3454
3455 The following example illustrates how to do that.  The example uses
3456 locking to show in which way the the callbacks and the event loop can
3457 run concurrently.  For the event loop, we use a fixed array.  For a
3458 real-world implementation, you should use a dynamically sized
3459 structure because the number of file descriptors needed for a crypto
3460 operation in @acronym{GPGME} is not predictable.
3461
3462 @example
3463 #include <pthread.h>
3464 #include <sys/types.h>
3465 #include <gpgme.h>
3466
3467 /* The following structure holds the result of a crypto operation.  */
3468 struct op_result
3469 @{
3470   int done;
3471   GpgmeError err;
3472 @};
3473
3474 /* The following structure holds the data associated with one I/O
3475 callback.  */
3476 struct one_fd
3477 @{
3478   int fd;
3479   int dir;
3480   GpgmeIOCb fnc;
3481   void *fnc_data;
3482 @};
3483
3484 struct event_loop
3485 @{
3486   pthread_mutex_t lock;
3487 #define MAX_FDS 32
3488   /* Unused slots are marked with FD being -1.  */
3489   struct one_fd fds[MAX_FDS];
3490 @};
3491 @end example
3492
3493 The following functions implement the I/O callback interface.
3494
3495 @example
3496 GpgmeError
3497 add_io_cb (void *data, int fd, int dir, GpgmeIOCb fnc, void *fnc_data,
3498            void **r_tag)
3499 @{
3500   struct event_loop *loop = data;
3501   struct one_fd *fds = loop->fds;
3502   int i;
3503
3504   pthread_mutex_lock (&loop->lock);
3505   for (i = 0; i < MAX_FDS; i++)
3506     @{
3507       if (fds[i].fd == -1)
3508         @{
3509           fds[i].fd = fd;
3510           fds[i].dir = dir;
3511           fds[i].fnc = fnc;
3512           fds[i].fnc_data = fnc_data;
3513           break;
3514         @}
3515     @}
3516   pthread_mutex_unlock (&loop->lock);
3517   if (i == MAX_FDS)
3518     return GPGME_General_Error;
3519   *r_tag = &fds[i];
3520   return 0;
3521 @}
3522
3523 void
3524 remove_io_cb (void *tag)
3525 @{
3526   struct one_fd *fd = tag;
3527
3528   pthread_mutex_lock (&loop->lock);
3529   fd->fd = -1;
3530   pthread_mutex_unlock (&loop->lock);
3531 @}
3532
3533 void
3534 event_io_cb (void *data, GpgmeEventIO type, void *type_data)
3535 @{
3536   struct op_result *result = data;
3537   GpgmeError *err = data;
3538
3539   /* We don't support list operations here.  */
3540   if (type == GPGME_EVENT_DONE)
3541     @{
3542       result->done = 1;
3543       result->err = *data;
3544     @}
3545 @}
3546 @end example
3547
3548 The final missing piece is the event loop, which will be presented
3549 next.  We only support waiting for the success of a single operation.
3550
3551 @example
3552 int
3553 do_select (struct event_loop *loop)
3554 @{
3555   fd_set rfds;
3556   fd_set wfds;
3557   int i, n;
3558   int any = 0;
3559
3560   pthread_mutex_lock (&loop->lock);
3561   FD_ZERO (&rfds);
3562   FD_ZERO (&wfds);
3563   for (i = 0; i < FDLIST_MAX; i++)
3564     if (fdlist[i].fd != -1)
3565       FD_SET (fdlist[i].fd, fdlist[i].dir ? &rfds : &wfds);
3566   pthread_mutex_unlock (&loop->unlock);
3567
3568   do
3569     @{
3570       n = select (FD_SETSIZE, &rfds, &wfds, NULL, 0);
3571     @}
3572   while (n < 0 && errno == EINTR);
3573
3574   if (n < 0)
3575     return n;   /* Error or timeout.  */
3576
3577   pthread_mutex_lock (&loop->lock);
3578   for (i = 0; i < FDLIST_MAX && n; i++)
3579     @{
3580       if (fdlist[i].fd != -1)
3581         @{
3582           if (FD_ISSET (fdlist[i].fd, fdlist[i].dir ? &rfds : &wfds))
3583             @{
3584               assert (n);
3585               n--;
3586               any = 1;
3587               /* The I/O callback handler can register/remove callbacks,
3588                  so we have to unlock the file descriptor list.  */
3589               pthread_mutex_unlock (&loop->lock);
3590               (*fdlist[i].fnc) (fdlist[i].fnc_data, fdlist[i].fd);
3591               pthread_mutex_lock (&loop->lock);
3592             @}
3593         @}
3594     @}
3595   pthread_mutex_unlock (&loop->lock);
3596   return any;
3597 @}
3598
3599 void
3600 wait_for_op (struct event_loop *loop, struct op_result *result)
3601 @{
3602   int ret;
3603
3604   do
3605     @{
3606       ret = do_select (loop);
3607     @}
3608   while (ret >= 0 && !result->done);
3609   return ret;
3610 @}
3611 @end example
3612
3613 The main function shows how to put it all together.
3614
3615 @example
3616 int
3617 main (int argc, char *argv[])
3618 @{
3619   struct event_loop loop;
3620   struct op_result result;
3621   GpgmeCtx ctx;
3622   GpgmeError err;
3623   GpgmeData sig, text;
3624   GpgmeSigStat status;
3625   int i;
3626   struct GpgmeIOCbs io_cbs =
3627   @{
3628     add_io_cb,
3629     &loop,
3630     remove_io_cb,
3631     event_io_cb,
3632     &result
3633   @};
3634
3635   /* Initialize the loop structure.  */
3636   loop.lock = PTHREAD_MUTEX_INITIALIZER;
3637   for (i = 0; i < MAX_FDS; i++)
3638     loop->fds[i].fd = -1;
3639
3640   /* Initialize the result structure.  */
3641   result.done = 0;
3642
3643   err = gpgme_data_new_from_file (&sig, "signature", 1);
3644   if (!err)
3645     err = gpgme_data_new_from_file (&text, "text", 1);
3646   if (!err)
3647     err = gpgme_new (&ctx);
3648   if (!err)
3649     @{
3650        gpgme_set_io_cbs (ctx, &io_cbs);
3651        err = gpgme_op_verify_start (ctx, sig, text, &status);
3652     @}
3653   if (err)
3654     @{
3655       fprintf (stderr, "gpgme error: %s\n", gpgme_strerror (err));
3656       exit (1);
3657     @}
3658
3659   wait_for_op (&loop, &result);
3660   if (!result.done)
3661     @{
3662       fprintf (stderr, "select error\n");
3663       exit (1);
3664     @}
3665   if (!result.err)
3666     @{
3667       fprintf (stderr, "verification failed: %s\n", gpgme_strerror (result.err));
3668       exit (1);
3669     @}
3670   /* Evaluate STATUS.  */
3671   @dots{}
3672   return 0;
3673 @}
3674 @end example
3675
3676
3677 @node I/O Callback Example GTK+
3678 @subsubsection I/O Callback Example GTK+
3679 @cindex GTK+, using @acronym{GPGME} with
3680
3681 The I/O callback interface can be used to integrate @acronym{GPGME}
3682 with the GTK+ event loop.  The following code snippets shows how this
3683 can be done using the appropriate register and remove I/O callback
3684 functions.  In this example, the private data of the register I/O
3685 callback function is unused.  The event notifications is missing
3686 because it does not require any GTK+ specific setup.
3687
3688 @example
3689 #include <gtk/gtk.h>
3690
3691 struct my_gpgme_io_cb
3692 @{
3693   GpgmeIOCb fnc;
3694   void *fnc_data;
3695   guint input_handler_id
3696 @};
3697
3698 void
3699 my_gpgme_io_cb (gpointer data, gint source, GdkInputCondition condition)
3700 @{
3701   struct my_gpgme_io_cb *iocb = data;
3702   (*(iocb->fnc)) (iocb->data, source);
3703 @}
3704
3705 void
3706 my_gpgme_remove_io_cb (void *data)
3707 @{
3708   struct my_gpgme_io_cb *iocb = data;
3709   gtk_input_remove (data->input_handler_id);
3710 @}
3711
3712 void
3713 my_gpgme_register_io_callback (void *data, int fd, int dir, GpgmeIOCb fnc,
3714                                void *fnc_data, void **tag)
3715 @{
3716   struct my_gpgme_io_cb *iocb = g_malloc (sizeof (struct my_gpgme_io_cb));
3717   iocb->fnc = fnc;
3718   iocb->data = fnc_data;
3719   iocb->input_handler_id = gtk_input_add_full (fd, dir
3720                                                    ? GDK_INPUT_READ
3721                                                    : GDK_INPUT_WRITE,
3722                                                my_gpgme_io_callback,
3723                                                0, iocb, NULL);
3724   *tag = iocb;
3725   return 0;
3726 @}
3727 @end example
3728
3729
3730 @node I/O Callback Example GDK
3731 @subsubsection I/O Callback Example GDK
3732 @cindex GDK, using @acronym{GPGME} with
3733
3734 The I/O callback interface can also be used to integrate
3735 @acronym{GPGME} with the GDK event loop.  The following code snippets
3736 shows how this can be done using the appropriate register and remove
3737 I/O callback functions.  In this example, the private data of the
3738 register I/O callback function is unused.  The event notifications is
3739 missing because it does not require any GDK specific setup.
3740
3741 It is very similar to the GTK+ example in the previous section.
3742
3743 @example
3744 #include <gdk/gdk.h>
3745
3746 struct my_gpgme_io_cb
3747 @{
3748   GpgmeIOCb fnc;
3749   void *fnc_data;
3750   gint tag;
3751 @};
3752
3753 void
3754 my_gpgme_io_cb (gpointer data, gint source, GdkInputCondition condition)
3755 @{
3756   struct my_gpgme_io_cb *iocb = data;
3757   (*(iocb->fnc)) (iocb->data, source);
3758 @}
3759
3760 void
3761 my_gpgme_remove_io_cb (void *data)
3762 @{
3763   struct my_gpgme_io_cb *iocb = data;
3764   gdk_input_remove (data->tag);
3765 @}
3766
3767 void
3768 my_gpgme_register_io_callback (void *data, int fd, int dir, GpgmeIOCb fnc,
3769                                void *fnc_data, void **tag)
3770 @{
3771   struct my_gpgme_io_cb *iocb = g_malloc (sizeof (struct my_gpgme_io_cb));
3772   iocb->fnc = fnc;
3773   iocb->data = fnc_data;
3774   iocb->tag = gtk_input_add_full (fd, dir ? GDK_INPUT_READ : GDK_INPUT_WRITE,
3775                                   my_gpgme_io_callback, iocb, NULL);
3776   *tag = iocb;
3777   return 0;
3778 @}
3779 @end example
3780
3781
3782 @include gpl.texi
3783
3784
3785 @include fdl.texi
3786
3787
3788 @node Concept Index
3789 @unnumbered Concept Index
3790
3791 @printindex cp
3792
3793
3794 @node Function and Data Index
3795 @unnumbered Function and Data Index
3796
3797 @printindex fn
3798
3799
3800 @summarycontents
3801 @contents
3802 @bye