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