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