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