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