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