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