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