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