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