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