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