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