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