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