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