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