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