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