doc/
[gpgme.git] / src / gpgme.h.in
1 /* gpgme.h - Public interface to GnuPG Made Easy.                   -*- c -*-
2    Copyright (C) 2000 Werner Koch (dd9jn)
3    Copyright (C) 2001, 2002, 2003, 2004, 2005, 2007, 2009 g10 Code GmbH
4
5    This file is part of GPGME.
6  
7    GPGME is free software; you can redistribute it and/or modify it
8    under the terms of the GNU Lesser General Public License as
9    published by the Free Software Foundation; either version 2.1 of
10    the License, or (at your option) any later version.
11    
12    GPGME is distributed in the hope that it will be useful, but
13    WITHOUT ANY WARRANTY; without even the implied warranty of
14    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
15    Lesser General Public License for more details.
16    
17    You should have received a copy of the GNU Lesser General Public
18    License along with this program; if not, see <http://www.gnu.org/licenses/>.
19  
20    File: @configure_input@  */
21
22 #ifndef GPGME_H
23 #define GPGME_H
24
25 #ifdef __GNUC__
26 #define _GPGME_INLINE __inline__
27 #elif __STDC_VERSION__ >= 199901L
28 #define _GPGME_INLINE inline
29 #else
30 #define _GPGME_INLINE
31 #endif
32
33 /* Include stdio.h for the FILE type definition.  */
34 #include <stdio.h>
35
36 #ifdef _MSC_VER
37   typedef long off_t;
38   typedef long ssize_t;
39 #else
40 # include <sys/types.h>
41 #endif
42
43 #include <gpg-error.h>
44
45 #ifdef __cplusplus
46 extern "C" {
47 #if 0 /* just to make Emacs auto-indent happy */
48 }
49 #endif
50 #endif /* __cplusplus */
51
52
53 \f
54 /* Check for compiler features.  */
55 #if __GNUC__
56 #define _GPGME_GCC_VERSION (__GNUC__ * 10000 \
57                             + __GNUC_MINOR__ * 100 \
58                             + __GNUC_PATCHLEVEL__)
59
60 #if _GPGME_GCC_VERSION > 30100
61 #define _GPGME_DEPRECATED       __attribute__ ((__deprecated__))
62 #endif
63 #endif
64
65 #ifndef _GPGME_DEPRECATED
66 #define _GPGME_DEPRECATED
67 #endif
68
69 \f
70 /* The version of this header should match the one of the library.  Do
71    not use this symbol in your application, use gpgme_check_version
72    instead.  The purpose of this macro is to let autoconf (using the
73    AM_PATH_GPGME macro) check that this header matches the installed
74    library.  */
75 #define GPGME_VERSION "@PACKAGE_VERSION@"
76
77 /* Check for a matching _FILE_OFFSET_BITS definition.  */
78 #if @NEED__FILE_OFFSET_BITS@
79 #ifndef _FILE_OFFSET_BITS
80 #error GPGME was compiled with _FILE_OFFSET_BITS = @NEED__FILE_OFFSET_BITS@, please see the section "Largefile support (LFS)" in the GPGME manual.
81 #else
82 #if (_FILE_OFFSET_BITS) != (@NEED__FILE_OFFSET_BITS@)
83 #error GPGME was compiled with a different value for _FILE_OFFSET_BITS, namely @NEED__FILE_OFFSET_BITS@, please see the section "Largefile support (LFS)" in the GPGME manual.
84 #endif
85 #endif
86 #endif
87
88
89 \f
90 /* Some opaque data types used by GPGME.  */
91
92 /* The context holds some global state and configration options, as
93    well as the results of a crypto operation.  */
94 struct gpgme_context;
95 typedef struct gpgme_context *gpgme_ctx_t;
96
97 /* The data object is used by GPGME to exchange arbitrary data.  */
98 struct gpgme_data;
99 typedef struct gpgme_data *gpgme_data_t;
100
101 \f
102 /* Wrappers for the libgpg-error library.  */
103
104 typedef gpg_error_t gpgme_error_t;
105 typedef gpg_err_code_t gpgme_err_code_t;
106 typedef gpg_err_source_t gpgme_err_source_t;
107
108
109 static _GPGME_INLINE gpgme_error_t
110 gpgme_err_make (gpgme_err_source_t source, gpgme_err_code_t code)
111 {
112   return gpg_err_make (source, code);
113 }
114
115
116 /* The user can define GPGME_ERR_SOURCE_DEFAULT before including this
117    file to specify a default source for gpgme_error.  */
118 #ifndef GPGME_ERR_SOURCE_DEFAULT
119 #define GPGME_ERR_SOURCE_DEFAULT  GPG_ERR_SOURCE_USER_1
120 #endif
121
122 static _GPGME_INLINE gpgme_error_t
123 gpgme_error (gpgme_err_code_t code)
124 {
125   return gpgme_err_make (GPGME_ERR_SOURCE_DEFAULT, code);
126 }
127
128
129 static _GPGME_INLINE gpgme_err_code_t
130 gpgme_err_code (gpgme_error_t err)
131 {
132   return gpg_err_code (err);
133 }
134
135
136 static _GPGME_INLINE gpgme_err_source_t
137 gpgme_err_source (gpgme_error_t err)
138 {
139   return gpg_err_source (err);
140 }
141
142
143 /* Return a pointer to a string containing a description of the error
144    code in the error value ERR.  This function is not thread safe.  */
145 const char *gpgme_strerror (gpgme_error_t err);
146
147 /* Return the error string for ERR in the user-supplied buffer BUF of
148    size BUFLEN.  This function is, in contrast to gpg_strerror,
149    thread-safe if a thread-safe strerror_r() function is provided by
150    the system.  If the function succeeds, 0 is returned and BUF
151    contains the string describing the error.  If the buffer was not
152    large enough, ERANGE is returned and BUF contains as much of the
153    beginning of the error string as fits into the buffer.  */
154 int gpgme_strerror_r (gpg_error_t err, char *buf, size_t buflen);
155
156
157 /* Return a pointer to a string containing a description of the error
158    source in the error value ERR.  */
159 const char *gpgme_strsource (gpgme_error_t err);
160
161
162 /* Retrieve the error code for the system error ERR.  This returns
163    GPG_ERR_UNKNOWN_ERRNO if the system error is not mapped (report
164    this).  */
165 gpgme_err_code_t gpgme_err_code_from_errno (int err);
166
167
168 /* Retrieve the system error for the error code CODE.  This returns 0
169    if CODE is not a system error code.  */
170 int gpgme_err_code_to_errno (gpgme_err_code_t code);
171
172   
173 /* Return an error value with the error source SOURCE and the system
174    error ERR.  */
175 gpgme_error_t gpgme_err_make_from_errno (gpgme_err_source_t source, int err);
176
177
178 /* Return an error value with the system error ERR.  */
179 gpgme_err_code_t gpgme_error_from_errno (int err);
180
181 \f
182 /* The possible encoding mode of gpgme_data_t objects.  */
183 typedef enum
184   {
185     GPGME_DATA_ENCODING_NONE   = 0,     /* Not specified.  */
186     GPGME_DATA_ENCODING_BINARY = 1,
187     GPGME_DATA_ENCODING_BASE64 = 2,
188     GPGME_DATA_ENCODING_ARMOR  = 3      /* Either PEM or OpenPGP Armor.  */
189   }
190 gpgme_data_encoding_t;
191
192 \f
193 /* Public key algorithms from libgcrypt.  */
194 typedef enum
195   {
196     GPGME_PK_RSA   = 1,
197     GPGME_PK_RSA_E = 2,
198     GPGME_PK_RSA_S = 3,
199     GPGME_PK_ELG_E = 16,
200     GPGME_PK_DSA   = 17,
201     GPGME_PK_ELG   = 20
202   }
203 gpgme_pubkey_algo_t;
204
205
206 /* Hash algorithms from libgcrypt.  */
207 typedef enum
208   {
209     GPGME_MD_NONE          = 0,  
210     GPGME_MD_MD5           = 1,
211     GPGME_MD_SHA1          = 2,
212     GPGME_MD_RMD160        = 3,
213     GPGME_MD_MD2           = 5,
214     GPGME_MD_TIGER         = 6,   /* TIGER/192. */
215     GPGME_MD_HAVAL         = 7,   /* HAVAL, 5 pass, 160 bit. */
216     GPGME_MD_SHA256        = 8,
217     GPGME_MD_SHA384        = 9,
218     GPGME_MD_SHA512        = 10,
219     GPGME_MD_MD4           = 301,
220     GPGME_MD_CRC32         = 302,
221     GPGME_MD_CRC32_RFC1510 = 303,
222     GPGME_MD_CRC24_RFC2440 = 304
223   }
224 gpgme_hash_algo_t;
225
226 \f
227 /* The possible signature stati.  Deprecated, use error value in sig
228    status.  */
229 typedef enum
230   {
231     GPGME_SIG_STAT_NONE  = 0,
232     GPGME_SIG_STAT_GOOD  = 1,
233     GPGME_SIG_STAT_BAD   = 2,
234     GPGME_SIG_STAT_NOKEY = 3,
235     GPGME_SIG_STAT_NOSIG = 4,
236     GPGME_SIG_STAT_ERROR = 5,
237     GPGME_SIG_STAT_DIFF  = 6,
238     GPGME_SIG_STAT_GOOD_EXP = 7,
239     GPGME_SIG_STAT_GOOD_EXPKEY = 8
240   }
241 _gpgme_sig_stat_t;
242 typedef _gpgme_sig_stat_t gpgme_sig_stat_t _GPGME_DEPRECATED;
243
244
245 /* The available signature modes.  */
246 typedef enum
247   {
248     GPGME_SIG_MODE_NORMAL = 0,
249     GPGME_SIG_MODE_DETACH = 1,
250     GPGME_SIG_MODE_CLEAR  = 2
251   }
252 gpgme_sig_mode_t;
253
254 \f
255 /* The available key and signature attributes.  Deprecated, use the
256    individual result structures instead.  */
257 typedef enum
258   {
259     GPGME_ATTR_KEYID        = 1,
260     GPGME_ATTR_FPR          = 2,
261     GPGME_ATTR_ALGO         = 3,
262     GPGME_ATTR_LEN          = 4,
263     GPGME_ATTR_CREATED      = 5,
264     GPGME_ATTR_EXPIRE       = 6,
265     GPGME_ATTR_OTRUST       = 7,
266     GPGME_ATTR_USERID       = 8,
267     GPGME_ATTR_NAME         = 9,
268     GPGME_ATTR_EMAIL        = 10,
269     GPGME_ATTR_COMMENT      = 11,
270     GPGME_ATTR_VALIDITY     = 12,
271     GPGME_ATTR_LEVEL        = 13,
272     GPGME_ATTR_TYPE         = 14,
273     GPGME_ATTR_IS_SECRET    = 15,
274     GPGME_ATTR_KEY_REVOKED  = 16,
275     GPGME_ATTR_KEY_INVALID  = 17,
276     GPGME_ATTR_UID_REVOKED  = 18,
277     GPGME_ATTR_UID_INVALID  = 19,
278     GPGME_ATTR_KEY_CAPS     = 20,
279     GPGME_ATTR_CAN_ENCRYPT  = 21,
280     GPGME_ATTR_CAN_SIGN     = 22,
281     GPGME_ATTR_CAN_CERTIFY  = 23,
282     GPGME_ATTR_KEY_EXPIRED  = 24,
283     GPGME_ATTR_KEY_DISABLED = 25,
284     GPGME_ATTR_SERIAL       = 26,
285     GPGME_ATTR_ISSUER       = 27,
286     GPGME_ATTR_CHAINID      = 28,
287     GPGME_ATTR_SIG_STATUS   = 29,
288     GPGME_ATTR_ERRTOK       = 30,
289     GPGME_ATTR_SIG_SUMMARY  = 31,
290     GPGME_ATTR_SIG_CLASS    = 32
291   }
292 _gpgme_attr_t;
293 typedef _gpgme_attr_t gpgme_attr_t _GPGME_DEPRECATED;
294
295 \f
296 /* The available validities for a trust item or key.  */
297 typedef enum
298   {
299     GPGME_VALIDITY_UNKNOWN   = 0,
300     GPGME_VALIDITY_UNDEFINED = 1,
301     GPGME_VALIDITY_NEVER     = 2,
302     GPGME_VALIDITY_MARGINAL  = 3,
303     GPGME_VALIDITY_FULL      = 4,
304     GPGME_VALIDITY_ULTIMATE  = 5
305   }
306 gpgme_validity_t;
307
308 \f
309 /* The available protocols.  */
310 typedef enum
311   {
312     GPGME_PROTOCOL_OpenPGP = 0,  /* The default mode.  */
313     GPGME_PROTOCOL_CMS     = 1,
314     GPGME_PROTOCOL_GPGCONF = 2,  /* Special code for gpgconf.  */
315     GPGME_PROTOCOL_ASSUAN  = 3,  /* Low-level access to an Assuan server.  */
316     GPGME_PROTOCOL_UNKNOWN = 255
317   }
318 gpgme_protocol_t;
319
320 \f
321 /* The available keylist mode flags.  */
322 #define GPGME_KEYLIST_MODE_LOCAL                1
323 #define GPGME_KEYLIST_MODE_EXTERN               2
324 #define GPGME_KEYLIST_MODE_SIGS                 4
325 #define GPGME_KEYLIST_MODE_SIG_NOTATIONS        8
326 #define GPGME_KEYLIST_MODE_EPHEMERAL            128
327 #define GPGME_KEYLIST_MODE_VALIDATE             256
328
329 typedef unsigned int gpgme_keylist_mode_t;
330
331 \f
332 /* Flags for the audit log functions.  */
333 #define GPGME_AUDITLOG_HTML      1 
334 #define GPGME_AUDITLOG_WITH_HELP 128
335
336 \f
337 /* Signature notations.  */
338
339 /* The available signature notation flags.  */
340 #define GPGME_SIG_NOTATION_HUMAN_READABLE       1
341 #define GPGME_SIG_NOTATION_CRITICAL             2
342
343 typedef unsigned int gpgme_sig_notation_flags_t;
344
345 struct _gpgme_sig_notation
346 {
347   struct _gpgme_sig_notation *next;
348
349   /* If NAME is a null pointer, then VALUE contains a policy URL
350      rather than a notation.  */
351   char *name;
352
353   /* The value of the notation data.  */
354   char *value;
355
356   /* The length of the name of the notation data.  */
357   int name_len;
358
359   /* The length of the value of the notation data.  */
360   int value_len;
361
362   /* The accumulated flags.  */
363   gpgme_sig_notation_flags_t flags;
364
365   /* Notation data is human-readable.  */
366   unsigned int human_readable : 1;
367
368   /* Notation data is critical.  */
369   unsigned int critical : 1;
370
371   /* Internal to GPGME, do not use.  */
372   int _unused : 30;
373 };
374 typedef struct _gpgme_sig_notation *gpgme_sig_notation_t;
375
376 \f
377 /* The possible stati for the edit operation.  */
378 typedef enum
379   {
380     GPGME_STATUS_EOF = 0,
381     /* mkstatus processing starts here */
382     GPGME_STATUS_ENTER = 1,
383     GPGME_STATUS_LEAVE = 2,
384     GPGME_STATUS_ABORT = 3,
385
386     GPGME_STATUS_GOODSIG = 4,
387     GPGME_STATUS_BADSIG = 5,
388     GPGME_STATUS_ERRSIG = 6,
389
390     GPGME_STATUS_BADARMOR = 7,
391
392     GPGME_STATUS_RSA_OR_IDEA = 8,
393     GPGME_STATUS_KEYEXPIRED = 9,
394     GPGME_STATUS_KEYREVOKED = 10,
395
396     GPGME_STATUS_TRUST_UNDEFINED = 11,
397     GPGME_STATUS_TRUST_NEVER = 12,
398     GPGME_STATUS_TRUST_MARGINAL = 13,
399     GPGME_STATUS_TRUST_FULLY = 14,
400     GPGME_STATUS_TRUST_ULTIMATE = 15,
401
402     GPGME_STATUS_SHM_INFO = 16,
403     GPGME_STATUS_SHM_GET = 17,
404     GPGME_STATUS_SHM_GET_BOOL = 18,
405     GPGME_STATUS_SHM_GET_HIDDEN = 19,
406
407     GPGME_STATUS_NEED_PASSPHRASE = 20,
408     GPGME_STATUS_VALIDSIG = 21,
409     GPGME_STATUS_SIG_ID = 22,
410     GPGME_STATUS_ENC_TO = 23,
411     GPGME_STATUS_NODATA = 24,
412     GPGME_STATUS_BAD_PASSPHRASE = 25,
413     GPGME_STATUS_NO_PUBKEY = 26,
414     GPGME_STATUS_NO_SECKEY = 27,
415     GPGME_STATUS_NEED_PASSPHRASE_SYM = 28,
416     GPGME_STATUS_DECRYPTION_FAILED = 29,
417     GPGME_STATUS_DECRYPTION_OKAY = 30,
418     GPGME_STATUS_MISSING_PASSPHRASE = 31,
419     GPGME_STATUS_GOOD_PASSPHRASE = 32,
420     GPGME_STATUS_GOODMDC = 33,
421     GPGME_STATUS_BADMDC = 34,
422     GPGME_STATUS_ERRMDC = 35,
423     GPGME_STATUS_IMPORTED = 36,
424     GPGME_STATUS_IMPORT_OK = 37,
425     GPGME_STATUS_IMPORT_PROBLEM = 38,
426     GPGME_STATUS_IMPORT_RES = 39,
427     GPGME_STATUS_FILE_START = 40,
428     GPGME_STATUS_FILE_DONE = 41,
429     GPGME_STATUS_FILE_ERROR = 42,
430
431     GPGME_STATUS_BEGIN_DECRYPTION = 43,
432     GPGME_STATUS_END_DECRYPTION = 44,
433     GPGME_STATUS_BEGIN_ENCRYPTION = 45,
434     GPGME_STATUS_END_ENCRYPTION = 46,
435
436     GPGME_STATUS_DELETE_PROBLEM = 47,
437     GPGME_STATUS_GET_BOOL = 48,
438     GPGME_STATUS_GET_LINE = 49,
439     GPGME_STATUS_GET_HIDDEN = 50,
440     GPGME_STATUS_GOT_IT = 51,
441     GPGME_STATUS_PROGRESS = 52,
442     GPGME_STATUS_SIG_CREATED = 53,
443     GPGME_STATUS_SESSION_KEY = 54,
444     GPGME_STATUS_NOTATION_NAME = 55,
445     GPGME_STATUS_NOTATION_DATA = 56,
446     GPGME_STATUS_POLICY_URL = 57,
447     GPGME_STATUS_BEGIN_STREAM = 58,
448     GPGME_STATUS_END_STREAM = 59,
449     GPGME_STATUS_KEY_CREATED = 60,
450     GPGME_STATUS_USERID_HINT = 61,
451     GPGME_STATUS_UNEXPECTED = 62,
452     GPGME_STATUS_INV_RECP = 63,
453     GPGME_STATUS_NO_RECP = 64,
454     GPGME_STATUS_ALREADY_SIGNED = 65,
455     GPGME_STATUS_SIGEXPIRED = 66,
456     GPGME_STATUS_EXPSIG = 67,
457     GPGME_STATUS_EXPKEYSIG = 68,
458     GPGME_STATUS_TRUNCATED = 69,
459     GPGME_STATUS_ERROR = 70,
460     GPGME_STATUS_NEWSIG = 71,
461     GPGME_STATUS_REVKEYSIG = 72,
462     GPGME_STATUS_SIG_SUBPACKET = 73,
463     GPGME_STATUS_NEED_PASSPHRASE_PIN = 74,
464     GPGME_STATUS_SC_OP_FAILURE = 75,
465     GPGME_STATUS_SC_OP_SUCCESS = 76,
466     GPGME_STATUS_CARDCTRL = 77,
467     GPGME_STATUS_BACKUP_KEY_CREATED = 78,
468     GPGME_STATUS_PKA_TRUST_BAD = 79,
469     GPGME_STATUS_PKA_TRUST_GOOD = 80,
470
471     GPGME_STATUS_PLAINTEXT = 81
472   }
473 gpgme_status_code_t;
474
475 \f
476 /* The engine information structure.  */
477 struct _gpgme_engine_info
478 {
479   struct _gpgme_engine_info *next;
480
481   /* The protocol ID.  */
482   gpgme_protocol_t protocol;
483
484   /* The file name of the engine binary.  */
485   char *file_name;
486   
487   /* The version string of the installed engine.  */
488   char *version;
489
490   /* The minimum version required for GPGME.  */
491   const char *req_version;
492
493   /* The home directory used, or NULL if default.  */
494   char *home_dir;
495 };
496 typedef struct _gpgme_engine_info *gpgme_engine_info_t;
497
498 \f
499 /* A subkey from a key.  */
500 struct _gpgme_subkey
501 {
502   struct _gpgme_subkey *next;
503
504   /* True if subkey is revoked.  */
505   unsigned int revoked : 1;
506
507   /* True if subkey is expired.  */
508   unsigned int expired : 1;
509
510   /* True if subkey is disabled.  */
511   unsigned int disabled : 1;
512
513   /* True if subkey is invalid.  */
514   unsigned int invalid : 1;
515
516   /* True if subkey can be used for encryption.  */
517   unsigned int can_encrypt : 1;
518
519   /* True if subkey can be used for signing.  */
520   unsigned int can_sign : 1;
521
522   /* True if subkey can be used for certification.  */
523   unsigned int can_certify : 1;
524
525   /* True if subkey is secret.  */
526   unsigned int secret : 1;
527
528   /* True if subkey can be used for authentication.  */
529   unsigned int can_authenticate : 1;
530
531   /* True if subkey is qualified for signatures according to German law.  */
532   unsigned int is_qualified : 1;
533
534   /* True if the secret key is stored on a smart card.  */
535   unsigned int is_cardkey : 1;
536
537   /* Internal to GPGME, do not use.  */
538   unsigned int _unused : 21;
539   
540   /* Public key algorithm supported by this subkey.  */
541   gpgme_pubkey_algo_t pubkey_algo;
542
543   /* Length of the subkey.  */
544   unsigned int length;
545
546   /* The key ID of the subkey.  */
547   char *keyid;
548
549   /* Internal to GPGME, do not use.  */
550   char _keyid[16 + 1];
551
552   /* The fingerprint of the subkey in hex digit form.  */
553   char *fpr;
554
555   /* The creation timestamp, -1 if invalid, 0 if not available.  */
556   long int timestamp;
557
558   /* The expiration timestamp, 0 if the subkey does not expire.  */
559   long int expires;
560
561   /* The serial number of a smart card holding this key or NULL.  */
562   char *card_number;
563 };
564 typedef struct _gpgme_subkey *gpgme_subkey_t;
565
566
567 /* A signature on a user ID.  */
568 struct _gpgme_key_sig
569 {
570   struct _gpgme_key_sig *next;
571
572   /* True if the signature is a revocation signature.  */
573   unsigned int revoked : 1;
574
575   /* True if the signature is expired.  */
576   unsigned int expired : 1;
577
578   /* True if the signature is invalid.  */
579   unsigned int invalid : 1;
580
581   /* True if the signature should be exported.  */
582   unsigned int exportable : 1;
583
584   /* Internal to GPGME, do not use.  */
585   unsigned int _unused : 28;
586
587   /* The public key algorithm used to create the signature.  */
588   gpgme_pubkey_algo_t pubkey_algo;
589
590   /* The key ID of key used to create the signature.  */
591   char *keyid;
592
593   /* Internal to GPGME, do not use.  */
594   char _keyid[16 + 1];
595
596   /* The creation timestamp, -1 if invalid, 0 if not available.  */
597   long int timestamp;
598
599   /* The expiration timestamp, 0 if the subkey does not expire.  */
600   long int expires;
601
602   /* Same as in gpgme_signature_t.  */
603   gpgme_error_t status;
604
605 #ifdef __cplusplus
606   unsigned int _obsolete_class _GPGME_DEPRECATED;
607 #else
608   /* Must be set to SIG_CLASS below.  */
609   unsigned int class _GPGME_DEPRECATED;
610 #endif
611
612   /* The user ID string.  */
613   char *uid;
614
615   /* The name part of the user ID.  */
616   char *name;
617
618   /* The email part of the user ID.  */
619   char *email;
620
621   /* The comment part of the user ID.  */
622   char *comment;
623
624   /* Crypto backend specific signature class.  */
625   unsigned int sig_class;
626
627   /* Notation data and policy URLs.  */
628   gpgme_sig_notation_t notations;
629
630   /* Internal to GPGME, do not use.  */
631   gpgme_sig_notation_t _last_notation;
632 };
633 typedef struct _gpgme_key_sig *gpgme_key_sig_t;
634
635
636 /* An user ID from a key.  */
637 struct _gpgme_user_id
638 {
639   struct _gpgme_user_id *next;
640
641   /* True if the user ID is revoked.  */
642   unsigned int revoked : 1;
643
644   /* True if the user ID is invalid.  */
645   unsigned int invalid : 1;
646
647   /* Internal to GPGME, do not use.  */
648   unsigned int _unused : 30;
649
650   /* The validity of the user ID.  */
651   gpgme_validity_t validity; 
652
653   /* The user ID string.  */
654   char *uid;
655
656   /* The name part of the user ID.  */
657   char *name;
658
659   /* The email part of the user ID.  */
660   char *email;
661
662   /* The comment part of the user ID.  */
663   char *comment;
664
665   /* The signatures of the user ID.  */
666   gpgme_key_sig_t signatures;
667
668   /* Internal to GPGME, do not use.  */
669   gpgme_key_sig_t _last_keysig;
670 };
671 typedef struct _gpgme_user_id *gpgme_user_id_t;
672
673
674 /* A key from the keyring.  */
675 struct _gpgme_key
676 {
677   /* Internal to GPGME, do not use.  */
678   unsigned int _refs;
679
680   /* True if key is revoked.  */
681   unsigned int revoked : 1;
682
683   /* True if key is expired.  */
684   unsigned int expired : 1;
685
686   /* True if key is disabled.  */
687   unsigned int disabled : 1;
688
689   /* True if key is invalid.  */
690   unsigned int invalid : 1;
691
692   /* True if key can be used for encryption.  */
693   unsigned int can_encrypt : 1;
694
695   /* True if key can be used for signing.  */
696   unsigned int can_sign : 1;
697
698   /* True if key can be used for certification.  */
699   unsigned int can_certify : 1;
700
701   /* True if key is secret.  */
702   unsigned int secret : 1;
703
704   /* True if key can be used for authentication.  */
705   unsigned int can_authenticate : 1;
706
707   /* True if subkey is qualified for signatures according to German law.  */
708   unsigned int is_qualified : 1;
709
710   /* Internal to GPGME, do not use.  */
711   unsigned int _unused : 22;
712
713   /* This is the protocol supported by this key.  */
714   gpgme_protocol_t protocol;
715
716   /* If protocol is GPGME_PROTOCOL_CMS, this string contains the
717      issuer serial.  */
718   char *issuer_serial;
719
720   /* If protocol is GPGME_PROTOCOL_CMS, this string contains the
721      issuer name.  */
722   char *issuer_name;
723
724   /* If protocol is GPGME_PROTOCOL_CMS, this string contains the chain
725      ID.  */
726   char *chain_id;
727
728   /* If protocol is GPGME_PROTOCOL_OpenPGP, this field contains the
729      owner trust.  */
730   gpgme_validity_t owner_trust;
731
732   /* The subkeys of the key.  */
733   gpgme_subkey_t subkeys;
734
735   /* The user IDs of the key.  */
736   gpgme_user_id_t uids;
737
738   /* Internal to GPGME, do not use.  */
739   gpgme_subkey_t _last_subkey;
740
741   /* Internal to GPGME, do not use.  */
742   gpgme_user_id_t _last_uid;
743
744   /* The keylist mode that was active when listing the key.  */
745   gpgme_keylist_mode_t keylist_mode;
746 };
747 typedef struct _gpgme_key *gpgme_key_t;
748
749
750 \f
751 /* Types for callback functions.  */
752
753 /* Request a passphrase from the user.  */
754 typedef gpgme_error_t (*gpgme_passphrase_cb_t) (void *hook,
755                                                 const char *uid_hint,
756                                                 const char *passphrase_info,
757                                                 int prev_was_bad, int fd);
758
759 /* Inform the user about progress made.  */
760 typedef void (*gpgme_progress_cb_t) (void *opaque, const char *what,
761                                      int type, int current, int total);
762
763 /* Interact with the user about an edit operation.  */
764 typedef gpgme_error_t (*gpgme_edit_cb_t) (void *opaque,
765                                           gpgme_status_code_t status,
766                                           const char *args, int fd);
767
768
769
770 \f
771 /* Context management functions.  */
772
773 /* Create a new context and return it in CTX.  */
774 gpgme_error_t gpgme_new (gpgme_ctx_t *ctx);
775
776 /* Release the context CTX.  */
777 void gpgme_release (gpgme_ctx_t ctx);
778
779 /* Set the protocol to be used by CTX to PROTO.  */
780 gpgme_error_t gpgme_set_protocol (gpgme_ctx_t ctx, gpgme_protocol_t proto);
781
782 /* Get the protocol used with CTX */
783 gpgme_protocol_t gpgme_get_protocol (gpgme_ctx_t ctx);
784
785 /* Get the string describing protocol PROTO, or NULL if invalid.  */
786 const char *gpgme_get_protocol_name (gpgme_protocol_t proto);
787
788 /* If YES is non-zero, enable armor mode in CTX, disable it otherwise.  */
789 void gpgme_set_armor (gpgme_ctx_t ctx, int yes);
790
791 /* Return non-zero if armor mode is set in CTX.  */
792 int gpgme_get_armor (gpgme_ctx_t ctx);
793
794 /* If YES is non-zero, enable text mode in CTX, disable it otherwise.  */
795 void gpgme_set_textmode (gpgme_ctx_t ctx, int yes);
796
797 /* Return non-zero if text mode is set in CTX.  */
798 int gpgme_get_textmode (gpgme_ctx_t ctx);
799
800 /* Use whatever the default of the backend crypto engine is.  */
801 #define GPGME_INCLUDE_CERTS_DEFAULT     -256
802
803 /* Include up to NR_OF_CERTS certificates in an S/MIME message.  */
804 void gpgme_set_include_certs (gpgme_ctx_t ctx, int nr_of_certs);
805
806 /* Return the number of certs to include in an S/MIME message.  */
807 int gpgme_get_include_certs (gpgme_ctx_t ctx);
808
809 /* Set keylist mode in CTX to MODE.  */
810 gpgme_error_t gpgme_set_keylist_mode (gpgme_ctx_t ctx,
811                                       gpgme_keylist_mode_t mode);
812
813 /* Get keylist mode in CTX.  */
814 gpgme_keylist_mode_t gpgme_get_keylist_mode (gpgme_ctx_t ctx);
815
816 /* Set the passphrase callback function in CTX to CB.  HOOK_VALUE is
817    passed as first argument to the passphrase callback function.  */
818 void gpgme_set_passphrase_cb (gpgme_ctx_t ctx,
819                               gpgme_passphrase_cb_t cb, void *hook_value);
820
821 /* Get the current passphrase callback function in *CB and the current
822    hook value in *HOOK_VALUE.  */
823 void gpgme_get_passphrase_cb (gpgme_ctx_t ctx, gpgme_passphrase_cb_t *cb,
824                               void **hook_value);
825
826 /* Set the progress callback function in CTX to CB.  HOOK_VALUE is
827    passed as first argument to the progress callback function.  */
828 void gpgme_set_progress_cb (gpgme_ctx_t c, gpgme_progress_cb_t cb,
829                             void *hook_value);
830
831 /* Get the current progress callback function in *CB and the current
832    hook value in *HOOK_VALUE.  */
833 void gpgme_get_progress_cb (gpgme_ctx_t ctx, gpgme_progress_cb_t *cb,
834                             void **hook_value);
835
836 /* This function sets the locale for the context CTX, or the default
837    locale if CTX is a null pointer.  */
838 gpgme_error_t gpgme_set_locale (gpgme_ctx_t ctx, int category,
839                                 const char *value);
840
841 /* Get the information about the configured engines.  A pointer to the
842    first engine in the statically allocated linked list is returned.
843    The returned data is valid until the next gpgme_ctx_set_engine_info.  */
844 gpgme_engine_info_t gpgme_ctx_get_engine_info (gpgme_ctx_t ctx);
845
846 /* Set the engine info for the context CTX, protocol PROTO, to the
847    file name FILE_NAME and the home directory HOME_DIR.  */
848 gpgme_error_t gpgme_ctx_set_engine_info (gpgme_ctx_t ctx,
849                                          gpgme_protocol_t proto,
850                                          const char *file_name,
851                                          const char *home_dir);
852
853 \f
854 /* Return a statically allocated string with the name of the public
855    key algorithm ALGO, or NULL if that name is not known.  */
856 const char *gpgme_pubkey_algo_name (gpgme_pubkey_algo_t algo);
857
858 /* Return a statically allocated string with the name of the hash
859    algorithm ALGO, or NULL if that name is not known.  */
860 const char *gpgme_hash_algo_name (gpgme_hash_algo_t algo);
861
862 \f
863 /* Delete all signers from CTX.  */
864 void gpgme_signers_clear (gpgme_ctx_t ctx);
865
866 /* Add KEY to list of signers in CTX.  */
867 gpgme_error_t gpgme_signers_add (gpgme_ctx_t ctx, const gpgme_key_t key);
868
869 /* Return the SEQth signer's key in CTX.  */
870 gpgme_key_t gpgme_signers_enum (const gpgme_ctx_t ctx, int seq);
871
872 /* Retrieve the signature status of signature IDX in CTX after a
873    successful verify operation in R_STAT (if non-null).  The creation
874    time stamp of the signature is returned in R_CREATED (if non-null).
875    The function returns a string containing the fingerprint.
876    Deprecated, use verify result directly.  */
877 const char *gpgme_get_sig_status (gpgme_ctx_t ctx, int idx,
878                                   _gpgme_sig_stat_t *r_stat,
879                                   time_t *r_created) _GPGME_DEPRECATED;
880
881 /* Retrieve certain attributes of a signature.  IDX is the index
882    number of the signature after a successful verify operation.  WHAT
883    is an attribute where GPGME_ATTR_EXPIRE is probably the most useful
884    one.  WHATIDX is to be passed as 0 for most attributes . */
885 unsigned long gpgme_get_sig_ulong_attr (gpgme_ctx_t c, int idx,
886                                         _gpgme_attr_t what, int whatidx)
887      _GPGME_DEPRECATED;
888 const char *gpgme_get_sig_string_attr (gpgme_ctx_t c, int idx,
889                                        _gpgme_attr_t what, int whatidx)
890      _GPGME_DEPRECATED;
891
892
893 /* Get the key used to create signature IDX in CTX and return it in
894    R_KEY.  */
895 gpgme_error_t gpgme_get_sig_key (gpgme_ctx_t ctx, int idx, gpgme_key_t *r_key)
896      _GPGME_DEPRECATED;
897
898 \f
899 /* Clear all notation data from the context.  */
900 void gpgme_sig_notation_clear (gpgme_ctx_t ctx);
901
902 /* Add the human-readable notation data with name NAME and value VALUE
903    to the context CTX, using the flags FLAGS.  If NAME is NULL, then
904    VALUE should be a policy URL.  The flag
905    GPGME_SIG_NOTATION_HUMAN_READABLE is forced to be true for notation
906    data, and false for policy URLs.  */
907 gpgme_error_t gpgme_sig_notation_add (gpgme_ctx_t ctx, const char *name,
908                                       const char *value,
909                                       gpgme_sig_notation_flags_t flags);
910
911 /* Get the sig notations for this context.  */
912 gpgme_sig_notation_t gpgme_sig_notation_get (gpgme_ctx_t ctx);
913
914 \f
915 /* Run control.  */
916
917 /* The type of an I/O callback function.  */
918 typedef gpgme_error_t (*gpgme_io_cb_t) (void *data, int fd);
919
920 /* The type of a function that can register FNC as the I/O callback
921    function for the file descriptor FD with direction dir (0: for writing,
922    1: for reading).  FNC_DATA should be passed as DATA to FNC.  The
923    function should return a TAG suitable for the corresponding
924    gpgme_remove_io_cb_t, and an error value.  */
925 typedef gpgme_error_t (*gpgme_register_io_cb_t) (void *data, int fd, int dir,
926                                                  gpgme_io_cb_t fnc,
927                                                  void *fnc_data, void **tag);
928
929 /* The type of a function that can remove a previously registered I/O
930    callback function given TAG as returned by the register
931    function.  */
932 typedef void (*gpgme_remove_io_cb_t) (void *tag);
933
934 typedef enum
935   {
936     GPGME_EVENT_START,
937     GPGME_EVENT_DONE,
938     GPGME_EVENT_NEXT_KEY,
939     GPGME_EVENT_NEXT_TRUSTITEM
940   }
941 gpgme_event_io_t;
942
943 /* The type of a function that is called when a context finished an
944    operation.  */
945 typedef void (*gpgme_event_io_cb_t) (void *data, gpgme_event_io_t type,
946                                      void *type_data);
947
948 struct gpgme_io_cbs
949 {
950   gpgme_register_io_cb_t add;
951   void *add_priv;
952   gpgme_remove_io_cb_t remove;
953   gpgme_event_io_cb_t event;
954   void *event_priv;
955 };
956 typedef struct gpgme_io_cbs *gpgme_io_cbs_t;
957
958 /* Set the I/O callback functions in CTX to IO_CBS.  */
959 void gpgme_set_io_cbs (gpgme_ctx_t ctx, gpgme_io_cbs_t io_cbs);
960
961 /* Get the current I/O callback functions.  */
962 void gpgme_get_io_cbs (gpgme_ctx_t ctx, gpgme_io_cbs_t io_cbs);
963
964 /* Process the pending operation and, if HANG is non-zero, wait for
965    the pending operation to finish.  */
966 gpgme_ctx_t gpgme_wait (gpgme_ctx_t ctx, gpgme_error_t *status, int hang);
967
968 \f
969 /* Functions to handle data objects.  */
970
971 /* Read up to SIZE bytes into buffer BUFFER from the data object with
972    the handle HANDLE.  Return the number of characters read, 0 on EOF
973    and -1 on error.  If an error occurs, errno is set.  */
974 typedef ssize_t (*gpgme_data_read_cb_t) (void *handle, void *buffer,
975                                          size_t size);
976
977 /* Write up to SIZE bytes from buffer BUFFER to the data object with
978    the handle HANDLE.  Return the number of characters written, or -1
979    on error.  If an error occurs, errno is set.  */
980 typedef ssize_t (*gpgme_data_write_cb_t) (void *handle, const void *buffer,
981                                           size_t size);
982
983 /* Set the current position from where the next read or write starts
984    in the data object with the handle HANDLE to OFFSET, relativ to
985    WHENCE.  */
986 typedef off_t (*gpgme_data_seek_cb_t) (void *handle, off_t offset, int whence);
987
988 /* Close the data object with the handle DL.  */
989 typedef void (*gpgme_data_release_cb_t) (void *handle);
990
991 struct gpgme_data_cbs
992 {
993   gpgme_data_read_cb_t read;
994   gpgme_data_write_cb_t write;
995   gpgme_data_seek_cb_t seek;
996   gpgme_data_release_cb_t release;
997 };
998 typedef struct gpgme_data_cbs *gpgme_data_cbs_t;
999
1000 /* Read up to SIZE bytes into buffer BUFFER from the data object with
1001    the handle DH.  Return the number of characters read, 0 on EOF and
1002    -1 on error.  If an error occurs, errno is set.  */
1003 ssize_t gpgme_data_read (gpgme_data_t dh, void *buffer, size_t size);
1004
1005 /* Write up to SIZE bytes from buffer BUFFER to the data object with
1006    the handle DH.  Return the number of characters written, or -1 on
1007    error.  If an error occurs, errno is set.  */
1008 ssize_t gpgme_data_write (gpgme_data_t dh, const void *buffer, size_t size);
1009
1010 /* Set the current position from where the next read or write starts
1011    in the data object with the handle DH to OFFSET, relativ to
1012    WHENCE.  */
1013 off_t gpgme_data_seek (gpgme_data_t dh, off_t offset, int whence);
1014
1015 /* Create a new data buffer and return it in R_DH.  */
1016 gpgme_error_t gpgme_data_new (gpgme_data_t *r_dh);
1017
1018 /* Destroy the data buffer DH.  */
1019 void gpgme_data_release (gpgme_data_t dh);
1020
1021 /* Create a new data buffer filled with SIZE bytes starting from
1022    BUFFER.  If COPY is zero, copying is delayed until necessary, and
1023    the data is taken from the original location when needed.  */
1024 gpgme_error_t gpgme_data_new_from_mem (gpgme_data_t *r_dh,
1025                                        const char *buffer, size_t size,
1026                                        int copy);
1027
1028 /* Destroy the data buffer DH and return a pointer to its content.
1029    The memory has be to released with gpgme_free() by the user.  It's
1030    size is returned in R_LEN.  */
1031 char *gpgme_data_release_and_get_mem (gpgme_data_t dh, size_t *r_len);
1032
1033 /* Release the memory returned by gpgme_data_release_and_get_mem().  */
1034 void gpgme_free (void *buffer);
1035
1036 gpgme_error_t gpgme_data_new_from_cbs (gpgme_data_t *dh,
1037                                        gpgme_data_cbs_t cbs,
1038                                        void *handle);
1039
1040 gpgme_error_t gpgme_data_new_from_fd (gpgme_data_t *dh, int fd);
1041
1042 gpgme_error_t gpgme_data_new_from_stream (gpgme_data_t *dh, FILE *stream);
1043
1044 /* Return the encoding attribute of the data buffer DH */
1045 gpgme_data_encoding_t gpgme_data_get_encoding (gpgme_data_t dh);
1046
1047 /* Set the encoding attribute of data buffer DH to ENC */
1048 gpgme_error_t gpgme_data_set_encoding (gpgme_data_t dh,
1049                                        gpgme_data_encoding_t enc);
1050
1051 /* Get the file name associated with the data object with handle DH, or
1052    NULL if there is none.  */
1053 char *gpgme_data_get_file_name (gpgme_data_t dh);
1054
1055 /* Set the file name associated with the data object with handle DH to
1056    FILE_NAME.  */
1057 gpgme_error_t gpgme_data_set_file_name (gpgme_data_t dh,
1058                                         const char *file_name);
1059
1060
1061 /* Create a new data buffer which retrieves the data from the callback
1062    function READ_CB.  Deprecated, please use gpgme_data_new_from_cbs
1063    instead.  */
1064 gpgme_error_t gpgme_data_new_with_read_cb (gpgme_data_t *r_dh,
1065                                            int (*read_cb) (void*,char *,
1066                                                            size_t,size_t*),
1067                                            void *read_cb_value)
1068      _GPGME_DEPRECATED;
1069
1070 /* Create a new data buffer filled with the content of file FNAME.
1071    COPY must be non-zero.  For delayed read, please use
1072    gpgme_data_new_from_fd or gpgme_data_new_from stream instead.  */
1073 gpgme_error_t gpgme_data_new_from_file (gpgme_data_t *r_dh,
1074                                         const char *fname,
1075                                         int copy);
1076
1077 /* Create a new data buffer filled with LENGTH bytes starting from
1078    OFFSET within the file FNAME or stream FP (exactly one must be
1079    non-zero).  */
1080 gpgme_error_t gpgme_data_new_from_filepart (gpgme_data_t *r_dh,
1081                                             const char *fname, FILE *fp,
1082                                             off_t offset, size_t length);
1083
1084 /* Reset the read pointer in DH.  Deprecated, please use
1085    gpgme_data_seek instead.  */
1086 gpgme_error_t gpgme_data_rewind (gpgme_data_t dh) _GPGME_DEPRECATED;
1087
1088 \f
1089 /* Key and trust functions.  */
1090
1091 /* Get the key with the fingerprint FPR from the crypto backend.  If
1092    SECRET is true, get the secret key.  */
1093 gpgme_error_t gpgme_get_key (gpgme_ctx_t ctx, const char *fpr,
1094                              gpgme_key_t *r_key, int secret);
1095
1096 /* Acquire a reference to KEY.  */
1097 void gpgme_key_ref (gpgme_key_t key);
1098
1099 /* Release a reference to KEY.  If this was the last one the key is
1100    destroyed.  */
1101 void gpgme_key_unref (gpgme_key_t key);
1102 void gpgme_key_release (gpgme_key_t key);
1103
1104 /* Return the value of the attribute WHAT of KEY, which has to be
1105    representable by a string.  IDX specifies the sub key or user ID
1106    for attributes related to sub keys or user IDs.  Deprecated, use
1107    key structure directly instead. */
1108 const char *gpgme_key_get_string_attr (gpgme_key_t key, _gpgme_attr_t what,
1109                                        const void *reserved, int idx)
1110      _GPGME_DEPRECATED;
1111
1112 /* Return the value of the attribute WHAT of KEY, which has to be
1113    representable by an unsigned integer.  IDX specifies the sub key or
1114    user ID for attributes related to sub keys or user IDs.
1115    Deprecated, use key structure directly instead.  */
1116 unsigned long gpgme_key_get_ulong_attr (gpgme_key_t key, _gpgme_attr_t what,
1117                                         const void *reserved, int idx)
1118      _GPGME_DEPRECATED;
1119
1120 /* Return the value of the attribute WHAT of a signature on user ID
1121    UID_IDX in KEY, which has to be representable by a string.  IDX
1122    specifies the signature.  Deprecated, use key structure directly
1123    instead.  */
1124 const char *gpgme_key_sig_get_string_attr (gpgme_key_t key, int uid_idx,
1125                                            _gpgme_attr_t what,
1126                                            const void *reserved, int idx)
1127      _GPGME_DEPRECATED;
1128
1129 /* Return the value of the attribute WHAT of a signature on user ID
1130    UID_IDX in KEY, which has to be representable by an unsigned
1131    integer string.  IDX specifies the signature.  Deprecated, use key
1132    structure directly instead.  */
1133 unsigned long gpgme_key_sig_get_ulong_attr (gpgme_key_t key, int uid_idx,
1134                                             _gpgme_attr_t what,
1135                                             const void *reserved, int idx)
1136      _GPGME_DEPRECATED;
1137
1138 \f
1139 /* Crypto Operations.  */
1140
1141 /* Cancel a pending asynchronous operation.  */
1142 gpgme_error_t gpgme_cancel (gpgme_ctx_t ctx);
1143
1144 /* Cancel a pending operation asynchronously.  */
1145 gpgme_error_t gpgme_cancel_async (gpgme_ctx_t ctx);
1146
1147 \f
1148 struct _gpgme_invalid_key
1149 {
1150   struct _gpgme_invalid_key *next;
1151   char *fpr;
1152   gpgme_error_t reason;
1153 };
1154 typedef struct _gpgme_invalid_key *gpgme_invalid_key_t;
1155
1156 \f
1157 /* Encryption.  */
1158 struct _gpgme_op_encrypt_result
1159 {
1160   /* The list of invalid recipients.  */
1161   gpgme_invalid_key_t invalid_recipients;
1162 };
1163 typedef struct _gpgme_op_encrypt_result *gpgme_encrypt_result_t;
1164
1165 /* Retrieve a pointer to the result of the encrypt operation.  */
1166 gpgme_encrypt_result_t gpgme_op_encrypt_result (gpgme_ctx_t ctx);
1167
1168 /* The valid encryption flags.  */
1169 typedef enum
1170   {
1171     GPGME_ENCRYPT_ALWAYS_TRUST = 1,
1172     GPGME_ENCRYPT_NO_ENCRYPT_TO = 2
1173   }
1174 gpgme_encrypt_flags_t;
1175
1176 /* Encrypt plaintext PLAIN within CTX for the recipients RECP and
1177    store the resulting ciphertext in CIPHER.  */
1178 gpgme_error_t gpgme_op_encrypt_start (gpgme_ctx_t ctx, gpgme_key_t recp[],
1179                                       gpgme_encrypt_flags_t flags,
1180                                       gpgme_data_t plain, gpgme_data_t cipher);
1181 gpgme_error_t gpgme_op_encrypt (gpgme_ctx_t ctx, gpgme_key_t recp[],
1182                                 gpgme_encrypt_flags_t flags,
1183                                 gpgme_data_t plain, gpgme_data_t cipher);
1184
1185 /* Encrypt plaintext PLAIN within CTX for the recipients RECP and
1186    store the resulting ciphertext in CIPHER.  Also sign the ciphertext
1187    with the signers in CTX.  */
1188 gpgme_error_t gpgme_op_encrypt_sign_start (gpgme_ctx_t ctx,
1189                                            gpgme_key_t recp[],
1190                                            gpgme_encrypt_flags_t flags,
1191                                            gpgme_data_t plain,
1192                                            gpgme_data_t cipher);
1193 gpgme_error_t gpgme_op_encrypt_sign (gpgme_ctx_t ctx, gpgme_key_t recp[],
1194                                      gpgme_encrypt_flags_t flags,
1195                                      gpgme_data_t plain, gpgme_data_t cipher);
1196
1197 \f
1198 /* Decryption.  */
1199
1200 struct _gpgme_recipient
1201 {
1202   struct _gpgme_recipient *next;
1203
1204   /* The key ID of key for which the text was encrypted.  */
1205   char *keyid;
1206
1207   /* Internal to GPGME, do not use.  */
1208   char _keyid[16 + 1];
1209
1210   /* The public key algorithm of the recipient key.  */
1211   gpgme_pubkey_algo_t pubkey_algo;
1212
1213   /* The status of the recipient.  */
1214   gpgme_error_t status;
1215 };
1216 typedef struct _gpgme_recipient *gpgme_recipient_t;
1217
1218 struct _gpgme_op_decrypt_result
1219 {
1220   char *unsupported_algorithm;
1221
1222   /* Key should not have been used for encryption.  */
1223   unsigned int wrong_key_usage : 1;
1224
1225   /* Internal to GPGME, do not use.  */
1226   int _unused : 31;
1227
1228   gpgme_recipient_t recipients;
1229
1230   /* The original file name of the plaintext message, if
1231      available.  */
1232   char *file_name;
1233 };
1234 typedef struct _gpgme_op_decrypt_result *gpgme_decrypt_result_t;
1235
1236 /* Retrieve a pointer to the result of the decrypt operation.  */
1237 gpgme_decrypt_result_t gpgme_op_decrypt_result (gpgme_ctx_t ctx);
1238
1239 /* Decrypt ciphertext CIPHER within CTX and store the resulting
1240    plaintext in PLAIN.  */
1241 gpgme_error_t gpgme_op_decrypt_start (gpgme_ctx_t ctx, gpgme_data_t cipher,
1242                                       gpgme_data_t plain);
1243 gpgme_error_t gpgme_op_decrypt (gpgme_ctx_t ctx,
1244                                 gpgme_data_t cipher, gpgme_data_t plain);
1245
1246 /* Decrypt ciphertext CIPHER and make a signature verification within
1247    CTX and store the resulting plaintext in PLAIN.  */
1248 gpgme_error_t gpgme_op_decrypt_verify_start (gpgme_ctx_t ctx,
1249                                              gpgme_data_t cipher,
1250                                              gpgme_data_t plain);
1251 gpgme_error_t gpgme_op_decrypt_verify (gpgme_ctx_t ctx, gpgme_data_t cipher,
1252                                        gpgme_data_t plain);
1253
1254 \f
1255 /* Signing.  */
1256 struct _gpgme_new_signature
1257 {
1258   struct _gpgme_new_signature *next;
1259
1260   /* The type of the signature.  */
1261   gpgme_sig_mode_t type;
1262
1263   /* The public key algorithm used to create the signature.  */
1264   gpgme_pubkey_algo_t pubkey_algo;
1265
1266   /* The hash algorithm used to create the signature.  */
1267   gpgme_hash_algo_t hash_algo;
1268
1269   /* Internal to GPGME, do not use.  Must be set to the same value as
1270      CLASS below.  */
1271   unsigned long _obsolete_class;
1272
1273   /* Signature creation time.  */
1274   long int timestamp;
1275
1276   /* The fingerprint of the signature.  */
1277   char *fpr;
1278
1279 #ifdef __cplusplus
1280   unsigned int _obsolete_class_2;
1281 #else
1282   /* Must be set to SIG_CLASS below.  */
1283   unsigned int class _GPGME_DEPRECATED;
1284 #endif
1285
1286   /* Crypto backend specific signature class.  */
1287   unsigned int sig_class;
1288 };
1289 typedef struct _gpgme_new_signature *gpgme_new_signature_t;
1290
1291 struct _gpgme_op_sign_result
1292 {
1293   /* The list of invalid signers.  */
1294   gpgme_invalid_key_t invalid_signers;
1295   gpgme_new_signature_t signatures;
1296 };
1297 typedef struct _gpgme_op_sign_result *gpgme_sign_result_t;
1298
1299 /* Retrieve a pointer to the result of the signing operation.  */
1300 gpgme_sign_result_t gpgme_op_sign_result (gpgme_ctx_t ctx);
1301
1302 /* Sign the plaintext PLAIN and store the signature in SIG.  */
1303 gpgme_error_t gpgme_op_sign_start (gpgme_ctx_t ctx,
1304                                    gpgme_data_t plain, gpgme_data_t sig,
1305                                    gpgme_sig_mode_t mode);
1306 gpgme_error_t gpgme_op_sign (gpgme_ctx_t ctx,
1307                              gpgme_data_t plain, gpgme_data_t sig,
1308                              gpgme_sig_mode_t mode);
1309
1310 \f
1311 /* Verify.  */
1312
1313 /* Flags used for the SUMMARY field in a gpgme_signature_t.  */
1314 typedef enum
1315   {
1316     GPGME_SIGSUM_VALID       = 0x0001,  /* The signature is fully valid.  */
1317     GPGME_SIGSUM_GREEN       = 0x0002,  /* The signature is good.  */
1318     GPGME_SIGSUM_RED         = 0x0004,  /* The signature is bad.  */
1319     GPGME_SIGSUM_KEY_REVOKED = 0x0010,  /* One key has been revoked.  */
1320     GPGME_SIGSUM_KEY_EXPIRED = 0x0020,  /* One key has expired.  */
1321     GPGME_SIGSUM_SIG_EXPIRED = 0x0040,  /* The signature has expired.  */
1322     GPGME_SIGSUM_KEY_MISSING = 0x0080,  /* Can't verify: key missing.  */
1323     GPGME_SIGSUM_CRL_MISSING = 0x0100,  /* CRL not available.  */
1324     GPGME_SIGSUM_CRL_TOO_OLD = 0x0200,  /* Available CRL is too old.  */
1325     GPGME_SIGSUM_BAD_POLICY  = 0x0400,  /* A policy was not met.  */
1326     GPGME_SIGSUM_SYS_ERROR   = 0x0800   /* A system error occured.  */
1327   }
1328 gpgme_sigsum_t;
1329
1330 struct _gpgme_signature
1331 {
1332   struct _gpgme_signature *next;
1333
1334   /* A summary of the signature status.  */
1335   gpgme_sigsum_t summary;
1336
1337   /* The fingerprint or key ID of the signature.  */
1338   char *fpr;
1339
1340   /* The status of the signature.  */
1341   gpgme_error_t status;
1342
1343   /* Notation data and policy URLs.  */
1344   gpgme_sig_notation_t notations;
1345
1346   /* Signature creation time.  */
1347   unsigned long timestamp;
1348
1349   /* Signature exipration time or 0.  */
1350   unsigned long exp_timestamp;
1351
1352   /* Key should not have been used for signing.  */
1353   unsigned int wrong_key_usage : 1;
1354
1355   /* PKA status: 0 = not available, 1 = bad, 2 = okay, 3 = RFU. */
1356   unsigned int pka_trust : 2;
1357
1358   /* Validity has been verified using the chain model. */
1359   unsigned int chain_model : 1;
1360
1361   /* Internal to GPGME, do not use.  */
1362   int _unused : 28;
1363
1364   gpgme_validity_t validity;
1365   gpgme_error_t validity_reason;
1366
1367   /* The public key algorithm used to create the signature.  */
1368   gpgme_pubkey_algo_t pubkey_algo;
1369
1370   /* The hash algorithm used to create the signature.  */
1371   gpgme_hash_algo_t hash_algo;
1372
1373   /* The mailbox from the PKA information or NULL. */
1374   char *pka_address;
1375 };
1376 typedef struct _gpgme_signature *gpgme_signature_t;
1377
1378 struct _gpgme_op_verify_result
1379 {
1380   gpgme_signature_t signatures;
1381
1382   /* The original file name of the plaintext message, if
1383      available.  */
1384   char *file_name;
1385 };
1386 typedef struct _gpgme_op_verify_result *gpgme_verify_result_t;
1387
1388 /* Retrieve a pointer to the result of the verify operation.  */
1389 gpgme_verify_result_t gpgme_op_verify_result (gpgme_ctx_t ctx);
1390
1391 /* Verify within CTX that SIG is a valid signature for TEXT.  */
1392 gpgme_error_t gpgme_op_verify_start (gpgme_ctx_t ctx, gpgme_data_t sig,
1393                                      gpgme_data_t signed_text,
1394                                      gpgme_data_t plaintext);
1395 gpgme_error_t gpgme_op_verify (gpgme_ctx_t ctx, gpgme_data_t sig,
1396                                gpgme_data_t signed_text,
1397                                gpgme_data_t plaintext);
1398
1399 \f
1400 /* Import.  */
1401
1402 /* The key was new.  */
1403 #define GPGME_IMPORT_NEW        1
1404
1405 /* The key contained new user IDs.  */
1406 #define GPGME_IMPORT_UID        2
1407
1408 /* The key contained new signatures.  */
1409 #define GPGME_IMPORT_SIG        4
1410
1411 /* The key contained new sub keys.  */
1412 #define GPGME_IMPORT_SUBKEY     8
1413
1414 /* The key contained a secret key.  */
1415 #define GPGME_IMPORT_SECRET     16
1416
1417
1418 struct _gpgme_import_status
1419 {
1420   struct _gpgme_import_status *next;
1421
1422   /* Fingerprint.  */
1423   char *fpr;
1424
1425   /* If a problem occured, the reason why the key could not be
1426      imported.  Otherwise GPGME_No_Error.  */
1427   gpgme_error_t result;
1428
1429   /* The result of the import, the GPGME_IMPORT_* values bit-wise
1430      ORed.  0 means the key was already known and no new components
1431      have been added.  */
1432   unsigned int status;
1433 };
1434 typedef struct _gpgme_import_status *gpgme_import_status_t;
1435
1436 /* Import.  */
1437 struct _gpgme_op_import_result
1438 {
1439   /* Number of considered keys.  */
1440   int considered;
1441
1442   /* Keys without user ID.  */
1443   int no_user_id;
1444
1445   /* Imported keys.  */
1446   int imported;
1447
1448   /* Imported RSA keys.  */
1449   int imported_rsa;
1450
1451   /* Unchanged keys.  */
1452   int unchanged;
1453
1454   /* Number of new user ids.  */
1455   int new_user_ids;
1456
1457   /* Number of new sub keys.  */
1458   int new_sub_keys;
1459
1460   /* Number of new signatures.  */
1461   int new_signatures;
1462
1463   /* Number of new revocations.  */
1464   int new_revocations;
1465
1466   /* Number of secret keys read.  */
1467   int secret_read;
1468
1469   /* Number of secret keys imported.  */
1470   int secret_imported;
1471
1472   /* Number of secret keys unchanged.  */
1473   int secret_unchanged;
1474
1475   /* Number of new keys skipped.  */
1476   int skipped_new_keys;
1477
1478   /* Number of keys not imported.  */
1479   int not_imported;
1480
1481   /* List of keys for which an import was attempted.  */
1482   gpgme_import_status_t imports;
1483 };
1484 typedef struct _gpgme_op_import_result *gpgme_import_result_t;
1485
1486 /* Retrieve a pointer to the result of the import operation.  */
1487 gpgme_import_result_t gpgme_op_import_result (gpgme_ctx_t ctx);
1488
1489 /* Import the key in KEYDATA into the keyring.  */
1490 gpgme_error_t gpgme_op_import_start (gpgme_ctx_t ctx, gpgme_data_t keydata);
1491 gpgme_error_t gpgme_op_import (gpgme_ctx_t ctx, gpgme_data_t keydata);
1492 gpgme_error_t gpgme_op_import_ext (gpgme_ctx_t ctx, gpgme_data_t keydata,
1493                                    int *nr) _GPGME_DEPRECATED;
1494
1495 \f
1496 /* Export the keys found by PATTERN into KEYDATA.  */
1497 gpgme_error_t gpgme_op_export_start (gpgme_ctx_t ctx, const char *pattern,
1498                                      unsigned int reserved,
1499                                      gpgme_data_t keydata);
1500 gpgme_error_t gpgme_op_export (gpgme_ctx_t ctx, const char *pattern,
1501                                unsigned int reserved, gpgme_data_t keydata);
1502
1503 gpgme_error_t gpgme_op_export_ext_start (gpgme_ctx_t ctx,
1504                                          const char *pattern[],
1505                                          unsigned int reserved,
1506                                          gpgme_data_t keydata);
1507 gpgme_error_t gpgme_op_export_ext (gpgme_ctx_t ctx, const char *pattern[],
1508                                    unsigned int reserved,
1509                                    gpgme_data_t keydata);
1510
1511 \f
1512 /* Key generation.  */
1513 struct _gpgme_op_genkey_result
1514 {
1515   /* A primary key was generated.  */
1516   unsigned int primary : 1;
1517
1518   /* A sub key was generated.  */
1519   unsigned int sub : 1;
1520
1521   /* Internal to GPGME, do not use.  */
1522   unsigned int _unused : 30;
1523
1524   /* The fingerprint of the generated key.  */
1525   char *fpr;
1526 };
1527 typedef struct _gpgme_op_genkey_result *gpgme_genkey_result_t;
1528
1529 /* Generate a new keypair and add it to the keyring.  PUBKEY and
1530    SECKEY should be null for now.  PARMS specifies what keys should be
1531    generated.  */
1532 gpgme_error_t gpgme_op_genkey_start (gpgme_ctx_t ctx, const char *parms,
1533                                      gpgme_data_t pubkey, gpgme_data_t seckey);
1534 gpgme_error_t gpgme_op_genkey (gpgme_ctx_t ctx, const char *parms,
1535                                gpgme_data_t pubkey, gpgme_data_t seckey);
1536
1537 /* Retrieve a pointer to the result of the genkey operation.  */
1538 gpgme_genkey_result_t gpgme_op_genkey_result (gpgme_ctx_t ctx);
1539
1540 \f
1541 /* Delete KEY from the keyring.  If ALLOW_SECRET is non-zero, secret
1542    keys are also deleted.  */
1543 gpgme_error_t gpgme_op_delete_start (gpgme_ctx_t ctx, const gpgme_key_t key,
1544                                      int allow_secret);
1545 gpgme_error_t gpgme_op_delete (gpgme_ctx_t ctx, const gpgme_key_t key,
1546                                int allow_secret);
1547
1548 \f
1549 /* Edit the key KEY.  Send status and command requests to FNC and
1550    output of edit commands to OUT.  */
1551 gpgme_error_t gpgme_op_edit_start (gpgme_ctx_t ctx, gpgme_key_t key,
1552                                    gpgme_edit_cb_t fnc, void *fnc_value,
1553                                    gpgme_data_t out);
1554 gpgme_error_t gpgme_op_edit (gpgme_ctx_t ctx, gpgme_key_t key,
1555                              gpgme_edit_cb_t fnc, void *fnc_value,
1556                              gpgme_data_t out);
1557
1558 /* Edit the card for the key KEY.  Send status and command requests to
1559    FNC and output of edit commands to OUT.  */
1560 gpgme_error_t gpgme_op_card_edit_start (gpgme_ctx_t ctx, gpgme_key_t key,
1561                                         gpgme_edit_cb_t fnc, void *fnc_value,
1562                                         gpgme_data_t out);
1563 gpgme_error_t gpgme_op_card_edit (gpgme_ctx_t ctx, gpgme_key_t key,
1564                                   gpgme_edit_cb_t fnc, void *fnc_value,
1565                                   gpgme_data_t out);
1566
1567 \f
1568 /* Key management functions.  */
1569 struct _gpgme_op_keylist_result
1570 {
1571   unsigned int truncated : 1;
1572
1573   /* Internal to GPGME, do not use.  */
1574   unsigned int _unused : 31;
1575 };
1576 typedef struct _gpgme_op_keylist_result *gpgme_keylist_result_t;
1577
1578 /* Retrieve a pointer to the result of the key listing operation.  */
1579 gpgme_keylist_result_t gpgme_op_keylist_result (gpgme_ctx_t ctx);
1580
1581 /* Start a keylist operation within CTX, searching for keys which
1582    match PATTERN.  If SECRET_ONLY is true, only secret keys are
1583    returned.  */
1584 gpgme_error_t gpgme_op_keylist_start (gpgme_ctx_t ctx, const char *pattern,
1585                                       int secret_only);
1586 gpgme_error_t gpgme_op_keylist_ext_start (gpgme_ctx_t ctx,
1587                                           const char *pattern[],
1588                                           int secret_only, int reserved);
1589
1590 /* Return the next key from the keylist in R_KEY.  */
1591 gpgme_error_t gpgme_op_keylist_next (gpgme_ctx_t ctx, gpgme_key_t *r_key);
1592
1593 /* Terminate a pending keylist operation within CTX.  */
1594 gpgme_error_t gpgme_op_keylist_end (gpgme_ctx_t ctx);
1595
1596 \f
1597 /* Trust items and operations.  */
1598
1599 struct _gpgme_trust_item
1600 {
1601   /* Internal to GPGME, do not use.  */
1602   unsigned int _refs;
1603
1604   /* The key ID to which the trust item belongs.  */
1605   char *keyid;
1606
1607   /* Internal to GPGME, do not use.  */
1608   char _keyid[16 + 1];
1609
1610   /* The type of the trust item, 1 refers to a key, 2 to a user ID.  */
1611   int type;
1612
1613   /* The trust level.  */
1614   int level;
1615
1616   /* The owner trust if TYPE is 1.  */
1617   char *owner_trust;
1618
1619   /* Internal to GPGME, do not use.  */
1620   char _owner_trust[2];
1621
1622   /* The calculated validity.  */
1623   char *validity;
1624  
1625   /* Internal to GPGME, do not use.  */
1626   char _validity[2];
1627
1628   /* The user name if TYPE is 2.  */
1629   char *name;
1630 };
1631 typedef struct _gpgme_trust_item *gpgme_trust_item_t;
1632
1633 /* Start a trustlist operation within CTX, searching for trust items
1634    which match PATTERN.  */
1635 gpgme_error_t gpgme_op_trustlist_start (gpgme_ctx_t ctx,
1636                                         const char *pattern, int max_level);
1637
1638 /* Return the next trust item from the trustlist in R_ITEM.  */
1639 gpgme_error_t gpgme_op_trustlist_next (gpgme_ctx_t ctx,
1640                                        gpgme_trust_item_t *r_item);
1641
1642 /* Terminate a pending trustlist operation within CTX.  */
1643 gpgme_error_t gpgme_op_trustlist_end (gpgme_ctx_t ctx);
1644
1645 /* Acquire a reference to ITEM.  */
1646 void gpgme_trust_item_ref (gpgme_trust_item_t item);
1647
1648 /* Release a reference to ITEM.  If this was the last one the trust
1649    item is destroyed.  */
1650 void gpgme_trust_item_unref (gpgme_trust_item_t item);
1651
1652 /* Release the trust item ITEM.  Deprecated, use
1653    gpgme_trust_item_unref.  */
1654 void gpgme_trust_item_release (gpgme_trust_item_t item) _GPGME_DEPRECATED;
1655
1656 /* Return the value of the attribute WHAT of ITEM, which has to be
1657    representable by a string.  Deprecated, use trust item structure
1658    directly.  */
1659 const char *gpgme_trust_item_get_string_attr (gpgme_trust_item_t item,
1660                                               _gpgme_attr_t what,
1661                                               const void *reserved, int idx)
1662      _GPGME_DEPRECATED;
1663
1664 /* Return the value of the attribute WHAT of KEY, which has to be
1665    representable by an integer.  IDX specifies a running index if the
1666    attribute appears more than once in the key.  Deprecated, use trust
1667    item structure directly.  */
1668 int gpgme_trust_item_get_int_attr (gpgme_trust_item_t item, _gpgme_attr_t what,
1669                                    const void *reserved, int idx)
1670      _GPGME_DEPRECATED;
1671
1672 \f
1673 /* Return the auditlog for the current session.  This may be called
1674    after a successful or failed operation.  If no audit log is
1675    available GPG_ERR_NO_DATA is returned.  */
1676 gpgme_error_t gpgme_op_getauditlog_start (gpgme_ctx_t ctx, gpgme_data_t output,
1677                                           unsigned int flags);
1678 gpgme_error_t gpgme_op_getauditlog (gpgme_ctx_t ctx, gpgme_data_t output, 
1679                                     unsigned int flags);
1680
1681
1682 \f
1683 /* Low-level Assuan protocol access.  */
1684 typedef gpgme_error_t (*gpgme_assuan_data_cb_t) 
1685      (void *opaque, const void *data, size_t datalen);
1686
1687 typedef gpgme_error_t (*gpgme_assuan_inquire_cb_t)
1688      (void *opaque, const char *name, const char *args,
1689       gpgme_data_t *r_data);
1690
1691 typedef gpgme_error_t (*gpgme_assuan_status_cb_t)
1692      (void *opaque, const char *status, const char *args);
1693
1694 struct _gpgme_op_assuan_result
1695 {
1696   /* The result of the actual assuan command.  An OK is indicated by a
1697      value of 0 and an ERR by the respective error error value.  */
1698   gpgme_error_t err;
1699 };
1700 typedef struct _gpgme_op_assuan_result *gpgme_assuan_result_t;
1701
1702
1703 /* Return the result of the last Assuan command. */
1704 gpgme_assuan_result_t gpgme_op_assuan_result (gpgme_ctx_t ctx);
1705
1706 /* Send the Assuan COMMAND and return results via the callbacks.
1707    Asynchronous variant. */
1708 gpgme_error_t gpgme_op_assuan_transact_start (gpgme_ctx_t ctx, 
1709                                               const char *command,
1710                                               gpgme_assuan_data_cb_t data_cb,
1711                                               void *data_cb_value,
1712                                               gpgme_assuan_inquire_cb_t inq_cb,
1713                                               void *inq_cb_value,
1714                                               gpgme_assuan_status_cb_t stat_cb,
1715                                               void *stat_cb_value);
1716
1717 /* Send the Assuan COMMAND and return results via the callbacks.
1718    Synchronous variant. */
1719 gpgme_error_t gpgme_op_assuan_transact (gpgme_ctx_t ctx, 
1720                                         const char *command,
1721                                         gpgme_assuan_data_cb_t data_cb,
1722                                         void *data_cb_value,
1723                                         gpgme_assuan_inquire_cb_t inq_cb,
1724                                         void *inq_cb_value,
1725                                         gpgme_assuan_status_cb_t stat_cb,
1726                                         void *stat_cb_value);
1727
1728
1729 \f
1730 /* Interface to gpgconf(1).  */
1731
1732 /* The expert level at which a configuration option or group of
1733    options should be displayed.  See the gpgconf(1) documentation for
1734    more details.  */
1735 typedef enum
1736   {
1737     GPGME_CONF_BASIC = 0,
1738     GPGME_CONF_ADVANCED = 1,
1739     GPGME_CONF_EXPERT = 2,
1740     GPGME_CONF_INVISIBLE = 3,
1741     GPGME_CONF_INTERNAL = 4
1742   }
1743 gpgme_conf_level_t;
1744
1745
1746 /* The data type of a configuration option argument.  See the gpgconf(1)
1747    documentation for more details.  */
1748 typedef enum
1749   {
1750     /* Basic types.  */
1751     GPGME_CONF_NONE = 0,
1752     GPGME_CONF_STRING = 1,
1753     GPGME_CONF_INT32 = 2,
1754     GPGME_CONF_UINT32 = 3,
1755
1756     /* Complex types.  */
1757     GPGME_CONF_FILENAME = 32,
1758     GPGME_CONF_LDAP_SERVER = 33,
1759     GPGME_CONF_KEY_FPR = 34,
1760     GPGME_CONF_PUB_KEY = 35,
1761     GPGME_CONF_SEC_KEY = 36,
1762     GPGME_CONF_ALIAS_LIST = 37
1763   }
1764 gpgme_conf_type_t;
1765 /* Macro for backward compatibility (even though it was undocumented
1766    and marked as experimental in 1.1.6 - will be removed after 1.1.7): */
1767 #define GPGME_CONF_PATHNAME GPGME_CONF_FILENAME
1768
1769
1770 /* This represents a single argument for a configuration option.
1771    Which of the members of value is used depends on the ALT_TYPE.  */
1772 typedef struct gpgme_conf_arg
1773 {
1774   struct gpgme_conf_arg *next;
1775   /* True if the option appears without an (optional) argument.  */
1776   unsigned int no_arg;
1777   union
1778   {
1779     unsigned int count;
1780     unsigned int uint32;
1781     int int32;
1782     char *string;
1783   } value;
1784 } *gpgme_conf_arg_t;
1785
1786
1787 /* The flags of a configuration option.  See the gpg-conf
1788    documentation for details.  */
1789 #define GPGME_CONF_GROUP        (1 << 0)
1790 #define GPGME_CONF_OPTIONAL     (1 << 1)
1791 #define GPGME_CONF_LIST         (1 << 2)
1792 #define GPGME_CONF_RUNTIME      (1 << 3)
1793 #define GPGME_CONF_DEFAULT      (1 << 4)
1794 #define GPGME_CONF_DEFAULT_DESC (1 << 5)
1795 #define GPGME_CONF_NO_ARG_DESC  (1 << 6)
1796 #define GPGME_CONF_NO_CHANGE    (1 << 7)
1797
1798
1799 /* The representation of a single configuration option.  See the
1800    gpg-conf documentation for details.  */
1801 typedef struct gpgme_conf_opt
1802 {
1803   struct gpgme_conf_opt *next;
1804   
1805   /* The option name.  */
1806   char *name;
1807
1808   /* The flags for this option.  */
1809   unsigned int flags;
1810
1811   /* The level of this option.  */
1812   gpgme_conf_level_t level;
1813
1814   /* The localized description of this option.  */
1815   char *description;
1816
1817   /* The type and alternate type of this option.  */
1818   gpgme_conf_type_t type;
1819   gpgme_conf_type_t alt_type;
1820
1821   /* The localized (short) name of the argument, if any.  */
1822   char *argname;
1823
1824   /* The default value.  */
1825   gpgme_conf_arg_t default_value;
1826   char *default_description;
1827   
1828   /* The default value if the option is not set.  */
1829   gpgme_conf_arg_t no_arg_value;
1830   char *no_arg_description;
1831
1832   /* The current value if the option is set.  */
1833   gpgme_conf_arg_t value;
1834
1835   /* The new value, if any.  NULL means reset to default.  */
1836   int change_value;
1837   gpgme_conf_arg_t new_value;
1838
1839   /* Free for application use.  */
1840   void *user_data;
1841 } *gpgme_conf_opt_t;
1842
1843
1844 /* The representation of a component that can be configured.  See the
1845    gpg-conf documentation for details.  */
1846 typedef struct gpgme_conf_comp
1847 {
1848   struct gpgme_conf_comp *next;
1849
1850   /* Internal to GPGME, do not use!  */
1851   gpgme_conf_opt_t *_last_opt_p;
1852
1853   /* The component name.  */
1854   char *name;
1855
1856   /* A human-readable description for the component.  */
1857   char *description;
1858
1859   /* The program name (an absolute path to the program).  */
1860   char *program_name;  
1861
1862   /* A linked list of options for this component.  */
1863   struct gpgme_conf_opt *options;
1864 } *gpgme_conf_comp_t;
1865
1866
1867 /* Allocate a new gpgme_conf_arg_t.  If VALUE is NULL, a "no arg
1868    default" is prepared.  If type is a string type, VALUE should point
1869    to the string.  Else, it should point to an unsigned or signed
1870    integer respectively.  */
1871 gpgme_error_t gpgme_conf_arg_new (gpgme_conf_arg_t *arg_p,
1872                                   gpgme_conf_type_t type, void *value);
1873
1874 /* This also releases all chained argument structures!  */
1875 void gpgme_conf_arg_release (gpgme_conf_arg_t arg, gpgme_conf_type_t type);
1876
1877 /* Register a change for the value of OPT to ARG.  If RESET is 1 (do
1878    not use any values but 0 or 1), ARG is ignored and the option is
1879    not changed (reverting a previous change).  Otherwise, if ARG is
1880    NULL, the option is cleared or reset to its default.  */
1881 gpgme_error_t gpgme_conf_opt_change (gpgme_conf_opt_t opt, int reset,
1882                                      gpgme_conf_arg_t arg);
1883
1884 /* Release a set of configurations.  */
1885 void gpgme_conf_release (gpgme_conf_comp_t conf);
1886  
1887 /* Retrieve the current configurations.  */
1888 gpgme_error_t gpgme_op_conf_load (gpgme_ctx_t ctx, gpgme_conf_comp_t *conf_p);
1889
1890 /* Save the configuration of component comp.  This function does not
1891    follow chained components!  */
1892 gpgme_error_t gpgme_op_conf_save (gpgme_ctx_t ctx, gpgme_conf_comp_t comp);
1893
1894 \f
1895 /* Various functions.  */
1896
1897 /* Check that the library fulfills the version requirement.  Note:
1898    This is here only for the case where a user takes a pointer from
1899    the old version of this function.  The new version and macro for
1900    run-time checks are below.  */
1901 const char *gpgme_check_version (const char *req_version);
1902
1903 /* Check that the library fulfills the version requirement and check
1904    for struct layout mismatch involving bitfields.  */
1905 const char *gpgme_check_version_internal (const char *req_version,
1906                                           size_t offset_sig_validity);
1907
1908 #define gpgme_check_version(req_version)                                \
1909   gpgme_check_version_internal (req_version,                            \
1910                                 offsetof (struct _gpgme_signature, validity))
1911
1912 /* Get the information about the configured and installed engines.  A
1913    pointer to the first engine in the statically allocated linked list
1914    is returned in *INFO.  If an error occurs, it is returned.  The
1915    returned data is valid until the next gpgme_set_engine_info.  */
1916 gpgme_error_t gpgme_get_engine_info (gpgme_engine_info_t *engine_info);
1917
1918 /* Set the default engine info for the protocol PROTO to the file name
1919    FILE_NAME and the home directory HOME_DIR.  */
1920 gpgme_error_t gpgme_set_engine_info (gpgme_protocol_t proto,
1921                                      const char *file_name,
1922                                      const char *home_dir);
1923
1924 \f
1925 /* Engine support functions.  */
1926
1927 /* Verify that the engine implementing PROTO is installed and
1928    available.  */
1929 gpgme_error_t gpgme_engine_check_version (gpgme_protocol_t proto);
1930
1931 \f
1932 /* Deprecated types.  */
1933 typedef gpgme_ctx_t GpgmeCtx _GPGME_DEPRECATED;
1934 typedef gpgme_data_t GpgmeData _GPGME_DEPRECATED;
1935 typedef gpgme_error_t GpgmeError _GPGME_DEPRECATED;
1936 typedef gpgme_data_encoding_t GpgmeDataEncoding _GPGME_DEPRECATED;
1937 typedef gpgme_pubkey_algo_t GpgmePubKeyAlgo _GPGME_DEPRECATED;
1938 typedef gpgme_hash_algo_t GpgmeHashAlgo _GPGME_DEPRECATED;
1939 typedef gpgme_sig_stat_t GpgmeSigStat _GPGME_DEPRECATED;
1940 typedef gpgme_sig_mode_t GpgmeSigMode _GPGME_DEPRECATED;
1941 typedef gpgme_attr_t GpgmeAttr _GPGME_DEPRECATED;
1942 typedef gpgme_validity_t GpgmeValidity _GPGME_DEPRECATED;
1943 typedef gpgme_protocol_t GpgmeProtocol _GPGME_DEPRECATED;
1944 typedef gpgme_engine_info_t GpgmeEngineInfo _GPGME_DEPRECATED;
1945 typedef gpgme_subkey_t GpgmeSubkey _GPGME_DEPRECATED;
1946 typedef gpgme_key_sig_t GpgmeKeySig _GPGME_DEPRECATED;
1947 typedef gpgme_user_id_t GpgmeUserID _GPGME_DEPRECATED;
1948 typedef gpgme_key_t GpgmeKey _GPGME_DEPRECATED;
1949 typedef gpgme_passphrase_cb_t GpgmePassphraseCb _GPGME_DEPRECATED;
1950 typedef gpgme_progress_cb_t GpgmeProgressCb _GPGME_DEPRECATED;
1951 typedef gpgme_io_cb_t GpgmeIOCb _GPGME_DEPRECATED;
1952 typedef gpgme_register_io_cb_t GpgmeRegisterIOCb _GPGME_DEPRECATED;
1953 typedef gpgme_remove_io_cb_t GpgmeRemoveIOCb _GPGME_DEPRECATED;
1954 typedef gpgme_event_io_t GpgmeEventIO _GPGME_DEPRECATED;
1955 typedef gpgme_event_io_cb_t GpgmeEventIOCb _GPGME_DEPRECATED;
1956 #define GpgmeIOCbs gpgme_io_cbs
1957 typedef gpgme_data_read_cb_t GpgmeDataReadCb _GPGME_DEPRECATED;
1958 typedef gpgme_data_write_cb_t GpgmeDataWriteCb _GPGME_DEPRECATED;
1959 typedef gpgme_data_seek_cb_t GpgmeDataSeekCb _GPGME_DEPRECATED;
1960 typedef gpgme_data_release_cb_t GpgmeDataReleaseCb _GPGME_DEPRECATED;
1961 #define GpgmeDataCbs gpgme_data_cbs
1962 typedef gpgme_encrypt_result_t GpgmeEncryptResult _GPGME_DEPRECATED;
1963 typedef gpgme_sig_notation_t GpgmeSigNotation _GPGME_DEPRECATED;
1964 typedef gpgme_signature_t GpgmeSignature _GPGME_DEPRECATED;
1965 typedef gpgme_verify_result_t GpgmeVerifyResult _GPGME_DEPRECATED;
1966 typedef gpgme_import_status_t GpgmeImportStatus _GPGME_DEPRECATED;
1967 typedef gpgme_import_result_t GpgmeImportResult _GPGME_DEPRECATED;
1968 typedef gpgme_genkey_result_t GpgmeGenKeyResult _GPGME_DEPRECATED;
1969 typedef gpgme_trust_item_t GpgmeTrustItem _GPGME_DEPRECATED;
1970 typedef gpgme_status_code_t GpgmeStatusCode _GPGME_DEPRECATED;
1971
1972 #ifdef __cplusplus
1973 }
1974 #endif
1975 #endif /* GPGME_H */