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