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