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