doc/
[gpgme.git] / doc / gpgme.texi
1 \input texinfo                  @c -*- Texinfo -*-
2 @setfilename gpgme.info
3 @settitle The `GnuPG Made Easy' Reference Manual
4
5 @dircategory GNU Libraries
6 @direntry
7 * @acronym{GPGME}: (gpgme)           Adding support for cryptography to your program.
8 @end direntry
9
10 @include version.texi
11
12 @c Unify some of the indices.
13 @syncodeindex tp fn
14 @syncodeindex pg fn
15
16 @ifinfo
17 This file documents the @acronym{GPGME} library.
18
19 This is Edition @value{EDITION}, last updated @value{UPDATED}, of
20 @cite{The `GnuPG Made Easy' Reference Manual}, for Version
21 @value{VERSION}.
22
23 Copyright @copyright{} 2002 g10 Code GmbH.
24
25 Permission is granted to copy, distribute and/or modify this document
26 under the terms of the GNU Free Documentation License, Version 1.1 or
27 any later version published by the Free Software Foundation; with the
28 Invariant Sections being ``Free Software Needs Free Documentation'' and
29 ``GNU Lesser General Public License'', the Front-Cover texts being (a)
30 (see below), and with the Back-Cover Texts being (b) (see below).  A
31 copy of the license is included in the section entitled ``GNU Free
32 Documentation License''.
33
34 @end ifinfo
35
36 @iftex
37 @shorttitlepage The `GnuPG Made Easy' Reference Manual
38 @end iftex
39 @titlepage
40 @center @titlefont{The `GnuPG Made Easy'}
41 @sp 1
42 @center @titlefont{Reference Manual}
43 @sp 6
44 @center Edition @value{EDITION}
45 @sp 1
46 @center last updated @value{UPDATED}
47 @sp 1
48 @center for version @value{VERSION}
49 @page
50 @vskip 0pt plus 1filll
51 Copyright @copyright{} 2002 g10 Code GmbH.
52
53 Permission is granted to copy, distribute and/or modify this document
54 under the terms of the GNU Free Documentation License, Version 1.1 or
55 any later version published by the Free Software Foundation; with the
56 Invariant Sections being ``Free Software Needs Free Documentation'' and
57 ``GNU Lesser General Public License'', the Front-Cover texts being (a)
58 (see below), and with the Back-Cover Texts being (b) (see below).  A
59 copy of the license is included in the section entitled ``GNU Free
60 Documentation License''.
61 @end titlepage
62 @page
63
64 @ifnottex
65 @node Top
66 @top Main Menu
67 This is Edition @value{EDITION}, last updated @value{UPDATED}, of
68 @cite{The `GnuPG Made Easy' Reference Manual}, for Version
69 @value{VERSION} of the @acronym{GPGME} library.
70 @end ifnottex
71
72 @menu
73 * Introduction::                  How to use this manual.
74 * Preparation::                   What you should do before using the library.
75 * Protocols and Engines::         Supported crypto protocols.
76 * Error Handling::                Error numbers and their meanings.
77 * Exchanging Data::               Passing data to and from @acronym{GPGME}.
78 * Contexts::                      Handling @acronym{GPGME} contexts.
79
80 Appendices
81
82 * Copying::                       The GNU General Public License says how you
83                                   can copy and share `GnuPG Made Easy'.
84 * Free Documentation License::    This manual is under the GNU Free
85                                   Documentation License.
86
87 Indices
88
89 * Concept Index::                 Index of concepts and programs.
90 * Function and Data Index::       Index of functions, variables and data types.
91
92
93 @detailmenu
94  --- The Detailed Node Listing ---
95
96 Introduction
97
98 * Getting Started::               Purpose of the manual, and how to use it.
99 * Features::                      Reasons to install and use @acronym{GPGME}.
100 * Overview::                      Basic architecture of the @acronym{GPGME} library.
101
102 Preparation
103
104 * Header::                        What header file you need to include.
105 * Building the Source::           Compiler options to be used.
106 * Library Version Check::         Getting and verifying the library version.
107
108 Protocols and Engines
109
110 * Engine Version Check::          Verifying the engine version.
111 * Engine Information::            Obtaining more information about the engines.
112 * OpenPGP::                       Support for the OpenPGP protocol.
113 * Cryptographic Message Syntax::  Support for the CMS.
114
115 Error Handling
116
117 * Error Values::                  A list of all error values used.
118 * Error Strings::                 How to get a descriptive string from a value.
119
120 Exchanging Data 
121
122 * Creating Data Buffers::         Creating new data buffers.
123 * Destroying Data Buffers::       Releasing data buffers.
124 * Manipulating Data Buffers::     Operations on data buffers.
125
126 Contexts
127
128 * Creating Contexts::             Creating new @acronym{GPGME} contexts.
129 * Destroying Contexts::           Releasing @acronym{GPGME} contexts.
130 * Context Attributes::            Setting properties of a context.
131 * Key Management::                Managing keys with @acronym{GPGME}.
132 * Trust Item Management::         Managing trust items with @acronym{GPGME}.
133 * Crypto Operations::             Using a context for cryptography.
134 * Run Control::                   Controlling how operations are run.
135
136 Context Attributes
137
138 * Protocol Selection::            Selecting the protocol used by a context.
139 * @acronym{ASCII} Armor::                   Requesting @acronym{ASCII} armored output.
140 * Text Mode::                     Choosing canonical text mode.
141 * Included Certificates::         Including a number of certificates.
142 * Key Listing Mode::              Selecting key listing mode.
143 * Passphrase Callback::           Getting the passphrase from the user.
144 * Progress Meter Callback::       Being informed about the progress.
145
146 Key Management
147
148 * Listing Keys::                  Browsing the list of available keys.
149 * Information About Keys::        Requesting detailed information about keys.
150 * Manipulating Keys::             Operations on keys.
151 * Generating Keys::               Creating new key pairs.
152 * Exporting Keys::                Retrieving key data from the key ring.
153 * Importing Keys::                Adding keys to the key ring.
154 * Deleting Keys::                 Removing keys from the key ring.
155
156 Trust Item Management
157
158 * Listing Trust Items::           Browsing the list of available trust items.
159 * Information About Trust Items:: Requesting detailed information about trust items.
160 * Manipulating Trust Items::      Operations on trust items.
161
162 Crypto Operations
163
164 * Decrypt::                       Decrypting a ciphertext.
165 * Verify::                        Verifying a signature.
166 * Decrypt and Verify::            Decrypting a signed ciphertext.
167 * Sign::                          Creating a signature.
168 * Encrypt::                       Encrypting a plaintext.
169 * Detailed Results::              How to obtain more info about the operation.
170
171 Sign
172
173 * Selecting Signers::             How to choose the keys to sign with.
174 * Creating a Signature::          How to create a signature.
175
176 Encrypt
177
178 * Selecting Recipients::          How to choose the recipients.
179 * Encrypting a Plaintext::        How to encrypt a plaintext.
180
181 Run Control
182
183 * Waiting For Completion::        Waiting until an operation is completed.
184 * Cancelling an Operation::       Interrupting a running operation.
185 * Hooking Up Into Idle Time::     Doing something when nothing has to be done.
186
187 @end detailmenu
188 @end menu
189
190 @node Introduction
191 @chapter Introduction
192
193 `GnuPG Made Easy' (@acronym{GPGME}) is a C language library that
194 allows to add support for cryptography to a program.  It is designed
195 to make access to crypto engines like GnuPG or GpgSM easier for
196 applications.  @acronym{GPGME} provides a high-level crypto API for
197 encryption, decryption, signing, signature verification and key
198 management.
199
200 @acronym{GPGME} uses GnuPG and GpgSM as its backends to support
201 OpenPGP and the Cryptographic Message Syntax (CMS).
202
203 @menu
204 * Getting Started::               Purpose of the manual, and how to use it.
205 * Features::                      Reasons to install and use @acronym{GPGME}.
206 * Overview::                      Basic architecture of the @acronym{GPGME} library.
207 @end menu
208
209
210 @node Getting Started
211 @section Getting Started
212
213 This library documents the @acronym{GPGME} library programming
214 interface.  All functions and data types provided by the library are
215 explained.
216
217 The reader is assumed to possess basic knowledge about cryptography in
218 general, and public key cryptography in particular.  The underlying
219 cryptographic engines that are used by the library are not explained,
220 but where necessary, special features or requirements by an engine are
221 mentioned as far as they are relevant to @acronym{GPGME} or its users.
222
223 This manual can be used in several ways.  If read from the beginning
224 to the end, it gives a good introduction into the library and how it
225 can be used in an application.  Forward references are included where
226 necessary.  Later on, the manual can be used as a reference manual to
227 get just the information needed about any particular interface of the
228 library.  Experienced programmers might want to start looking at the
229 examples at the end of the manual, and then only read up those parts
230 of the interface which are unclear.
231
232
233 @node Features
234 @section Features
235
236 @acronym{GPGME} has a couple of advantages over other libraries doing
237 a similar job, and over implementing support for GnuPG or other crypto
238 engines into your application directly.
239
240 @table @asis
241 @item it's free software
242 Anybody can use, modify, and redistribute it under the terms of the GNU
243 General Public License (@pxref{Copying}).
244
245 @item it's flexible
246 @acronym{GPGME} provides transparent support for several cryptographic
247 protocols by different engines.  Currently, @acronym{GPGME} supports
248 the OpenPGP protocol using GnuPG as the backend, and the Cryptographic
249 Message Syntax using GpgSM as the backend.
250
251 @item it's easy
252 @acronym{GPGME} hides the differences between the protocols and
253 engines from the programmer behind an easy-to-use interface.  This way
254 the programmer can focus on the other parts of the program, and still
255 integrate strong cryptography in his application.  Once support for
256 @acronym{GPGME} has been added to a program, it is easy to add support
257 for other crypto protocols once @acronym{GPGME} backends provide them.
258 @end table
259
260
261 @node Overview
262 @section Overview
263
264 @acronym{GPGME} provides a data abstraction that is used to pass data
265 to the crypto engine, and receive returned data from it.  Data can be
266 read from memory or from files, but it can also be provided by a
267 callback function.
268
269 The actual cryptographic operations are always set within a context.
270 A context provides configuration parameters that define the behaviour
271 of all operations performed within it.  Only one operation per context
272 is allowed at any time, but when one operation is finished, you can
273 run the next operation in the same context.  There can be more than
274 one context, and all can run different operations at the same time.
275
276 Furthermore, @acronym{GPGME} has rich key management facilities
277 including listing keys, querying their attributes, generating,
278 importing, exporting and deleting keys, and acquiring information
279 about the trust path.
280
281 @cindex thread-safeness
282 @cindex multi-threading
283 @strong{Caution:} The @acronym{GPGME} library is not thread-safe.  It
284 will be to some extent in the future, but currently great care has to
285 be taken if @acronym{GPGME} is used in a multi-threaded environment.
286
287
288 @node Preparation
289 @chapter Preparation
290
291 To use @acronym{GPGME}, you have to perform some changes to your
292 sources and the build system.  The necessary changes are small and
293 explained in the following sections.  At the end of this chapter, it
294 is described how the library is initialized, and how the requirements
295 of the library are verified.
296
297 @menu
298 * Header::                        What header file you need to include.
299 * Building the Source::           Compiler options to be used.
300 * Library Version Check::         Getting and verifying the library version.
301 @end menu
302
303
304 @node Header
305 @section Header
306 @cindex header file
307 @cindex include file
308
309 All interfaces (data types and functions) of the library are defined
310 in the header file `gpgme.h'.  You must include this in all programs
311 using the library, either directly or through some other header file,
312 like this:
313
314 @example
315 #include <gpgme.h>
316 @end example
317
318 The name space of @acronym{GPGME} is @code{gpgme_*} for function
319 names, @code{Gpgme*} for data types and @code{GPGME_*} for other
320 symbols.
321
322
323 @node Building the Source
324 @section Building the Source
325 @cindex compiler options
326 @cindex compiler flags
327
328 If you want to compile a source file including the `gpgme.h' header
329 file, you must make sure that the compiler can find it in the
330 directory hierarchy.  This is accomplished by adding the path to the
331 directory in which the header file is located to the compilers include
332 file search path (via the @option{-I} option).
333
334 However, the path to the include file is determined at the time the
335 source is configured.  To solve this problem, gpgme ships with a small
336 helper program @command{gpgme-config} that knows about the path to the
337 include file and other configuration options.  The options that need
338 to be added to the compiler invocation at compile time are output by
339 the @option{--cflags} option to @command{gpgme-config}.  The following
340 example shows how it can be used at the command line:
341
342 @example
343 gcc -c foo.c `gpgme-config --cflags`
344 @end example
345
346 Adding the output of @samp{gpgme-config --cflags} to the compilers
347 command line will ensure that the compiler can find the @acronym{GPGME} header
348 file.
349
350 A similar problem occurs when linking the program with the library.
351 Again, the compiler has to find the library files.  For this to work,
352 the path to the library files has to be added to the library search
353 path (via the @option{-L} option).  For this, the option
354 @option{--libs} to @command{gpgme-config} can be used.  For
355 convenience, this option also outputs all other options that are
356 required to link the program with @acronym{GPGME} (in particular, the
357 @samp{-lgpgme} option).  The example shows how to link @file{foo.o}
358 with the @acronym{GPGME} library to a program @command{foo}.
359
360 @example
361 gcc -o foo foo.o `gpgme-config --libs`
362 @end example
363
364 Of course you can also combine both examples to a single command by
365 specifying both options to @command{gpgme-config}:
366
367 @example
368 gcc -o foo foo.c `gpgme-config --cflags --libs`
369 @end example
370
371
372 @node Library Version Check
373 @section Library Version Check
374 @cindex version check, of the library
375
376 @deftypefun {const char *} gpgme_check_version (@w{const char *@var{required_version}})
377 The function @code{gpgme_check_version} has three purposes.  It can be
378 used to retrieve the version number of the library.  In addition it
379 can verify that the version number is higher than a certain required
380 version number.  In either case, the function initializes some
381 sub-systems, and for this reason alone it must be invoked early in
382 your program, before you make use of the other functions in
383 @acronym{GPGME}.
384
385 If @var{required_version} is @code{NULL}, the function returns a
386 pointer to a statically allocated string containing the version number
387 of the library.
388
389 If @var{required_version} is not @code{NULL}, it should point to a
390 string containing a version number, and the function checks that the
391 version of the library is at least as high as the version number
392 provided.  In this case, the function returns a pointer to a
393 statically allocated string containing the version number of the
394 library.  If @var{REQUIRED_VERSION} is not a valid version number, or
395 if the version requirement is not met, the function returns
396 @code{NULL}.
397
398 If you use a version of a library that is backwards compatible with
399 older releases, but contains additional interfaces which your program
400 uses, this function provides a run-time check if the necessary
401 features are provided by the installed version of the library.
402 @end deftypefun
403
404
405 @node Protocols and Engines
406 @chapter Protocols and Engines
407 @cindex protocol
408 @cindex engine
409 @cindex crypto engine
410 @cindex backend
411 @cindex crypto backend
412
413 @acronym{GPGME} supports several cryptographic protocols, however, it
414 does not implement them.  Rather it uses backends (also called
415 engines) which implement the protocol.  @acronym{GPGME} uses
416 inter-process communication to pass data back and forth between the
417 application and the backend, but the details of the communication
418 protocol and invocation of the backends is completely hidden by the
419 interface.  All complexity is handled by @acronym{GPGME}.  Where an
420 exchange of information between the application and the backend is
421 necessary, @acronym{GPGME} provides the necessary callback function
422 hooks and further interfaces.
423
424 @deftp {Data type} {enum GpgmeProtocol}
425 @tindex GpgmeProtocol
426 The @code{GpgmeProtocol} type specifies the set of possible protocol
427 values that are supported by @acronym{GPGME}.  The following protocols
428 are supported:
429
430 @table @code
431 @item GPGME_PROTOCOL_OpenPGP
432 This specifies the OpenPGP protocol.
433 @item GPGME_PROTOCOL_CMS
434 This specifies the Cryptographic Message Syntax.
435 @end table
436 @end deftp
437
438 @menu
439 * Engine Version Check::          Verifying the engine version.
440 * Engine Information::            Obtaining more information about the engines.
441 * OpenPGP::                       Support for the OpenPGP protocol.
442 * Cryptographic Message Syntax::  Support for the CMS.
443 @end menu
444
445
446 @node Engine Version Check
447 @section Engine Version Check
448 @cindex version check, of the engines
449
450 @deftypefun GpgmeError gpgme_engine_check_version (@w{GpgmeProtocol @var{protocol}})
451 The function @code{gpgme_engine_check_version} verifies that the
452 engine implementing the protocol @var{PROTOCOL} is installed in the
453 expected path and meets the version requirement of @acronym{GPGME}.
454
455 This function returns @code{GPGME_No_Error} if the engine is available
456 and @code{GPGME_Invalid_Engine} if it is not.
457 @end deftypefun
458
459 @deftypefun GpgmeError gpgme_check_engine (void)
460 The function @code{gpgme_check_engine} is equivalent to
461
462 @example
463 gpgme_engine_check_version (GPGME_PROTOCOL_OpenPGP);
464 @end example
465
466 This function is deprecated and provided for backwards compatibility
467 only.  It is obsoleted by @code{gpgme_engine_check_version}.
468 @end deftypefun
469
470
471 @node Engine Information
472 @section Engine Information
473 @cindex engine, information about
474
475 @deftypefun {const char *} gpgme_get_engine_info (void)
476 The function @code{gpgme_get_engine_info} returns an @acronym{XML}
477 string containing information about the available protocols and the
478 engine which implement them.  The following information is returned
479 for each engine:
480
481 @table @samp
482 @item <protocol>
483 The name of the protocol.
484 @item <version>
485 The version of the engine.
486 @item <path>
487 The path to the engine binary.
488 @end table
489
490 A string is always returned.  If an error occurs, the string will
491 contain an @samp{<error>} tag with a description of the failure.
492 @end deftypefun
493
494 Here is the example output of what @code{gpgme_get_engine_info} might
495 return on your system:
496
497 @example
498 <EngineInfo>
499  <engine>
500   <protocol>OpenPGP</protocol>
501   <version>1.0.6</version>
502   <path>/usr/bin/gpg</path>
503  </engine>
504  <engine>
505   <protocol>CMS</protocol>
506   <version>0.0.0</version>
507   <path>/usr/bin/gpgsm</path>
508  </engine>
509 </EngineInfo>
510 @end example
511
512
513 @node OpenPGP
514 @section OpenPGP
515 @cindex OpenPGP
516 @cindex GnuPG
517 @cindex protocol, GnuPG
518 @cindex engine, GnuPG
519
520 OpenPGP is implemented by GnuPG, the @acronym{GNU} Privacy Guard.
521 This is the first protocol that was supported by @acronym{GPGME}.
522
523 The OpenPGP protocol is specified by @code{GPGME_PROTOCOL_OpenPGP}.
524
525
526 @node Cryptographic Message Syntax
527 @section Cryptographic Message Syntax
528 @cindex CMS
529 @cindex cryptographic message syntax
530 @cindex GpgSM
531 @cindex protocol, CMS
532 @cindex engine, GpgSM
533 @cindex S/MIME
534 @cindex protocol, S/MIME
535
536 @acronym{CMS} is implemented by GpgSM, the S/MIME implementation for
537 GnuPG.
538
539 The @acronym{CMS} protocol is specified by @code{GPGME_PROTOCOL_CMS}.
540
541
542 @node Error Handling
543 @chapter Error Handling
544 @cindex error handling
545
546 Many functions in @acronym{GPGME} can return an error if they fail.
547 For this reason, the application should always catch the error
548 condition and take appropriate measures, for example by releasing the
549 resources and passing the error up to the caller, or by displaying a
550 descriptive message to the user and cancelling the operation.
551
552 Some error values do not indicate a system error or an error in the
553 operation, but the result of an operation that failed properly.  For
554 example, if you try to decrypt a tempered message, the decryption will
555 fail.  Another error value actually means that the end of a data
556 buffer or list has been reached.  The following descriptions explain
557 what each error message means in general.  Some error values have
558 specific meanings if returned by a specific function.  Such cases are
559 described in the documentation of those functions.
560
561 @menu
562 * Error Values::                  A list of all error values used.
563 * Error Strings::                 How to get a descriptive string from a value.
564 @end menu
565
566
567 @node Error Values
568 @section Error Values
569 @cindex error values, list of
570
571 @deftp {Data type} {enum GpgmeError}
572 @tindex GpgmeError
573 The @code{GpgmeError} type specifies the set of all error values that
574 are used by @acronym{GPGME}.  Possible values are:
575
576 @table @code
577 @item GPGME_EOF
578 This value indicates the end of a list, buffer or file.
579
580 @item GPGME_No_Error
581 This value indicates success.  The value of this error is @code{0}.
582
583 @item GPGME_General_Error
584 This value means that something went wrong, but either there is not
585 enough information about the problem to return a more useful error
586 value, or there is no separate error value for this type of problem.
587
588 @item GPGME_Out_Of_Core
589 This value means that an out-of-memory condition occurred.
590
591 @item GPGME_Invalid_Value
592 This value means that some user provided data was out of range.  This
593 can also refer to objects.  For example, if an empty @code{GpgmeData}
594 object was expected, but one containing data was provided, this error
595 value is returned.
596
597 @item GPGME_Busy
598 This value is returned if you try to start a new operation in a
599 context that is already busy with some earlier operation which was not
600 cancelled or finished yet.
601
602 @item GPGME_No_Request
603 This value is in some sense the opposite of @code{GPGME_Busy}.  There
604 is no pending operation, but it is required for the function to
605 succeed.
606
607 @item GPGME_Exec_Error
608 This value means that an error occurred when trying to spawn a child
609 process.
610
611 @item GPGME_Too_Many_Procs
612 This value means that there are too many active backend processes.
613
614 @item GPGME_Pipe_Error
615 This value means that the creation of a pipe failed.
616
617 @item GPGME_No_Recipients 
618 This value means that no recipients for a message have been set.
619
620 @item GPGME_No_Data
621 This value means that a @code{GpgmeData} object which was expected to
622 have content was found empty.
623
624 @item GPGME_Conflict
625 This value means that a conflict of some sort occurred.
626
627 @item GPGME_Not_Implemented
628 This value indicates that the specific function (or operation) is not
629 implemented.  This error should never happen.  It can only occur if
630 you use certain values or configuration options which do not work,
631 but for which we think that they should work at some later time.
632
633 @item GPGME_Read_Error
634 This value means that an I/O read operation failed.
635
636 @item GPGME_Write_Error
637 This value means that an I/O write operation failed.
638
639 @item GPGME_Invalid_Type
640 This value means that a user provided object was of a wrong or
641 incompatible type.  Usually this refers to the type of a
642 @code{GpgmeData} object.
643
644 @item GPGME_Invalid_Mode
645 This value means that a @code{GpgmeData} object has an incorrect mode
646 of operation (for example, doesn't support output although it is
647 attempted to use it as an output buffer).
648
649 @item GPGME_File_Error
650 This value means that a file I/O operation failed.  The value of
651 @code{errno} contains the system error value.
652
653 @item GPGME_Decryption_Failed
654 This value indicates that a decryption operation was unsuccessful.
655
656 @item GPGME_No_Passphrase
657 This value means that the user did not provide a passphrase when
658 requested.
659
660 @item GPGME_Canceled
661 This value means that the operation was canceled.
662
663 @item GPGME_Invalid_Key
664 This value means that a key was invalid.
665
666 @item GPGME_Invalid_Engine
667 This value means that the engine that implements the desired protocol
668 is currently not available.  This can either be because the sources
669 were configured to exclude support for this engine, or because the
670 engine is not installed properly.
671 @end table
672 @end deftp
673
674
675 @node Error Strings
676 @section Error Strings
677 @cindex error values, printing of
678 @cindex error strings
679
680 @deftypefun {const char *} gpgme_strerror (@w{GpgmeError @var{err}})
681 The function @code{gpgme_strerror} returns a pointer to a statically
682 allocated string containing a description of the error with the error
683 value @var{err}.  This string can be used to output a diagnostic
684 message to the user.
685 @end deftypefun
686
687
688 @node Exchanging Data
689 @chapter Exchanging Data
690 @cindex data, exchanging
691
692 A lot of data has to be exchanged between the user and the crypto
693 engine, like plaintext messages, ciphertext, signatures and
694 information about the keys.  The technical details about exchanging
695 the data information are completely abstracted by @acronym{GPGME}.
696 The user provides and receives the data via @code{GpgmeData} objects,
697 regardless of the communication protocol between @acronym{GPGME} and
698 the crypto engine in use.
699
700 @deftp {Data type} {GpgmeData}
701 The @code{GpgmeData} type is a handle for a container for generic
702 data, which is used by @acronym{GPGME} to exchange data with the user.
703 @end deftp
704
705 @menu
706 * Creating Data Buffers::         Creating new data buffers.
707 * Destroying Data Buffers::       Releasing data buffers.
708 * Manipulating Data Buffers::     Operations on data buffers.
709 @end menu
710
711
712 @node Creating Data Buffers
713 @section Creating Data Buffers
714 @cindex data buffer, creation
715
716 @deftypefun GpgmeError gpgme_data_new (@w{GpgmeData *@var{dh}})
717 The function @code{gpgme_data_new} creates a new @code{GpgmeData}
718 object and returns a handle for it in @var{dh}.  The data object is
719 initially empty.
720
721 The function returns @code{GPGME_No_Error} if the data object was
722 successfully created, @code{GPGME_Invalid_Value} if @var{dh} is not a
723 valid pointer, and @code{GPGME_Out_Of_Core} if not enough memory is
724 available.
725 @end deftypefun
726
727 @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}})
728 The function @code{gpgme_data_new_from_mem} creates a new
729 @code{GpgmeData} object and fills it with @var{size} bytes starting
730 from @var{buffer}.
731
732 If @var{copy} is not zero, a private copy of the data is made.  If
733 @var{copy} is zero, the data is taken from the specified buffer as
734 needed, and the user has to ensure that the buffer remains valid for
735 the whole life span of the data object.
736
737 The function returns @code{GPGME_No_Error} if the data object was
738 successfully created, @code{GPGME_Invalid_Value} if @var{dh} or
739 @var{buffer} is not a valid pointer, and @code{GPGME_Out_Of_Core} if
740 not enough memory is available.
741 @end deftypefun
742
743 @deftypefun GpgmeError gpgme_data_new_from_file (@w{GpgmeData *@var{dh}}, @w{const char *@var{filename}}, @w{int @var{copy}})
744 The function @code{gpgme_data_new_from_file} creates a new
745 @code{GpgmeData} object and fills it with the content of the file
746 @var{filename}.
747
748 If @var{copy} is not zero, the whole file is read in at initialization
749 time and the file is not used anymore after that.  This is the only
750 mode supported currently.  Later, a value of zero for @var{copy} might
751 cause all reads to be delayed until the data is needed, but this is
752 not yet implemented.
753
754 The function returns @code{GPGME_No_Error} if the data object was
755 successfully created, @code{GPGME_Invalid_Value} if @var{dh} or
756 @var{filename} is not a valid pointer, @code{GPGME_File_Error} if an
757 I/O operation fails, @code{GPGME_Not_Implemented} if @var{code} is
758 zero, and @code{GPGME_Out_Of_Core} if not enough memory is available.
759 @end deftypefun
760
761 @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}})
762 The function @code{gpgme_data_new_from_filepart} creates a new
763 @code{GpgmeData} object and fills it with a part of the file specified
764 by @var{filename} or @var{fp}.
765
766 Exactly one of @var{filename} and @var{fp} must be non-zero, the other
767 must be zero.  The argument that is not zero specifies the file from
768 which @var{length} bytes are read into the data object, starting from
769 @var{offset}.
770
771 The function returns @code{GPGME_No_Error} if the data object was
772 successfully created, @code{GPGME_Invalid_Value} if @var{dh} and
773 exactly one of @var{filename} and @var{fp} is not a valid pointer,
774 @code{GPGME_File_Error} if an I/O operation fails, and
775 @code{GPGME_Out_Of_Core} if not enough memory is available.
776 @end deftypefun
777
778
779 @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}})
780 The function @code{gpgme_data_new_with_read_cb} creates a new
781 @code{GpgmeData} object and uses the callback function @var{readfunc}
782 to retrieve the data on demand.  As the callback function can supply
783 the data in any way it wants, this is the most flexible data type
784 @acronym{GPGME} provides.  However, it can not be used to write data.
785
786 The callback function receives @var{hook_value} as its first argument
787 whenever it is invoked.  It should return up to @var{count} bytes in
788 @var{buffer}, and return the number of bytes actually read in
789 @var{nread}.  It may return @code{0} in @var{nread} if no data is
790 currently available.  To indicate @code{EOF} the function should
791 return with an error code of @code{-1} and set @var{nread} to
792 @code{0}.  The callback function may support to reset its internal
793 read pointer if it is invoked with @var{buffer} and @var{nread} being
794 @code{NULL} and @var{count} being @code{0}.
795
796 The function returns @code{GPGME_No_Error} if the data object was
797 successfully created, @code{GPGME_Invalid_Value} if @var{dh} or
798 @var{readfunc} is not a valid pointer, and @code{GPGME_Out_Of_Core} if
799 not enough memory is available.
800 @end deftypefun
801
802
803 @node Destroying Data Buffers
804 @section Destroying Data Buffers
805 @cindex data buffer, destruction
806
807 @deftypefun void gpgme_data_release (@w{GpgmeData @var{dh}})
808 The function @code{gpgme_data_release} destroys the data object with
809 the handle @var{dh}.  It releases all associated resources that were
810 not provided by the user in the first place.
811 @end deftypefun
812
813 @deftypefun {char *} gpgme_data_release_and_get_mem (@w{GpgmeData @var{dh}}, @w{size_t *@var{length}})
814 The function @code{gpgme_data_release_and_get_mem} is like
815 @code{gpgme_data_release}, except that it returns the data buffer and
816 its length that was provided by the object.
817
818 The user has to release the buffer with @code{free}.  In case the user
819 provided the data buffer in non-copy mode, a copy will be made for
820 this purpose.
821
822 In case an error returns, or there is no suitable data buffer that can
823 be returned to the user, the function will return @code{NULL}.
824 @end deftypefun
825
826
827 @node Manipulating Data Buffers
828 @section Manipulating Data Buffers
829 @cindex data buffere, manipulation
830
831 @deftypefun GpgmeError gpgme_data_read (@w{GpgmeData @var{dh}}, @w{char *@var{buffer}}, @w{size_t @var{length}}, @w{size_t *@var{nread}})
832 The function @code{gpgme_data_read} reads up to @var{length} bytes
833 from the data object with the handle @var{dh} into the space starting
834 at @var{buffer}.  The actual amount read is returned in @var{nread}.
835
836 If @var{buffer} is @code{NULL}, the function returns the amount of
837 bytes available in @var{nread} without changing the read pointer.
838 This is not supported by all types of data objects.  If this function
839 is not supported, @code{GPGME_Invalid_Type} is returned.
840
841 If the end of the data object is reached, the function returns
842 @code{GPGME_EOF} and sets @var{nread} to zero.
843
844 In all other cases, the function returns @code{GPGME_No_Error} if the
845 operation was successfully performed and @code{GPGME_Invalid_Value} if
846 @var{dh} is not a valid pointer.
847 @end deftypefun
848
849 @deftypefun GpgmeError gpgme_data_rewind (@w{GpgmeData @var{dh}})
850 The function @code{gpgme_data_rewind} resets the read pointer of the
851 data object with the handle @var{dh}, so that a subsequent
852 @code{gpgme_data_read} operation starts at the beginning of the data.
853
854 The function returns @code{GPGME_No_Error} if the operation was
855 successfully performed, @code{GPGME_Not_Implemented} if the operation
856 is not supported (for example, by a read callback function supplied by
857 the user) and @code{GPGME_Invalid_Value} if @var{dh} is not a valid
858 pointer.
859 @end deftypefun
860
861 @deftypefun GpgmeError gpgme_data_write (@w{GpgmeData @var{dh}}, @w{const char *@var{buffer}}, @w{size_t @var{length}})
862 The function @code{gpgme_data_write} writes @var{length} bytes
863 starting from @var{buffer} into the data object with the handle
864 @var{dh} at the current write position.
865
866 The function returns @code{GPGME_No_Error} if the operation was
867 successfully performed, @code{GPGME_Invalid_Value} if @var{dh} or
868 @var{buffer} is not a valid pointer, @code{GPGME_Invalid_Type} or
869 @code{GPGME_Invalid_Mode} if the data object type does not support
870 writing, and @code{GPGME_Out_Of_Core} if not enough memory is
871 available.
872 @end deftypefun
873
874 @deftp {Data type} {enum GpgmeDataType}
875 @tindex GpgmeDataType
876 The @code{GpgmeDataType} type specifies the type of a @code{GpgmeData} object.
877 The following data types are available:
878
879 @table @code
880 @item GPGME_DATA_TYPE_NONE
881 This specifies that the type is not yet determined.
882
883 @item GPGME_DATA_TYPE_MEM
884 This specifies that the data is stored in memory.
885
886 @item GPGME_DATA_TYPE_FD
887 This type is not implemented.
888
889 @item GPGME_DATA_TYPE_FILE
890 This type is not implemented.
891
892 @item GPGME_DATA_TYPE_CB
893 This type specifies that the data is provided by a callback function
894 implemented by the user.
895 @end table
896 @end deftp
897
898 @deftypefun GpgmeDataType gpgme_data_get_type (@w{GpgmeData @var{dh}})
899 The function @code{gpgme_data_get_type} returns the type of the data
900 object with the handle @var{dh}.  If @var{dh} is not a valid pointer,
901 @code{GPGME_DATA_TYPE_NONE} is returned.
902 @end deftypefun
903
904
905 @node Contexts
906 @chapter Contexts
907 @cindex context
908
909 All cryptographic operations in @acronym{GPGME} are performed within a
910 context, which contains the internal state of the operation as well as
911 configuration parameters.  By using several contexts you can run
912 several cryptographic operations in parallel, with different
913 configuration.
914
915 @deftp {Data type} {GpgmeCtx}
916 The @code{GpgmeCtx} type is a handle for a @acronym{GPGME} context,
917 which is used to hold the configuration, status and result of
918 cryptographic operations.
919 @end deftp
920
921 @menu
922 * Creating Contexts::             Creating new @acronym{GPGME} contexts.
923 * Destroying Contexts::           Releasing @acronym{GPGME} contexts.
924 * Context Attributes::            Setting properties of a context.
925 * Key Management::                Managing keys with @acronym{GPGME}.
926 * Trust Item Management::         Managing trust items with @acronym{GPGME}.
927 * Crypto Operations::             Using a context for cryptography.
928 * Run Control::                   Controlling how operations are run.
929 @end menu
930
931
932 @node Creating Contexts
933 @section Creating Contexts
934 @cindex context, creation
935
936 @deftypefun GpgmeError gpgme_new (@w{GpgmeCtx *@var{ctx}})
937 The function @code{gpgme_data_new} creates a new @code{GpgmeCtx}
938 object and returns a handle for it in @var{ctx}.
939
940 The function returns @code{GPGME_No_Error} if the context was
941 successfully created, @code{GPGME_Invalid_Value} if @var{ctx} is not a
942 valid pointer, and @code{GPGME_Out_Of_Core} if not enough memory is
943 available.
944 @end deftypefun
945
946
947 @node Destroying Contexts
948 @section Destroying Contexts
949 @cindex context, destruction
950
951 @deftypefun void gpgme_release (@w{GpgmeCtx @var{ctx}})
952 The function @code{gpgme_release} destroys the context with the handle
953 @var{ctx} and releases all associated resources.
954 @end deftypefun
955
956
957 @node Context Attributes
958 @section Context Attributes
959 @cindex context, attributes
960
961 @menu
962 * Protocol Selection::            Selecting the protocol used by a context.
963 * @acronym{ASCII} Armor::                   Requesting @acronym{ASCII} armored output.
964 * Text Mode::                     Choosing canonical text mode.
965 * Included Certificates::       Including a number of certificates.
966 * Key Listing Mode::              Selecting key listing mode.
967 * Passphrase Callback::           Getting the passphrase from the user.
968 * Progress Meter Callback::       Being informed about the progress.
969 @end menu
970
971
972 @node Protocol Selection
973 @subsection Protocol Selection
974 @cindex context, selecting protocol
975 @cindex protocol, selecting
976
977 @deftypefun GpgmeError gpgme_set_protocol (@w{GpgmeCtx @var{ctx}}, @w{GpgmeProtocol @var{proto}})
978 The function @code{gpgme_set_protocol} sets the protocol used within
979 the context @var{ctx} to @var{proto}.  All crypto operations will be
980 performed by the crypto engine configured for that protocol.
981 @xref{Protocols and Engines}.
982
983 Setting the protocol with @code{gpgme_set_protocol} does not check if
984 the crypto engine for that protocol is available and installed
985 correctly.  @xref{Engine Version Check}.
986
987 The function returns @code{GPGME_No_Error} if the protocol could be
988 set successfully, and @code{GPGME_Invalid_Value} if @var{protocol} is
989 not a valid protocol.
990 @end deftypefun
991
992
993 @node @acronym{ASCII} Armor
994 @subsection @acronym{ASCII} Armor
995 @cindex context, armor mode
996 @cindex @acronym{ASCII} armor
997 @cindex armor mode
998
999 @deftypefun void gpgme_set_armor (@w{GpgmeCtx @var{ctx}}, @w{int @var{yes}})
1000 The function @code{gpgme_set_armor} specifies if the output should be
1001 @acronym{ASCII} armored.  By default, output is not @acronym{ASCII}
1002 armored.
1003
1004 @acronym{ASCII} armored output is disabled if @var{yes} is zero, and
1005 enabled otherwise.
1006 @end deftypefun
1007
1008 @deftypefun int gpgme_get_armor (@w{GpgmeCtx @var{ctx}})
1009 The function @code{gpgme_get_armor} returns 1 if the output is
1010 @acronym{ASCII} armored, and @code{0} if it is not, or if @var{ctx} is
1011 not a valid pointer.
1012 @end deftypefun
1013
1014
1015 @node Text Mode
1016 @subsection Text Mode
1017 @cindex context, text mode
1018 @cindex text mode
1019 @cindex canonical text mode
1020
1021 @deftypefun void gpgme_set_textmode (@w{GpgmeCtx @var{ctx}}, @w{int @var{yes}})
1022 The function @code{gpgme_set_textmode} specifies if canonical text mode
1023 should be used.  By default, text mode is not used.
1024
1025 Text mode is for example used for the RFC2015 signatures; note that
1026 the updated RFC 3156 mandates that the mail user agent does some
1027 preparations so that text mode is not needed anymore.
1028
1029 This option is only relevant to the OpenPGP crypto engine, and ignored
1030 by all other engines.
1031
1032 Canonical text mode is disabled if @var{yes} is zero, and enabled
1033 otherwise.
1034 @end deftypefun
1035
1036 @deftypefun int gpgme_get_textmode (@w{GpgmeCtx @var{ctx}})
1037 The function @code{gpgme_get_textmode} returns 1 if canonical text
1038 mode is enabled, and @code{0} if it is not, or if @var{ctx} is not a
1039 valid pointer.
1040 @end deftypefun
1041
1042
1043 @node Included Certificates
1044 @subsection Included Certificates
1045 @cindex certificates, included
1046
1047 @deftypefun void gpgme_set_include_certs (@w{GpgmeCtx @var{ctx}}, @w{int @var{nr_of_certs}})
1048 The function @code{gpgme_set_include_certs} specifies how many
1049 certificates should be included in an S/MIME signed message.  By
1050 default, only the sender's certificate is included.  The possible
1051 values of @var{nr_of_certs} are:
1052
1053 @table @code
1054 @item -2
1055 Include all certificates except the root certificate.
1056 @item -1
1057 Include all certificates.
1058 @item 0
1059 Include no certificates.
1060 @item 1
1061 Include the sender's certificate only.
1062 @item n
1063 Include the first n certificates of the certificates path, starting
1064 from the sender's certificate.  The number @code{n} must be positive.
1065 @end table
1066
1067 Values of @var{nr_of_certs} smaller than -2 are undefined.
1068
1069 This option is only relevant to the CMS crypto engine, and ignored
1070 by all other engines.
1071 @end deftypefun
1072
1073 @deftypefun int gpgme_get_include_certs (@w{GpgmeCtx @var{ctx}})
1074 The function @code{gpgme_get_include_certs} returns the number of
1075 certificates to include into an S/MIME signed message.
1076 @end deftypefun
1077
1078
1079 @node Key Listing Mode
1080 @subsection Key Listing Mode
1081 @cindex key listing mode
1082 @cindex key listing, mode of
1083
1084 @deftypefun void gpgme_set_keylist_mode (@w{GpgmeCtx @var{ctx}}, @w{int @var{mode}})
1085 The function @code{gpgme_set_keylist_mode} changes the default
1086 behaviour of the key listing functions.  The value in @var{mode} is a
1087 bitwise-or combination of one or multiple of the following bit values:
1088
1089 @table @code
1090 @item GPGME_KEYLIST_MODE_LOCAL
1091 The @code{GPGME_KEYLIST_MODE_LOCAL} symbol specifies that the local
1092 keyring should be searched for keys in the keylisting operation.  This
1093 is the default.
1094
1095 @item GPGME_KEYLIST_MODE_EXTERN
1096 The @code{GPGME_KEYLIST_MODE_EXTERN} symbol specifies that an external
1097 source should be should be searched for keys in the keylisting
1098 operation.  The type of external source is dependant on the crypto
1099 engine used.  For example, it can be a remote keyserver or LDAP
1100 certificate server.
1101 @end table
1102
1103 At least one of @code{GPGME_KEYLIST_MODE_LOCAL} and
1104 @code{GPGME_KEYLIST_MODE_EXTERN} must be specified.  For future binary
1105 compatibility, you should get the current mode with
1106 @code{gpgme_get_keylist_mode} and modify it by setting or clearing the
1107 appropriate bits, and then using that calulcated value in the
1108 @code{gpgme_set_keylisting_mode} operation.  This will leave all other
1109 bits in the mode value intact (in particular those that are not used
1110 in the current version of the library).
1111
1112 The function returns @code{GPGME_No_Error} if the mode could be set
1113 correctly, and @code{GPGME_Invalid_Value} if @var{ctx} is not a valid
1114 pointer or @var{mode} is not a valid mode.
1115 @end deftypefun
1116
1117
1118 @deftypefun int gpgme_get_keylist_mode (@w{GpgmeCtx @var{ctx}})
1119 The function @code{gpgme_get_keylist_mode} returns the current key
1120 listing mode of the context @var{ctx}.  This value can then be
1121 modified and used in a subsequent @code{gpgme_set_keylist_mode}
1122 operation to only affect the desired bits (and leave all others
1123 intact).
1124
1125 The function returns 0 if @var{ctx} is not a valid pointer, and the
1126 current mode otherwise.  Note that 0 is not a valid mode value.
1127 @end deftypefun
1128
1129
1130 @node Passphrase Callback
1131 @subsection Passphrase Callback
1132 @cindex callback, passphrase
1133 @cindex passphrase callback
1134
1135 @deftp {Data type} {const char *(*GpgmePassphraseCb)(void *@var{hook}, const char *@var{desc}, void **@var{r_hd})}
1136 @tindex GpgmePassphraseCb
1137 The @code{GpgmePassphraseCb} type is the type of functions usable as
1138 passphrase callback function.
1139
1140 The string @var{desc} contains a test usable to be displayed to the
1141 user of the application.  The function should return a passphrase for
1142 the context when invoked with @var{desc} not being @code{NULL}.
1143
1144 The user may store information about the resources associated with the
1145 returned passphrase in @var{*r_hd}.  When the passphrase is no longer
1146 needed by @acronym{GPGME}, the passphrase callback function will be
1147 called with @var{desc} being @var{NULL}, and @var{r_hd} being the same
1148 as at the first invocation.
1149 @end deftp
1150
1151 @deftypefun void gpgme_set_passphrase_cb (@w{GpgmeCtx @var{ctx}}, @w{GpgmePassphraseCb @var{passfunc}}, @w{void *@var{hook_value}})
1152 The function @code{gpgme_set_passphrase_cb} sets the function that is
1153 used when a passphrase needs to be provided by the user to
1154 @var{passfunc}.  The function @var{passfunc} needs to implemented by
1155 the user, and whenever it is called, it is called with its first
1156 argument being @var{hook_value}.  By default, no passphrase callback
1157 function is set.
1158
1159 Not all crypto engines require this callback to retrieve the
1160 passphrase.  It is better if the engine retrieves the passphrase from
1161 a trusted agent (a daemon process), rather than having each user to
1162 implement their own passphrase query.
1163
1164 The user can disable the use of a passphrase callback function by
1165 calling @code{gpgme_set_passphrase_cb} with @var{passfunc} being
1166 @code{NULL}.
1167 @end deftypefun
1168
1169
1170 @node Progress Meter Callback
1171 @subsection Progress Meter Callback
1172 @cindex callback, progress meter
1173 @cindex progress meter callback
1174
1175 @deftp {Data type} {const char *(*GpgmeProgressCb)(void *@var{hook}, const char *@var{what}, int @var{type}, int @var{current}, int @var{total})}
1176 @tindex GpgmeProgressCb
1177 The @code{GpgmeProgressCb} type is the type of functions usable as
1178 progress callback function.
1179
1180 The arguments are specific to the crypto engine.  More information
1181 about the progress information returned from the GnuPG engine can be
1182 found in the GnuPG source code in the file @file{doc/DETAILS} in the
1183 section PROGRESS.
1184 @end deftp
1185
1186 @deftypefun void gpgme_set_progress_cb (@w{GpgmeCtx @var{ctx}}, @w{GpgmeProgressCb @var{progfunc}}, @w{void *@var{hook_value}})
1187 The function @code{gpgme_set_progress_cb} sets the function that is
1188 used when progress information about a cryptographic operation is
1189 available.  The function @var{progfunc} needs to implemented by the
1190 user, and whenever it is called, it is called with its first argument
1191 being @var{hook_value}.  By default, no progress callback function
1192 is set.
1193
1194 Setting a callback function allows an interactive program to display
1195 progress information about a long operation to the user.
1196
1197 The user can disable the use of a progress callback function by
1198 calling @code{gpgme_set_progress_cb} with @var{progfunc} being
1199 @code{NULL}.
1200 @end deftypefun
1201
1202
1203 @node Key Management
1204 @section Key Management
1205 @cindex key management
1206
1207 Some of the cryptographic operations require that recipients or
1208 signers are specified.  This is always done by specifying the
1209 respective keys that should be used for the operation.  The following
1210 section describes how such keys can be selected and manipulated.
1211
1212 @deftp {Data type} GpgmeKey
1213 The @code{GpgmeKey} type is a handle for a public or secret key, and
1214 is used to select the key for operations involving it.
1215
1216 A key can contain several user IDs and sub keys.
1217 @end deftp
1218
1219 @menu
1220 * Listing Keys::                  Browsing the list of available keys.
1221 * Information About Keys::        Requesting detailed information about keys.
1222 * Manipulating Keys::             Operations on keys.
1223 * Generating Keys::               Creating new key pairs.
1224 * Exporting Keys::                Retrieving key data from the key ring.
1225 * Importing Keys::                Adding keys to the key ring.
1226 * Deleting Keys::                 Removing keys from the key ring.
1227 @end menu
1228
1229
1230 @node Listing Keys
1231 @subsection Listing Keys
1232 @cindex listing keys
1233 @cindex key listing
1234 @cindex key listing, start
1235 @cindex key ring, list
1236 @cindex key ring, search
1237
1238 @deftypefun GpgmeError gpgme_op_keylist_start (@w{GpgmeCtx @var{ctx}}, @w{const char *@var{pattern}}, @w{int @var{secret_only}})
1239 The function @code{gpgme_op_keylist_start} initiates a key listing
1240 operation inside the context @var{ctx}.  It sets everything up so that
1241 subsequent invocations of @code{gpgme_op_keylist_next} return the keys
1242 in the list.
1243
1244 If @var{pattern} is @code{NULL}, all available keys are returned.
1245 Otherwise, @var{pattern} contains an engine specific expression that
1246 is used to limit the list to all keys matching the pattern.
1247
1248 If @var{secret_only} is not @code{0}, the list is restricted to secret
1249 keys only.
1250
1251 The context will be busy until either all keys are received (and
1252 @code{gpgme_op_keylist_next} returns @code{GPGME_EOF}), or
1253 @code{gpgme_op_keylist_end} is called to finish the operation.
1254
1255 The function returns @code{GPGME_Invalid_Value} if @var{ctx} is not a
1256 valid pointer, and passes through any errors that are reported by the
1257 crypto engine support routines.
1258 @end deftypefun
1259
1260 @deftypefun GpgmeError gpgme_op_keylist_next (@w{GpgmeCtx @var{ctx}}, @w{GpgmeKey *@var{r_key}})
1261 The function @code{gpgme_op_keylist_next} returns the next key in the
1262 list created by a previous @code{gpgme_op_keylist_start} operation in
1263 the context @var{ctx}.  The key will have one reference for the user.
1264 @xref{Manipulating Keys}.
1265
1266 This is the only way to get at @code{GpgmeKey} objects in
1267 @acronym{GPGME}.
1268
1269 If the last key in the list has already been returned,
1270 @code{gpgme_op_keylist_next} returns @code{GPGME_EOF}.
1271
1272 The function returns @code{GPGME_Invalid_Value} if @var{ctx} or
1273 @var{r_key} is not a valid pointer, @code{GPGME_No_Request} if there
1274 is no pending operation, @code{GPGME_Out_Of_Core} if there is not
1275 enough memory for the operation.
1276 @end deftypefun
1277
1278 @deftypefun GpgmeError gpgme_op_keylist_end (@w{GpgmeCtx @var{ctx}})
1279 The function @code{gpgme_op_keylist_next} ends a pending key list
1280 operation in the context @var{ctx}.
1281
1282 The function returns @code{GPGME_Invalid_Value} if @var{ctx} is not a
1283 valid pointer, @code{GPGME_No_Request} if there is no pending
1284 operation, @code{GPGME_Out_Of_Core} if at some time during the
1285 operation there was not enough memory available.
1286 @end deftypefun
1287
1288
1289 @node Information About Keys
1290 @subsection Information About Keys
1291 @cindex key, information about
1292 @cindex key, attributes
1293 @cindex attributes, of a key
1294
1295 @deftypefun {char *} gpgme_key_get_as_xml (@w{GpgmeKey @var{key}})
1296 The function @code{gpgme_key_get_as_xml} returns a string in
1297 @acronym{XML} format describing the key @var{key}.  The user has to
1298 release the string with @code{free}.
1299
1300 The function returns @code{NULL} if @var{key} is not a valid pointer,
1301 or there is not enough memory available.
1302 @end deftypefun
1303
1304 @deftp {Data type} GpgmeAttr
1305 The @code{GpgmeAttr} type is used to specify a key or trust item
1306 attribute.  The following attributes are defined:
1307
1308 @table @code
1309 @item GPGME_ATTR_KEYID
1310 This is the key ID of a sub key.  It is representable as a string.
1311
1312 For trust items, the trust item refers to the key with this ID.
1313
1314 @item GPGME_ATTR_FPR
1315 This is the fingerprint of a sub key.  It is representable as a
1316 string.
1317
1318 @item GPGME_ATTR_ALGO
1319 This is the crypto algorithm for which the sub key can be used.  It
1320 is representable as a string and as a number.  The numbers correspond
1321 to the @code{enum gcry_pk_algos} values in the gcrypt library.
1322
1323 @item GPGME_ATTR_LEN
1324 This is the key length of a sub key.  It is representable as a
1325 number.
1326
1327 @item GPGME_ATTR_CREATED
1328 This is the timestamp at creation time of a sub key.  It is
1329 representable as a number.
1330
1331 @item GPGME_ATTR_EXPIRE
1332 XXX FIXME
1333
1334 @item GPGME_ATTR_OTRUST
1335 XXX FIXME  (also for trust items)
1336
1337 @item GPGME_ATTR_USERID
1338 This is a user ID.  There can be more than one user IDs in a
1339 @var{GpgmeKey} object.  The first one (with index 0) is the primary
1340 user ID.  The user ID is representable as a number.
1341
1342 For trust items, this is the user ID associated with this trust item.
1343
1344 @item GPGME_ATTR_NAME
1345 This is the name belonging to a user ID.  It is representable as a string.
1346
1347 @item GPGME_ATTR_EMAIL
1348 This is the email address belonging to a user ID.  It is representable
1349 as a string.
1350
1351 @item GPGME_ATTR_COMMENT
1352 This is the comment belonging to a user ID.  It is representable as a
1353 string.
1354
1355 @item GPGME_ATTR_VALIDITY
1356 This is the validity belonging to a user ID.  It is representable as a
1357 string and as a number.  See below for a list of available validities.
1358
1359 For trust items, this is the validity that is associated with this
1360 trust item.
1361
1362 @item GPGME_ATTR_UID_REVOKED
1363 This specifies if a user ID is revoked.  It is representable as a
1364 number, and is @code{1} if the user ID is revoked, and @code{0}
1365 otherwise.
1366
1367 @item GPGME_ATTR_UID_INVALID
1368 This specifies if a user ID is invalid.  It is representable as a
1369 number, and is @code{1} if the user ID is invalid, and @code{0}
1370 otherwise.
1371
1372 @item GPGME_ATTR_LEVEL
1373 This is the trust level of a trust item.
1374
1375 @item GPGME_ATTR_TYPE
1376 This is the type of a trust item.
1377
1378 @item GPGME_ATTR_IS_SECRET
1379 This specifies if the key is a secret key.  It is representable as a
1380 string or a number.  If the key is a secret key, the representation is
1381 ``1'' or @code{1}, otherwise it is @code{NULL} or @code{0}.
1382
1383 @item GPGME_ATTR_KEY_REVOKED
1384 This specifies if a sub key is revoked.  It is representable as a
1385 number, and is @code{1} if the key is revoked, and @code{0} otherwise.
1386
1387 @item GPGME_ATTR_KEY_INVALID
1388 This specifies if a sub key is invalid.  It is representable as a
1389 number, and is @code{1} if the key is invalid, and @code{0} otherwise.
1390
1391 @item GPGME_ATTR_KEY_EXPIRED
1392 This specifies if a sub key is expired.  It is representable as a
1393 number, and is @code{1} if the key is expired, and @code{0} otherwise.
1394
1395 @item GPGME_ATTR_KEY_DISABLED
1396 This specifies if a sub key is disabled.  It is representable as a
1397 number, and is @code{1} if the key is disabled, and @code{0} otherwise.
1398
1399 @item GPGME_ATTR_KEY_CAPS
1400 This is a description of the capabilities of a sub key.  It is
1401 representable as a string.  The string contains the letter ``e'' if
1402 the key can be used for encryption, ``s'' if the key can be used for
1403 signatures, and ``c'' if the key can be used for certifications.
1404
1405 @item GPGME_ATTR_CAN_ENCRYPT
1406 This specifies if a sub key can be used for encryption.  It is
1407 representable as a number, and is @code{1} if the sub key can be used
1408 for encryption, and @code{0} otherwise.
1409
1410 @item GPGME_ATTR_CAN_SIGN
1411 This specifies if a sub key can be used for signatures.  It is
1412 representable as a number, and is @code{1} if the sub key can be used
1413 for signatures, and @code{0} otherwise.
1414
1415 @item GPGME_ATTR_CAN_CERTIFY
1416 This specifies if a sub key can be used for certifications.  It is
1417 representable as a number, and is @code{1} if the sub key can be used
1418 for certifications, and @code{0} otherwise.
1419 @end table
1420 @end deftp
1421
1422 @deftp {Data type} GpgmeValidity
1423 The @code{GpgmeValidity} type is used to specify the validity of a user ID
1424 in a key.  The following validities are defined:
1425
1426 @table @code
1427 @item GPGME_VALIDITY_UNKNOWN
1428 The user ID is of unknown validity.  The string representation of this
1429 validity is ``?''.
1430
1431 @item GPGME_VALIDITY_UNDEFINED
1432 The validity of the user ID is undefined.  The string representation of this
1433 validity is ``q''.
1434
1435 @item GPGME_VALIDITY_NEVER
1436 The user ID is never valid.  The string representation of this
1437 validity is ``n''.
1438
1439 @item GPGME_VALIDITY_MARGINAL
1440 The user ID is marginally valid.  The string representation of this
1441 validity is ``m''.
1442
1443 @item GPGME_VALIDITY_FULL
1444 The user ID is fully valid.  The string representation of this
1445 validity is ``f''.
1446
1447 @item GPGME_VALIDITY_ULTIMATE
1448 The user ID is ultimately valid.  The string representation of this
1449 validity is ``u''.
1450 @end table
1451 @end deftp
1452
1453 @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}})
1454 The function @code{gpgme_key_get_string_attr} returns the value of the
1455 string-representable attribute @var{what} of key @var{key}.  If the
1456 attribute occurs more than once in the key, the index is specified by
1457 @var{idx}.  This applies to attributes of sub keys and user IDs.  The
1458 argument @var{reserved} is reserved for later use and should be
1459 @code{NULL}.
1460
1461 The string returned is only valid as long as the key is valid.
1462
1463 The function returns @code{0} if an attribute can't be returned as a
1464 string, @var{key} is not a valid pointer, @var{idx} out of range,
1465 or @var{reserved} not @code{NULL}.
1466 @end deftypefun
1467
1468 @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}})
1469 The function @code{gpgme_key_get_ulong_attr} returns the value of the
1470 number-representable attribute @var{what} of key @var{key}.  If the
1471 attribute occurs more than once in the key, the index is specified by
1472 @var{idx}.  This applies to attributes of sub keys and user IDs.  The
1473 argument @var{reserved} is reserved for later use and should be
1474 @code{NULL}.
1475
1476 The function returns @code{0} if the attribute can't be returned as a
1477 number, @var{key} is not a valid pointer, @var{idx} out of range,
1478 or @var{reserved} not @code{NULL}.
1479 @end deftypefun
1480
1481
1482 @node Manipulating Keys
1483 @subsection Manipulating Keys
1484 @cindex key, manipulation
1485
1486 @deftypefun void gpgme_key_ref (@w{GpgmeKey @var{key}})
1487 The function @code{gpgme_key_ref} acquires an additional reference for
1488 the key @var{key}.
1489 @end deftypefun
1490
1491 @deftypefun void gpgme_key_unref (@w{GpgmeKey @var{key}})
1492 @deftypefunx void gpgme_key_release (@w{GpgmeKey @var{key}})
1493 The function @code{gpgme_key_ref} releases a reference for the key
1494 @var{key}.  If this was the last reference, the key will be destroyed
1495 and all resources associated to it will be released.
1496
1497 The function @code{gpgme_key_release} is an alias for
1498 @code{gpgme_key_unref}.
1499 @end deftypefun
1500
1501
1502 @node Generating Keys
1503 @subsection Generating Keys
1504 @cindex key, creation
1505 @cindex key ring, add
1506
1507 @deftypefun GpgmeError gpgme_op_genkey (@w{GpgmeCtx @var{ctx}}, @w{const char *@var{parms}}, @w{GpgmeData @var{pubkey}}, @w{GpgmeData @var{seckey}})
1508 The function @code{gpgme_op_genkey} generates a new key pair in the
1509 context @var{ctx} and puts it into the standard key ring if both
1510 @var{pubkey} and @var{seckey} are @code{NULL}.  In this case the
1511 function returns immediately after starting the operation, and does
1512 not wait for it to complete.  If @var{pubkey} is not @code{NULL} it
1513 should be the handle for an empty (newly created) data object, and
1514 upon successful completion the data object will contain the public
1515 key.  If @var{seckey} is not @code{NULL} it should be the handle for
1516 an empty (newly created) data object, and upon successful completion
1517 the data object will contain the secret key.
1518
1519 Note that not all crypto engines support this interface equally.
1520 GnuPG does not support @var{pubkey} and @var{subkey}, they should be
1521 both @code{NULL}, and the key pair will be added to the standard key
1522 ring.  GpgSM does only support @var{pubkey}, the secret key will be
1523 stored by @command{gpg-agent}.  GpgSM expects @var{pubkey} being not
1524 @code{NULL}.
1525
1526 The argument @var{parms} specifies parameters for the key in an XML
1527 string.  The details about the format of @var{parms} are specific to
1528 the crypto engine used by @var{ctx}.  Here is an example for GnuPG as
1529 the crypto engine:
1530
1531 @example
1532 <GnupgKeyParms format="internal">
1533 Key-Type: DSA
1534 Key-Length: 1024
1535 Subkey-Type: ELG-E
1536 Subkey-Length: 1024
1537 Name-Real: Joe Tester
1538 Name-Comment: with stupid passphrase
1539 Name-Email: joe@@foo.bar
1540 Expire-Date: 0
1541 Passphrase: abc
1542 </GnupgKeyParms>
1543 @end example
1544
1545 Here is an example for GpgSM as the crypto engine:
1546 @example
1547 <GnupgKeyParms format="internal">
1548 Key-Type: RSA
1549 Key-Length: 1024
1550 Name-DN: C=de,O=g10 code,OU=Testlab,CN=Joe 2 Tester
1551 Name-Email: joe@@foo.bar
1552 </GnupgKeyParms>
1553 @end example
1554
1555 Strings should be given in UTF-8 encoding.  The only format supported
1556 for now is ``internal''.  The content of the @code{GnupgKeyParms}
1557 container is passed verbatim to GnuPG.  Control statements are not
1558 allowed.
1559
1560 The function returns @code{GPGME_No_Error} if the operation could be
1561 started successfully, @code{GPGME_Invalid_Value} if @var{parms} is not
1562 a valid XML string, @code{GPGME_Not_Supported} if @var{pubkey} or
1563 @var{seckey} is not valid, and @code{GPGME_General_Error} if no key
1564 was created by the backend.
1565 @end deftypefun
1566
1567 @deftypefun GpgmeError gpgme_op_genkey_start (@w{GpgmeCtx @var{ctx}}, @w{const char *@var{parms}}, @w{GpgmeData @var{pubkey}}, @w{GpgmeData @var{seckey}})
1568 The function @code{gpgme_op_genkey_start} initiates a
1569 @code{gpgme_op_genkey} operation.  It can be completed by calling
1570 @code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
1571
1572 The function returns @code{GPGME_No_Error} if the operation could be
1573 started successfully, @code{GPGME_Invalid_Value} if @var{parms} is not
1574 a valid XML string, and @code{GPGME_Not_Supported} if @var{pubkey} or
1575 @var{seckey} is not @code{NULL}.
1576 @end deftypefun
1577
1578
1579 @node Exporting Keys
1580 @subsection Exporting Keys
1581 @cindex key, export
1582 @cindex key ring, export from
1583
1584 @deftypefun GpgmeError gpgme_op_export (@w{GpgmeCtx @var{ctx}}, @w{GpgmeRecipients @var{recipients}}, @w{GpgmeData @var{keydata}})
1585 The function @code{gpgme_op_export} extracts the public keys of the
1586 user IDs in @var{recipients} and returns them in the data buffer
1587 @var{keydata}.  The type of the public keys returned is determined by
1588 the @acronym{ASCII} armor attribute set for the context @var{ctx}.
1589
1590 The function returns @code{GPGME_No_Error} if the operation completed
1591 successfully, @code{GPGME_Invalid_Value} if @var{recipients} is
1592 @code{NULL} or @var{keydata} is not a valid empty data buffer, and
1593 passes through any errors that are reported by the crypto engine
1594 support routines.
1595 @end deftypefun
1596
1597 @deftypefun GpgmeError gpgme_op_export_start (@w{GpgmeCtx @var{ctx}}, @w{GpgmeRecipients @var{recipients}}, @w{GpgmeData @var{keydata}})
1598 The function @code{gpgme_op_export_start} initiates a
1599 @code{gpgme_op_export} operation.  It can be completed by calling
1600 @code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
1601
1602 The function returns @code{GPGME_No_Error} if the operation could be
1603 started successfully, and @code{GPGME_Invalid_Value} if
1604 @var{recipients} is @code{NULL} or @var{keydata} is not a valid empty
1605 data buffer.
1606 @end deftypefun
1607
1608
1609 @node Importing Keys
1610 @subsection Importing Keys
1611 @cindex key, import
1612 @cindex key ring, import to
1613
1614 @deftypefun GpgmeError gpgme_op_import (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{keydata}})
1615 The function @code{gpgme_op_import} adds the keys in the data buffer
1616 @var{keydata} to the key ring of the crypto engine used by @var{ctx}.
1617 The format of @var{keydata} can be @var{ASCII} armored, for example,
1618 but the details are specific to the crypto engine.
1619
1620 More information about the import is available with
1621 @code{gpgme_get_op_info}.  @xref{Detailed Results}.
1622
1623 The function returns @code{GPGME_No_Error} if the import was completed
1624 successfully, @code{GPGME_Invalid_Value} if @var{keydata} if @var{ctx}
1625 or @var{keydata} is not a valid pointer, and @code{GPGME_No_Data} if
1626 @var{keydata} is an empty data buffer.
1627 @end deftypefun
1628
1629 @deftypefun GpgmeError gpgme_op_import_start (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{keydata}})
1630 The function @code{gpgme_op_import_start} initiates a
1631 @code{gpgme_op_import} operation.  It can be completed by calling
1632 @code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
1633
1634 The function returns @code{GPGME_No_Error} if the import could be
1635 started successfully, @code{GPGME_Invalid_Value} if @var{keydata} if
1636 @var{ctx} or @var{keydata} is not a valid pointer, and
1637 @code{GPGME_No_Data} if @var{keydata} is an empty data buffer.
1638 @end deftypefun
1639
1640
1641 @node Deleting Keys
1642 @subsection Deleting Keys
1643 @cindex key, delete
1644 @cindex key ring, delete from
1645
1646 @deftypefun GpgmeError gpgme_op_delete (@w{GpgmeCtx @var{ctx}}, @w{const GpgmeKey @var{key}}, @w{int @var{allow_secret}})
1647 The function @code{gpgme_op_delete} deletes the key @var{key} from the
1648 key ring of the crypto engine used by @var{ctx}.  If
1649 @var{allow_secret} is @code{0}, only public keys are deleted,
1650 otherwise secret keys are deleted as well.
1651
1652 The function returns @code{GPGME_No_Error} if the key was deleted
1653 successfully, @code{GPGME_Invalid_Value} if @var{ctx} or @var{key} is
1654 not a valid pointer, @code{GPGME_Invalid_Key} if @var{key} could not
1655 be found in the keyring, and @code{GPGME_Conflict} if the secret key
1656 for @var{key} is available, but @var{allow_secret} is zero.
1657 @end deftypefun
1658
1659 @deftypefun GpgmeError gpgme_op_delete_start (@w{GpgmeCtx @var{ctx}}, @w{const GpgmeKey @var{key}}, @w{int @var{allow_secret}})
1660 The function @code{gpgme_op_delete_start} initiates a
1661 @code{gpgme_op_delete} operation.  It can be completed by calling
1662 @code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
1663
1664 The function returns @code{GPGME_No_Error} if the operation was
1665 started successfully, and @code{GPGME_Invalid_Value} if @var{ctx} or
1666 @var{key} is not a valid pointer.
1667 @end deftypefun
1668
1669
1670 @node Trust Item Management
1671 @section Trust Item Management
1672 @cindex trust item
1673
1674 @strong{Caution:} The trust items interface is experimental.
1675
1676 @deftp {Data type} GpgmeTrustItem
1677 The @code{GpgmeTrustItem} type is a handle for a trust item.
1678 @end deftp
1679
1680 @menu
1681 * Listing Trust Items::           Browsing the list of available trust items.
1682 * Information About Trust Items:: Requesting detailed information about trust items.
1683 * Manipulating Trust Items::      Operations on trust items.
1684 @end menu
1685
1686
1687 @node Listing Trust Items
1688 @subsection Listing Trust Items
1689 @cindex trust item list
1690
1691 @deftypefun GpgmeError gpgme_op_trustlist_start (@w{GpgmeCtx @var{ctx}}, @w{const char *@var{pattern}}, @w{int @var{max_level}})
1692 The function @code{gpgme_op_trustlist_start} initiates a trust item
1693 listing operation inside the context @var{ctx}.  It sets everything up
1694 so that subsequent invocations of @code{gpgme_op_trustlist_next} return
1695 the trust items in the list.
1696
1697 The string @var{pattern} contains an engine specific expression that
1698 is used to limit the list to all trust items matching the pattern.  It
1699 can not be the empty string.
1700
1701 The argument @var{max_level} is currently ignored.
1702
1703 The context will be busy until either all trust items are received
1704 (and @code{gpgme_op_trustlist_next} returns @code{GPGME_EOF}), or
1705 @code{gpgme_op_trustlist_end} is called to finish the operation.
1706
1707 The function returns @code{GPGME_Invalid_Value} if @var{ctx} is not a
1708 valid pointer, and passes through any errors that are reported by the
1709 crypto engine support routines.
1710 @end deftypefun
1711
1712 @deftypefun GpgmeError gpgme_op_trustlist_next (@w{GpgmeCtx @var{ctx}}, @w{GpgmeTrustItem *@var{r_item}})
1713 The function @code{gpgme_op_trustlist_next} returns the next trust
1714 item in the list created by a previous @code{gpgme_op_trustlist_start}
1715 operation in the context @var{ctx}.  The trust item can be destroyed
1716 with @code{gpgme_trust_item_release}.  @xref{Manipulating Trust Items}.
1717
1718 This is the only way to get at @code{GpgmeTrustItem} objects in
1719 @acronym{GPGME}.
1720
1721 If the last trust item in the list has already been returned,
1722 @code{gpgme_op_trustlist_next} returns @code{GPGME_EOF}.
1723
1724 The function returns @code{GPGME_Invalid_Value} if @var{ctx} or
1725 @var{r_item} is not a valid pointer, @code{GPGME_No_Request} if there
1726 is no pending operation, @code{GPGME_Out_Of_Core} if there is not
1727 enough memory for the operation.
1728 @end deftypefun
1729
1730 @deftypefun GpgmeError gpgme_op_trustlist_end (@w{GpgmeCtx @var{ctx}})
1731 The function @code{gpgme_op_trustlist_next} ends a pending key list
1732 operation in the context @var{ctx}.
1733
1734 The function returns @code{GPGME_Invalid_Value} if @var{ctx} is not a
1735 valid pointer, @code{GPGME_No_Request} if there is no pending
1736 operation, @code{GPGME_Out_Of_Core} if at some time during the
1737 operation there was not enough memory available.
1738 @end deftypefun
1739
1740
1741 @node Information About Trust Items
1742 @subsection Information About Trust Items
1743 @cindex trust item, information about
1744 @cindex trust item, attributes
1745 @cindex attributes, of a trust item
1746
1747 Trust items have attributes which can be queried using the interfaces
1748 below.  The attribute identifiers are shared with those for key
1749 attributes.  @xref{Information About Keys}.
1750
1751 @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}})
1752 The function @code{gpgme_trust_item_get_string_attr} returns the value
1753 of the string-representable attribute @var{what} of trust item
1754 @var{item}.  If the attribute occurs more than once in the trust
1755 items, the index is specified by @var{idx}.  However, currently no
1756 such attributes exists, so @var{idx} should be @code{0}.  The argument
1757 @var{reserved} is reserved for later use and should be @code{NULL}.
1758
1759 The string returned is only valid as long as the key is valid.
1760
1761 The function returns @code{0} if an attribute can't be returned as a
1762 string, @var{key} is not a valid pointer, @var{idx} out of range,
1763 or @var{reserved} not @code{NULL}.
1764 @end deftypefun
1765
1766 @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}})
1767 The function @code{gpgme_trust_item_get_int_attr} returns the value of
1768 the number-representable attribute @var{what} of trust item
1769 @var{item}.  If the attribute occurs more than once in the trust item,
1770 the index is specified by @var{idx}.  However, currently no such
1771 attribute exists, so @var{idx} should be @code{0}.  The argument
1772 @var{reserved} is reserved for later use and should be @code{NULL}.
1773
1774 The function returns @code{0} if the attribute can't be returned as a
1775 number, @var{key} is not a valid pointer, @var{idx} out of range,
1776 or @var{reserved} not @code{NULL}.
1777 @end deftypefun
1778
1779
1780 @node Manipulating Trust Items
1781 @subsection Manipulating Trust Items
1782 @cindex trust item, manipulation
1783
1784 @deftypefun void gpgme_trust_item_release (@w{GpgmeTrustItem @var{item}})
1785 The function @code{gpgme_trust_item_release} destroys a
1786 @code{GpgmeTrustItem} object and releases all associated resources.
1787 @end deftypefun
1788
1789 @node Crypto Operations
1790 @section Crypto Operations
1791 @cindex cryptographic operation
1792
1793 @menu
1794 * Decrypt::                       Decrypting a ciphertext.
1795 * Verify::                        Verifying a signature.
1796 * Decrypt and Verify::            Decrypting a signed ciphertext.
1797 * Sign::                          Creating a signature.
1798 * Encrypt::                       Encrypting a plaintext.
1799 * Detailed Results::              How to obtain more info about the operation.
1800 @end menu
1801
1802
1803 @node Decrypt
1804 @subsection Decrypt
1805 @cindex decryption
1806 @cindex cryptographic operation, decryption
1807
1808 @deftypefun GpgmeError gpgme_op_decrypt (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{cipher}}, @w{GpgmeData @var{plain}})
1809 The function @code{gpgme_op_decrypt} decrypts the ciphertext in the
1810 data object @var{cipher} and stores it into the data object
1811 @var{plain}.
1812
1813 The function returns @code{GPGME_No_Error} if the ciphertext could be
1814 decrypted successfully, @code{GPGME_Invalid_Value} if @var{ctx},
1815 @var{cipher} or @var{plain} is not a valid pointer,
1816 @code{GPGME_No_Data} if @var{cipher} does not contain any data to
1817 decrypt, @code{GPGME_Decryption_Failed} if @var{cipher} is not a valid
1818 cipher text, @code{GPGME_No_Passphrase} if the passphrase for the
1819 secret key could not be retrieved, and passes through any errors that
1820 are reported by the crypto engine support routines.
1821 @end deftypefun
1822
1823 @deftypefun GpgmeError gpgme_op_decrypt_start (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{cipher}}, @w{GpgmeData @var{plain}})
1824 The function @code{gpgme_op_decrypt_start} initiates a
1825 @code{gpgme_op_decrypt} operation.  It can be completed by calling
1826 @code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
1827
1828 The function returns @code{GPGME_No_Error} if the operation could be
1829 started successfully, and @code{GPGME_Invalid_Value} if @var{cipher}
1830 or @var{plain} is not a valid pointer.
1831 @end deftypefun
1832
1833
1834 @node Verify
1835 @subsection Verify
1836 @cindex verification
1837 @cindex signature, verification
1838 @cindex cryptographic operation, verification
1839 @cindex cryptographic operation, signature check
1840 @cindex signature, status
1841
1842 @deftp {Data type} {enum GpgmeSigStat}
1843 @tindex GpgmeSigStat
1844 The @code{GpgmeSigStat} type holds the result of a signature check, or
1845 the combined result of all signatures.  The following results are
1846 possible:
1847
1848 @table @code
1849 @item GPGME_SIG_STAT_NONE
1850 This status should not occur in normal operation.
1851
1852 @item GPGME_SIG_STAT_GOOD
1853 This status indicates that the signature is valid.  For the combined
1854 result this status means that all signatures are valid.
1855
1856 @item GPGME_SIG_STAT_BAD
1857 This status indicates that the signature is invalid.  For the combined
1858 result this status means that all signatures are invalid.
1859
1860 @item GPGME_SIG_STAT_NOKEY
1861 This status indicates that the signature could not be verified due to
1862 a missing key.  For the combined result this status means that all
1863 signatures could not be checked due to missing keys.
1864
1865 @item GPGME_SIG_STAT_NOSIG
1866 This status indicates that the signature data provided was not a real
1867 signature.
1868
1869 @item GPGME_SIG_STAT_ERROR
1870 This status indicates that there was some other error which prevented
1871 the signature verification.
1872
1873 @item GPGME_SIG_STAT_DIFF
1874 For the combined result this status means that at least two signatures
1875 have a different status.  You can get each key's status with
1876 @code{gpgme_get_sig_status}.
1877 @end table
1878 @end deftp
1879
1880 @deftypefun GpgmeError gpgme_op_verify (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{sig}}, @w{GpgmeData @var{plain}}, @w{GpgmeSigStat *@var{r_stat}})
1881 The function @code{gpgme_op_verify} verifies that the detached
1882 signature in the data object @var{sig} is a valid signature for the
1883 plaintext in the data object @var{plain}.
1884
1885 The combined status of all signatures is returned in @var{r_stat}.
1886 The results of the individual signature verifications can be retrieved
1887 with @code{gpgme_get_sig_status} and @code{gpgme_get_sig_key}.
1888
1889 The function returns @code{GPGME_No_Error} if the operation could be
1890 completed successfully, @code{GPGME_Invalid_Value} if @var{ctx},
1891 @var{sig}, @var{plain} or @var{r_stat} is not a valid pointer,
1892 @code{GPGME_No_Data} if @var{sig} or @var{plain} does not contain any
1893 data to verify, and passes through any errors that are reported by the
1894 crypto engine support routines.
1895 @end deftypefun
1896
1897 @deftypefun GpgmeError gpgme_op_verify_start (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{sig}}, @w{GpgmeData @var{plain}})
1898 The function @code{gpgme_op_verify_start} initiates a
1899 @code{gpgme_op_verify} operation.  It can be completed by calling
1900 @code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
1901
1902 The function returns @code{GPGME_No_Error} if the operation could be
1903 started successfully, @code{GPGME_Invalid_Value} if @var{ctx},
1904 @var{sig}, @var{plain} or @var{r_stat} is not a valid pointer, and
1905 @code{GPGME_No_Data} if @var{sig} or @var{plain} does not contain any
1906 data to verify.
1907 @end deftypefun
1908
1909 @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}})
1910 The function @code{gpgme_get_sig_status} receives information about a
1911 signature after the @code{gpgme_op_verify} or
1912 @code{gpgme_op_verify_decrypt} operation.  A single detached signature
1913 can contain signatures by more than one key.  The @var{idx} specifies
1914 which signature's information should be retrieved, starting from
1915 @var{0}.
1916
1917 The status of the signature will be returned in @var{r_stat} if it is
1918 not @code{NULL}.  The creation time stamp of the signature will be
1919 returned in @var{r_created} if it is not @var{NULL}.
1920
1921 The function returns a statically allocated string that contains the
1922 fingerprint of the key which signed the plaintext, or @code{NULL} if
1923 @var{ctx} is not a valid pointer, the operation is still pending, or
1924 no verification could be performed.
1925 @end deftypefun
1926
1927 @deftypefun {const char *} gpgme_get_sig_key (@w{GpgmeCtx @var{ctx}}, @w{int @var{idx}}, @w{GpgmeSigKey *@var{r_stat}})
1928 The function @code{gpgme_get_sig_status} receives a @code{GpgmeKey}
1929 object for the key which was used to verify the signature after the
1930 @code{gpgme_op_verify} or @code{gpgme_op_verify_decrypt} operation.  A
1931 single detached signature can contain signatures by more than one key.
1932 The @var{idx} specifies which signature's information should be
1933 retrieved, starting from @var{0}.  The key will have on reference for
1934 the user.
1935
1936 The function is a convenient way to retrieve the keys belonging to the
1937 fingerprints returned by @code{gpgme_get_sig_status}.
1938
1939 The function returns @code{GPGME_No_Error} if the key could be
1940 returned, @code{GPGME_Invalid_Value} if @var{r_key} is not a valid
1941 pointer, @code{GPGME_Invalid_Key} if the fingerprint is not valid,
1942 @code{GPGME_EOF} if @var{idx} is too large, or some other error value
1943 if a problem occurred requesting the key.
1944 @end deftypefun
1945
1946 @deftypefun {char *} gpgme_get_notation (@w{GpgmeCtx @var{ctx}})
1947 The function @code{gpgme_get_notation} can be used to retrieve
1948 notation data from the last signature check in the context @var{ctx}.
1949
1950 If there is notation data available from the last signature check,
1951 this function may be used to return this notation data as a string.
1952 The string is an XML representation of that data embedded in a
1953 <notation> container.  The user has to release the string with
1954 @code{free}.
1955
1956 The function returns a string if the notation data is available or
1957 @code{NULL} if there is no such data available.
1958 @end deftypefun
1959
1960
1961 @node Decrypt and Verify
1962 @subsection Decrypt and Verify
1963 @cindex decryption and verification
1964 @cindex verification and decryption
1965 @cindex signature check
1966 @cindex cryptographic operation, decryption and verification
1967
1968 @deftypefun GpgmeError gpgme_op_decrypt_verify (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{cipher}}, @w{GpgmeData @var{plain}}, @w{GpgmeSigStat *@var{r_stat}})
1969 The function @code{gpgme_op_decrypt_verify} decrypts the ciphertext in
1970 the data object @var{cipher} and stores it into the data object
1971 @var{plain}.  If @var{cipher} contains signatures, they will be
1972 verified and their combined status will be returned in @var{r_stat}.
1973
1974 After the operation completed, @code{gpgme_op_get_sig_status} and
1975 @code{gpgme_op_get_sig_key} can be used to retrieve more information
1976 about the signatures.
1977
1978 The function returns @code{GPGME_No_Error} if the ciphertext could be
1979 decrypted successfully, @code{GPGME_Invalid_Value} if @var{ctx},
1980 @var{cipher}, @var{plain} or @var{r_stat} is not a valid pointer,
1981 @code{GPGME_No_Data} if @var{cipher} does not contain any data to
1982 decrypt, @code{GPGME_Decryption_Failed} if @var{cipher} is not a valid
1983 cipher text, @code{GPGME_No_Passphrase} if the passphrase for the
1984 secret key could not be retrieved, and passes through any errors that
1985 are reported by the crypto engine support routines.
1986 @end deftypefun
1987
1988 @deftypefun GpgmeError gpgme_op_decrypt_verify (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{cipher}}, @w{GpgmeData @var{plain}})
1989 The function @code{gpgme_op_decrypt_verify_start} initiates a
1990 @code{gpgme_op_decrypt_verify} operation.  It can be completed by
1991 calling @code{gpgme_wait} on the context.  @xref{Waiting For
1992 Completion}.
1993
1994 The function returns @code{GPGME_No_Error} if the operation could be
1995 started successfully, @code{GPGME_Invalid_Value} if @var{ctx},
1996 @var{cipher}, @var{plain} or @var{r_stat} is not a valid pointer, and
1997 @code{GPGME_No_Data} if @var{cipher} does not contain any data to
1998 decrypt.
1999 @end deftypefun
2000
2001
2002 @node Sign
2003 @subsection Sign
2004 @cindex signature, creation
2005 @cindex sign
2006 @cindex cryptographic operation, signing
2007
2008 A signature can contain signatures by one or more keys.  The set of
2009 keys used to create a signatures is contained in a context, and is
2010 applied to all following signing operations in this context (until the
2011 set is changed).
2012
2013 @menu
2014 * Selecting Signers::             How to choose the keys to sign with.
2015 * Creating a Signature::          How to create a signature.
2016 @end menu
2017
2018
2019 @node Selecting Signers
2020 @subsubsection Selecting Signers
2021 @cindex signature, selecting signers
2022 @cindex signers, selecting
2023
2024 @deftypefun void gpgme_signers_clear (@w{GpgmeCtx @var{ctx}})
2025 The function @code{gpgme_signers_clear} releases a reference for each
2026 key on the signers list and removes the list of signers from the
2027 context @var{ctx}.
2028
2029 Every context starts with an empty list.
2030 @end deftypefun
2031
2032 @deftypefun GpgmeError gpgme_signers_add (@w{GpgmeCtx @var{ctx}}, @w{const GpgmeKey @var{key}})
2033 The function @code{gpgme_signers_add} adds the key @var{key} to the
2034 list of signers in the context @var{ctx}.
2035
2036 One reference for the key is consumed.
2037 @end deftypefun
2038
2039 @deftypefun GpgmeKey gpgme_signers_enum (@w{const GpgmeCtx @var{ctx}}, @w{int @var{seq}})
2040 The function @code{gpgme_signers_enum} returns the @var{seq}th key in
2041 the list of signers in the context @var{ctx}.  An additional reference
2042 is acquired for the user.
2043
2044 If @var{seq} is out of range, @code{NULL} is returned.
2045 @end deftypefun
2046
2047
2048 @node Creating a Signature
2049 @subsubsection Creating a Signature
2050
2051 @deftp {Data type} {enum GpgmeSigMode}
2052 @tindex GpgmeSigMode
2053 The @code{GpgmeSigMode} type is used to specify the desired type of a
2054 signature.  The following modes are available:
2055
2056 @table @code
2057 @item GPGME_SIG_MODE_NORMAL
2058 A normal signature is made, the output includes the plaintext and the
2059 signature.
2060
2061 @item GPGME_SIG_MODE_DETACH
2062 A detached signature is made.
2063
2064 @item GPGME_SIG_MODE_CLEAR
2065 A clear text signature is made.  The @acronym{ASCII} armor and text
2066 mode settings of the context are ignored.
2067 @end table
2068 @end deftp
2069
2070 @deftypefun GpgmeError gpgme_op_sign (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{plain}}, @w{GpgmeData @var{sig}}, @w{GpgmeSigMode @var{mode}})
2071 The function @code{gpgme_op_sign} creates a signature for the text in
2072 the data object @var{plain} and returns it in the data object
2073 @var{sig}.  The type of the signature created is determined by the
2074 @acronym{ASCII} armor and text mode attributes set for the context
2075 @var{ctx} and the requested signature mode @var{mode}.
2076
2077 More information about the signatures is available with
2078 @code{gpgme_get_op_info}.  @xref{Detailed Results}.
2079
2080 If an S/MIME signed message is created using the CMS crypto engine,
2081 the number of certificates to include in the message can be specified
2082 with @code{gpgme_set_include_certs}.  @xref{Included Certificates}.
2083
2084 The function returns @code{GPGME_No_Error} if the signature could be
2085 created successfully, @code{GPGME_Invalid_Value} if @var{ctx},
2086 @var{plain} or @var{sig} is not a valid pointer, @code{GPGME_No_Data}
2087 if the signature could not be created, @code{GPGME_No_Passphrase} if
2088 the passphrase for the secret key could not be retrieved, and passes
2089 through any errors that are reported by the crypto engine support
2090 routines.
2091 @end deftypefun
2092
2093 @deftypefun GpgmeError gpgme_op_sign (@w{GpgmeCtx @var{ctx}}, @w{GpgmeData @var{plain}}, @w{GpgmeData @var{sig}}, @w{GpgmeSigMode @var{mode}})
2094 The function @code{gpgme_op_sign_start} initiates a
2095 @code{gpgme_op_sign} operation.  It can be completed by calling
2096 @code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
2097
2098 The function returns @code{GPGME_No_Error} if the operation could be
2099 started successfully, and @code{GPGME_Invalid_Value} if @var{ctx},
2100 @var{plain} or @var{sig} is not a valid pointer.
2101 @end deftypefun
2102
2103
2104 @node Encrypt
2105 @subsection Encrypt
2106 @cindex encryption
2107 @cindex cryptographic operation, encryption
2108
2109 One plaintext can be encrypted for several recipients at the same
2110 time.  The list of recipients is created independently of any context,
2111 and then passed to the encryption operation.
2112
2113 @menu
2114 * Selecting Recipients::          How to choose the recipients.
2115 * Encrypting a Plaintext::        How to encrypt a plaintext.
2116 @end menu
2117
2118
2119 @node Selecting Recipients
2120 @subsubsection Selecting Recipients
2121 @cindex encryption, selecting recipients
2122 @cindex recipients
2123
2124 @deftp {Data type} GpgmeRecipients
2125 The @code{GpgmeRecipients} type is a handle for a set of recipients
2126 that can be used in an encryption process.
2127 @end deftp
2128
2129 @deftypefun GpgmeError gpgme_recipients_new (@w{GpgmeRecipients *@var{r_rset}})
2130 The function @code{gpgme_recipients_new} creates a new, empty set of
2131 recipients and returns a handle for it in @var{r_rset}.
2132
2133 The function returns @code{GPGME_No_Error} if the recipient set could
2134 be created successfully, and @code{GPGME_Out_Of_Core} if not enough
2135 memory was available.
2136 @end deftypefun
2137
2138 @deftypefun void gpgme_recipients_release (@w{GpgmeRecipients @var{rset}})
2139 The function @code{gpgme_recipients_release} destroys the set of
2140 recipients @var{rset} and releases all associated resources.
2141 @end deftypefun
2142
2143 @deftypefun GpgmeError gpgme_recipients_add_name (@w{GpgmeRecipients @var{rset}}, @w{const char *@var{name}})
2144 The function @code{gpgme_recipients_add_name} adds the recipient
2145 @var{name} to the set of recipients @var{rset}.  This is equivalent to
2146 @code{gpgme_recipients_add_name_with_validity} with a validity of
2147 @code{GPGME_VALIDITY_UNKNOWN}.
2148
2149 The function returns @code{GPGME_No_Error} if the recipient was added
2150 successfully, @code{GPGME_Invalid_Value} if @var{rset} or @var{name}
2151 is not a valid pointer, and @code{GPGME_Out_Of_Core} if not enough
2152 memory is available.
2153 @end deftypefun
2154
2155 @deftypefun GpgmeError gpgme_recipients_add_name_with_validity (@w{GpgmeRecipients @var{rset}}, @w{const char *@var{name}}, @w{GpgmeValidity @var{val}})
2156 The function @code{gpgme_recipients_add_name_with_validity} adds the
2157 recipient @var{name} with the validity @var{val} to the set of
2158 recipients @var{rset}.  If the validity is not known, the function
2159 @code{gpgme_recipients_add_name} can be used.
2160 @xref{Information About Keys}, for the possible values for @var{val}.
2161
2162 The function returns @code{GPGME_No_Error} if the recipient was added
2163 successfully, @code{GPGME_Invalid_Value} if @var{rset} or @var{name}
2164 is not a valid pointer, and @code{GPGME_Out_Of_Core} if not enough
2165 memory is available.
2166 @end deftypefun
2167
2168 @deftypefun {unsigned int} gpgme_recipients_count (@w{const @var{GpgmeRecipients rset}})
2169 The function @code{gpgme_recipients_count} returns the number of
2170 recipients in the set @var{rset}.
2171 @end deftypefun
2172
2173 @deftypefun GpgmeError gpgme_recipients_enum_open (@w{const GpgmeRecipients @var{rset}}, @w{void **@var{iter}})
2174 The function @code{gpgme_recipients_enum_open} creates a new iterator
2175 @var{iter} that can be used to walk through the set of recipients in
2176 @var{rset}, using @code{gpgme_recipients_enum_read}.
2177
2178 If the iterator is not needed anymore, it can be closed with
2179 @code{gpgme_recipients_enum_close}.
2180
2181 The function returns @code{GPGME_No_Error} if the enumerator was
2182 successfully created and @code{GPGME_Invalid_Value} if @var{rset} or
2183 @var{iter} is not a valid pointer.
2184 @end deftypefun
2185
2186 @deftypefun {const char *} gpgme_recipients_enum_read (@w{const GpgmeRecipients @var{rset}}, @w{void **@var{iter}})
2187 The function @code{gpgme_recipients_enum_read} returns a string
2188 containing the name of the next recipient in the set @var{rset} for
2189 the iterator @var{iter}.  The string is valid as long as @var{rset} is
2190 valid or the function is called the next time with the same recipient
2191 set and iterator, whatever is earlier.
2192 @end deftypefun
2193
2194 @deftypefun GpgmeError gpgme_recipients_enum_close (@w{const GpgmeRecipients @var{rset}}, @w{void **@var{iter}})
2195 The function @code{gpgme_recipients_enum_close} releases the iterator
2196 @var{iter} for the recipient set @var{rset}.
2197 @end deftypefun
2198
2199
2200 @node Encrypting a Plaintext
2201 @subsubsection Encrypting a Plaintext
2202
2203 @deftypefun GpgmeError gpgme_op_encrypt (@w{GpgmeCtx @var{ctx}}, @w{GpgmeRecipients @var{rset}}, @w{GpgmeData @var{plain}}, @w{GpgmeData @var{cipher}})
2204 The function @code{gpgme_op_crypt} encrypts the plaintext in the data
2205 object @var{plain} for the recipients @var{rset} and stores the
2206 ciphertext in the data object @var{cipher}.  The type of the
2207 ciphertext created is determined by the @acronym{ASCII} armor and text
2208 mode attributes set for the context @var{ctx}.
2209
2210 More information about the encrypted text is available with
2211 @code{gpgme_get_op_info}.  @xref{Detailed Results}.
2212
2213 The function returns @code{GPGME_No_Error} if the ciphertext could be
2214 created successfully, @code{GPGME_Invalid_Value} if @var{ctx},
2215 @var{rset}, @var{plain} or @var{cipher} is not a valid pointer,
2216 @code{GPGME_No_Recipient} if @var{rset} does not contain any
2217 valid recipients, @code{GPGME_No_Passphrase} if the passphrase for the
2218 secret key could not be retrieved, and passes through any errors that
2219 are reported by the crypto engine support routines.
2220 @end deftypefun
2221
2222 @deftypefun GpgmeError gpgme_op_encrypt_start (@w{GpgmeCtx @var{ctx}}, @w{GpgmeRecipients @var{rset}}, @w{GpgmeData @var{plain}}, @w{GpgmeData @var{cipher}})
2223 The function @code{gpgme_op_encrypt_start} initiates a
2224 @code{gpgme_op_encrypt} operation.  It can be completed by calling
2225 @code{gpgme_wait} on the context.  @xref{Waiting For Completion}.
2226
2227 The function returns @code{GPGME_No_Error} if the operation could be
2228 started successfully, @code{GPGME_Invalid_Value} if @var{ctx},
2229 @var{rset}, @var{plain} or @var{cipher} is not a valid pointer, and
2230 @code{GPGME_No_Recipient} if @var{rset} does not contain any valid
2231 recipients.
2232 @end deftypefun
2233
2234
2235 @node Detailed Results
2236 @subsection Detailed Results
2237 @cindex cryptographic operation, detailed results
2238
2239 @deftypefun {char *} gpgme_get_op_info (@w{GpgmeCtx @var{ctx}}, @w{int @var{reserved}})
2240 The function @code{gpgme_get_op_info} retrieves more information about
2241 the last crypto operation.
2242
2243 The function returns a string in the XML format.  The user has to
2244 release the string with @code{free}.
2245
2246 Here is a sample of the information that might be returned:
2247 @example
2248 <GnupgOperationInfo>
2249   <signature>
2250     <detached/> <!-- or cleartext or standard -->
2251     <algo>17</algo>
2252     <hashalgo>2</hashalgo>
2253     <micalg>pgp-sha1</micalg>
2254     <sigclass>01</sigclass>
2255     <created>9222222</created>
2256     <fpr>121212121212121212</fpr>
2257   </signature>
2258 </GnupgOperationInfo>
2259 @end example
2260
2261 Currently, the only operations that return additional information are
2262 encrypt and sign.  @xref{Encrypt}, @xref{Sign}.
2263
2264 The function returns a string or @code{NULL} if no such data is
2265 available.
2266 @end deftypefun
2267
2268
2269 @node Run Control
2270 @section Run Control
2271 @cindex run control
2272 @cindex cryptographic operation, running
2273
2274 Some basic support for running operations asynchronously is available
2275 in @acronym{GPGME}.  You can use it to set up a context completely up
2276 to initiating the desired operation, but delay performing it to a
2277 later point.
2278
2279 @menu
2280 * Waiting For Completion::        Waiting until an operation is completed.
2281 * Cancelling an Operation::       Interrupting a running operation.
2282 * Hooking Up Into Idle Time::     Doing something when nothing has to be done.
2283 @end menu
2284
2285
2286 @node Waiting For Completion
2287 @subsection Waiting For Completion
2288 @cindex cryptographic operation, wait for
2289 @cindex wait for completion
2290
2291 @deftypefun GpgmeCtx gpgme_wait (@w{GpgmeCtx @var{ctx}}, @w{GpgmeError *@var{status}}, @w{int @var{hang}})
2292 The function @code{gpgme_wait} does continue the pending operation
2293 within the context @var{ctx}.  In particular, it ensures the data
2294 exchange between @acronym{GPGME} and the crypto backend and watches
2295 over the run time status of the backend process.
2296
2297 If @var{hang} is true, the function does not return until the
2298 operation is completed or cancelled.  Otherwise the function will not
2299 block for a long time.
2300
2301 The error status of the finished operation is returned in
2302 @var{status}.
2303
2304 The @var{ctx} argument can be @code{NULL}.  In that case,
2305 @code{gpgme_wait} waits for any context to complete its operation.
2306
2307 The function returns the @var{ctx} of the context which has finished
2308 the operation.
2309 @end deftypefun
2310
2311
2312 @node Cancelling an Operation
2313 @subsection Cancelling an Operation
2314 @cindex cancellation
2315 @cindex cryptographic operation, cancel
2316
2317 @deftypefun void gpgme_cancel (@w{GpgmeCtx @var{ctx}})
2318 The function @code{gpgme_cancel} tries to cancel the pending
2319 operation.  The function @code{gpgme_wait} might notice the
2320 cancellation flag and return.  It is currently not guaranteed to work
2321 under all circumstances.  It's current primary purpose is to prevent
2322 asking for a passphrase again in the passphrase callback.
2323 @end deftypefun
2324
2325
2326 @node Hooking Up Into Idle Time
2327 @subsection Hooking Up Into Idle Time
2328 @cindex idle time
2329 @cindex idle function
2330
2331 @deftp {Data type} {void (*GpgmeIdleFunc) (void)}
2332 @tindex GpgmeIdleFunc
2333 The @code{GpgmeIdleFunc} type is the type of functions usable as
2334 an idle function that can be registered with @code{gpgme_register_idle}.
2335 @end deftp
2336
2337 @deftypefun GpgmeIdleFunc gpgme_register_idle (@w{GpgmeIdleFunc @var{idle}})
2338 The function @code{gpgme_register_idle} can be used to register
2339 @var{idle} as the idle function.
2340
2341 @var{idle} will be called whenever @acronym{GPGME} thinks that it is
2342 idle and time can better be spent elsewhere.  Setting @var{idle} to
2343 @code{NULL} disables use of the idle function (this is the default).
2344
2345 The function returns the old idle function, or @code{NULL} if none was
2346 registered yet.
2347 @end deftypefun
2348
2349
2350 @include gpl.texi
2351
2352
2353 @include fdl.texi
2354
2355
2356 @node Concept Index
2357 @unnumbered Concept Index
2358
2359 @printindex cp
2360
2361
2362 @node Function and Data Index
2363 @unnumbered Function and Data Index
2364
2365 @printindex fn
2366
2367
2368 @summarycontents
2369 @contents
2370 @bye
2371
2372 @c  LocalWords:  GPGME gpgme