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