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