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