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