Add public function gpgme_get_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 /* Get the pinentry mode of CTX.  */
879 gpgme_pinentry_mode_t gpgme_get_pinentry_mode (gpgme_ctx_t ctx);
880
881 /* Set the passphrase callback function in CTX to CB.  HOOK_VALUE is
882    passed as first argument to the passphrase callback function.  */
883 void gpgme_set_passphrase_cb (gpgme_ctx_t ctx,
884                               gpgme_passphrase_cb_t cb, void *hook_value);
885
886 /* Get the current passphrase callback function in *CB and the current
887    hook value in *HOOK_VALUE.  */
888 void gpgme_get_passphrase_cb (gpgme_ctx_t ctx, gpgme_passphrase_cb_t *cb,
889                               void **hook_value);
890
891 /* Set the progress callback function in CTX to CB.  HOOK_VALUE is
892    passed as first argument to the progress callback function.  */
893 void gpgme_set_progress_cb (gpgme_ctx_t c, gpgme_progress_cb_t cb,
894                             void *hook_value);
895
896 /* Get the current progress callback function in *CB and the current
897    hook value in *HOOK_VALUE.  */
898 void gpgme_get_progress_cb (gpgme_ctx_t ctx, gpgme_progress_cb_t *cb,
899                             void **hook_value);
900
901 /* This function sets the locale for the context CTX, or the default
902    locale if CTX is a null pointer.  */
903 gpgme_error_t gpgme_set_locale (gpgme_ctx_t ctx, int category,
904                                 const char *value);
905
906 /* Get the information about the configured engines.  A pointer to the
907    first engine in the statically allocated linked list is returned.
908    The returned data is valid until the next gpgme_ctx_set_engine_info.  */
909 gpgme_engine_info_t gpgme_ctx_get_engine_info (gpgme_ctx_t ctx);
910
911 /* Set the engine info for the context CTX, protocol PROTO, to the
912    file name FILE_NAME and the home directory HOME_DIR.  */
913 gpgme_error_t gpgme_ctx_set_engine_info (gpgme_ctx_t ctx,
914                                          gpgme_protocol_t proto,
915                                          const char *file_name,
916                                          const char *home_dir);
917
918 \f
919 /* Return a statically allocated string with the name of the public
920    key algorithm ALGO, or NULL if that name is not known.  */
921 const char *gpgme_pubkey_algo_name (gpgme_pubkey_algo_t algo);
922
923 /* Return a statically allocated string with the name of the hash
924    algorithm ALGO, or NULL if that name is not known.  */
925 const char *gpgme_hash_algo_name (gpgme_hash_algo_t algo);
926
927 \f
928 /* Delete all signers from CTX.  */
929 void gpgme_signers_clear (gpgme_ctx_t ctx);
930
931 /* Add KEY to list of signers in CTX.  */
932 gpgme_error_t gpgme_signers_add (gpgme_ctx_t ctx, const gpgme_key_t key);
933
934 /* Return the SEQth signer's key in CTX.  */
935 gpgme_key_t gpgme_signers_enum (const gpgme_ctx_t ctx, int seq);
936
937 /* Retrieve the signature status of signature IDX in CTX after a
938    successful verify operation in R_STAT (if non-null).  The creation
939    time stamp of the signature is returned in R_CREATED (if non-null).
940    The function returns a string containing the fingerprint.
941    Deprecated, use verify result directly.  */
942 const char *gpgme_get_sig_status (gpgme_ctx_t ctx, int idx,
943                                   _gpgme_sig_stat_t *r_stat,
944                                   time_t *r_created) _GPGME_DEPRECATED;
945
946 /* Retrieve certain attributes of a signature.  IDX is the index
947    number of the signature after a successful verify operation.  WHAT
948    is an attribute where GPGME_ATTR_EXPIRE is probably the most useful
949    one.  WHATIDX is to be passed as 0 for most attributes . */
950 unsigned long gpgme_get_sig_ulong_attr (gpgme_ctx_t c, int idx,
951                                         _gpgme_attr_t what, int whatidx)
952      _GPGME_DEPRECATED;
953 const char *gpgme_get_sig_string_attr (gpgme_ctx_t c, int idx,
954                                        _gpgme_attr_t what, int whatidx)
955      _GPGME_DEPRECATED;
956
957
958 /* Get the key used to create signature IDX in CTX and return it in
959    R_KEY.  */
960 gpgme_error_t gpgme_get_sig_key (gpgme_ctx_t ctx, int idx, gpgme_key_t *r_key)
961      _GPGME_DEPRECATED;
962
963 \f
964 /* Clear all notation data from the context.  */
965 void gpgme_sig_notation_clear (gpgme_ctx_t ctx);
966
967 /* Add the human-readable notation data with name NAME and value VALUE
968    to the context CTX, using the flags FLAGS.  If NAME is NULL, then
969    VALUE should be a policy URL.  The flag
970    GPGME_SIG_NOTATION_HUMAN_READABLE is forced to be true for notation
971    data, and false for policy URLs.  */
972 gpgme_error_t gpgme_sig_notation_add (gpgme_ctx_t ctx, const char *name,
973                                       const char *value,
974                                       gpgme_sig_notation_flags_t flags);
975
976 /* Get the sig notations for this context.  */
977 gpgme_sig_notation_t gpgme_sig_notation_get (gpgme_ctx_t ctx);
978
979 \f
980 /* Run control.  */
981
982 /* The type of an I/O callback function.  */
983 typedef gpgme_error_t (*gpgme_io_cb_t) (void *data, int fd);
984
985 /* The type of a function that can register FNC as the I/O callback
986    function for the file descriptor FD with direction dir (0: for writing,
987    1: for reading).  FNC_DATA should be passed as DATA to FNC.  The
988    function should return a TAG suitable for the corresponding
989    gpgme_remove_io_cb_t, and an error value.  */
990 typedef gpgme_error_t (*gpgme_register_io_cb_t) (void *data, int fd, int dir,
991                                                  gpgme_io_cb_t fnc,
992                                                  void *fnc_data, void **tag);
993
994 /* The type of a function that can remove a previously registered I/O
995    callback function given TAG as returned by the register
996    function.  */
997 typedef void (*gpgme_remove_io_cb_t) (void *tag);
998
999 typedef enum
1000   {
1001     GPGME_EVENT_START,
1002     GPGME_EVENT_DONE,
1003     GPGME_EVENT_NEXT_KEY,
1004     GPGME_EVENT_NEXT_TRUSTITEM
1005   }
1006 gpgme_event_io_t;
1007
1008 struct gpgme_io_event_done_data
1009 {
1010   /* A fatal IPC error or an operational error in state-less
1011      protocols.  */
1012   gpgme_error_t err;
1013
1014   /* An operational errors in session-based protocols.  */
1015   gpgme_error_t op_err;
1016 };
1017 typedef struct gpgme_io_event_done_data *gpgme_io_event_done_data_t;
1018
1019 /* The type of a function that is called when a context finished an
1020    operation.  */
1021 typedef void (*gpgme_event_io_cb_t) (void *data, gpgme_event_io_t type,
1022                                      void *type_data);
1023
1024 struct gpgme_io_cbs
1025 {
1026   gpgme_register_io_cb_t add;
1027   void *add_priv;
1028   gpgme_remove_io_cb_t remove;
1029   gpgme_event_io_cb_t event;
1030   void *event_priv;
1031 };
1032 typedef struct gpgme_io_cbs *gpgme_io_cbs_t;
1033
1034 /* Set the I/O callback functions in CTX to IO_CBS.  */
1035 void gpgme_set_io_cbs (gpgme_ctx_t ctx, gpgme_io_cbs_t io_cbs);
1036
1037 /* Get the current I/O callback functions.  */
1038 void gpgme_get_io_cbs (gpgme_ctx_t ctx, gpgme_io_cbs_t io_cbs);
1039
1040 /* Wrappers around the internal I/O functions for use with
1041    gpgme_passphrase_cb_t and gpgme_edit_cb_t.  */
1042 ssize_t gpgme_io_read (int fd, void *buffer, size_t count);
1043 ssize_t gpgme_io_write (int fd, const void *buffer, size_t count);
1044 int     gpgme_io_writen (int fd, const void *buffer, size_t count);
1045
1046 /* Process the pending operation and, if HANG is non-zero, wait for
1047    the pending operation to finish.  */
1048 gpgme_ctx_t gpgme_wait (gpgme_ctx_t ctx, gpgme_error_t *status, int hang);
1049
1050 gpgme_ctx_t gpgme_wait_ext (gpgme_ctx_t ctx, gpgme_error_t *status,
1051                             gpgme_error_t *op_err, int hang);
1052
1053 \f
1054 /* Functions to handle data objects.  */
1055
1056 /* Read up to SIZE bytes into buffer BUFFER from the data object with
1057    the handle HANDLE.  Return the number of characters read, 0 on EOF
1058    and -1 on error.  If an error occurs, errno is set.  */
1059 typedef ssize_t (*gpgme_data_read_cb_t) (void *handle, void *buffer,
1060                                          size_t size);
1061
1062 /* Write up to SIZE bytes from buffer BUFFER to the data object with
1063    the handle HANDLE.  Return the number of characters written, or -1
1064    on error.  If an error occurs, errno is set.  */
1065 typedef ssize_t (*gpgme_data_write_cb_t) (void *handle, const void *buffer,
1066                                           size_t size);
1067
1068 /* Set the current position from where the next read or write starts
1069    in the data object with the handle HANDLE to OFFSET, relativ to
1070    WHENCE.  */
1071 typedef off_t (*gpgme_data_seek_cb_t) (void *handle, off_t offset, int whence);
1072
1073 /* Close the data object with the handle DL.  */
1074 typedef void (*gpgme_data_release_cb_t) (void *handle);
1075
1076 struct gpgme_data_cbs
1077 {
1078   gpgme_data_read_cb_t read;
1079   gpgme_data_write_cb_t write;
1080   gpgme_data_seek_cb_t seek;
1081   gpgme_data_release_cb_t release;
1082 };
1083 typedef struct gpgme_data_cbs *gpgme_data_cbs_t;
1084
1085 /* Read up to SIZE bytes into buffer BUFFER from the data object with
1086    the handle DH.  Return the number of characters read, 0 on EOF and
1087    -1 on error.  If an error occurs, errno is set.  */
1088 ssize_t gpgme_data_read (gpgme_data_t dh, void *buffer, size_t size);
1089
1090 /* Write up to SIZE bytes from buffer BUFFER to the data object with
1091    the handle DH.  Return the number of characters written, or -1 on
1092    error.  If an error occurs, errno is set.  */
1093 ssize_t gpgme_data_write (gpgme_data_t dh, const void *buffer, size_t size);
1094
1095 /* Set the current position from where the next read or write starts
1096    in the data object with the handle DH to OFFSET, relativ to
1097    WHENCE.  */
1098 off_t gpgme_data_seek (gpgme_data_t dh, off_t offset, int whence);
1099
1100 /* Create a new data buffer and return it in R_DH.  */
1101 gpgme_error_t gpgme_data_new (gpgme_data_t *r_dh);
1102
1103 /* Destroy the data buffer DH.  */
1104 void gpgme_data_release (gpgme_data_t dh);
1105
1106 /* Create a new data buffer filled with SIZE bytes starting from
1107    BUFFER.  If COPY is zero, copying is delayed until necessary, and
1108    the data is taken from the original location when needed.  */
1109 gpgme_error_t gpgme_data_new_from_mem (gpgme_data_t *r_dh,
1110                                        const char *buffer, size_t size,
1111                                        int copy);
1112
1113 /* Destroy the data buffer DH and return a pointer to its content.
1114    The memory has be to released with gpgme_free() by the user.  It's
1115    size is returned in R_LEN.  */
1116 char *gpgme_data_release_and_get_mem (gpgme_data_t dh, size_t *r_len);
1117
1118 /* Release the memory returned by gpgme_data_release_and_get_mem().  */
1119 void gpgme_free (void *buffer);
1120
1121 gpgme_error_t gpgme_data_new_from_cbs (gpgme_data_t *dh,
1122                                        gpgme_data_cbs_t cbs,
1123                                        void *handle);
1124
1125 gpgme_error_t gpgme_data_new_from_fd (gpgme_data_t *dh, int fd);
1126
1127 gpgme_error_t gpgme_data_new_from_stream (gpgme_data_t *dh, FILE *stream);
1128
1129 /* Return the encoding attribute of the data buffer DH */
1130 gpgme_data_encoding_t gpgme_data_get_encoding (gpgme_data_t dh);
1131
1132 /* Set the encoding attribute of data buffer DH to ENC */
1133 gpgme_error_t gpgme_data_set_encoding (gpgme_data_t dh,
1134                                        gpgme_data_encoding_t enc);
1135
1136 /* Get the file name associated with the data object with handle DH, or
1137    NULL if there is none.  */
1138 char *gpgme_data_get_file_name (gpgme_data_t dh);
1139
1140 /* Set the file name associated with the data object with handle DH to
1141    FILE_NAME.  */
1142 gpgme_error_t gpgme_data_set_file_name (gpgme_data_t dh,
1143                                         const char *file_name);
1144
1145
1146 /* Create a new data buffer which retrieves the data from the callback
1147    function READ_CB.  Deprecated, please use gpgme_data_new_from_cbs
1148    instead.  */
1149 gpgme_error_t gpgme_data_new_with_read_cb (gpgme_data_t *r_dh,
1150                                            int (*read_cb) (void*,char *,
1151                                                            size_t,size_t*),
1152                                            void *read_cb_value)
1153      _GPGME_DEPRECATED;
1154
1155 /* Create a new data buffer filled with the content of file FNAME.
1156    COPY must be non-zero.  For delayed read, please use
1157    gpgme_data_new_from_fd or gpgme_data_new_from stream instead.  */
1158 gpgme_error_t gpgme_data_new_from_file (gpgme_data_t *r_dh,
1159                                         const char *fname,
1160                                         int copy);
1161
1162 /* Create a new data buffer filled with LENGTH bytes starting from
1163    OFFSET within the file FNAME or stream FP (exactly one must be
1164    non-zero).  */
1165 gpgme_error_t gpgme_data_new_from_filepart (gpgme_data_t *r_dh,
1166                                             const char *fname, FILE *fp,
1167                                             off_t offset, size_t length);
1168
1169 /* Reset the read pointer in DH.  Deprecated, please use
1170    gpgme_data_seek instead.  */
1171 gpgme_error_t gpgme_data_rewind (gpgme_data_t dh) _GPGME_DEPRECATED;
1172
1173 \f
1174 /* Key and trust functions.  */
1175
1176 /* Get the key with the fingerprint FPR from the crypto backend.  If
1177    SECRET is true, get the secret key.  */
1178 gpgme_error_t gpgme_get_key (gpgme_ctx_t ctx, const char *fpr,
1179                              gpgme_key_t *r_key, int secret);
1180
1181 /* Acquire a reference to KEY.  */
1182 void gpgme_key_ref (gpgme_key_t key);
1183
1184 /* Release a reference to KEY.  If this was the last one the key is
1185    destroyed.  */
1186 void gpgme_key_unref (gpgme_key_t key);
1187 void gpgme_key_release (gpgme_key_t key);
1188
1189 /* Return the value of the attribute WHAT of KEY, which has to be
1190    representable by a string.  IDX specifies the sub key or user ID
1191    for attributes related to sub keys or user IDs.  Deprecated, use
1192    key structure directly instead. */
1193 const char *gpgme_key_get_string_attr (gpgme_key_t key, _gpgme_attr_t what,
1194                                        const void *reserved, int idx)
1195      _GPGME_DEPRECATED;
1196
1197 /* Return the value of the attribute WHAT of KEY, which has to be
1198    representable by an unsigned integer.  IDX specifies the sub key or
1199    user ID for attributes related to sub keys or user IDs.
1200    Deprecated, use key structure directly instead.  */
1201 unsigned long gpgme_key_get_ulong_attr (gpgme_key_t key, _gpgme_attr_t what,
1202                                         const void *reserved, int idx)
1203      _GPGME_DEPRECATED;
1204
1205 /* Return the value of the attribute WHAT of a signature on user ID
1206    UID_IDX in KEY, which has to be representable by a string.  IDX
1207    specifies the signature.  Deprecated, use key structure directly
1208    instead.  */
1209 const char *gpgme_key_sig_get_string_attr (gpgme_key_t key, int uid_idx,
1210                                            _gpgme_attr_t what,
1211                                            const void *reserved, int idx)
1212      _GPGME_DEPRECATED;
1213
1214 /* Return the value of the attribute WHAT of a signature on user ID
1215    UID_IDX in KEY, which has to be representable by an unsigned
1216    integer string.  IDX specifies the signature.  Deprecated, use key
1217    structure directly instead.  */
1218 unsigned long gpgme_key_sig_get_ulong_attr (gpgme_key_t key, int uid_idx,
1219                                             _gpgme_attr_t what,
1220                                             const void *reserved, int idx)
1221      _GPGME_DEPRECATED;
1222
1223 \f
1224 /* Crypto Operations.  */
1225
1226 /* Cancel a pending asynchronous operation.  */
1227 gpgme_error_t gpgme_cancel (gpgme_ctx_t ctx);
1228
1229 /* Cancel a pending operation asynchronously.  */
1230 gpgme_error_t gpgme_cancel_async (gpgme_ctx_t ctx);
1231
1232 \f
1233 struct _gpgme_invalid_key
1234 {
1235   struct _gpgme_invalid_key *next;
1236   char *fpr;
1237   gpgme_error_t reason;
1238 };
1239 typedef struct _gpgme_invalid_key *gpgme_invalid_key_t;
1240
1241 \f
1242 /* Encryption.  */
1243 struct _gpgme_op_encrypt_result
1244 {
1245   /* The list of invalid recipients.  */
1246   gpgme_invalid_key_t invalid_recipients;
1247 };
1248 typedef struct _gpgme_op_encrypt_result *gpgme_encrypt_result_t;
1249
1250 /* Retrieve a pointer to the result of the encrypt operation.  */
1251 gpgme_encrypt_result_t gpgme_op_encrypt_result (gpgme_ctx_t ctx);
1252
1253 /* The valid encryption flags.  */
1254 typedef enum
1255   {
1256     GPGME_ENCRYPT_ALWAYS_TRUST = 1,
1257     GPGME_ENCRYPT_NO_ENCRYPT_TO = 2,
1258     GPGME_ENCRYPT_PREPARE = 4,
1259     GPGME_ENCRYPT_EXPECT_SIGN = 8
1260   }
1261 gpgme_encrypt_flags_t;
1262
1263 /* Encrypt plaintext PLAIN within CTX for the recipients RECP and
1264    store the resulting ciphertext in CIPHER.  */
1265 gpgme_error_t gpgme_op_encrypt_start (gpgme_ctx_t ctx, gpgme_key_t recp[],
1266                                       gpgme_encrypt_flags_t flags,
1267                                       gpgme_data_t plain, gpgme_data_t cipher);
1268 gpgme_error_t gpgme_op_encrypt (gpgme_ctx_t ctx, gpgme_key_t recp[],
1269                                 gpgme_encrypt_flags_t flags,
1270                                 gpgme_data_t plain, gpgme_data_t cipher);
1271
1272 /* Encrypt plaintext PLAIN within CTX for the recipients RECP and
1273    store the resulting ciphertext in CIPHER.  Also sign the ciphertext
1274    with the signers in CTX.  */
1275 gpgme_error_t gpgme_op_encrypt_sign_start (gpgme_ctx_t ctx,
1276                                            gpgme_key_t recp[],
1277                                            gpgme_encrypt_flags_t flags,
1278                                            gpgme_data_t plain,
1279                                            gpgme_data_t cipher);
1280 gpgme_error_t gpgme_op_encrypt_sign (gpgme_ctx_t ctx, gpgme_key_t recp[],
1281                                      gpgme_encrypt_flags_t flags,
1282                                      gpgme_data_t plain, gpgme_data_t cipher);
1283
1284 \f
1285 /* Decryption.  */
1286
1287 struct _gpgme_recipient
1288 {
1289   struct _gpgme_recipient *next;
1290
1291   /* The key ID of key for which the text was encrypted.  */
1292   char *keyid;
1293
1294   /* Internal to GPGME, do not use.  */
1295   char _keyid[16 + 1];
1296
1297   /* The public key algorithm of the recipient key.  */
1298   gpgme_pubkey_algo_t pubkey_algo;
1299
1300   /* The status of the recipient.  */
1301   gpgme_error_t status;
1302 };
1303 typedef struct _gpgme_recipient *gpgme_recipient_t;
1304
1305 struct _gpgme_op_decrypt_result
1306 {
1307   char *unsupported_algorithm;
1308
1309   /* Key should not have been used for encryption.  */
1310   unsigned int wrong_key_usage : 1;
1311
1312   /* Internal to GPGME, do not use.  */
1313   int _unused : 31;
1314
1315   gpgme_recipient_t recipients;
1316
1317   /* The original file name of the plaintext message, if
1318      available.  */
1319   char *file_name;
1320 };
1321 typedef struct _gpgme_op_decrypt_result *gpgme_decrypt_result_t;
1322
1323 /* Retrieve a pointer to the result of the decrypt operation.  */
1324 gpgme_decrypt_result_t gpgme_op_decrypt_result (gpgme_ctx_t ctx);
1325
1326 /* Decrypt ciphertext CIPHER within CTX and store the resulting
1327    plaintext in PLAIN.  */
1328 gpgme_error_t gpgme_op_decrypt_start (gpgme_ctx_t ctx, gpgme_data_t cipher,
1329                                       gpgme_data_t plain);
1330 gpgme_error_t gpgme_op_decrypt (gpgme_ctx_t ctx,
1331                                 gpgme_data_t cipher, gpgme_data_t plain);
1332
1333 /* Decrypt ciphertext CIPHER and make a signature verification within
1334    CTX and store the resulting plaintext in PLAIN.  */
1335 gpgme_error_t gpgme_op_decrypt_verify_start (gpgme_ctx_t ctx,
1336                                              gpgme_data_t cipher,
1337                                              gpgme_data_t plain);
1338 gpgme_error_t gpgme_op_decrypt_verify (gpgme_ctx_t ctx, gpgme_data_t cipher,
1339                                        gpgme_data_t plain);
1340
1341 \f
1342 /* Signing.  */
1343 struct _gpgme_new_signature
1344 {
1345   struct _gpgme_new_signature *next;
1346
1347   /* The type of the signature.  */
1348   gpgme_sig_mode_t type;
1349
1350   /* The public key algorithm used to create the signature.  */
1351   gpgme_pubkey_algo_t pubkey_algo;
1352
1353   /* The hash algorithm used to create the signature.  */
1354   gpgme_hash_algo_t hash_algo;
1355
1356   /* Internal to GPGME, do not use.  Must be set to the same value as
1357      CLASS below.  */
1358   unsigned long _obsolete_class;
1359
1360   /* Signature creation time.  */
1361   long int timestamp;
1362
1363   /* The fingerprint of the signature.  */
1364   char *fpr;
1365
1366 #ifdef __cplusplus
1367   unsigned int _obsolete_class_2;
1368 #else
1369   /* Must be set to SIG_CLASS below.  */
1370   unsigned int class _GPGME_DEPRECATED_OUTSIDE_GPGME;
1371 #endif
1372
1373   /* Crypto backend specific signature class.  */
1374   unsigned int sig_class;
1375 };
1376 typedef struct _gpgme_new_signature *gpgme_new_signature_t;
1377
1378 struct _gpgme_op_sign_result
1379 {
1380   /* The list of invalid signers.  */
1381   gpgme_invalid_key_t invalid_signers;
1382   gpgme_new_signature_t signatures;
1383 };
1384 typedef struct _gpgme_op_sign_result *gpgme_sign_result_t;
1385
1386 /* Retrieve a pointer to the result of the signing operation.  */
1387 gpgme_sign_result_t gpgme_op_sign_result (gpgme_ctx_t ctx);
1388
1389 /* Sign the plaintext PLAIN and store the signature in SIG.  */
1390 gpgme_error_t gpgme_op_sign_start (gpgme_ctx_t ctx,
1391                                    gpgme_data_t plain, gpgme_data_t sig,
1392                                    gpgme_sig_mode_t mode);
1393 gpgme_error_t gpgme_op_sign (gpgme_ctx_t ctx,
1394                              gpgme_data_t plain, gpgme_data_t sig,
1395                              gpgme_sig_mode_t mode);
1396
1397 \f
1398 /* Verify.  */
1399
1400 /* Flags used for the SUMMARY field in a gpgme_signature_t.  */
1401 typedef enum
1402   {
1403     GPGME_SIGSUM_VALID       = 0x0001,  /* The signature is fully valid.  */
1404     GPGME_SIGSUM_GREEN       = 0x0002,  /* The signature is good.  */
1405     GPGME_SIGSUM_RED         = 0x0004,  /* The signature is bad.  */
1406     GPGME_SIGSUM_KEY_REVOKED = 0x0010,  /* One key has been revoked.  */
1407     GPGME_SIGSUM_KEY_EXPIRED = 0x0020,  /* One key has expired.  */
1408     GPGME_SIGSUM_SIG_EXPIRED = 0x0040,  /* The signature has expired.  */
1409     GPGME_SIGSUM_KEY_MISSING = 0x0080,  /* Can't verify: key missing.  */
1410     GPGME_SIGSUM_CRL_MISSING = 0x0100,  /* CRL not available.  */
1411     GPGME_SIGSUM_CRL_TOO_OLD = 0x0200,  /* Available CRL is too old.  */
1412     GPGME_SIGSUM_BAD_POLICY  = 0x0400,  /* A policy was not met.  */
1413     GPGME_SIGSUM_SYS_ERROR   = 0x0800   /* A system error occured.  */
1414   }
1415 gpgme_sigsum_t;
1416
1417 struct _gpgme_signature
1418 {
1419   struct _gpgme_signature *next;
1420
1421   /* A summary of the signature status.  */
1422   gpgme_sigsum_t summary;
1423
1424   /* The fingerprint or key ID of the signature.  */
1425   char *fpr;
1426
1427   /* The status of the signature.  */
1428   gpgme_error_t status;
1429
1430   /* Notation data and policy URLs.  */
1431   gpgme_sig_notation_t notations;
1432
1433   /* Signature creation time.  */
1434   unsigned long timestamp;
1435
1436   /* Signature exipration time or 0.  */
1437   unsigned long exp_timestamp;
1438
1439   /* Key should not have been used for signing.  */
1440   unsigned int wrong_key_usage : 1;
1441
1442   /* PKA status: 0 = not available, 1 = bad, 2 = okay, 3 = RFU. */
1443   unsigned int pka_trust : 2;
1444
1445   /* Validity has been verified using the chain model. */
1446   unsigned int chain_model : 1;
1447
1448   /* Internal to GPGME, do not use.  */
1449   int _unused : 28;
1450
1451   gpgme_validity_t validity;
1452   gpgme_error_t validity_reason;
1453
1454   /* The public key algorithm used to create the signature.  */
1455   gpgme_pubkey_algo_t pubkey_algo;
1456
1457   /* The hash algorithm used to create the signature.  */
1458   gpgme_hash_algo_t hash_algo;
1459
1460   /* The mailbox from the PKA information or NULL. */
1461   char *pka_address;
1462 };
1463 typedef struct _gpgme_signature *gpgme_signature_t;
1464
1465 struct _gpgme_op_verify_result
1466 {
1467   gpgme_signature_t signatures;
1468
1469   /* The original file name of the plaintext message, if
1470      available.  */
1471   char *file_name;
1472 };
1473 typedef struct _gpgme_op_verify_result *gpgme_verify_result_t;
1474
1475 /* Retrieve a pointer to the result of the verify operation.  */
1476 gpgme_verify_result_t gpgme_op_verify_result (gpgme_ctx_t ctx);
1477
1478 /* Verify within CTX that SIG is a valid signature for TEXT.  */
1479 gpgme_error_t gpgme_op_verify_start (gpgme_ctx_t ctx, gpgme_data_t sig,
1480                                      gpgme_data_t signed_text,
1481                                      gpgme_data_t plaintext);
1482 gpgme_error_t gpgme_op_verify (gpgme_ctx_t ctx, gpgme_data_t sig,
1483                                gpgme_data_t signed_text,
1484                                gpgme_data_t plaintext);
1485
1486 \f
1487 /* Import.  */
1488
1489 /* The key was new.  */
1490 #define GPGME_IMPORT_NEW        1
1491
1492 /* The key contained new user IDs.  */
1493 #define GPGME_IMPORT_UID        2
1494
1495 /* The key contained new signatures.  */
1496 #define GPGME_IMPORT_SIG        4
1497
1498 /* The key contained new sub keys.  */
1499 #define GPGME_IMPORT_SUBKEY     8
1500
1501 /* The key contained a secret key.  */
1502 #define GPGME_IMPORT_SECRET     16
1503
1504
1505 struct _gpgme_import_status
1506 {
1507   struct _gpgme_import_status *next;
1508
1509   /* Fingerprint.  */
1510   char *fpr;
1511
1512   /* If a problem occured, the reason why the key could not be
1513      imported.  Otherwise GPGME_No_Error.  */
1514   gpgme_error_t result;
1515
1516   /* The result of the import, the GPGME_IMPORT_* values bit-wise
1517      ORed.  0 means the key was already known and no new components
1518      have been added.  */
1519   unsigned int status;
1520 };
1521 typedef struct _gpgme_import_status *gpgme_import_status_t;
1522
1523 /* Import.  */
1524 struct _gpgme_op_import_result
1525 {
1526   /* Number of considered keys.  */
1527   int considered;
1528
1529   /* Keys without user ID.  */
1530   int no_user_id;
1531
1532   /* Imported keys.  */
1533   int imported;
1534
1535   /* Imported RSA keys.  */
1536   int imported_rsa;
1537
1538   /* Unchanged keys.  */
1539   int unchanged;
1540
1541   /* Number of new user ids.  */
1542   int new_user_ids;
1543
1544   /* Number of new sub keys.  */
1545   int new_sub_keys;
1546
1547   /* Number of new signatures.  */
1548   int new_signatures;
1549
1550   /* Number of new revocations.  */
1551   int new_revocations;
1552
1553   /* Number of secret keys read.  */
1554   int secret_read;
1555
1556   /* Number of secret keys imported.  */
1557   int secret_imported;
1558
1559   /* Number of secret keys unchanged.  */
1560   int secret_unchanged;
1561
1562   /* Number of new keys skipped.  */
1563   int skipped_new_keys;
1564
1565   /* Number of keys not imported.  */
1566   int not_imported;
1567
1568   /* List of keys for which an import was attempted.  */
1569   gpgme_import_status_t imports;
1570 };
1571 typedef struct _gpgme_op_import_result *gpgme_import_result_t;
1572
1573 /* Retrieve a pointer to the result of the import operation.  */
1574 gpgme_import_result_t gpgme_op_import_result (gpgme_ctx_t ctx);
1575
1576 /* Import the key in KEYDATA into the keyring.  */
1577 gpgme_error_t gpgme_op_import_start (gpgme_ctx_t ctx, gpgme_data_t keydata);
1578 gpgme_error_t gpgme_op_import (gpgme_ctx_t ctx, gpgme_data_t keydata);
1579 gpgme_error_t gpgme_op_import_ext (gpgme_ctx_t ctx, gpgme_data_t keydata,
1580                                    int *nr) _GPGME_DEPRECATED;
1581
1582 /* Import the keys from the array KEYS into the keyring.  */
1583 gpgme_error_t gpgme_op_import_keys_start (gpgme_ctx_t ctx, gpgme_key_t keys[]);
1584 gpgme_error_t gpgme_op_import_keys (gpgme_ctx_t ctx, gpgme_key_t keys[]);
1585
1586
1587 \f
1588 /* Export the keys found by PATTERN into KEYDATA.  */
1589 gpgme_error_t gpgme_op_export_start (gpgme_ctx_t ctx, const char *pattern,
1590                                      gpgme_export_mode_t mode,
1591                                      gpgme_data_t keydata);
1592 gpgme_error_t gpgme_op_export (gpgme_ctx_t ctx, const char *pattern,
1593                                gpgme_export_mode_t mode,
1594                                gpgme_data_t keydata);
1595
1596 gpgme_error_t gpgme_op_export_ext_start (gpgme_ctx_t ctx,
1597                                          const char *pattern[],
1598                                          gpgme_export_mode_t mode,
1599                                          gpgme_data_t keydata);
1600 gpgme_error_t gpgme_op_export_ext (gpgme_ctx_t ctx, const char *pattern[],
1601                                    gpgme_export_mode_t mode,
1602                                    gpgme_data_t keydata);
1603
1604 /* Export the keys from the array KEYS into KEYDATA.  */
1605 gpgme_error_t gpgme_op_export_keys_start (gpgme_ctx_t ctx,
1606                                           gpgme_key_t keys[],
1607                                           gpgme_export_mode_t mode,
1608                                           gpgme_data_t keydata);
1609 gpgme_error_t gpgme_op_export_keys (gpgme_ctx_t ctx,
1610                                     gpgme_key_t keys[],
1611                                     gpgme_export_mode_t mode,
1612                                     gpgme_data_t keydata);
1613
1614
1615 \f
1616 /* Key generation.  */
1617 struct _gpgme_op_genkey_result
1618 {
1619   /* A primary key was generated.  */
1620   unsigned int primary : 1;
1621
1622   /* A sub key was generated.  */
1623   unsigned int sub : 1;
1624
1625   /* Internal to GPGME, do not use.  */
1626   unsigned int _unused : 30;
1627
1628   /* The fingerprint of the generated key.  */
1629   char *fpr;
1630 };
1631 typedef struct _gpgme_op_genkey_result *gpgme_genkey_result_t;
1632
1633 /* Generate a new keypair and add it to the keyring.  PUBKEY and
1634    SECKEY should be null for now.  PARMS specifies what keys should be
1635    generated.  */
1636 gpgme_error_t gpgme_op_genkey_start (gpgme_ctx_t ctx, const char *parms,
1637                                      gpgme_data_t pubkey, gpgme_data_t seckey);
1638 gpgme_error_t gpgme_op_genkey (gpgme_ctx_t ctx, const char *parms,
1639                                gpgme_data_t pubkey, gpgme_data_t seckey);
1640
1641 /* Retrieve a pointer to the result of the genkey operation.  */
1642 gpgme_genkey_result_t gpgme_op_genkey_result (gpgme_ctx_t ctx);
1643
1644 \f
1645 /* Delete KEY from the keyring.  If ALLOW_SECRET is non-zero, secret
1646    keys are also deleted.  */
1647 gpgme_error_t gpgme_op_delete_start (gpgme_ctx_t ctx, const gpgme_key_t key,
1648                                      int allow_secret);
1649 gpgme_error_t gpgme_op_delete (gpgme_ctx_t ctx, const gpgme_key_t key,
1650                                int allow_secret);
1651
1652 \f
1653 /* Edit the key KEY.  Send status and command requests to FNC and
1654    output of edit commands to OUT.  */
1655 gpgme_error_t gpgme_op_edit_start (gpgme_ctx_t ctx, gpgme_key_t key,
1656                                    gpgme_edit_cb_t fnc, void *fnc_value,
1657                                    gpgme_data_t out);
1658 gpgme_error_t gpgme_op_edit (gpgme_ctx_t ctx, gpgme_key_t key,
1659                              gpgme_edit_cb_t fnc, void *fnc_value,
1660                              gpgme_data_t out);
1661
1662 /* Edit the card for the key KEY.  Send status and command requests to
1663    FNC and output of edit commands to OUT.  */
1664 gpgme_error_t gpgme_op_card_edit_start (gpgme_ctx_t ctx, gpgme_key_t key,
1665                                         gpgme_edit_cb_t fnc, void *fnc_value,
1666                                         gpgme_data_t out);
1667 gpgme_error_t gpgme_op_card_edit (gpgme_ctx_t ctx, gpgme_key_t key,
1668                                   gpgme_edit_cb_t fnc, void *fnc_value,
1669                                   gpgme_data_t out);
1670
1671 \f
1672 /* Key management functions.  */
1673 struct _gpgme_op_keylist_result
1674 {
1675   unsigned int truncated : 1;
1676
1677   /* Internal to GPGME, do not use.  */
1678   unsigned int _unused : 31;
1679 };
1680 typedef struct _gpgme_op_keylist_result *gpgme_keylist_result_t;
1681
1682 /* Retrieve a pointer to the result of the key listing operation.  */
1683 gpgme_keylist_result_t gpgme_op_keylist_result (gpgme_ctx_t ctx);
1684
1685 /* Start a keylist operation within CTX, searching for keys which
1686    match PATTERN.  If SECRET_ONLY is true, only secret keys are
1687    returned.  */
1688 gpgme_error_t gpgme_op_keylist_start (gpgme_ctx_t ctx, const char *pattern,
1689                                       int secret_only);
1690 gpgme_error_t gpgme_op_keylist_ext_start (gpgme_ctx_t ctx,
1691                                           const char *pattern[],
1692                                           int secret_only, int reserved);
1693
1694 /* Return the next key from the keylist in R_KEY.  */
1695 gpgme_error_t gpgme_op_keylist_next (gpgme_ctx_t ctx, gpgme_key_t *r_key);
1696
1697 /* Terminate a pending keylist operation within CTX.  */
1698 gpgme_error_t gpgme_op_keylist_end (gpgme_ctx_t ctx);
1699
1700 /* Change the passphrase for KEY.  FLAGS is reserved for future use
1701    and must be passed as 0.  */
1702 gpgme_error_t gpgme_op_passwd_start (gpgme_ctx_t ctx, gpgme_key_t key,
1703                                      unsigned int flags);
1704 gpgme_error_t gpgme_op_passwd (gpgme_ctx_t ctx, gpgme_key_t key,
1705                                unsigned int flags);
1706
1707
1708 \f
1709 /* Trust items and operations.  */
1710
1711 struct _gpgme_trust_item
1712 {
1713   /* Internal to GPGME, do not use.  */
1714   unsigned int _refs;
1715
1716   /* The key ID to which the trust item belongs.  */
1717   char *keyid;
1718
1719   /* Internal to GPGME, do not use.  */
1720   char _keyid[16 + 1];
1721
1722   /* The type of the trust item, 1 refers to a key, 2 to a user ID.  */
1723   int type;
1724
1725   /* The trust level.  */
1726   int level;
1727
1728   /* The owner trust if TYPE is 1.  */
1729   char *owner_trust;
1730
1731   /* Internal to GPGME, do not use.  */
1732   char _owner_trust[2];
1733
1734   /* The calculated validity.  */
1735   char *validity;
1736
1737   /* Internal to GPGME, do not use.  */
1738   char _validity[2];
1739
1740   /* The user name if TYPE is 2.  */
1741   char *name;
1742 };
1743 typedef struct _gpgme_trust_item *gpgme_trust_item_t;
1744
1745 /* Start a trustlist operation within CTX, searching for trust items
1746    which match PATTERN.  */
1747 gpgme_error_t gpgme_op_trustlist_start (gpgme_ctx_t ctx,
1748                                         const char *pattern, int max_level);
1749
1750 /* Return the next trust item from the trustlist in R_ITEM.  */
1751 gpgme_error_t gpgme_op_trustlist_next (gpgme_ctx_t ctx,
1752                                        gpgme_trust_item_t *r_item);
1753
1754 /* Terminate a pending trustlist operation within CTX.  */
1755 gpgme_error_t gpgme_op_trustlist_end (gpgme_ctx_t ctx);
1756
1757 /* Acquire a reference to ITEM.  */
1758 void gpgme_trust_item_ref (gpgme_trust_item_t item);
1759
1760 /* Release a reference to ITEM.  If this was the last one the trust
1761    item is destroyed.  */
1762 void gpgme_trust_item_unref (gpgme_trust_item_t item);
1763
1764 /* Release the trust item ITEM.  Deprecated, use
1765    gpgme_trust_item_unref.  */
1766 void gpgme_trust_item_release (gpgme_trust_item_t item) _GPGME_DEPRECATED;
1767
1768 /* Return the value of the attribute WHAT of ITEM, which has to be
1769    representable by a string.  Deprecated, use trust item structure
1770    directly.  */
1771 const char *gpgme_trust_item_get_string_attr (gpgme_trust_item_t item,
1772                                               _gpgme_attr_t what,
1773                                               const void *reserved, int idx)
1774      _GPGME_DEPRECATED;
1775
1776 /* Return the value of the attribute WHAT of KEY, which has to be
1777    representable by an integer.  IDX specifies a running index if the
1778    attribute appears more than once in the key.  Deprecated, use trust
1779    item structure directly.  */
1780 int gpgme_trust_item_get_int_attr (gpgme_trust_item_t item, _gpgme_attr_t what,
1781                                    const void *reserved, int idx)
1782      _GPGME_DEPRECATED;
1783
1784 \f
1785 /* Return the auditlog for the current session.  This may be called
1786    after a successful or failed operation.  If no audit log is
1787    available GPG_ERR_NO_DATA is returned.  */
1788 gpgme_error_t gpgme_op_getauditlog_start (gpgme_ctx_t ctx, gpgme_data_t output,
1789                                           unsigned int flags);
1790 gpgme_error_t gpgme_op_getauditlog (gpgme_ctx_t ctx, gpgme_data_t output,
1791                                     unsigned int flags);
1792
1793
1794 \f
1795 /* Low-level Assuan protocol access.  */
1796 typedef gpgme_error_t (*gpgme_assuan_data_cb_t)
1797      (void *opaque, const void *data, size_t datalen);
1798
1799 typedef gpgme_error_t (*gpgme_assuan_inquire_cb_t)
1800      (void *opaque, const char *name, const char *args,
1801       gpgme_data_t *r_data);
1802
1803 typedef gpgme_error_t (*gpgme_assuan_status_cb_t)
1804      (void *opaque, const char *status, const char *args);
1805
1806 /* Send the Assuan COMMAND and return results via the callbacks.
1807    Asynchronous variant. */
1808 gpgme_error_t gpgme_op_assuan_transact_start (gpgme_ctx_t ctx,
1809                                               const char *command,
1810                                               gpgme_assuan_data_cb_t data_cb,
1811                                               void *data_cb_value,
1812                                               gpgme_assuan_inquire_cb_t inq_cb,
1813                                               void *inq_cb_value,
1814                                               gpgme_assuan_status_cb_t stat_cb,
1815                                               void *stat_cb_value);
1816
1817 /* Send the Assuan COMMAND and return results via the callbacks.
1818    Synchronous variant. */
1819 gpgme_error_t gpgme_op_assuan_transact_ext (gpgme_ctx_t ctx,
1820                                             const char *command,
1821                                             gpgme_assuan_data_cb_t data_cb,
1822                                             void *data_cb_value,
1823                                             gpgme_assuan_inquire_cb_t inq_cb,
1824                                             void *inq_cb_value,
1825                                             gpgme_assuan_status_cb_t stat_cb,
1826                                             void *stat_cb_value,
1827                                             gpgme_error_t *op_err);
1828
1829 /* Compat.  */
1830 struct _gpgme_op_assuan_result
1831 {
1832   /* Deprecated.  Use the second value in a DONE event or the
1833      synchronous variant gpgme_op_assuan_transact_ext.  */
1834   gpgme_error_t err _GPGME_DEPRECATED_OUTSIDE_GPGME;
1835 };
1836 typedef struct _gpgme_op_assuan_result *gpgme_assuan_result_t;
1837
1838
1839 /* Return the result of the last Assuan command. */
1840 gpgme_assuan_result_t gpgme_op_assuan_result (gpgme_ctx_t ctx)
1841   _GPGME_DEPRECATED;
1842
1843 gpgme_error_t
1844 gpgme_op_assuan_transact (gpgme_ctx_t ctx,
1845                               const char *command,
1846                               gpgme_assuan_data_cb_t data_cb,
1847                               void *data_cb_value,
1848                               gpgme_assuan_inquire_cb_t inq_cb,
1849                               void *inq_cb_value,
1850                               gpgme_assuan_status_cb_t status_cb,
1851                               void *status_cb_value) _GPGME_DEPRECATED;
1852
1853 \f
1854 /* Crypto container support.  */
1855 struct _gpgme_op_vfs_mount_result
1856 {
1857   char *mount_dir;
1858 };
1859 typedef struct _gpgme_op_vfs_mount_result *gpgme_vfs_mount_result_t;
1860
1861 gpgme_vfs_mount_result_t gpgme_op_vfs_mount_result (gpgme_ctx_t ctx);
1862
1863 /* The container is automatically unmounted when the context is reset
1864    or destroyed.  Transmission errors are returned directly,
1865    operational errors are returned in OP_ERR.  */
1866 gpgme_error_t gpgme_op_vfs_mount (gpgme_ctx_t ctx, const char *container_file,
1867                                   const char *mount_dir, unsigned int flags,
1868                                   gpgme_error_t *op_err);
1869
1870 gpgme_error_t gpgme_op_vfs_create (gpgme_ctx_t ctx, gpgme_key_t recp[],
1871                                    const char *container_file,
1872                                    unsigned int flags, gpgme_error_t *op_err);
1873
1874 \f
1875 /* Interface to gpgconf(1).  */
1876
1877 /* The expert level at which a configuration option or group of
1878    options should be displayed.  See the gpgconf(1) documentation for
1879    more details.  */
1880 typedef enum
1881   {
1882     GPGME_CONF_BASIC = 0,
1883     GPGME_CONF_ADVANCED = 1,
1884     GPGME_CONF_EXPERT = 2,
1885     GPGME_CONF_INVISIBLE = 3,
1886     GPGME_CONF_INTERNAL = 4
1887   }
1888 gpgme_conf_level_t;
1889
1890
1891 /* The data type of a configuration option argument.  See the gpgconf(1)
1892    documentation for more details.  */
1893 typedef enum
1894   {
1895     /* Basic types.  */
1896     GPGME_CONF_NONE = 0,
1897     GPGME_CONF_STRING = 1,
1898     GPGME_CONF_INT32 = 2,
1899     GPGME_CONF_UINT32 = 3,
1900
1901     /* Complex types.  */
1902     GPGME_CONF_FILENAME = 32,
1903     GPGME_CONF_LDAP_SERVER = 33,
1904     GPGME_CONF_KEY_FPR = 34,
1905     GPGME_CONF_PUB_KEY = 35,
1906     GPGME_CONF_SEC_KEY = 36,
1907     GPGME_CONF_ALIAS_LIST = 37
1908   }
1909 gpgme_conf_type_t;
1910
1911 /* For now, compatibility.  */
1912 #define GPGME_CONF_PATHNAME GPGME_CONF_FILENAME
1913
1914
1915 /* This represents a single argument for a configuration option.
1916    Which of the members of value is used depends on the ALT_TYPE.  */
1917 typedef struct gpgme_conf_arg
1918 {
1919   struct gpgme_conf_arg *next;
1920   /* True if the option appears without an (optional) argument.  */
1921   unsigned int no_arg;
1922   union
1923   {
1924     unsigned int count;
1925     unsigned int uint32;
1926     int int32;
1927     char *string;
1928   } value;
1929 } *gpgme_conf_arg_t;
1930
1931
1932 /* The flags of a configuration option.  See the gpg-conf
1933    documentation for details.  */
1934 #define GPGME_CONF_GROUP        (1 << 0)
1935 #define GPGME_CONF_OPTIONAL     (1 << 1)
1936 #define GPGME_CONF_LIST         (1 << 2)
1937 #define GPGME_CONF_RUNTIME      (1 << 3)
1938 #define GPGME_CONF_DEFAULT      (1 << 4)
1939 #define GPGME_CONF_DEFAULT_DESC (1 << 5)
1940 #define GPGME_CONF_NO_ARG_DESC  (1 << 6)
1941 #define GPGME_CONF_NO_CHANGE    (1 << 7)
1942
1943
1944 /* The representation of a single configuration option.  See the
1945    gpg-conf documentation for details.  */
1946 typedef struct gpgme_conf_opt
1947 {
1948   struct gpgme_conf_opt *next;
1949
1950   /* The option name.  */
1951   char *name;
1952
1953   /* The flags for this option.  */
1954   unsigned int flags;
1955
1956   /* The level of this option.  */
1957   gpgme_conf_level_t level;
1958
1959   /* The localized description of this option.  */
1960   char *description;
1961
1962   /* The type and alternate type of this option.  */
1963   gpgme_conf_type_t type;
1964   gpgme_conf_type_t alt_type;
1965
1966   /* The localized (short) name of the argument, if any.  */
1967   char *argname;
1968
1969   /* The default value.  */
1970   gpgme_conf_arg_t default_value;
1971   char *default_description;
1972
1973   /* The default value if the option is not set.  */
1974   gpgme_conf_arg_t no_arg_value;
1975   char *no_arg_description;
1976
1977   /* The current value if the option is set.  */
1978   gpgme_conf_arg_t value;
1979
1980   /* The new value, if any.  NULL means reset to default.  */
1981   int change_value;
1982   gpgme_conf_arg_t new_value;
1983
1984   /* Free for application use.  */
1985   void *user_data;
1986 } *gpgme_conf_opt_t;
1987
1988
1989 /* The representation of a component that can be configured.  See the
1990    gpg-conf documentation for details.  */
1991 typedef struct gpgme_conf_comp
1992 {
1993   struct gpgme_conf_comp *next;
1994
1995   /* Internal to GPGME, do not use!  */
1996   gpgme_conf_opt_t *_last_opt_p;
1997
1998   /* The component name.  */
1999   char *name;
2000
2001   /* A human-readable description for the component.  */
2002   char *description;
2003
2004   /* The program name (an absolute path to the program).  */
2005   char *program_name;
2006
2007   /* A linked list of options for this component.  */
2008   struct gpgme_conf_opt *options;
2009 } *gpgme_conf_comp_t;
2010
2011
2012 /* Allocate a new gpgme_conf_arg_t.  If VALUE is NULL, a "no arg
2013    default" is prepared.  If type is a string type, VALUE should point
2014    to the string.  Else, it should point to an unsigned or signed
2015    integer respectively.  */
2016 gpgme_error_t gpgme_conf_arg_new (gpgme_conf_arg_t *arg_p,
2017                                   gpgme_conf_type_t type, const void *value);
2018
2019 /* This also releases all chained argument structures!  */
2020 void gpgme_conf_arg_release (gpgme_conf_arg_t arg, gpgme_conf_type_t type);
2021
2022 /* Register a change for the value of OPT to ARG.  If RESET is 1 (do
2023    not use any values but 0 or 1), ARG is ignored and the option is
2024    not changed (reverting a previous change).  Otherwise, if ARG is
2025    NULL, the option is cleared or reset to its default.  */
2026 gpgme_error_t gpgme_conf_opt_change (gpgme_conf_opt_t opt, int reset,
2027                                      gpgme_conf_arg_t arg);
2028
2029 /* Release a set of configurations.  */
2030 void gpgme_conf_release (gpgme_conf_comp_t conf);
2031
2032 /* Retrieve the current configurations.  */
2033 gpgme_error_t gpgme_op_conf_load (gpgme_ctx_t ctx, gpgme_conf_comp_t *conf_p);
2034
2035 /* Save the configuration of component comp.  This function does not
2036    follow chained components!  */
2037 gpgme_error_t gpgme_op_conf_save (gpgme_ctx_t ctx, gpgme_conf_comp_t comp);
2038
2039 \f
2040 /* UIServer support.  */
2041
2042 /* Create a dummy key to specify an email address.  */
2043 gpgme_error_t gpgme_key_from_uid (gpgme_key_t *key, const char *name);
2044
2045
2046 \f
2047 /* Various functions.  */
2048
2049 /* Set special global flags; consult the manual before use.  */
2050 int gpgme_set_global_flag (const char *name, const char *value);
2051
2052 /* Check that the library fulfills the version requirement.  Note:
2053    This is here only for the case where a user takes a pointer from
2054    the old version of this function.  The new version and macro for
2055    run-time checks are below.  */
2056 const char *gpgme_check_version (const char *req_version);
2057
2058 /* Check that the library fulfills the version requirement and check
2059    for struct layout mismatch involving bitfields.  */
2060 const char *gpgme_check_version_internal (const char *req_version,
2061                                           size_t offset_sig_validity);
2062
2063 #define gpgme_check_version(req_version)                                \
2064   gpgme_check_version_internal (req_version,                            \
2065                                 offsetof (struct _gpgme_signature, validity))
2066
2067 /* Get the information about the configured and installed engines.  A
2068    pointer to the first engine in the statically allocated linked list
2069    is returned in *INFO.  If an error occurs, it is returned.  The
2070    returned data is valid until the next gpgme_set_engine_info.  */
2071 gpgme_error_t gpgme_get_engine_info (gpgme_engine_info_t *engine_info);
2072
2073 /* Set the default engine info for the protocol PROTO to the file name
2074    FILE_NAME and the home directory HOME_DIR.  */
2075 gpgme_error_t gpgme_set_engine_info (gpgme_protocol_t proto,
2076                                      const char *file_name,
2077                                      const char *home_dir);
2078
2079 \f
2080 /* Engine support functions.  */
2081
2082 /* Verify that the engine implementing PROTO is installed and
2083    available.  */
2084 gpgme_error_t gpgme_engine_check_version (gpgme_protocol_t proto);
2085
2086 \f
2087 void gpgme_result_ref (void *result);
2088 void gpgme_result_unref (void *result);
2089
2090 \f
2091 /* Deprecated types.  */
2092 typedef gpgme_ctx_t GpgmeCtx _GPGME_DEPRECATED;
2093 typedef gpgme_data_t GpgmeData _GPGME_DEPRECATED;
2094 typedef gpgme_error_t GpgmeError _GPGME_DEPRECATED;
2095 typedef gpgme_data_encoding_t GpgmeDataEncoding _GPGME_DEPRECATED;
2096 typedef gpgme_pubkey_algo_t GpgmePubKeyAlgo _GPGME_DEPRECATED;
2097 typedef gpgme_hash_algo_t GpgmeHashAlgo _GPGME_DEPRECATED;
2098 typedef gpgme_sig_stat_t GpgmeSigStat _GPGME_DEPRECATED;
2099 typedef gpgme_sig_mode_t GpgmeSigMode _GPGME_DEPRECATED;
2100 typedef gpgme_attr_t GpgmeAttr _GPGME_DEPRECATED;
2101 typedef gpgme_validity_t GpgmeValidity _GPGME_DEPRECATED;
2102 typedef gpgme_protocol_t GpgmeProtocol _GPGME_DEPRECATED;
2103 typedef gpgme_engine_info_t GpgmeEngineInfo _GPGME_DEPRECATED;
2104 typedef gpgme_subkey_t GpgmeSubkey _GPGME_DEPRECATED;
2105 typedef gpgme_key_sig_t GpgmeKeySig _GPGME_DEPRECATED;
2106 typedef gpgme_user_id_t GpgmeUserID _GPGME_DEPRECATED;
2107 typedef gpgme_key_t GpgmeKey _GPGME_DEPRECATED;
2108 typedef gpgme_passphrase_cb_t GpgmePassphraseCb _GPGME_DEPRECATED;
2109 typedef gpgme_progress_cb_t GpgmeProgressCb _GPGME_DEPRECATED;
2110 typedef gpgme_io_cb_t GpgmeIOCb _GPGME_DEPRECATED;
2111 typedef gpgme_register_io_cb_t GpgmeRegisterIOCb _GPGME_DEPRECATED;
2112 typedef gpgme_remove_io_cb_t GpgmeRemoveIOCb _GPGME_DEPRECATED;
2113 typedef gpgme_event_io_t GpgmeEventIO _GPGME_DEPRECATED;
2114 typedef gpgme_event_io_cb_t GpgmeEventIOCb _GPGME_DEPRECATED;
2115 #define GpgmeIOCbs gpgme_io_cbs
2116 typedef gpgme_data_read_cb_t GpgmeDataReadCb _GPGME_DEPRECATED;
2117 typedef gpgme_data_write_cb_t GpgmeDataWriteCb _GPGME_DEPRECATED;
2118 typedef gpgme_data_seek_cb_t GpgmeDataSeekCb _GPGME_DEPRECATED;
2119 typedef gpgme_data_release_cb_t GpgmeDataReleaseCb _GPGME_DEPRECATED;
2120 #define GpgmeDataCbs gpgme_data_cbs
2121 typedef gpgme_encrypt_result_t GpgmeEncryptResult _GPGME_DEPRECATED;
2122 typedef gpgme_sig_notation_t GpgmeSigNotation _GPGME_DEPRECATED;
2123 typedef gpgme_signature_t GpgmeSignature _GPGME_DEPRECATED;
2124 typedef gpgme_verify_result_t GpgmeVerifyResult _GPGME_DEPRECATED;
2125 typedef gpgme_import_status_t GpgmeImportStatus _GPGME_DEPRECATED;
2126 typedef gpgme_import_result_t GpgmeImportResult _GPGME_DEPRECATED;
2127 typedef gpgme_genkey_result_t GpgmeGenKeyResult _GPGME_DEPRECATED;
2128 typedef gpgme_trust_item_t GpgmeTrustItem _GPGME_DEPRECATED;
2129 typedef gpgme_status_code_t GpgmeStatusCode _GPGME_DEPRECATED;
2130
2131 #ifdef __cplusplus
2132 }
2133 #endif
2134 #endif /* GPGME_H */
2135 /*
2136 @emacs_local_vars_begin@
2137 @emacs_local_vars_read_only@
2138 @emacs_local_vars_end@
2139 */