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