core: Add public function gpgme_get_ctx_flag.
[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 /* If YES is non-zero, try to return session keys during decryption,
1044    do not otherwise.  */
1045 void gpgme_set_export_session_keys (gpgme_ctx_t ctx, int yes);
1046
1047 /* Return non-zero if export_session_keys is set in CTX.  */
1048 int gpgme_get_export_session_keys (gpgme_ctx_t ctx);
1049
1050 /* Use whatever the default of the backend crypto engine is.  */
1051 #define GPGME_INCLUDE_CERTS_DEFAULT     -256
1052
1053 /* Include up to NR_OF_CERTS certificates in an S/MIME message.  */
1054 void gpgme_set_include_certs (gpgme_ctx_t ctx, int nr_of_certs);
1055
1056 /* Return the number of certs to include in an S/MIME message.  */
1057 int gpgme_get_include_certs (gpgme_ctx_t ctx);
1058
1059 /* Set keylist mode in CTX to MODE.  */
1060 gpgme_error_t gpgme_set_keylist_mode (gpgme_ctx_t ctx,
1061                                       gpgme_keylist_mode_t mode);
1062
1063 /* Get keylist mode in CTX.  */
1064 gpgme_keylist_mode_t gpgme_get_keylist_mode (gpgme_ctx_t ctx);
1065
1066 /* Set the pinentry mode for CTX to MODE. */
1067 gpgme_error_t gpgme_set_pinentry_mode (gpgme_ctx_t ctx,
1068                                        gpgme_pinentry_mode_t mode);
1069
1070 /* Get the pinentry mode of CTX.  */
1071 gpgme_pinentry_mode_t gpgme_get_pinentry_mode (gpgme_ctx_t ctx);
1072
1073 /* Set the passphrase callback function in CTX to CB.  HOOK_VALUE is
1074    passed as first argument to the passphrase callback function.  */
1075 void gpgme_set_passphrase_cb (gpgme_ctx_t ctx,
1076                               gpgme_passphrase_cb_t cb, void *hook_value);
1077
1078 /* Get the current passphrase callback function in *CB and the current
1079    hook value in *HOOK_VALUE.  */
1080 void gpgme_get_passphrase_cb (gpgme_ctx_t ctx, gpgme_passphrase_cb_t *cb,
1081                               void **hook_value);
1082
1083 /* Set the progress callback function in CTX to CB.  HOOK_VALUE is
1084    passed as first argument to the progress callback function.  */
1085 void gpgme_set_progress_cb (gpgme_ctx_t c, gpgme_progress_cb_t cb,
1086                             void *hook_value);
1087
1088 /* Get the current progress callback function in *CB and the current
1089    hook value in *HOOK_VALUE.  */
1090 void gpgme_get_progress_cb (gpgme_ctx_t ctx, gpgme_progress_cb_t *cb,
1091                             void **hook_value);
1092
1093 /* Set the status callback function in CTX to CB.  HOOK_VALUE is
1094    passed as first argument to the status callback function.  */
1095 void gpgme_set_status_cb (gpgme_ctx_t c, gpgme_status_cb_t cb,
1096                           void *hook_value);
1097
1098 /* Get the current status callback function in *CB and the current
1099    hook value in *HOOK_VALUE.  */
1100 void gpgme_get_status_cb (gpgme_ctx_t ctx, gpgme_status_cb_t *cb,
1101                           void **hook_value);
1102
1103 /* This function sets the locale for the context CTX, or the default
1104    locale if CTX is a null pointer.  */
1105 gpgme_error_t gpgme_set_locale (gpgme_ctx_t ctx, int category,
1106                                 const char *value);
1107
1108 /* Get the information about the configured engines.  A pointer to the
1109    first engine in the statically allocated linked list is returned.
1110    The returned data is valid until the next gpgme_ctx_set_engine_info.  */
1111 gpgme_engine_info_t gpgme_ctx_get_engine_info (gpgme_ctx_t ctx);
1112
1113 /* Set the engine info for the context CTX, protocol PROTO, to the
1114    file name FILE_NAME and the home directory HOME_DIR.  */
1115 gpgme_error_t gpgme_ctx_set_engine_info (gpgme_ctx_t ctx,
1116                                          gpgme_protocol_t proto,
1117                                          const char *file_name,
1118                                          const char *home_dir);
1119
1120 /* Delete all signers from CTX.  */
1121 void gpgme_signers_clear (gpgme_ctx_t ctx);
1122
1123 /* Add KEY to list of signers in CTX.  */
1124 gpgme_error_t gpgme_signers_add (gpgme_ctx_t ctx, const gpgme_key_t key);
1125
1126 /* Return the number of signers in CTX.  */
1127 unsigned int gpgme_signers_count (const gpgme_ctx_t ctx);
1128
1129 /* Return the SEQth signer's key in CTX.  */
1130 gpgme_key_t gpgme_signers_enum (const gpgme_ctx_t ctx, int seq);
1131
1132 /* Retrieve the signature status of signature IDX in CTX after a
1133    successful verify operation in R_STAT (if non-null).  The creation
1134    time stamp of the signature is returned in R_CREATED (if non-null).
1135    The function returns a string containing the fingerprint.
1136    Deprecated, use verify result directly.  */
1137 const char *gpgme_get_sig_status (gpgme_ctx_t ctx, int idx,
1138                                   _gpgme_sig_stat_t *r_stat,
1139                                   time_t *r_created) _GPGME_DEPRECATED(0,4);
1140
1141 /* Retrieve certain attributes of a signature.  IDX is the index
1142    number of the signature after a successful verify operation.  WHAT
1143    is an attribute where GPGME_ATTR_EXPIRE is probably the most useful
1144    one.  WHATIDX is to be passed as 0 for most attributes . */
1145 unsigned long gpgme_get_sig_ulong_attr (gpgme_ctx_t c, int idx,
1146                                         _gpgme_attr_t what, int whatidx)
1147      _GPGME_DEPRECATED(0,4);
1148 const char *gpgme_get_sig_string_attr (gpgme_ctx_t c, int idx,
1149                                        _gpgme_attr_t what, int whatidx)
1150      _GPGME_DEPRECATED(0,4);
1151
1152
1153 /* Get the key used to create signature IDX in CTX and return it in
1154    R_KEY.  */
1155 gpgme_error_t gpgme_get_sig_key (gpgme_ctx_t ctx, int idx, gpgme_key_t *r_key)
1156      _GPGME_DEPRECATED(0,4);
1157
1158
1159 /* Clear all notation data from the context.  */
1160 void gpgme_sig_notation_clear (gpgme_ctx_t ctx);
1161
1162 /* Add the human-readable notation data with name NAME and value VALUE
1163    to the context CTX, using the flags FLAGS.  If NAME is NULL, then
1164    VALUE should be a policy URL.  The flag
1165    GPGME_SIG_NOTATION_HUMAN_READABLE is forced to be true for notation
1166    data, and false for policy URLs.  */
1167 gpgme_error_t gpgme_sig_notation_add (gpgme_ctx_t ctx, const char *name,
1168                                       const char *value,
1169                                       gpgme_sig_notation_flags_t flags);
1170
1171 /* Get the sig notations for this context.  */
1172 gpgme_sig_notation_t gpgme_sig_notation_get (gpgme_ctx_t ctx);
1173
1174 /* Store a sender address in the context.  */
1175 gpgme_error_t gpgme_set_sender (gpgme_ctx_t ctx, const char *address);
1176
1177 /* Get the sender address from the context.  */
1178 const char *gpgme_get_sender (gpgme_ctx_t ctx);
1179
1180
1181 \f
1182 /*
1183  * Run control.
1184  */
1185
1186 /* The type of an I/O callback function.  */
1187 typedef gpgme_error_t (*gpgme_io_cb_t) (void *data, int fd);
1188
1189 /* The type of a function that can register FNC as the I/O callback
1190    function for the file descriptor FD with direction dir (0: for writing,
1191    1: for reading).  FNC_DATA should be passed as DATA to FNC.  The
1192    function should return a TAG suitable for the corresponding
1193    gpgme_remove_io_cb_t, and an error value.  */
1194 typedef gpgme_error_t (*gpgme_register_io_cb_t) (void *data, int fd, int dir,
1195                                                  gpgme_io_cb_t fnc,
1196                                                  void *fnc_data, void **tag);
1197
1198 /* The type of a function that can remove a previously registered I/O
1199    callback function given TAG as returned by the register
1200    function.  */
1201 typedef void (*gpgme_remove_io_cb_t) (void *tag);
1202
1203 typedef enum
1204   {
1205     GPGME_EVENT_START,
1206     GPGME_EVENT_DONE,
1207     GPGME_EVENT_NEXT_KEY,
1208     GPGME_EVENT_NEXT_TRUSTITEM
1209   }
1210 gpgme_event_io_t;
1211
1212 struct gpgme_io_event_done_data
1213 {
1214   /* A fatal IPC error or an operational error in state-less
1215      protocols.  */
1216   gpgme_error_t err;
1217
1218   /* An operational errors in session-based protocols.  */
1219   gpgme_error_t op_err;
1220 };
1221 typedef struct gpgme_io_event_done_data *gpgme_io_event_done_data_t;
1222
1223 /* The type of a function that is called when a context finished an
1224    operation.  */
1225 typedef void (*gpgme_event_io_cb_t) (void *data, gpgme_event_io_t type,
1226                                      void *type_data);
1227
1228 struct gpgme_io_cbs
1229 {
1230   gpgme_register_io_cb_t add;
1231   void *add_priv;
1232   gpgme_remove_io_cb_t remove;
1233   gpgme_event_io_cb_t event;
1234   void *event_priv;
1235 };
1236 typedef struct gpgme_io_cbs *gpgme_io_cbs_t;
1237
1238 /* Set the I/O callback functions in CTX to IO_CBS.  */
1239 void gpgme_set_io_cbs (gpgme_ctx_t ctx, gpgme_io_cbs_t io_cbs);
1240
1241 /* Get the current I/O callback functions.  */
1242 void gpgme_get_io_cbs (gpgme_ctx_t ctx, gpgme_io_cbs_t io_cbs);
1243
1244 /* Wrappers around the internal I/O functions for use with
1245    gpgme_passphrase_cb_t and gpgme_interact_cb_t.  */
1246 @API__SSIZE_T@ gpgme_io_read (int fd, void *buffer, size_t count);
1247 @API__SSIZE_T@ gpgme_io_write (int fd, const void *buffer, size_t count);
1248 int     gpgme_io_writen (int fd, const void *buffer, size_t count);
1249
1250 /* Process the pending operation and, if HANG is non-zero, wait for
1251    the pending operation to finish.  */
1252 gpgme_ctx_t gpgme_wait (gpgme_ctx_t ctx, gpgme_error_t *status, int hang);
1253
1254 gpgme_ctx_t gpgme_wait_ext (gpgme_ctx_t ctx, gpgme_error_t *status,
1255                             gpgme_error_t *op_err, int hang);
1256
1257 /* Cancel a pending asynchronous operation.  */
1258 gpgme_error_t gpgme_cancel (gpgme_ctx_t ctx);
1259
1260 /* Cancel a pending operation asynchronously.  */
1261 gpgme_error_t gpgme_cancel_async (gpgme_ctx_t ctx);
1262
1263
1264 \f
1265 /*
1266  * Functions to handle data objects.
1267  */
1268
1269 /* Read up to SIZE bytes into buffer BUFFER from the data object with
1270    the handle HANDLE.  Return the number of characters read, 0 on EOF
1271    and -1 on error.  If an error occurs, errno is set.  */
1272 typedef @API__SSIZE_T@ (*gpgme_data_read_cb_t) (void *handle, void *buffer,
1273                                          size_t size);
1274
1275 /* Write up to SIZE bytes from buffer BUFFER to the data object with
1276    the handle HANDLE.  Return the number of characters written, or -1
1277    on error.  If an error occurs, errno is set.  */
1278 typedef @API__SSIZE_T@ (*gpgme_data_write_cb_t) (void *handle, const void *buffer,
1279                                           size_t size);
1280
1281 /* Set the current position from where the next read or write starts
1282    in the data object with the handle HANDLE to OFFSET, relativ to
1283    WHENCE.  Returns the new offset in bytes from the beginning of the
1284    data object.  */
1285 typedef @API__OFF_T@ (*gpgme_data_seek_cb_t) (void *handle,
1286                                        @API__OFF_T@ offset, int whence);
1287
1288 /* Close the data object with the handle HANDLE.  */
1289 typedef void (*gpgme_data_release_cb_t) (void *handle);
1290
1291 struct gpgme_data_cbs
1292 {
1293   gpgme_data_read_cb_t read;
1294   gpgme_data_write_cb_t write;
1295   gpgme_data_seek_cb_t seek;
1296   gpgme_data_release_cb_t release;
1297 };
1298 typedef struct gpgme_data_cbs *gpgme_data_cbs_t;
1299
1300 /* Read up to SIZE bytes into buffer BUFFER from the data object with
1301    the handle DH.  Return the number of characters read, 0 on EOF and
1302    -1 on error.  If an error occurs, errno is set.  */
1303 @API__SSIZE_T@ gpgme_data_read (gpgme_data_t dh, void *buffer, size_t size);
1304
1305 /* Write up to SIZE bytes from buffer BUFFER to the data object with
1306    the handle DH.  Return the number of characters written, or -1 on
1307    error.  If an error occurs, errno is set.  */
1308 @API__SSIZE_T@ gpgme_data_write (gpgme_data_t dh, const void *buffer, size_t size);
1309
1310 /* Set the current position from where the next read or write starts
1311    in the data object with the handle DH to OFFSET, relativ to WHENCE.
1312    Returns the new offset in bytes from the beginning of the data
1313    object.  */
1314 @API__OFF_T@ gpgme_data_seek (gpgme_data_t dh, @API__OFF_T@ offset, int whence);
1315
1316 /* Create a new data buffer and return it in R_DH.  */
1317 gpgme_error_t gpgme_data_new (gpgme_data_t *r_dh);
1318
1319 /* Destroy the data buffer DH.  */
1320 void gpgme_data_release (gpgme_data_t dh);
1321
1322 /* Create a new data buffer filled with SIZE bytes starting from
1323    BUFFER.  If COPY is zero, copying is delayed until necessary, and
1324    the data is taken from the original location when needed.  */
1325 gpgme_error_t gpgme_data_new_from_mem (gpgme_data_t *r_dh,
1326                                        const char *buffer, size_t size,
1327                                        int copy);
1328
1329 /* Destroy the data buffer DH and return a pointer to its content.
1330    The memory has be to released with gpgme_free() by the user.  It's
1331    size is returned in R_LEN.  */
1332 char *gpgme_data_release_and_get_mem (gpgme_data_t dh, size_t *r_len);
1333
1334 /* Release the memory returned by gpgme_data_release_and_get_mem() and
1335    some other functions.  */
1336 void gpgme_free (void *buffer);
1337
1338 gpgme_error_t gpgme_data_new_from_cbs (gpgme_data_t *dh,
1339                                        gpgme_data_cbs_t cbs,
1340                                        void *handle);
1341
1342 gpgme_error_t gpgme_data_new_from_fd (gpgme_data_t *dh, int fd);
1343
1344 gpgme_error_t gpgme_data_new_from_stream (gpgme_data_t *dh, FILE *stream);
1345
1346 /* Return the encoding attribute of the data buffer DH */
1347 gpgme_data_encoding_t gpgme_data_get_encoding (gpgme_data_t dh);
1348
1349 /* Set the encoding attribute of data buffer DH to ENC */
1350 gpgme_error_t gpgme_data_set_encoding (gpgme_data_t dh,
1351                                        gpgme_data_encoding_t enc);
1352
1353 /* Get the file name associated with the data object with handle DH, or
1354    NULL if there is none.  */
1355 char *gpgme_data_get_file_name (gpgme_data_t dh);
1356
1357 /* Set the file name associated with the data object with handle DH to
1358    FILE_NAME.  */
1359 gpgme_error_t gpgme_data_set_file_name (gpgme_data_t dh,
1360                                         const char *file_name);
1361
1362 /* Set a flag for the data object DH.  See the manual for details.  */
1363 gpg_error_t gpgme_data_set_flag (gpgme_data_t dh,
1364                                  const char *name, const char *value);
1365
1366 /* Try to identify the type of the data in DH.  */
1367 gpgme_data_type_t gpgme_data_identify (gpgme_data_t dh, int reserved);
1368
1369
1370 /* Create a new data buffer which retrieves the data from the callback
1371    function READ_CB.  Deprecated, please use gpgme_data_new_from_cbs
1372    instead.  */
1373 gpgme_error_t gpgme_data_new_with_read_cb (gpgme_data_t *r_dh,
1374                                            int (*read_cb) (void*,char *,
1375                                                            size_t,size_t*),
1376                                            void *read_cb_value)
1377      _GPGME_DEPRECATED(0,4);
1378
1379 /* Create a new data buffer filled with the content of file FNAME.
1380    COPY must be non-zero.  For delayed read, please use
1381    gpgme_data_new_from_fd or gpgme_data_new_from_stream instead.  */
1382 gpgme_error_t gpgme_data_new_from_file (gpgme_data_t *r_dh,
1383                                         const char *fname,
1384                                         int copy);
1385
1386 /* Create a new data buffer filled with LENGTH bytes starting from
1387    OFFSET within the file FNAME or stream FP (exactly one must be
1388    non-zero).  */
1389 gpgme_error_t gpgme_data_new_from_filepart (gpgme_data_t *r_dh,
1390                                             const char *fname, FILE *fp,
1391                                             @API__OFF_T@ offset, size_t length);
1392
1393 /* Reset the read pointer in DH.  Deprecated, please use
1394    gpgme_data_seek instead.  */
1395 gpgme_error_t gpgme_data_rewind (gpgme_data_t dh) _GPGME_DEPRECATED(0,4);
1396
1397
1398 \f
1399 /*
1400  * Key and trust functions.
1401  */
1402
1403 /* Get the key with the fingerprint FPR from the crypto backend.  If
1404    SECRET is true, get the secret key.  */
1405 gpgme_error_t gpgme_get_key (gpgme_ctx_t ctx, const char *fpr,
1406                              gpgme_key_t *r_key, int secret);
1407
1408 /* Create a dummy key to specify an email address.  */
1409 gpgme_error_t gpgme_key_from_uid (gpgme_key_t *key, const char *name);
1410
1411 /* Acquire a reference to KEY.  */
1412 void gpgme_key_ref (gpgme_key_t key);
1413
1414 /* Release a reference to KEY.  If this was the last one the key is
1415    destroyed.  */
1416 void gpgme_key_unref (gpgme_key_t key);
1417 void gpgme_key_release (gpgme_key_t key);
1418
1419 /* Return the value of the attribute WHAT of KEY, which has to be
1420    representable by a string.  IDX specifies the sub key or user ID
1421    for attributes related to sub keys or user IDs.  Deprecated, use
1422    key structure directly instead. */
1423 const char *gpgme_key_get_string_attr (gpgme_key_t key, _gpgme_attr_t what,
1424                                        const void *reserved, int idx)
1425      _GPGME_DEPRECATED(0,4);
1426
1427 /* Return the value of the attribute WHAT of KEY, which has to be
1428    representable by an unsigned integer.  IDX specifies the sub key or
1429    user ID for attributes related to sub keys or user IDs.
1430    Deprecated, use key structure directly instead.  */
1431 unsigned long gpgme_key_get_ulong_attr (gpgme_key_t key, _gpgme_attr_t what,
1432                                         const void *reserved, int idx)
1433      _GPGME_DEPRECATED(0,4);
1434
1435 /* Return the value of the attribute WHAT of a signature on user ID
1436    UID_IDX in KEY, which has to be representable by a string.  IDX
1437    specifies the signature.  Deprecated, use key structure directly
1438    instead.  */
1439 const char *gpgme_key_sig_get_string_attr (gpgme_key_t key, int uid_idx,
1440                                            _gpgme_attr_t what,
1441                                            const void *reserved, int idx)
1442      _GPGME_DEPRECATED(0,4);
1443
1444 /* Return the value of the attribute WHAT of a signature on user ID
1445    UID_IDX in KEY, which has to be representable by an unsigned
1446    integer string.  IDX specifies the signature.  Deprecated, use key
1447    structure directly instead.  */
1448 unsigned long gpgme_key_sig_get_ulong_attr (gpgme_key_t key, int uid_idx,
1449                                             _gpgme_attr_t what,
1450                                             const void *reserved, int idx)
1451      _GPGME_DEPRECATED(0,4);
1452
1453
1454 \f
1455 /*
1456  * Encryption.
1457  */
1458
1459 struct _gpgme_op_encrypt_result
1460 {
1461   /* The list of invalid recipients.  */
1462   gpgme_invalid_key_t invalid_recipients;
1463 };
1464 typedef struct _gpgme_op_encrypt_result *gpgme_encrypt_result_t;
1465
1466 /* Retrieve a pointer to the result of the encrypt operation.  */
1467 gpgme_encrypt_result_t gpgme_op_encrypt_result (gpgme_ctx_t ctx);
1468
1469 /* The valid encryption flags.  */
1470 typedef enum
1471   {
1472     GPGME_ENCRYPT_ALWAYS_TRUST = 1,
1473     GPGME_ENCRYPT_NO_ENCRYPT_TO = 2,
1474     GPGME_ENCRYPT_PREPARE = 4,
1475     GPGME_ENCRYPT_EXPECT_SIGN = 8,
1476     GPGME_ENCRYPT_NO_COMPRESS = 16,
1477     GPGME_ENCRYPT_SYMMETRIC = 32
1478   }
1479 gpgme_encrypt_flags_t;
1480
1481 /* Encrypt plaintext PLAIN within CTX for the recipients RECP and
1482    store the resulting ciphertext in CIPHER.  */
1483 gpgme_error_t gpgme_op_encrypt_start (gpgme_ctx_t ctx, gpgme_key_t recp[],
1484                                       gpgme_encrypt_flags_t flags,
1485                                       gpgme_data_t plain, gpgme_data_t cipher);
1486 gpgme_error_t gpgme_op_encrypt (gpgme_ctx_t ctx, gpgme_key_t recp[],
1487                                 gpgme_encrypt_flags_t flags,
1488                                 gpgme_data_t plain, gpgme_data_t cipher);
1489
1490 /* Encrypt plaintext PLAIN within CTX for the recipients RECP and
1491    store the resulting ciphertext in CIPHER.  Also sign the ciphertext
1492    with the signers in CTX.  */
1493 gpgme_error_t gpgme_op_encrypt_sign_start (gpgme_ctx_t ctx,
1494                                            gpgme_key_t recp[],
1495                                            gpgme_encrypt_flags_t flags,
1496                                            gpgme_data_t plain,
1497                                            gpgme_data_t cipher);
1498 gpgme_error_t gpgme_op_encrypt_sign (gpgme_ctx_t ctx, gpgme_key_t recp[],
1499                                      gpgme_encrypt_flags_t flags,
1500                                      gpgme_data_t plain, gpgme_data_t cipher);
1501
1502 \f
1503 /*
1504  * Decryption.
1505  */
1506
1507 struct _gpgme_recipient
1508 {
1509   struct _gpgme_recipient *next;
1510
1511   /* The key ID of key for which the text was encrypted.  */
1512   char *keyid;
1513
1514   /* Internal to GPGME, do not use.  */
1515   char _keyid[16 + 1];
1516
1517   /* The public key algorithm of the recipient key.  */
1518   gpgme_pubkey_algo_t pubkey_algo;
1519
1520   /* The status of the recipient.  */
1521   gpgme_error_t status;
1522 };
1523 typedef struct _gpgme_recipient *gpgme_recipient_t;
1524
1525 struct _gpgme_op_decrypt_result
1526 {
1527   char *unsupported_algorithm;
1528
1529   /* Key should not have been used for encryption.  */
1530   unsigned int wrong_key_usage : 1;
1531
1532   /* Internal to GPGME, do not use.  */
1533   int _unused : 31;
1534
1535   gpgme_recipient_t recipients;
1536
1537   /* The original file name of the plaintext message, if
1538      available.  */
1539   char *file_name;
1540
1541   /* A textual representation of the session key used to decrypt the
1542    * message, if available */
1543   char *session_key;
1544 };
1545 typedef struct _gpgme_op_decrypt_result *gpgme_decrypt_result_t;
1546
1547 /* Retrieve a pointer to the result of the decrypt operation.  */
1548 gpgme_decrypt_result_t gpgme_op_decrypt_result (gpgme_ctx_t ctx);
1549
1550 /* Decrypt ciphertext CIPHER within CTX and store the resulting
1551    plaintext in PLAIN.  */
1552 gpgme_error_t gpgme_op_decrypt_start (gpgme_ctx_t ctx, gpgme_data_t cipher,
1553                                       gpgme_data_t plain);
1554 gpgme_error_t gpgme_op_decrypt (gpgme_ctx_t ctx,
1555                                 gpgme_data_t cipher, gpgme_data_t plain);
1556
1557 /* Decrypt ciphertext CIPHER and make a signature verification within
1558    CTX and store the resulting plaintext in PLAIN.  */
1559 gpgme_error_t gpgme_op_decrypt_verify_start (gpgme_ctx_t ctx,
1560                                              gpgme_data_t cipher,
1561                                              gpgme_data_t plain);
1562 gpgme_error_t gpgme_op_decrypt_verify (gpgme_ctx_t ctx, gpgme_data_t cipher,
1563                                        gpgme_data_t plain);
1564
1565 \f
1566 /*
1567  * Signing.
1568  */
1569
1570 struct _gpgme_new_signature
1571 {
1572   struct _gpgme_new_signature *next;
1573
1574   /* The type of the signature.  */
1575   gpgme_sig_mode_t type;
1576
1577   /* The public key algorithm used to create the signature.  */
1578   gpgme_pubkey_algo_t pubkey_algo;
1579
1580   /* The hash algorithm used to create the signature.  */
1581   gpgme_hash_algo_t hash_algo;
1582
1583   /* Internal to GPGME, do not use.  Must be set to the same value as
1584      CLASS below.  */
1585   unsigned long _obsolete_class;
1586
1587   /* Signature creation time.  */
1588   long int timestamp;
1589
1590   /* The fingerprint of the signature.  */
1591   char *fpr;
1592
1593 #ifdef __cplusplus
1594   unsigned int _obsolete_class_2;
1595 #else
1596   /* Must be set to SIG_CLASS below.  */
1597   unsigned int class _GPGME_DEPRECATED_OUTSIDE_GPGME(0,4);
1598 #endif
1599
1600   /* Crypto backend specific signature class.  */
1601   unsigned int sig_class;
1602 };
1603 typedef struct _gpgme_new_signature *gpgme_new_signature_t;
1604
1605 struct _gpgme_op_sign_result
1606 {
1607   /* The list of invalid signers.  */
1608   gpgme_invalid_key_t invalid_signers;
1609   gpgme_new_signature_t signatures;
1610 };
1611 typedef struct _gpgme_op_sign_result *gpgme_sign_result_t;
1612
1613 /* Retrieve a pointer to the result of the signing operation.  */
1614 gpgme_sign_result_t gpgme_op_sign_result (gpgme_ctx_t ctx);
1615
1616 /* Sign the plaintext PLAIN and store the signature in SIG.  */
1617 gpgme_error_t gpgme_op_sign_start (gpgme_ctx_t ctx,
1618                                    gpgme_data_t plain, gpgme_data_t sig,
1619                                    gpgme_sig_mode_t mode);
1620 gpgme_error_t gpgme_op_sign (gpgme_ctx_t ctx,
1621                              gpgme_data_t plain, gpgme_data_t sig,
1622                              gpgme_sig_mode_t mode);
1623
1624 \f
1625 /*
1626  * Verify.
1627  */
1628
1629 /* Flags used for the SUMMARY field in a gpgme_signature_t.  */
1630 typedef enum
1631   {
1632     GPGME_SIGSUM_VALID       = 0x0001,  /* The signature is fully valid.  */
1633     GPGME_SIGSUM_GREEN       = 0x0002,  /* The signature is good.  */
1634     GPGME_SIGSUM_RED         = 0x0004,  /* The signature is bad.  */
1635     GPGME_SIGSUM_KEY_REVOKED = 0x0010,  /* One key has been revoked.  */
1636     GPGME_SIGSUM_KEY_EXPIRED = 0x0020,  /* One key has expired.  */
1637     GPGME_SIGSUM_SIG_EXPIRED = 0x0040,  /* The signature has expired.  */
1638     GPGME_SIGSUM_KEY_MISSING = 0x0080,  /* Can't verify: key missing.  */
1639     GPGME_SIGSUM_CRL_MISSING = 0x0100,  /* CRL not available.  */
1640     GPGME_SIGSUM_CRL_TOO_OLD = 0x0200,  /* Available CRL is too old.  */
1641     GPGME_SIGSUM_BAD_POLICY  = 0x0400,  /* A policy was not met.  */
1642     GPGME_SIGSUM_SYS_ERROR   = 0x0800,  /* A system error occurred.  */
1643     GPGME_SIGSUM_TOFU_CONFLICT=0x1000   /* Tofu conflict detected.  */
1644   }
1645 gpgme_sigsum_t;
1646
1647
1648 struct _gpgme_signature
1649 {
1650   struct _gpgme_signature *next;
1651
1652   /* A summary of the signature status.  */
1653   gpgme_sigsum_t summary;
1654
1655   /* The fingerprint of the signature.  This can be a subkey.  */
1656   char *fpr;
1657
1658   /* The status of the signature.  */
1659   gpgme_error_t status;
1660
1661   /* Notation data and policy URLs.  */
1662   gpgme_sig_notation_t notations;
1663
1664   /* Signature creation time.  */
1665   unsigned long timestamp;
1666
1667   /* Signature expiration time or 0.  */
1668   unsigned long exp_timestamp;
1669
1670   /* Key should not have been used for signing.  */
1671   unsigned int wrong_key_usage : 1;
1672
1673   /* PKA status: 0 = not available, 1 = bad, 2 = okay, 3 = RFU. */
1674   unsigned int pka_trust : 2;
1675
1676   /* Validity has been verified using the chain model. */
1677   unsigned int chain_model : 1;
1678
1679   /* Internal to GPGME, do not use.  */
1680   int _unused : 28;
1681
1682   gpgme_validity_t validity;
1683   gpgme_error_t validity_reason;
1684
1685   /* The public key algorithm used to create the signature.  */
1686   gpgme_pubkey_algo_t pubkey_algo;
1687
1688   /* The hash algorithm used to create the signature.  */
1689   gpgme_hash_algo_t hash_algo;
1690
1691   /* The mailbox from the PKA information or NULL. */
1692   char *pka_address;
1693
1694   /* If non-NULL, a possible incomplete key object with the data
1695    * available for the signature.  */
1696   gpgme_key_t key;
1697 };
1698 typedef struct _gpgme_signature *gpgme_signature_t;
1699
1700 struct _gpgme_op_verify_result
1701 {
1702   gpgme_signature_t signatures;
1703
1704   /* The original file name of the plaintext message, if
1705      available.  */
1706   char *file_name;
1707 };
1708 typedef struct _gpgme_op_verify_result *gpgme_verify_result_t;
1709
1710 /* Retrieve a pointer to the result of the verify operation.  */
1711 gpgme_verify_result_t gpgme_op_verify_result (gpgme_ctx_t ctx);
1712
1713 /* Verify within CTX that SIG is a valid signature for TEXT.  */
1714 gpgme_error_t gpgme_op_verify_start (gpgme_ctx_t ctx, gpgme_data_t sig,
1715                                      gpgme_data_t signed_text,
1716                                      gpgme_data_t plaintext);
1717 gpgme_error_t gpgme_op_verify (gpgme_ctx_t ctx, gpgme_data_t sig,
1718                                gpgme_data_t signed_text,
1719                                gpgme_data_t plaintext);
1720
1721 \f
1722 /*
1723  * Import/Export
1724  */
1725
1726 #define GPGME_IMPORT_NEW        1  /* The key was new.  */
1727 #define GPGME_IMPORT_UID        2  /* The key contained new user IDs.  */
1728 #define GPGME_IMPORT_SIG        4  /* The key contained new signatures.  */
1729 #define GPGME_IMPORT_SUBKEY     8  /* The key contained new sub keys.  */
1730 #define GPGME_IMPORT_SECRET    16  /* The key contained a secret key.  */
1731
1732
1733 struct _gpgme_import_status
1734 {
1735   struct _gpgme_import_status *next;
1736
1737   /* Fingerprint.  */
1738   char *fpr;
1739
1740   /* If a problem occurred, the reason why the key could not be
1741      imported.  Otherwise GPGME_No_Error.  */
1742   gpgme_error_t result;
1743
1744   /* The result of the import, the GPGME_IMPORT_* values bit-wise
1745      ORed.  0 means the key was already known and no new components
1746      have been added.  */
1747   unsigned int status;
1748 };
1749 typedef struct _gpgme_import_status *gpgme_import_status_t;
1750
1751 /* Import result object.  */
1752 struct _gpgme_op_import_result
1753 {
1754   /* Number of considered keys.  */
1755   int considered;
1756
1757   /* Keys without user ID.  */
1758   int no_user_id;
1759
1760   /* Imported keys.  */
1761   int imported;
1762
1763   /* Imported RSA keys.  */
1764   int imported_rsa;
1765
1766   /* Unchanged keys.  */
1767   int unchanged;
1768
1769   /* Number of new user ids.  */
1770   int new_user_ids;
1771
1772   /* Number of new sub keys.  */
1773   int new_sub_keys;
1774
1775   /* Number of new signatures.  */
1776   int new_signatures;
1777
1778   /* Number of new revocations.  */
1779   int new_revocations;
1780
1781   /* Number of secret keys read.  */
1782   int secret_read;
1783
1784   /* Number of secret keys imported.  */
1785   int secret_imported;
1786
1787   /* Number of secret keys unchanged.  */
1788   int secret_unchanged;
1789
1790   /* Number of new keys skipped.  */
1791   int skipped_new_keys;
1792
1793   /* Number of keys not imported.  */
1794   int not_imported;
1795
1796   /* List of keys for which an import was attempted.  */
1797   gpgme_import_status_t imports;
1798 };
1799 typedef struct _gpgme_op_import_result *gpgme_import_result_t;
1800
1801 /* Retrieve a pointer to the result of the import operation.  */
1802 gpgme_import_result_t gpgme_op_import_result (gpgme_ctx_t ctx);
1803
1804 /* Import the key in KEYDATA into the keyring.  */
1805 gpgme_error_t gpgme_op_import_start (gpgme_ctx_t ctx, gpgme_data_t keydata);
1806 gpgme_error_t gpgme_op_import (gpgme_ctx_t ctx, gpgme_data_t keydata);
1807 gpgme_error_t gpgme_op_import_ext (gpgme_ctx_t ctx, gpgme_data_t keydata,
1808                                    int *nr) _GPGME_DEPRECATED(0,4);
1809
1810 /* Import the keys from the array KEYS into the keyring.  */
1811 gpgme_error_t gpgme_op_import_keys_start (gpgme_ctx_t ctx, gpgme_key_t keys[]);
1812 gpgme_error_t gpgme_op_import_keys (gpgme_ctx_t ctx, gpgme_key_t keys[]);
1813
1814
1815 /* Export the keys found by PATTERN into KEYDATA.  */
1816 gpgme_error_t gpgme_op_export_start (gpgme_ctx_t ctx, const char *pattern,
1817                                      gpgme_export_mode_t mode,
1818                                      gpgme_data_t keydata);
1819 gpgme_error_t gpgme_op_export (gpgme_ctx_t ctx, const char *pattern,
1820                                gpgme_export_mode_t mode,
1821                                gpgme_data_t keydata);
1822
1823 gpgme_error_t gpgme_op_export_ext_start (gpgme_ctx_t ctx,
1824                                          const char *pattern[],
1825                                          gpgme_export_mode_t mode,
1826                                          gpgme_data_t keydata);
1827 gpgme_error_t gpgme_op_export_ext (gpgme_ctx_t ctx, const char *pattern[],
1828                                    gpgme_export_mode_t mode,
1829                                    gpgme_data_t keydata);
1830
1831 /* Export the keys from the array KEYS into KEYDATA.  */
1832 gpgme_error_t gpgme_op_export_keys_start (gpgme_ctx_t ctx,
1833                                           gpgme_key_t keys[],
1834                                           gpgme_export_mode_t mode,
1835                                           gpgme_data_t keydata);
1836 gpgme_error_t gpgme_op_export_keys (gpgme_ctx_t ctx,
1837                                     gpgme_key_t keys[],
1838                                     gpgme_export_mode_t mode,
1839                                     gpgme_data_t keydata);
1840
1841
1842 \f
1843 /*
1844  * Key generation.
1845  */
1846
1847 /* Flags for the key creation functions.  */
1848 #define GPGME_CREATE_SIGN       (1 << 0)  /* Allow usage: signing.     */
1849 #define GPGME_CREATE_ENCR       (1 << 1)  /* Allow usage: encryption.  */
1850 #define GPGME_CREATE_CERT       (1 << 2)  /* Allow usage: certification.  */
1851 #define GPGME_CREATE_AUTH       (1 << 3)  /* Allow usage: authentication.  */
1852 #define GPGME_CREATE_NOPASSWD   (1 << 7)  /* Create w/o passphrase.    */
1853 #define GPGME_CREATE_SELFSIGNED (1 << 8)  /* Create self-signed cert.  */
1854 #define GPGME_CREATE_NOSTORE    (1 << 9)  /* Do not store the key.     */
1855 #define GPGME_CREATE_WANTPUB    (1 << 10) /* Return the public key.    */
1856 #define GPGME_CREATE_WANTSEC    (1 << 11) /* Return the secret key.    */
1857 #define GPGME_CREATE_FORCE      (1 << 12) /* Force creation.           */
1858
1859 struct _gpgme_op_genkey_result
1860 {
1861   /* A primary key was generated.  */
1862   unsigned int primary : 1;
1863
1864   /* A sub key was generated.  */
1865   unsigned int sub : 1;
1866
1867   /* A user id was generated.  */
1868   unsigned int uid : 1;
1869
1870   /* Internal to GPGME, do not use.  */
1871   unsigned int _unused : 29;
1872
1873   /* The fingerprint of the generated key.  */
1874   char *fpr;
1875
1876   /* A memory data object with the created public key.  Only set when
1877    * GPGME_CREATE_WANTPUB has been used. */
1878   gpgme_data_t pubkey;
1879
1880   /* A memory data object with the created secret key.  Only set when
1881    * GPGME_CREATE_WANTSEC has been used. */
1882   gpgme_data_t seckey;
1883 };
1884 typedef struct _gpgme_op_genkey_result *gpgme_genkey_result_t;
1885
1886 /* Generate a new keypair and add it to the keyring.  PUBKEY and
1887    SECKEY should be null for now.  PARMS specifies what keys should be
1888    generated.  */
1889 gpgme_error_t gpgme_op_genkey_start (gpgme_ctx_t ctx, const char *parms,
1890                                      gpgme_data_t pubkey, gpgme_data_t seckey);
1891 gpgme_error_t gpgme_op_genkey (gpgme_ctx_t ctx, const char *parms,
1892                                gpgme_data_t pubkey, gpgme_data_t seckey);
1893
1894 /* Generate a key pair using the modern interface.  */
1895 gpgme_error_t gpgme_op_createkey_start (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 gpgme_error_t gpgme_op_createkey       (gpgme_ctx_t ctx,
1903                                         const char *userid,
1904                                         const char *algo,
1905                                         unsigned long reserved,
1906                                         unsigned long expires,
1907                                         gpgme_key_t certkey,
1908                                         unsigned int flags);
1909 /* Add a new subkey to KEY.  */
1910 gpgme_error_t gpgme_op_createsubkey_start (gpgme_ctx_t ctx,
1911                                            gpgme_key_t key,
1912                                            const char *algo,
1913                                            unsigned long reserved,
1914                                            unsigned long expires,
1915                                            unsigned int flags);
1916 gpgme_error_t gpgme_op_createsubkey       (gpgme_ctx_t ctx,
1917                                            gpgme_key_t key,
1918                                            const char *algo,
1919                                            unsigned long reserved,
1920                                            unsigned long expires,
1921                                            unsigned int flags);
1922
1923 /* Add USERID to an existing KEY.  */
1924 gpgme_error_t gpgme_op_adduid_start (gpgme_ctx_t ctx,
1925                                      gpgme_key_t key, const char *userid,
1926                                      unsigned int reserved);
1927 gpgme_error_t gpgme_op_adduid       (gpgme_ctx_t ctx,
1928                                      gpgme_key_t key, const char *userid,
1929                                      unsigned int reserved);
1930
1931 /* Revoke a USERID from a KEY.  */
1932 gpgme_error_t gpgme_op_revuid_start (gpgme_ctx_t ctx,
1933                                      gpgme_key_t key, const char *userid,
1934                                      unsigned int reserved);
1935 gpgme_error_t gpgme_op_revuid       (gpgme_ctx_t ctx,
1936                                      gpgme_key_t key, const char *userid,
1937                                      unsigned int reserved);
1938
1939
1940
1941 /* Retrieve a pointer to the result of a genkey, createkey, or
1942  * createsubkey operation.  */
1943 gpgme_genkey_result_t gpgme_op_genkey_result (gpgme_ctx_t ctx);
1944
1945
1946 /* Delete KEY from the keyring.  If ALLOW_SECRET is non-zero, secret
1947    keys are also deleted.  */
1948 gpgme_error_t gpgme_op_delete_start (gpgme_ctx_t ctx, const gpgme_key_t key,
1949                                      int allow_secret);
1950 gpgme_error_t gpgme_op_delete (gpgme_ctx_t ctx, const gpgme_key_t key,
1951                                int allow_secret);
1952
1953 \f
1954 /*
1955  * Key signing interface
1956  */
1957
1958 /* Flags for the key signing functions.  */
1959 #define GPGME_KEYSIGN_LOCAL     (1 << 7)  /* Create a local signature.  */
1960 #define GPGME_KEYSIGN_LFSEP     (1 << 8)  /* Indicate LF separated user ids. */
1961 #define GPGME_KEYSIGN_NOEXPIRE  (1 << 9)  /* Force no expiration.  */
1962
1963
1964 /* Sign the USERID of KEY using the current set of signers.  */
1965 gpgme_error_t gpgme_op_keysign_start (gpgme_ctx_t ctx,
1966                                       gpgme_key_t key, const char *userid,
1967                                       unsigned long expires,
1968                                       unsigned int flags);
1969 gpgme_error_t gpgme_op_keysign       (gpgme_ctx_t ctx,
1970                                       gpgme_key_t key, const char *userid,
1971                                       unsigned long expires,
1972                                       unsigned int flags);
1973
1974
1975
1976 \f
1977 /*
1978  * Key edit interface
1979  */
1980
1981 /* Flags to select the mode of the interact.  */
1982 #define GPGME_INTERACT_CARD   (1 << 0)  /* Use --card-edit mode. */
1983
1984
1985 /* Edit the KEY.  Send status and command requests to FNC and
1986    output of edit commands to OUT.  */
1987 gpgme_error_t gpgme_op_interact_start (gpgme_ctx_t ctx,
1988                                        gpgme_key_t key,
1989                                        unsigned int flags,
1990                                        gpgme_interact_cb_t fnc,
1991                                        void *fnc_value,
1992                                        gpgme_data_t out);
1993 gpgme_error_t gpgme_op_interact (gpgme_ctx_t ctx, gpgme_key_t key,
1994                                  unsigned int flags,
1995                                  gpgme_interact_cb_t fnc,
1996                                  void *fnc_value,
1997                                  gpgme_data_t out);
1998
1999 gpgme_error_t gpgme_op_edit_start (gpgme_ctx_t ctx, gpgme_key_t key,
2000                                    gpgme_edit_cb_t fnc, void *fnc_value,
2001                                    gpgme_data_t out) _GPGME_DEPRECATED(1,7);
2002 gpgme_error_t gpgme_op_edit       (gpgme_ctx_t ctx, gpgme_key_t key,
2003                                    gpgme_edit_cb_t fnc, void *fnc_value,
2004                                    gpgme_data_t out) _GPGME_DEPRECATED(1,7);
2005 gpgme_error_t gpgme_op_card_edit_start (gpgme_ctx_t ctx, gpgme_key_t key,
2006                                         gpgme_edit_cb_t fnc, void *fnc_value,
2007                                         gpgme_data_t out)
2008                                         _GPGME_DEPRECATED(1,7);
2009 gpgme_error_t gpgme_op_card_edit       (gpgme_ctx_t ctx, gpgme_key_t key,
2010                                         gpgme_edit_cb_t fnc, void *fnc_value,
2011                                         gpgme_data_t out)
2012                                         _GPGME_DEPRECATED(1,7);
2013
2014
2015 /* Set the Tofu policy of KEY to POLCIY.  */
2016 gpgme_error_t gpgme_op_tofu_policy_start (gpgme_ctx_t ctx,
2017                                           gpgme_key_t key,
2018                                           gpgme_tofu_policy_t policy);
2019 gpgme_error_t gpgme_op_tofu_policy       (gpgme_ctx_t ctx,
2020                                           gpgme_key_t key,
2021                                           gpgme_tofu_policy_t policy);
2022
2023
2024
2025 \f
2026 /*
2027  * Key listing
2028  */
2029
2030 struct _gpgme_op_keylist_result
2031 {
2032   unsigned int truncated : 1;
2033
2034   /* Internal to GPGME, do not use.  */
2035   unsigned int _unused : 31;
2036 };
2037 typedef struct _gpgme_op_keylist_result *gpgme_keylist_result_t;
2038
2039 /* Retrieve a pointer to the result of the key listing operation.  */
2040 gpgme_keylist_result_t gpgme_op_keylist_result (gpgme_ctx_t ctx);
2041
2042 /* Start a keylist operation within CTX, searching for keys which
2043    match PATTERN.  If SECRET_ONLY is true, only secret keys are
2044    returned.  */
2045 gpgme_error_t gpgme_op_keylist_start (gpgme_ctx_t ctx, const char *pattern,
2046                                       int secret_only);
2047 gpgme_error_t gpgme_op_keylist_ext_start (gpgme_ctx_t ctx,
2048                                           const char *pattern[],
2049                                           int secret_only, int reserved);
2050
2051 /* Return the next key from the keylist in R_KEY.  */
2052 gpgme_error_t gpgme_op_keylist_next (gpgme_ctx_t ctx, gpgme_key_t *r_key);
2053
2054 /* Terminate a pending keylist operation within CTX.  */
2055 gpgme_error_t gpgme_op_keylist_end (gpgme_ctx_t ctx);
2056
2057 /* Change the passphrase for KEY.  FLAGS is reserved for future use
2058    and must be passed as 0.  */
2059 gpgme_error_t gpgme_op_passwd_start (gpgme_ctx_t ctx, gpgme_key_t key,
2060                                      unsigned int flags);
2061 gpgme_error_t gpgme_op_passwd (gpgme_ctx_t ctx, gpgme_key_t key,
2062                                unsigned int flags);
2063
2064
2065 \f
2066 /*
2067  * Trust items and operations.
2068  */
2069
2070 struct _gpgme_trust_item
2071 {
2072   /* Internal to GPGME, do not use.  */
2073   unsigned int _refs;
2074
2075   /* The key ID to which the trust item belongs.  */
2076   char *keyid;
2077
2078   /* Internal to GPGME, do not use.  */
2079   char _keyid[16 + 1];
2080
2081   /* The type of the trust item, 1 refers to a key, 2 to a user ID.  */
2082   int type;
2083
2084   /* The trust level.  */
2085   int level;
2086
2087   /* The owner trust if TYPE is 1.  */
2088   char *owner_trust;
2089
2090   /* Internal to GPGME, do not use.  */
2091   char _owner_trust[2];
2092
2093   /* The calculated validity.  */
2094   char *validity;
2095
2096   /* Internal to GPGME, do not use.  */
2097   char _validity[2];
2098
2099   /* The user name if TYPE is 2.  */
2100   char *name;
2101 };
2102 typedef struct _gpgme_trust_item *gpgme_trust_item_t;
2103
2104 /* Start a trustlist operation within CTX, searching for trust items
2105    which match PATTERN.  */
2106 gpgme_error_t gpgme_op_trustlist_start (gpgme_ctx_t ctx,
2107                                         const char *pattern, int max_level);
2108
2109 /* Return the next trust item from the trustlist in R_ITEM.  */
2110 gpgme_error_t gpgme_op_trustlist_next (gpgme_ctx_t ctx,
2111                                        gpgme_trust_item_t *r_item);
2112
2113 /* Terminate a pending trustlist operation within CTX.  */
2114 gpgme_error_t gpgme_op_trustlist_end (gpgme_ctx_t ctx);
2115
2116 /* Acquire a reference to ITEM.  */
2117 void gpgme_trust_item_ref (gpgme_trust_item_t item);
2118
2119 /* Release a reference to ITEM.  If this was the last one the trust
2120    item is destroyed.  */
2121 void gpgme_trust_item_unref (gpgme_trust_item_t item);
2122
2123 /* Release the trust item ITEM.  Deprecated, use
2124    gpgme_trust_item_unref.  */
2125 void gpgme_trust_item_release (gpgme_trust_item_t item) _GPGME_DEPRECATED(0,4);
2126
2127 /* Return the value of the attribute WHAT of ITEM, which has to be
2128    representable by a string.  Deprecated, use trust item structure
2129    directly.  */
2130 const char *gpgme_trust_item_get_string_attr (gpgme_trust_item_t item,
2131                                               _gpgme_attr_t what,
2132                                               const void *reserved, int idx)
2133      _GPGME_DEPRECATED(0,4);
2134
2135 /* Return the value of the attribute WHAT of KEY, which has to be
2136    representable by an integer.  IDX specifies a running index if the
2137    attribute appears more than once in the key.  Deprecated, use trust
2138    item structure directly.  */
2139 int gpgme_trust_item_get_int_attr (gpgme_trust_item_t item, _gpgme_attr_t what,
2140                                    const void *reserved, int idx)
2141      _GPGME_DEPRECATED(0,4);
2142
2143
2144 \f
2145 /*
2146  * Audit log
2147  */
2148
2149 /* Return the auditlog for the current session.  This may be called
2150    after a successful or failed operation.  If no audit log is
2151    available GPG_ERR_NO_DATA is returned.  */
2152 gpgme_error_t gpgme_op_getauditlog_start (gpgme_ctx_t ctx, gpgme_data_t output,
2153                                           unsigned int flags);
2154 gpgme_error_t gpgme_op_getauditlog (gpgme_ctx_t ctx, gpgme_data_t output,
2155                                     unsigned int flags);
2156
2157
2158 \f
2159 /*
2160  * Spawn interface
2161  */
2162
2163 /* Flags for the spawn operations.  */
2164 #define GPGME_SPAWN_DETACHED      1
2165 #define GPGME_SPAWN_ALLOW_SET_FG  2
2166
2167
2168 /* Run the command FILE with the arguments in ARGV.  Connect stdin to
2169    DATAIN, stdout to DATAOUT, and STDERR to DATAERR.  If one the data
2170    streams is NULL, connect to /dev/null instead.  */
2171 gpgme_error_t gpgme_op_spawn_start (gpgme_ctx_t ctx,
2172                                     const char *file, const char *argv[],
2173                                     gpgme_data_t datain,
2174                                     gpgme_data_t dataout, gpgme_data_t dataerr,
2175                                     unsigned int flags);
2176 gpgme_error_t gpgme_op_spawn (gpgme_ctx_t ctx,
2177                               const char *file, const char *argv[],
2178                               gpgme_data_t datain,
2179                               gpgme_data_t dataout, gpgme_data_t dataerr,
2180                               unsigned int flags);
2181
2182 \f
2183 /*
2184  * Low-level Assuan protocol access.
2185  */
2186 typedef gpgme_error_t (*gpgme_assuan_data_cb_t)
2187      (void *opaque, const void *data, size_t datalen);
2188
2189 typedef gpgme_error_t (*gpgme_assuan_inquire_cb_t)
2190      (void *opaque, const char *name, const char *args,
2191       gpgme_data_t *r_data);
2192
2193 typedef gpgme_error_t (*gpgme_assuan_status_cb_t)
2194      (void *opaque, const char *status, const char *args);
2195
2196 /* Send the Assuan COMMAND and return results via the callbacks.
2197    Asynchronous variant. */
2198 gpgme_error_t gpgme_op_assuan_transact_start (gpgme_ctx_t ctx,
2199                                               const char *command,
2200                                               gpgme_assuan_data_cb_t data_cb,
2201                                               void *data_cb_value,
2202                                               gpgme_assuan_inquire_cb_t inq_cb,
2203                                               void *inq_cb_value,
2204                                               gpgme_assuan_status_cb_t stat_cb,
2205                                               void *stat_cb_value);
2206
2207 /* Send the Assuan COMMAND and return results via the callbacks.
2208    Synchronous variant. */
2209 gpgme_error_t gpgme_op_assuan_transact_ext (gpgme_ctx_t ctx,
2210                                             const char *command,
2211                                             gpgme_assuan_data_cb_t data_cb,
2212                                             void *data_cb_value,
2213                                             gpgme_assuan_inquire_cb_t inq_cb,
2214                                             void *inq_cb_value,
2215                                             gpgme_assuan_status_cb_t stat_cb,
2216                                             void *stat_cb_value,
2217                                             gpgme_error_t *op_err);
2218
2219 /* Compat.  */
2220 struct _gpgme_op_assuan_result
2221 {
2222   /* Deprecated.  Use the second value in a DONE event or the
2223      synchronous variant gpgme_op_assuan_transact_ext.  */
2224   gpgme_error_t err _GPGME_DEPRECATED_OUTSIDE_GPGME(1,2);
2225 };
2226 typedef struct _gpgme_op_assuan_result *gpgme_assuan_result_t;
2227
2228
2229 /* Return the result of the last Assuan command. */
2230 gpgme_assuan_result_t gpgme_op_assuan_result (gpgme_ctx_t ctx)
2231   _GPGME_DEPRECATED(1,2);
2232
2233 gpgme_error_t
2234 gpgme_op_assuan_transact (gpgme_ctx_t ctx,
2235                               const char *command,
2236                               gpgme_assuan_data_cb_t data_cb,
2237                               void *data_cb_value,
2238                               gpgme_assuan_inquire_cb_t inq_cb,
2239                               void *inq_cb_value,
2240                               gpgme_assuan_status_cb_t status_cb,
2241                           void *status_cb_value) _GPGME_DEPRECATED(1,2);
2242
2243 \f
2244 /*
2245  * Crypto container support.
2246  */
2247
2248 struct _gpgme_op_vfs_mount_result
2249 {
2250   char *mount_dir;
2251 };
2252 typedef struct _gpgme_op_vfs_mount_result *gpgme_vfs_mount_result_t;
2253
2254 gpgme_vfs_mount_result_t gpgme_op_vfs_mount_result (gpgme_ctx_t ctx);
2255
2256 /* The container is automatically unmounted when the context is reset
2257    or destroyed.  Transmission errors are returned directly,
2258    operational errors are returned in OP_ERR.  */
2259 gpgme_error_t gpgme_op_vfs_mount (gpgme_ctx_t ctx, const char *container_file,
2260                                   const char *mount_dir, unsigned int flags,
2261                                   gpgme_error_t *op_err);
2262
2263 gpgme_error_t gpgme_op_vfs_create (gpgme_ctx_t ctx, gpgme_key_t recp[],
2264                                    const char *container_file,
2265                                    unsigned int flags, gpgme_error_t *op_err);
2266
2267 \f
2268 /*
2269  * Interface to gpgconf(1).
2270  */
2271
2272 /* The expert level at which a configuration option or group of
2273    options should be displayed.  See the gpgconf(1) documentation for
2274    more details.  */
2275 typedef enum
2276   {
2277     GPGME_CONF_BASIC = 0,
2278     GPGME_CONF_ADVANCED = 1,
2279     GPGME_CONF_EXPERT = 2,
2280     GPGME_CONF_INVISIBLE = 3,
2281     GPGME_CONF_INTERNAL = 4
2282   }
2283 gpgme_conf_level_t;
2284
2285
2286 /* The data type of a configuration option argument.  See the gpgconf(1)
2287    documentation for more details.  */
2288 typedef enum
2289   {
2290     /* Basic types.  */
2291     GPGME_CONF_NONE = 0,
2292     GPGME_CONF_STRING = 1,
2293     GPGME_CONF_INT32 = 2,
2294     GPGME_CONF_UINT32 = 3,
2295
2296     /* Complex types.  */
2297     GPGME_CONF_FILENAME = 32,
2298     GPGME_CONF_LDAP_SERVER = 33,
2299     GPGME_CONF_KEY_FPR = 34,
2300     GPGME_CONF_PUB_KEY = 35,
2301     GPGME_CONF_SEC_KEY = 36,
2302     GPGME_CONF_ALIAS_LIST = 37
2303   }
2304 gpgme_conf_type_t;
2305
2306 /* For now, compatibility.  */
2307 #define GPGME_CONF_PATHNAME GPGME_CONF_FILENAME
2308
2309
2310 /* This represents a single argument for a configuration option.
2311    Which of the members of value is used depends on the ALT_TYPE.  */
2312 typedef struct gpgme_conf_arg
2313 {
2314   struct gpgme_conf_arg *next;
2315   /* True if the option appears without an (optional) argument.  */
2316   unsigned int no_arg;
2317   union
2318   {
2319     unsigned int count;
2320     unsigned int uint32;
2321     int int32;
2322     char *string;
2323   } value;
2324 } *gpgme_conf_arg_t;
2325
2326
2327 /* The flags of a configuration option.  See the gpgconf
2328    documentation for details.  */
2329 #define GPGME_CONF_GROUP        (1 << 0)
2330 #define GPGME_CONF_OPTIONAL     (1 << 1)
2331 #define GPGME_CONF_LIST         (1 << 2)
2332 #define GPGME_CONF_RUNTIME      (1 << 3)
2333 #define GPGME_CONF_DEFAULT      (1 << 4)
2334 #define GPGME_CONF_DEFAULT_DESC (1 << 5)
2335 #define GPGME_CONF_NO_ARG_DESC  (1 << 6)
2336 #define GPGME_CONF_NO_CHANGE    (1 << 7)
2337
2338
2339 /* The representation of a single configuration option.  See the
2340    gpg-conf documentation for details.  */
2341 typedef struct gpgme_conf_opt
2342 {
2343   struct gpgme_conf_opt *next;
2344
2345   /* The option name.  */
2346   char *name;
2347
2348   /* The flags for this option.  */
2349   unsigned int flags;
2350
2351   /* The level of this option.  */
2352   gpgme_conf_level_t level;
2353
2354   /* The localized description of this option.  */
2355   char *description;
2356
2357   /* The type and alternate type of this option.  */
2358   gpgme_conf_type_t type;
2359   gpgme_conf_type_t alt_type;
2360
2361   /* The localized (short) name of the argument, if any.  */
2362   char *argname;
2363
2364   /* The default value.  */
2365   gpgme_conf_arg_t default_value;
2366   char *default_description;
2367
2368   /* The default value if the option is not set.  */
2369   gpgme_conf_arg_t no_arg_value;
2370   char *no_arg_description;
2371
2372   /* The current value if the option is set.  */
2373   gpgme_conf_arg_t value;
2374
2375   /* The new value, if any.  NULL means reset to default.  */
2376   int change_value;
2377   gpgme_conf_arg_t new_value;
2378
2379   /* Free for application use.  */
2380   void *user_data;
2381 } *gpgme_conf_opt_t;
2382
2383
2384 /* The representation of a component that can be configured.  See the
2385    gpg-conf documentation for details.  */
2386 typedef struct gpgme_conf_comp
2387 {
2388   struct gpgme_conf_comp *next;
2389
2390   /* Internal to GPGME, do not use!  */
2391   gpgme_conf_opt_t *_last_opt_p;
2392
2393   /* The component name.  */
2394   char *name;
2395
2396   /* A human-readable description for the component.  */
2397   char *description;
2398
2399   /* The program name (an absolute path to the program).  */
2400   char *program_name;
2401
2402   /* A linked list of options for this component.  */
2403   struct gpgme_conf_opt *options;
2404 } *gpgme_conf_comp_t;
2405
2406
2407 /* Allocate a new gpgme_conf_arg_t.  If VALUE is NULL, a "no arg
2408    default" is prepared.  If type is a string type, VALUE should point
2409    to the string.  Else, it should point to an unsigned or signed
2410    integer respectively.  */
2411 gpgme_error_t gpgme_conf_arg_new (gpgme_conf_arg_t *arg_p,
2412                                   gpgme_conf_type_t type, const void *value);
2413
2414 /* This also releases all chained argument structures!  */
2415 void gpgme_conf_arg_release (gpgme_conf_arg_t arg, gpgme_conf_type_t type);
2416
2417 /* Register a change for the value of OPT to ARG.  If RESET is 1 (do
2418    not use any values but 0 or 1), ARG is ignored and the option is
2419    not changed (reverting a previous change).  Otherwise, if ARG is
2420    NULL, the option is cleared or reset to its default.  */
2421 gpgme_error_t gpgme_conf_opt_change (gpgme_conf_opt_t opt, int reset,
2422                                      gpgme_conf_arg_t arg);
2423
2424 /* Release a set of configurations.  */
2425 void gpgme_conf_release (gpgme_conf_comp_t conf);
2426
2427 /* Retrieve the current configurations.  */
2428 gpgme_error_t gpgme_op_conf_load (gpgme_ctx_t ctx, gpgme_conf_comp_t *conf_p);
2429
2430 /* Save the configuration of component comp.  This function does not
2431    follow chained components!  */
2432 gpgme_error_t gpgme_op_conf_save (gpgme_ctx_t ctx, gpgme_conf_comp_t comp);
2433
2434
2435 /* Information about software versions.  */
2436 typedef struct _gpgme_op_query_swdb_result
2437 {
2438   /* RFU */
2439   struct _gpgme_op_query_swdb_result *next;
2440
2441   /* The name of the package (e.g. "gpgme", "gnupg") */
2442   char *name;
2443
2444   /* The version number of the installed version.  */
2445   char *iversion;
2446
2447   /* The time the online info was created.  */
2448   unsigned long created;
2449
2450   /* The time the online info was retrieved.  */
2451   unsigned long retrieved;
2452
2453   /* This bit is set if an error occured or some of the information
2454    * in this structure may not be set.  */
2455   unsigned int warning : 1;
2456
2457   /* An update is available.  */
2458   unsigned int update : 1;
2459
2460   /* The update is important.  */
2461   unsigned int urgent : 1;
2462
2463   /* No information at all available.  */
2464   unsigned int noinfo : 1;
2465
2466   /* The package name is not known. */
2467   unsigned int unknown : 1;
2468
2469   /* The information here is too old.  */
2470   unsigned int tooold : 1;
2471
2472   /* Other error.  */
2473   unsigned int error : 1;
2474
2475   unsigned int _reserved : 25;
2476
2477   /* The version number of the latest released version.  */
2478   char *version;
2479
2480   /* The release date of that version.  */
2481   unsigned long reldate;
2482
2483 } *gpgme_query_swdb_result_t;
2484
2485
2486 /* Run the gpgconf --query-swdb command.  */
2487 gpgme_error_t gpgme_op_query_swdb (gpgme_ctx_t ctx,
2488                                    const char *name, const char *iversion,
2489                                    unsigned int reserved);
2490
2491 /* Return the result from the last query_swdb operation.  */
2492 gpgme_query_swdb_result_t gpgme_op_query_swdb_result (gpgme_ctx_t ctx);
2493
2494
2495
2496 \f
2497 /*
2498  * Various functions.
2499  */
2500
2501 /* Set special global flags; consult the manual before use.  */
2502 int gpgme_set_global_flag (const char *name, const char *value);
2503
2504 /* Check that the library fulfills the version requirement.  Note:
2505    This is here only for the case where a user takes a pointer from
2506    the old version of this function.  The new version and macro for
2507    run-time checks are below.  */
2508 const char *gpgme_check_version (const char *req_version);
2509
2510 /* Check that the library fulfills the version requirement and check
2511    for struct layout mismatch involving bitfields.  */
2512 const char *gpgme_check_version_internal (const char *req_version,
2513                                           size_t offset_sig_validity);
2514
2515 #define gpgme_check_version(req_version)                                \
2516   gpgme_check_version_internal (req_version,                            \
2517                                 offsetof (struct _gpgme_signature, validity))
2518
2519 /* Return the default values for various directories.  */
2520 const char *gpgme_get_dirinfo (const char *what);
2521
2522 /* Get the information about the configured and installed engines.  A
2523    pointer to the first engine in the statically allocated linked list
2524    is returned in *INFO.  If an error occurs, it is returned.  The
2525    returned data is valid until the next gpgme_set_engine_info.  */
2526 gpgme_error_t gpgme_get_engine_info (gpgme_engine_info_t *engine_info);
2527
2528 /* Set the default engine info for the protocol PROTO to the file name
2529    FILE_NAME and the home directory HOME_DIR.  */
2530 gpgme_error_t gpgme_set_engine_info (gpgme_protocol_t proto,
2531                                      const char *file_name,
2532                                      const char *home_dir);
2533
2534 /* Verify that the engine implementing PROTO is installed and
2535    available.  */
2536 gpgme_error_t gpgme_engine_check_version (gpgme_protocol_t proto);
2537
2538
2539 /* Reference counting for result objects.  */
2540 void gpgme_result_ref (void *result);
2541 void gpgme_result_unref (void *result);
2542
2543 /* Return a public key algorithm string (e.g. "rsa2048").  Caller must
2544    free using gpgme_free.  */
2545 char *gpgme_pubkey_algo_string (gpgme_subkey_t subkey);
2546
2547 /* Return a statically allocated string with the name of the public
2548    key algorithm ALGO, or NULL if that name is not known.  */
2549 const char *gpgme_pubkey_algo_name (gpgme_pubkey_algo_t algo);
2550
2551 /* Return a statically allocated string with the name of the hash
2552    algorithm ALGO, or NULL if that name is not known.  */
2553 const char *gpgme_hash_algo_name (gpgme_hash_algo_t algo);
2554
2555 /* Return the addr-spec from a user id.  Caller must free the result
2556  * with gpgme_free. */
2557 char *gpgme_addrspec_from_uid (const char *uid);
2558
2559
2560 \f
2561 /*
2562  * Deprecated types.
2563  */
2564 typedef gpgme_ctx_t GpgmeCtx _GPGME_DEPRECATED(0,4);
2565 typedef gpgme_data_t GpgmeData _GPGME_DEPRECATED(0,4);
2566 typedef gpgme_error_t GpgmeError _GPGME_DEPRECATED(0,4);
2567 typedef gpgme_data_encoding_t GpgmeDataEncoding _GPGME_DEPRECATED(0,4);
2568 typedef gpgme_pubkey_algo_t GpgmePubKeyAlgo _GPGME_DEPRECATED(0,4);
2569 typedef gpgme_hash_algo_t GpgmeHashAlgo _GPGME_DEPRECATED(0,4);
2570 typedef gpgme_sig_stat_t GpgmeSigStat _GPGME_DEPRECATED(0,4);
2571 typedef gpgme_sig_mode_t GpgmeSigMode _GPGME_DEPRECATED(0,4);
2572 typedef gpgme_attr_t GpgmeAttr _GPGME_DEPRECATED(0,4);
2573 typedef gpgme_validity_t GpgmeValidity _GPGME_DEPRECATED(0,4);
2574 typedef gpgme_protocol_t GpgmeProtocol _GPGME_DEPRECATED(0,4);
2575 typedef gpgme_engine_info_t GpgmeEngineInfo _GPGME_DEPRECATED(0,4);
2576 typedef gpgme_subkey_t GpgmeSubkey _GPGME_DEPRECATED(0,4);
2577 typedef gpgme_key_sig_t GpgmeKeySig _GPGME_DEPRECATED(0,4);
2578 typedef gpgme_user_id_t GpgmeUserID _GPGME_DEPRECATED(0,4);
2579 typedef gpgme_key_t GpgmeKey _GPGME_DEPRECATED(0,4);
2580 typedef gpgme_passphrase_cb_t GpgmePassphraseCb _GPGME_DEPRECATED(0,4);
2581 typedef gpgme_progress_cb_t GpgmeProgressCb _GPGME_DEPRECATED(0,4);
2582 typedef gpgme_io_cb_t GpgmeIOCb _GPGME_DEPRECATED(0,4);
2583 typedef gpgme_register_io_cb_t GpgmeRegisterIOCb _GPGME_DEPRECATED(0,4);
2584 typedef gpgme_remove_io_cb_t GpgmeRemoveIOCb _GPGME_DEPRECATED(0,4);
2585 typedef gpgme_event_io_t GpgmeEventIO _GPGME_DEPRECATED(0,4);
2586 typedef gpgme_event_io_cb_t GpgmeEventIOCb _GPGME_DEPRECATED(0,4);
2587 #define GpgmeIOCbs gpgme_io_cbs
2588 typedef gpgme_data_read_cb_t GpgmeDataReadCb _GPGME_DEPRECATED(0,4);
2589 typedef gpgme_data_write_cb_t GpgmeDataWriteCb _GPGME_DEPRECATED(0,4);
2590 typedef gpgme_data_seek_cb_t GpgmeDataSeekCb _GPGME_DEPRECATED(0,4);
2591 typedef gpgme_data_release_cb_t GpgmeDataReleaseCb _GPGME_DEPRECATED(0,4);
2592 #define GpgmeDataCbs gpgme_data_cbs
2593 typedef gpgme_encrypt_result_t GpgmeEncryptResult _GPGME_DEPRECATED(0,4);
2594 typedef gpgme_sig_notation_t GpgmeSigNotation _GPGME_DEPRECATED(0,4);
2595 typedef gpgme_signature_t GpgmeSignature _GPGME_DEPRECATED(0,4);
2596 typedef gpgme_verify_result_t GpgmeVerifyResult _GPGME_DEPRECATED(0,4);
2597 typedef gpgme_import_status_t GpgmeImportStatus _GPGME_DEPRECATED(0,4);
2598 typedef gpgme_import_result_t GpgmeImportResult _GPGME_DEPRECATED(0,4);
2599 typedef gpgme_genkey_result_t GpgmeGenKeyResult _GPGME_DEPRECATED(0,4);
2600 typedef gpgme_trust_item_t GpgmeTrustItem _GPGME_DEPRECATED(0,4);
2601 typedef gpgme_status_code_t GpgmeStatusCode _GPGME_DEPRECATED(0,4);
2602
2603 #ifdef __cplusplus
2604 }
2605 #endif
2606 #endif /* GPGME_H */
2607 /*
2608 @emacs_local_vars_begin@
2609 @emacs_local_vars_read_only@
2610 @emacs_local_vars_end@
2611 */