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