2003-09-14 Marcus Brinkmann <marcus@g10code.de>
[gpgme.git] / gpgme / gpgme.h
1 /* gpgme.h - Public interface to GnuPG Made Easy.
2    Copyright (C) 2000 Werner Koch (dd9jn)
3    Copyright (C) 2001, 2002, 2003 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 General Public License as published by
9    the Free Software Foundation; either version 2 of the License, or
10    (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    General Public License for more details.
16  
17    You should have received a copy of the GNU General Public License
18    along with GPGME; if not, write to the Free Software Foundation,
19    Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.  */
20
21 #ifndef GPGME_H
22 #define GPGME_H
23
24 #ifdef __GNUC__
25 #define _GPGME_INLINE __inline__
26 #elif __STDC_VERSION__ >= 199901L
27 #define _GPGME_INLINE inline
28 #else
29 #define _GPGME_INLINE
30 #endif
31
32 /* Include stdio.h for the FILE type definition.  */
33 #include <stdio.h>
34
35 #ifdef _MSC_VER
36   typedef long off_t;
37   typedef long ssize_t;
38 #else
39 # include <sys/types.h>
40 #endif
41
42 #ifdef __cplusplus
43 extern "C" {
44 #if 0 /* just to make Emacs auto-indent happy */
45 }
46 #endif
47 #endif
48
49 #include <gpg-error.h>
50
51 \f
52 /* Check for compiler features.  */
53 #if __GNUC__
54 #define _GPGME_GCC_VERSION (__GNUC__ * 10000 \
55                             + __GNUC_MINOR__ * 100 \
56                             + __GNUC_PATCHLEVEL__)
57
58 #if _GPGME_GCC_VERSION > 30100
59 #define _GPGME_DEPRECATED       __attribute__ ((__deprecated__))
60 #endif
61 #endif
62
63 #ifndef _GPGME_DEPRECATED
64 #define _GPGME_DEPRECATED
65 #endif
66
67 \f
68 /* The version of this header should match the one of the library.  Do
69    not use this symbol in your application, use gpgme_check_version
70    instead.  The purpose of this macro is to let autoconf (using the
71    AM_PATH_GPGME macro) check that this header matches the installed
72    library.  Warning: Do not edit the next line.  configure will do
73    that for you!  */
74 #define GPGME_VERSION "0.4.3"
75
76 \f
77 /* Some opaque data types used by GPGME.  */
78
79 /* The context holds some global state and configration options, as
80    well as the results of a crypto operation.  */
81 struct gpgme_context;
82 typedef struct gpgme_context *gpgme_ctx_t;
83
84 /* The data object is used by GPGME to exchange arbitrary data.  */
85 struct gpgme_data;
86 typedef struct gpgme_data *gpgme_data_t;
87
88 \f
89 /* Wrappers for the libgpg-error library.  */
90
91 typedef gpg_error_t gpgme_error_t;
92 typedef gpg_err_code_t gpgme_err_code_t;
93 typedef gpg_err_source_t gpgme_err_source_t;
94
95
96 static _GPGME_INLINE gpgme_error_t
97 gpgme_err_make (gpgme_err_source_t source, gpgme_err_code_t code)
98 {
99   return gpg_err_make (source, code);
100 }
101
102
103 /* The user can define GPGME_ERR_SOURCE_DEFAULT before including this
104    file to specify a default source for gpgme_error.  */
105 #ifndef GPGME_ERR_SOURCE_DEFAULT
106 #define GPGME_ERR_SOURCE_DEFAULT  GPG_ERR_SOURCE_USER_1
107 #endif
108
109 static _GPGME_INLINE gpgme_error_t
110 gpgme_error (gpgme_err_code_t code)
111 {
112   return gpgme_err_make (GPGME_ERR_SOURCE_DEFAULT, code);
113 }
114
115
116 static _GPGME_INLINE gpgme_err_code_t
117 gpgme_err_code (gpgme_error_t err)
118 {
119   return gpg_err_code (err);
120 }
121
122
123 static _GPGME_INLINE gpgme_err_source_t
124 gpgme_err_source (gpgme_error_t err)
125 {
126   return gpg_err_source (err);
127 }
128
129
130 /* Return a pointer to a string containing a description of the error
131    code in the error value ERR.  This function is not thread safe.  */
132 const char *gpgme_strerror (gpgme_error_t err);
133
134 /* Return a pointer to a string containing a description of the error
135    code in the error value ERR.  The buffer for the string is
136    allocated with malloc(), and has to be released by the user.  On
137    error, NULL is returned.  */
138 char *gpgme_strerror_r (gpgme_error_t err);
139
140
141 /* Return a pointer to a string containing a description of the error
142    source in the error value ERR.  */
143 const char *gpgme_strsource (gpgme_error_t err);
144
145
146 /* Retrieve the error code for the system error ERR.  This returns
147    GPG_ERR_UNKNOWN_ERRNO if the system error is not mapped (report
148    this).  */
149 gpgme_err_code_t gpgme_err_code_from_errno (int err);
150
151
152 /* Retrieve the system error for the error code CODE.  This returns 0
153    if CODE is not a system error code.  */
154 int gpgme_err_code_to_errno (gpgme_err_code_t code);
155
156   
157 /* Return an error value with the error source SOURCE and the system
158    error ERR.  */
159 gpgme_error_t gpgme_err_make_from_errno (gpgme_err_source_t source, int err);
160
161
162 /* Return an error value with the system error ERR.  */
163 gpgme_err_code_t gpgme_error_from_errno (int err);
164
165 \f
166 /* The possible encoding mode of gpgme_data_t objects.  */
167 typedef enum
168   {
169     GPGME_DATA_ENCODING_NONE   = 0,     /* Not specified.  */
170     GPGME_DATA_ENCODING_BINARY = 1,
171     GPGME_DATA_ENCODING_BASE64 = 2,
172     GPGME_DATA_ENCODING_ARMOR  = 3      /* Either PEM or OpenPGP Armor.  */
173   }
174 gpgme_data_encoding_t;
175
176 \f
177 /* Public key algorithms from libgcrypt.  */
178 typedef enum
179   {
180     GPGME_PK_RSA   = 1,
181     GPGME_PK_RSA_E = 2,
182     GPGME_PK_RSA_S = 3,
183     GPGME_PK_ELG_E = 16,
184     GPGME_PK_DSA   = 17,
185     GPGME_PK_ELG   = 20
186   }
187 gpgme_pubkey_algo_t;
188
189
190 /* Hash algorithms from libgcrypt.  */
191 typedef enum
192   {
193     GPGME_MD_NONE          = 0,  
194     GPGME_MD_MD5           = 1,
195     GPGME_MD_SHA1          = 2,
196     GPGME_MD_RMD160        = 3,
197     GPGME_MD_MD2           = 5,
198     GPGME_MD_TIGER         = 6,   /* TIGER/192. */
199     GPGME_MD_HAVAL         = 7,   /* HAVAL, 5 pass, 160 bit. */
200     GPGME_MD_SHA256        = 8,
201     GPGME_MD_SHA384        = 9,
202     GPGME_MD_SHA512        = 10,
203     GPGME_MD_MD4           = 301,
204     GPGME_MD_CRC32         = 302,
205     GPGME_MD_CRC32_RFC1510 = 303,
206     GPGME_MD_CRC24_RFC2440 = 304
207   }
208 gpgme_hash_algo_t;
209
210 \f
211 /* The possible signature stati.  Deprecated, use error value in sig
212    status.  */
213 typedef enum
214   {
215     GPGME_SIG_STAT_NONE  = 0,
216     GPGME_SIG_STAT_GOOD  = 1,
217     GPGME_SIG_STAT_BAD   = 2,
218     GPGME_SIG_STAT_NOKEY = 3,
219     GPGME_SIG_STAT_NOSIG = 4,
220     GPGME_SIG_STAT_ERROR = 5,
221     GPGME_SIG_STAT_DIFF  = 6,
222     GPGME_SIG_STAT_GOOD_EXP = 7,
223     GPGME_SIG_STAT_GOOD_EXPKEY = 8
224   }
225 _gpgme_sig_stat_t;
226 typedef _gpgme_sig_stat_t gpgme_sig_stat_t _GPGME_DEPRECATED;
227
228
229 /* The available signature modes.  */
230 typedef enum
231   {
232     GPGME_SIG_MODE_NORMAL = 0,
233     GPGME_SIG_MODE_DETACH = 1,
234     GPGME_SIG_MODE_CLEAR  = 2
235   }
236 gpgme_sig_mode_t;
237
238 \f
239 /* The available key and signature attributes.  Deprecated, use the
240    individual result structures instead.  */
241 typedef enum
242   {
243     GPGME_ATTR_KEYID        = 1,
244     GPGME_ATTR_FPR          = 2,
245     GPGME_ATTR_ALGO         = 3,
246     GPGME_ATTR_LEN          = 4,
247     GPGME_ATTR_CREATED      = 5,
248     GPGME_ATTR_EXPIRE       = 6,
249     GPGME_ATTR_OTRUST       = 7,
250     GPGME_ATTR_USERID       = 8,
251     GPGME_ATTR_NAME         = 9,
252     GPGME_ATTR_EMAIL        = 10,
253     GPGME_ATTR_COMMENT      = 11,
254     GPGME_ATTR_VALIDITY     = 12,
255     GPGME_ATTR_LEVEL        = 13,
256     GPGME_ATTR_TYPE         = 14,
257     GPGME_ATTR_IS_SECRET    = 15,
258     GPGME_ATTR_KEY_REVOKED  = 16,
259     GPGME_ATTR_KEY_INVALID  = 17,
260     GPGME_ATTR_UID_REVOKED  = 18,
261     GPGME_ATTR_UID_INVALID  = 19,
262     GPGME_ATTR_KEY_CAPS     = 20,
263     GPGME_ATTR_CAN_ENCRYPT  = 21,
264     GPGME_ATTR_CAN_SIGN     = 22,
265     GPGME_ATTR_CAN_CERTIFY  = 23,
266     GPGME_ATTR_KEY_EXPIRED  = 24,
267     GPGME_ATTR_KEY_DISABLED = 25,
268     GPGME_ATTR_SERIAL       = 26,
269     GPGME_ATTR_ISSUER       = 27,
270     GPGME_ATTR_CHAINID      = 28,
271     GPGME_ATTR_SIG_STATUS   = 29,
272     GPGME_ATTR_ERRTOK       = 30,
273     GPGME_ATTR_SIG_SUMMARY  = 31,
274     GPGME_ATTR_SIG_CLASS    = 32
275   }
276 _gpgme_attr_t;
277 typedef _gpgme_attr_t gpgme_attr_t _GPGME_DEPRECATED;
278
279 \f
280 /* The available validities for a trust item or key.  */
281 typedef enum
282   {
283     GPGME_VALIDITY_UNKNOWN   = 0,
284     GPGME_VALIDITY_UNDEFINED = 1,
285     GPGME_VALIDITY_NEVER     = 2,
286     GPGME_VALIDITY_MARGINAL  = 3,
287     GPGME_VALIDITY_FULL      = 4,
288     GPGME_VALIDITY_ULTIMATE  = 5
289   }
290 gpgme_validity_t;
291
292 \f
293 /* The available protocols.  */
294 typedef enum
295   {
296     GPGME_PROTOCOL_OpenPGP = 0,  /* The default mode.  */
297     GPGME_PROTOCOL_CMS     = 1,
298   }
299 gpgme_protocol_t;
300
301 \f
302 /* The possible stati for the edit operation.  */
303 typedef enum
304   {
305     GPGME_STATUS_EOF,
306     /* mkstatus processing starts here */
307     GPGME_STATUS_ENTER,
308     GPGME_STATUS_LEAVE,
309     GPGME_STATUS_ABORT,
310
311     GPGME_STATUS_GOODSIG,
312     GPGME_STATUS_BADSIG,
313     GPGME_STATUS_ERRSIG,
314
315     GPGME_STATUS_BADARMOR,
316
317     GPGME_STATUS_RSA_OR_IDEA,
318     GPGME_STATUS_KEYEXPIRED,
319     GPGME_STATUS_KEYREVOKED,
320
321     GPGME_STATUS_TRUST_UNDEFINED,
322     GPGME_STATUS_TRUST_NEVER,
323     GPGME_STATUS_TRUST_MARGINAL,
324     GPGME_STATUS_TRUST_FULLY,
325     GPGME_STATUS_TRUST_ULTIMATE,
326
327     GPGME_STATUS_SHM_INFO,
328     GPGME_STATUS_SHM_GET,
329     GPGME_STATUS_SHM_GET_BOOL,
330     GPGME_STATUS_SHM_GET_HIDDEN,
331
332     GPGME_STATUS_NEED_PASSPHRASE,
333     GPGME_STATUS_VALIDSIG,
334     GPGME_STATUS_SIG_ID,
335     GPGME_STATUS_ENC_TO,
336     GPGME_STATUS_NODATA,
337     GPGME_STATUS_BAD_PASSPHRASE,
338     GPGME_STATUS_NO_PUBKEY,
339     GPGME_STATUS_NO_SECKEY,
340     GPGME_STATUS_NEED_PASSPHRASE_SYM,
341     GPGME_STATUS_DECRYPTION_FAILED,
342     GPGME_STATUS_DECRYPTION_OKAY,
343     GPGME_STATUS_MISSING_PASSPHRASE,
344     GPGME_STATUS_GOOD_PASSPHRASE,
345     GPGME_STATUS_GOODMDC,
346     GPGME_STATUS_BADMDC,
347     GPGME_STATUS_ERRMDC,
348     GPGME_STATUS_IMPORTED,
349     GPGME_STATUS_IMPORT_OK,
350     GPGME_STATUS_IMPORT_PROBLEM,
351     GPGME_STATUS_IMPORT_RES,
352     GPGME_STATUS_FILE_START,
353     GPGME_STATUS_FILE_DONE,
354     GPGME_STATUS_FILE_ERROR,
355
356     GPGME_STATUS_BEGIN_DECRYPTION,
357     GPGME_STATUS_END_DECRYPTION,
358     GPGME_STATUS_BEGIN_ENCRYPTION,
359     GPGME_STATUS_END_ENCRYPTION,
360
361     GPGME_STATUS_DELETE_PROBLEM,
362     GPGME_STATUS_GET_BOOL,
363     GPGME_STATUS_GET_LINE,
364     GPGME_STATUS_GET_HIDDEN,
365     GPGME_STATUS_GOT_IT,
366     GPGME_STATUS_PROGRESS,
367     GPGME_STATUS_SIG_CREATED,
368     GPGME_STATUS_SESSION_KEY,
369     GPGME_STATUS_NOTATION_NAME,
370     GPGME_STATUS_NOTATION_DATA,
371     GPGME_STATUS_POLICY_URL,
372     GPGME_STATUS_BEGIN_STREAM,
373     GPGME_STATUS_END_STREAM,
374     GPGME_STATUS_KEY_CREATED,
375     GPGME_STATUS_USERID_HINT,
376     GPGME_STATUS_UNEXPECTED,
377     GPGME_STATUS_INV_RECP,
378     GPGME_STATUS_NO_RECP,
379     GPGME_STATUS_ALREADY_SIGNED,
380     GPGME_STATUS_SIGEXPIRED,
381     GPGME_STATUS_EXPSIG,
382     GPGME_STATUS_EXPKEYSIG,
383     GPGME_STATUS_TRUNCATED,
384     GPGME_STATUS_ERROR
385   }
386 gpgme_status_code_t;
387
388 \f
389 /* The engine information structure.  */
390 struct _gpgme_engine_info
391 {
392   struct _gpgme_engine_info *next;
393
394   /* The protocol ID.  */
395   gpgme_protocol_t protocol;
396
397   /* The file name of the engine binary.  */
398   const char *file_name;
399
400   /* The version string of the installed engine.  */
401   const char *version;
402
403   /* The minimum version required for GPGME.  */
404   const char *req_version;
405 };
406 typedef struct _gpgme_engine_info *gpgme_engine_info_t;
407
408 \f
409 /* A subkey from a key.  */
410 struct _gpgme_subkey
411 {
412   struct _gpgme_subkey *next;
413
414   /* True if subkey is revoked.  */
415   unsigned int revoked : 1;
416
417   /* True if subkey is expired.  */
418   unsigned int expired : 1;
419
420   /* True if subkey is disabled.  */
421   unsigned int disabled : 1;
422
423   /* True if subkey is invalid.  */
424   unsigned int invalid : 1;
425
426   /* True if subkey can be used for encryption.  */
427   unsigned int can_encrypt : 1;
428
429   /* True if subkey can be used for signing.  */
430   unsigned int can_sign : 1;
431
432   /* True if subkey can be used for certification.  */
433   unsigned int can_certify : 1;
434
435   /* True if subkey is secret.  */
436   unsigned int secret : 1;
437
438   /* True if subkey can be used for authentication.  */
439   unsigned int can_authenticate : 1;
440
441   /* Internal to GPGME, do not use.  */
442   unsigned int _unused : 23;
443   
444   /* Public key algorithm supported by this subkey.  */
445   gpgme_pubkey_algo_t pubkey_algo;
446
447   /* Length of the subkey.  */
448   unsigned int length;
449
450   /* The key ID of the subkey.  */
451   char *keyid;
452
453   /* Internal to GPGME, do not use.  */
454   char _keyid[16 + 1];
455
456   /* The fingerprint of the subkey in hex digit form.  */
457   char *fpr;
458
459   /* The creation timestamp, -1 if invalid, 0 if not available.  */
460   long int timestamp;
461
462   /* The expiration timestamp, 0 if the subkey does not expire.  */
463   long int expires;
464 };
465 typedef struct _gpgme_subkey *gpgme_subkey_t;
466
467
468 /* A signature on a user ID.  */
469 struct _gpgme_key_sig
470 {
471   struct _gpgme_key_sig *next;
472
473   /* True if the signature is revoked.  */
474   unsigned int revoked : 1;
475
476   /* True if the signature is expired.  */
477   unsigned int expired : 1;
478
479   /* True if the signature is invalid.  */
480   unsigned int invalid : 1;
481
482   /* True if the signature should be exported.  */
483   unsigned int exportable : 1;
484
485   /* Internal to GPGME, do not use.  */
486   unsigned int _unused : 28;
487
488   /* The public key algorithm used to create the signature.  */
489   gpgme_pubkey_algo_t pubkey_algo;
490
491   /* The key ID of key used to create the signature.  */
492   char *keyid;
493
494   /* Internal to GPGME, do not use.  */
495   char _keyid[16 + 1];
496
497   /* The creation timestamp, -1 if invalid, 0 if not available.  */
498   long int timestamp;
499
500   /* The expiration timestamp, 0 if the subkey does not expire.  */
501   long int expires;
502
503   /* Same as in gpgme_signature_t.  */
504   gpgme_error_t status;
505
506   /* Crypto backend specific signature class.  */
507   unsigned int class;
508
509   /* The user ID string.  */
510   char *uid;
511
512   /* The name part of the user ID.  */
513   char *name;
514
515   /* The email part of the user ID.  */
516   char *email;
517
518   /* The comment part of the user ID.  */
519   char *comment;
520 };
521 typedef struct _gpgme_key_sig *gpgme_key_sig_t;
522
523
524 /* An user ID from a key.  */
525 struct _gpgme_user_id
526 {
527   struct _gpgme_user_id *next;
528
529   /* True if the user ID is revoked.  */
530   unsigned int revoked : 1;
531
532   /* True if the user ID is invalid.  */
533   unsigned int invalid : 1;
534
535   /* Internal to GPGME, do not use.  */
536   unsigned int _unused : 30;
537
538   /* The validity of the user ID.  */
539   gpgme_validity_t validity; 
540
541   /* The user ID string.  */
542   char *uid;
543
544   /* The name part of the user ID.  */
545   char *name;
546
547   /* The email part of the user ID.  */
548   char *email;
549
550   /* The comment part of the user ID.  */
551   char *comment;
552
553   /* The signatures of the user ID.  */
554   gpgme_key_sig_t signatures;
555
556   /* Internal to GPGME, do not use.  */
557   gpgme_key_sig_t _last_keysig;
558 };
559 typedef struct _gpgme_user_id *gpgme_user_id_t;
560
561
562 /* A key from the keyring.  */
563 struct _gpgme_key
564 {
565   /* Internal to GPGME, do not use.  */
566   unsigned int _refs;
567
568   /* True if key is revoked.  */
569   unsigned int revoked : 1;
570
571   /* True if key is expired.  */
572   unsigned int expired : 1;
573
574   /* True if key is disabled.  */
575   unsigned int disabled : 1;
576
577   /* True if key is invalid.  */
578   unsigned int invalid : 1;
579
580   /* True if key can be used for encryption.  */
581   unsigned int can_encrypt : 1;
582
583   /* True if key can be used for signing.  */
584   unsigned int can_sign : 1;
585
586   /* True if key can be used for certification.  */
587   unsigned int can_certify : 1;
588
589   /* True if key is secret.  */
590   unsigned int secret : 1;
591
592   /* True if key can be used for authentication.  */
593   unsigned int can_authenticate : 1;
594
595   /* Internal to GPGME, do not use.  */
596   unsigned int _unused : 23;
597
598   /* This is the protocol supported by this key.  */
599   gpgme_protocol_t protocol;
600
601   /* If protocol is GPGME_PROTOCOL_CMS, this string contains the
602      issuer serial.  */
603   char *issuer_serial;
604
605   /* If protocol is GPGME_PROTOCOL_CMS, this string contains the
606      issuer name.  */
607   char *issuer_name;
608
609   /* If protocol is GPGME_PROTOCOL_CMS, this string contains the chain
610      ID.  */
611   char *chain_id;
612
613   /* If protocol is GPGME_PROTOCOL_OpenPGP, this field contains the
614      owner trust.  */
615   gpgme_validity_t owner_trust;
616
617   /* The subkeys of the key.  */
618   gpgme_subkey_t subkeys;
619
620   /* The user IDs of the key.  */
621   gpgme_user_id_t uids;
622
623   /* Internal to GPGME, do not use.  */
624   gpgme_subkey_t _last_subkey;
625
626   /* Internal to GPGME, do not use.  */
627   gpgme_user_id_t _last_uid;
628 };
629 typedef struct _gpgme_key *gpgme_key_t;
630
631
632 \f
633 /* Types for callback functions.  */
634
635 /* Request a passphrase from the user.  */
636 typedef gpgme_error_t (*gpgme_passphrase_cb_t) (void *hook,
637                                                 const char *uid_hint,
638                                                 const char *passphrase_info,
639                                                 int prev_was_bad, int fd);
640
641 /* Inform the user about progress made.  */
642 typedef void (*gpgme_progress_cb_t) (void *opaque, const char *what,
643                                      int type, int current, int total);
644
645 /* Interact with the user about an edit operation.  */
646 typedef gpgme_error_t (*gpgme_edit_cb_t) (void *opaque,
647                                           gpgme_status_code_t status,
648                                           const char *args, int fd);
649
650 \f
651 /* Context management functions.  */
652
653 /* Create a new context and return it in CTX.  */
654 gpgme_error_t gpgme_new (gpgme_ctx_t *ctx);
655
656 /* Release the context CTX.  */
657 void gpgme_release (gpgme_ctx_t ctx);
658
659 /* Set the protocol to be used by CTX to PROTO.  */
660 gpgme_error_t gpgme_set_protocol (gpgme_ctx_t ctx, gpgme_protocol_t proto);
661
662 /* Get the protocol used with CTX */
663 gpgme_protocol_t gpgme_get_protocol (gpgme_ctx_t ctx);
664
665 /* Get the string describing protocol PROTO, or NULL if invalid.  */
666 const char *gpgme_get_protocol_name (gpgme_protocol_t proto);
667
668 /* If YES is non-zero, enable armor mode in CTX, disable it otherwise.  */
669 void gpgme_set_armor (gpgme_ctx_t ctx, int yes);
670
671 /* Return non-zero if armor mode is set in CTX.  */
672 int gpgme_get_armor (gpgme_ctx_t ctx);
673
674 /* If YES is non-zero, enable text mode in CTX, disable it otherwise.  */
675 void gpgme_set_textmode (gpgme_ctx_t ctx, int yes);
676
677 /* Return non-zero if text mode is set in CTX.  */
678 int gpgme_get_textmode (gpgme_ctx_t ctx);
679
680 /* Include up to NR_OF_CERTS certificates in an S/MIME message.  */
681 void gpgme_set_include_certs (gpgme_ctx_t ctx, int nr_of_certs);
682
683 /* Return the number of certs to include in an S/MIME message.  */
684 int gpgme_get_include_certs (gpgme_ctx_t ctx);
685
686 /* The available keylist mode flags.  */
687 typedef enum
688   {
689     GPGME_KEYLIST_MODE_LOCAL  = 1,
690     GPGME_KEYLIST_MODE_EXTERN = 2,
691     GPGME_KEYLIST_MODE_SIGS   = 4
692   }
693 gpgme_keylist_mode_t;
694
695 /* Set keylist mode in CTX to MODE.  */
696 gpgme_error_t gpgme_set_keylist_mode (gpgme_ctx_t ctx,
697                                       gpgme_keylist_mode_t mode);
698
699 /* Get keylist mode in CTX.  */
700 gpgme_keylist_mode_t gpgme_get_keylist_mode (gpgme_ctx_t ctx);
701
702 /* Set the passphrase callback function in CTX to CB.  HOOK_VALUE is
703    passed as first argument to the passphrase callback function.  */
704 void gpgme_set_passphrase_cb (gpgme_ctx_t ctx,
705                               gpgme_passphrase_cb_t cb, void *hook_value);
706
707 /* Get the current passphrase callback function in *CB and the current
708    hook value in *HOOK_VALUE.  */
709 void gpgme_get_passphrase_cb (gpgme_ctx_t ctx, gpgme_passphrase_cb_t *cb,
710                               void **hook_value);
711
712 /* Set the progress callback function in CTX to CB.  HOOK_VALUE is
713    passed as first argument to the progress callback function.  */
714 void gpgme_set_progress_cb (gpgme_ctx_t c, gpgme_progress_cb_t cb,
715                             void *hook_value);
716
717 /* Get the current progress callback function in *CB and the current
718    hook value in *HOOK_VALUE.  */
719 void gpgme_get_progress_cb (gpgme_ctx_t ctx, gpgme_progress_cb_t *cb,
720                             void **hook_value);
721
722 \f
723 /* Return a statically allocated string with the name of the public
724    key algorithm ALGO, or NULL if that name is not known.  */
725 const char *gpgme_pubkey_algo_name (gpgme_pubkey_algo_t algo);
726
727 /* Return a statically allocated string with the name of the hash
728    algorithm ALGO, or NULL if that name is not known.  */
729 const char *gpgme_hash_algo_name (gpgme_hash_algo_t algo);
730
731 \f
732 /* Delete all signers from CTX.  */
733 void gpgme_signers_clear (gpgme_ctx_t ctx);
734
735 /* Add KEY to list of signers in CTX.  */
736 gpgme_error_t gpgme_signers_add (gpgme_ctx_t ctx, const gpgme_key_t key);
737
738 /* Return the SEQth signer's key in CTX.  */
739 gpgme_key_t gpgme_signers_enum (const gpgme_ctx_t ctx, int seq);
740
741 /* Retrieve the signature status of signature IDX in CTX after a
742    successful verify operation in R_STAT (if non-null).  The creation
743    time stamp of the signature is returned in R_CREATED (if non-null).
744    The function returns a string containing the fingerprint.
745    Deprecated, use verify result directly.  */
746 const char *gpgme_get_sig_status (gpgme_ctx_t ctx, int idx,
747                                   _gpgme_sig_stat_t *r_stat,
748                                   time_t *r_created) _GPGME_DEPRECATED;
749
750 /* Retrieve certain attributes of a signature.  IDX is the index
751    number of the signature after a successful verify operation.  WHAT
752    is an attribute where GPGME_ATTR_EXPIRE is probably the most useful
753    one.  WHATIDX is to be passed as 0 for most attributes . */
754 unsigned long gpgme_get_sig_ulong_attr (gpgme_ctx_t c, int idx,
755                                         _gpgme_attr_t what, int whatidx)
756      _GPGME_DEPRECATED;
757 const char *gpgme_get_sig_string_attr (gpgme_ctx_t c, int idx,
758                                        _gpgme_attr_t what, int whatidx)
759      _GPGME_DEPRECATED;
760
761
762 /* Get the key used to create signature IDX in CTX and return it in
763    R_KEY.  */
764 gpgme_error_t gpgme_get_sig_key (gpgme_ctx_t ctx, int idx, gpgme_key_t *r_key)
765      _GPGME_DEPRECATED;
766
767 \f
768 /* Run control.  */
769
770 /* The type of an I/O callback function.  */
771 typedef gpgme_error_t (*gpgme_io_cb_t) (void *data, int fd);
772
773 /* The type of a function that can register FNC as the I/O callback
774    function for the file descriptor FD with direction dir (0: for writing,
775    1: for reading).  FNC_DATA should be passed as DATA to FNC.  The
776    function should return a TAG suitable for the corresponding
777    gpgme_remove_io_cb_t, and an error value.  */
778 typedef gpgme_error_t (*gpgme_register_io_cb_t) (void *data, int fd, int dir,
779                                                  gpgme_io_cb_t fnc,
780                                                  void *fnc_data, void **tag);
781
782 /* The type of a function that can remove a previously registered I/O
783    callback function given TAG as returned by the register
784    function.  */
785 typedef void (*gpgme_remove_io_cb_t) (void *tag);
786
787 typedef enum
788   {
789     GPGME_EVENT_START,
790     GPGME_EVENT_DONE,
791     GPGME_EVENT_NEXT_KEY,
792     GPGME_EVENT_NEXT_TRUSTITEM
793   }
794 gpgme_event_io_t;
795
796 /* The type of a function that is called when a context finished an
797    operation.  */
798 typedef void (*gpgme_event_io_cb_t) (void *data, gpgme_event_io_t type,
799                                      void *type_data);
800
801 struct gpgme_io_cbs
802 {
803   gpgme_register_io_cb_t add;
804   void *add_priv;
805   gpgme_remove_io_cb_t remove;
806   gpgme_event_io_cb_t event;
807   void *event_priv;
808 };
809 typedef struct gpgme_io_cbs *gpgme_io_cbs_t;
810
811 /* Set the I/O callback functions in CTX to IO_CBS.  */
812 void gpgme_set_io_cbs (gpgme_ctx_t ctx, gpgme_io_cbs_t io_cbs);
813
814 /* Get the current I/O callback functions.  */
815 void gpgme_get_io_cbs (gpgme_ctx_t ctx, gpgme_io_cbs_t io_cbs);
816
817 /* Process the pending operation and, if HANG is non-zero, wait for
818    the pending operation to finish.  */
819 gpgme_ctx_t gpgme_wait (gpgme_ctx_t ctx, gpgme_error_t *status, int hang);
820
821 \f
822 /* Functions to handle data objects.  */
823
824 /* Read up to SIZE bytes into buffer BUFFER from the data object with
825    the handle HANDLE.  Return the number of characters read, 0 on EOF
826    and -1 on error.  If an error occurs, errno is set.  */
827 typedef ssize_t (*gpgme_data_read_cb_t) (void *handle, void *buffer,
828                                          size_t size);
829
830 /* Write up to SIZE bytes from buffer BUFFER to the data object with
831    the handle HANDLE.  Return the number of characters written, or -1
832    on error.  If an error occurs, errno is set.  */
833 typedef ssize_t (*gpgme_data_write_cb_t) (void *handle, const void *buffer,
834                                           size_t size);
835
836 /* Set the current position from where the next read or write starts
837    in the data object with the handle HANDLE to OFFSET, relativ to
838    WHENCE.  */
839 typedef off_t (*gpgme_data_seek_cb_t) (void *handle, off_t offset, int whence);
840
841 /* Close the data object with the handle DL.  */
842 typedef void (*gpgme_data_release_cb_t) (void *handle);
843
844 struct gpgme_data_cbs
845 {
846   gpgme_data_read_cb_t read;
847   gpgme_data_write_cb_t write;
848   gpgme_data_seek_cb_t seek;
849   gpgme_data_release_cb_t release;
850 };
851 typedef struct gpgme_data_cbs *gpgme_data_cbs_t;
852
853 /* Read up to SIZE bytes into buffer BUFFER from the data object with
854    the handle DH.  Return the number of characters read, 0 on EOF and
855    -1 on error.  If an error occurs, errno is set.  */
856 ssize_t gpgme_data_read (gpgme_data_t dh, void *buffer, size_t size);
857
858 /* Write up to SIZE bytes from buffer BUFFER to the data object with
859    the handle DH.  Return the number of characters written, or -1 on
860    error.  If an error occurs, errno is set.  */
861 ssize_t gpgme_data_write (gpgme_data_t dh, const void *buffer, size_t size);
862
863 /* Set the current position from where the next read or write starts
864    in the data object with the handle DH to OFFSET, relativ to
865    WHENCE.  */
866 off_t gpgme_data_seek (gpgme_data_t dh, off_t offset, int whence);
867
868 /* Create a new data buffer and return it in R_DH.  */
869 gpgme_error_t gpgme_data_new (gpgme_data_t *r_dh);
870
871 /* Destroy the data buffer DH.  */
872 void gpgme_data_release (gpgme_data_t dh);
873
874 /* Create a new data buffer filled with SIZE bytes starting from
875    BUFFER.  If COPY is zero, copying is delayed until necessary, and
876    the data is taken from the original location when needed.  */
877 gpgme_error_t gpgme_data_new_from_mem (gpgme_data_t *r_dh,
878                                        const char *buffer, size_t size,
879                                        int copy);
880
881 /* Destroy the data buffer DH and return a pointer to its content.
882    The memory has be to released with free by the user.  It's size is
883    returned in R_LEN.  */
884 char *gpgme_data_release_and_get_mem (gpgme_data_t dh, size_t *r_len);
885
886 gpgme_error_t gpgme_data_new_from_cbs (gpgme_data_t *dh,
887                                        gpgme_data_cbs_t cbs,
888                                        void *handle);
889
890 gpgme_error_t gpgme_data_new_from_fd (gpgme_data_t *dh, int fd);
891
892 gpgme_error_t gpgme_data_new_from_stream (gpgme_data_t *dh, FILE *stream);
893
894 /* Return the encoding attribute of the data buffer DH */
895 gpgme_data_encoding_t gpgme_data_get_encoding (gpgme_data_t dh);
896
897 /* Set the encoding attribute of data buffer DH to ENC */
898 gpgme_error_t gpgme_data_set_encoding (gpgme_data_t dh,
899                                        gpgme_data_encoding_t enc);
900
901
902
903 /* Create a new data buffer which retrieves the data from the callback
904    function READ_CB.  Deprecated, please use gpgme_data_new_from_cbs
905    instead.  */
906 gpgme_error_t gpgme_data_new_with_read_cb (gpgme_data_t *r_dh,
907                                            int (*read_cb) (void*,char *,
908                                                            size_t,size_t*),
909                                            void *read_cb_value)
910      _GPGME_DEPRECATED;
911
912 /* Create a new data buffer filled with the content of file FNAME.
913    COPY must be non-zero.  For delayed read, please use
914    gpgme_data_new_from_fd or gpgme_data_new_from stream instead.  */
915 gpgme_error_t gpgme_data_new_from_file (gpgme_data_t *r_dh,
916                                         const char *fname,
917                                         int copy);
918
919 /* Create a new data buffer filled with LENGTH bytes starting from
920    OFFSET within the file FNAME or stream FP (exactly one must be
921    non-zero).  */
922 gpgme_error_t gpgme_data_new_from_filepart (gpgme_data_t *r_dh,
923                                             const char *fname, FILE *fp,
924                                             off_t offset, size_t length);
925
926 /* Reset the read pointer in DH.  Deprecated, please use
927    gpgme_data_seek instead.  */
928 gpgme_error_t gpgme_data_rewind (gpgme_data_t dh) _GPGME_DEPRECATED;
929
930 \f
931 /* Key and trust functions.  */
932
933 /* Get the key with the fingerprint FPR from the crypto backend.  If
934    SECRET is true, get the secret key.  */
935 gpgme_error_t gpgme_get_key (gpgme_ctx_t ctx, const char *fpr,
936                              gpgme_key_t *r_key, int secret);
937
938 /* Acquire a reference to KEY.  */
939 void gpgme_key_ref (gpgme_key_t key);
940
941 /* Release a reference to KEY.  If this was the last one the key is
942    destroyed.  */
943 void gpgme_key_unref (gpgme_key_t key);
944 void gpgme_key_release (gpgme_key_t key);
945
946 /* Return the value of the attribute WHAT of KEY, which has to be
947    representable by a string.  IDX specifies the sub key or user ID
948    for attributes related to sub keys or user IDs.  Deprecated, use
949    key structure directly instead. */
950 const char *gpgme_key_get_string_attr (gpgme_key_t key, _gpgme_attr_t what,
951                                        const void *reserved, int idx)
952      _GPGME_DEPRECATED;
953
954 /* Return the value of the attribute WHAT of KEY, which has to be
955    representable by an unsigned integer.  IDX specifies the sub key or
956    user ID for attributes related to sub keys or user IDs.
957    Deprecated, use key structure directly instead.  */
958 unsigned long gpgme_key_get_ulong_attr (gpgme_key_t key, _gpgme_attr_t what,
959                                         const void *reserved, int idx)
960      _GPGME_DEPRECATED;
961
962 /* Return the value of the attribute WHAT of a signature on user ID
963    UID_IDX in KEY, which has to be representable by a string.  IDX
964    specifies the signature.  Deprecated, use key structure directly
965    instead.  */
966 const char *gpgme_key_sig_get_string_attr (gpgme_key_t key, int uid_idx,
967                                            _gpgme_attr_t what,
968                                            const void *reserved, int idx)
969      _GPGME_DEPRECATED;
970
971 /* Return the value of the attribute WHAT of a signature on user ID
972    UID_IDX in KEY, which has to be representable by an unsigned
973    integer string.  IDX specifies the signature.  Deprecated, use key
974    structure directly instead.  */
975 unsigned long gpgme_key_sig_get_ulong_attr (gpgme_key_t key, int uid_idx,
976                                             _gpgme_attr_t what,
977                                             const void *reserved, int idx)
978      _GPGME_DEPRECATED;
979
980 \f
981 /* Crypto Operations.  */
982
983 struct _gpgme_invalid_key
984 {
985   struct _gpgme_invalid_key *next;
986   char *fpr;
987   gpgme_error_t reason;
988 };
989 typedef struct _gpgme_invalid_key *gpgme_invalid_key_t;
990
991 \f
992 /* Encryption.  */
993 struct _gpgme_op_encrypt_result
994 {
995   /* The list of invalid recipients.  */
996   gpgme_invalid_key_t invalid_recipients;
997 };
998 typedef struct _gpgme_op_encrypt_result *gpgme_encrypt_result_t;
999
1000 /* Retrieve a pointer to the result of the encrypt operation.  */
1001 gpgme_encrypt_result_t gpgme_op_encrypt_result (gpgme_ctx_t ctx);
1002
1003 /* The valid encryption flags.  */
1004 typedef enum
1005   {
1006     GPGME_ENCRYPT_ALWAYS_TRUST = 1
1007   }
1008 gpgme_encrypt_flags_t;
1009
1010 /* Encrypt plaintext PLAIN within CTX for the recipients RECP and
1011    store the resulting ciphertext in CIPHER.  */
1012 gpgme_error_t gpgme_op_encrypt_start (gpgme_ctx_t ctx, gpgme_key_t recp[],
1013                                       gpgme_encrypt_flags_t flags,
1014                                       gpgme_data_t plain, gpgme_data_t cipher);
1015 gpgme_error_t gpgme_op_encrypt (gpgme_ctx_t ctx, gpgme_key_t recp[],
1016                                 gpgme_encrypt_flags_t flags,
1017                                 gpgme_data_t plain, gpgme_data_t cipher);
1018
1019 /* Encrypt plaintext PLAIN within CTX for the recipients RECP and
1020    store the resulting ciphertext in CIPHER.  Also sign the ciphertext
1021    with the signers in CTX.  */
1022 gpgme_error_t gpgme_op_encrypt_sign_start (gpgme_ctx_t ctx,
1023                                            gpgme_key_t recp[],
1024                                            gpgme_encrypt_flags_t flags,
1025                                            gpgme_data_t plain,
1026                                            gpgme_data_t cipher);
1027 gpgme_error_t gpgme_op_encrypt_sign (gpgme_ctx_t ctx, gpgme_key_t recp[],
1028                                      gpgme_encrypt_flags_t flags,
1029                                      gpgme_data_t plain, gpgme_data_t cipher);
1030
1031 \f
1032 /* Decryption.  */
1033 struct _gpgme_op_decrypt_result
1034 {
1035   char *unsupported_algorithm;
1036 };
1037 typedef struct _gpgme_op_decrypt_result *gpgme_decrypt_result_t;
1038
1039 /* Retrieve a pointer to the result of the decrypt operation.  */
1040 gpgme_decrypt_result_t gpgme_op_decrypt_result (gpgme_ctx_t ctx);
1041
1042 /* Decrypt ciphertext CIPHER within CTX and store the resulting
1043    plaintext in PLAIN.  */
1044 gpgme_error_t gpgme_op_decrypt_start (gpgme_ctx_t ctx, gpgme_data_t cipher,
1045                                       gpgme_data_t plain);
1046 gpgme_error_t gpgme_op_decrypt (gpgme_ctx_t ctx,
1047                                 gpgme_data_t cipher, gpgme_data_t plain);
1048
1049 /* Decrypt ciphertext CIPHER and make a signature verification within
1050    CTX and store the resulting plaintext in PLAIN.  */
1051 gpgme_error_t gpgme_op_decrypt_verify_start (gpgme_ctx_t ctx,
1052                                              gpgme_data_t cipher,
1053                                              gpgme_data_t plain);
1054 gpgme_error_t gpgme_op_decrypt_verify (gpgme_ctx_t ctx, gpgme_data_t cipher,
1055                                        gpgme_data_t plain);
1056
1057 \f
1058 /* Signing.  */
1059 struct _gpgme_new_signature
1060 {
1061   struct _gpgme_new_signature *next;
1062
1063   /* The type of the signature.  */
1064   gpgme_sig_mode_t type;
1065
1066   /* The public key algorithm used to create the signature.  */
1067   gpgme_pubkey_algo_t pubkey_algo;
1068
1069   /* The hash algorithm used to create the signature.  */
1070   gpgme_hash_algo_t hash_algo;
1071
1072   /* Internal to GPGME, do not use.  Must be set to the same value as
1073      CLASS below.  */
1074   unsigned long _obsolete_class;
1075
1076   /* Signature creation time.  */
1077   long int timestamp;
1078
1079   /* The fingerprint of the signature.  */
1080   char *fpr;
1081
1082   /* Crypto backend specific signature class.  */
1083   unsigned int class;
1084 };
1085 typedef struct _gpgme_new_signature *gpgme_new_signature_t;
1086
1087 struct _gpgme_op_sign_result
1088 {
1089   /* The list of invalid signers.  */
1090   gpgme_invalid_key_t invalid_signers;
1091   gpgme_new_signature_t signatures;
1092 };
1093 typedef struct _gpgme_op_sign_result *gpgme_sign_result_t;
1094
1095 /* Retrieve a pointer to the result of the signing operation.  */
1096 gpgme_sign_result_t gpgme_op_sign_result (gpgme_ctx_t ctx);
1097
1098 /* Sign the plaintext PLAIN and store the signature in SIG.  */
1099 gpgme_error_t gpgme_op_sign_start (gpgme_ctx_t ctx,
1100                                    gpgme_data_t plain, gpgme_data_t sig,
1101                                    gpgme_sig_mode_t mode);
1102 gpgme_error_t gpgme_op_sign (gpgme_ctx_t ctx,
1103                              gpgme_data_t plain, gpgme_data_t sig,
1104                              gpgme_sig_mode_t mode);
1105
1106 \f
1107 /* Verify.  */
1108 struct _gpgme_sig_notation
1109 {
1110   struct _gpgme_sig_notation *next;
1111
1112   /* If NAME is a null pointer, then VALUE contains a policy URL
1113      rather than a notation.  */
1114   char *name;
1115   char *value;
1116 };
1117 typedef struct _gpgme_sig_notation *gpgme_sig_notation_t;
1118
1119 /* Flags used for the SUMMARY field in a gpgme_signature_t.  */
1120 typedef enum
1121   {
1122     GPGME_SIGSUM_VALID       = 0x0001,  /* The signature is fully valid.  */
1123     GPGME_SIGSUM_GREEN       = 0x0002,  /* The signature is good.  */
1124     GPGME_SIGSUM_RED         = 0x0004,  /* The signature is bad.  */
1125     GPGME_SIGSUM_KEY_REVOKED = 0x0010,  /* One key has been revoked.  */
1126     GPGME_SIGSUM_KEY_EXPIRED = 0x0020,  /* One key has expired.  */
1127     GPGME_SIGSUM_SIG_EXPIRED = 0x0040,  /* The signature has expired.  */
1128     GPGME_SIGSUM_KEY_MISSING = 0x0080,  /* Can't verify: key missing.  */
1129     GPGME_SIGSUM_CRL_MISSING = 0x0100,  /* CRL not available.  */
1130     GPGME_SIGSUM_CRL_TOO_OLD = 0x0200,  /* Available CRL is too old.  */
1131     GPGME_SIGSUM_BAD_POLICY  = 0x0400,  /* A policy was not met.  */
1132     GPGME_SIGSUM_SYS_ERROR   = 0x0800   /* A system error occured.  */
1133   }
1134 gpgme_sigsum_t;
1135
1136 struct _gpgme_signature
1137 {
1138   struct _gpgme_signature *next;
1139
1140   /* A summary of the signature status.  */
1141   gpgme_sigsum_t summary;
1142
1143   /* The fingerprint or key ID of the signature.  */
1144   char *fpr;
1145
1146   /* The status of the signature.  */
1147   gpgme_error_t status;
1148
1149   /* Notation data and policy URLs.  */
1150   gpgme_sig_notation_t notations;
1151
1152   /* Signature creation time.  */
1153   unsigned long timestamp;
1154
1155   /* Signature exipration time or 0.  */
1156   unsigned long exp_timestamp;
1157
1158   int wrong_key_usage : 1;
1159
1160   /* Internal to GPGME, do not use.  */
1161   int _unused : 31;
1162
1163   gpgme_validity_t validity;
1164   gpgme_error_t validity_reason;
1165 };
1166 typedef struct _gpgme_signature *gpgme_signature_t;
1167
1168 struct _gpgme_op_verify_result
1169 {
1170   gpgme_signature_t signatures;
1171 };
1172 typedef struct _gpgme_op_verify_result *gpgme_verify_result_t;
1173
1174 /* Retrieve a pointer to the result of the verify operation.  */
1175 gpgme_verify_result_t gpgme_op_verify_result (gpgme_ctx_t ctx);
1176
1177 /* Verify within CTX that SIG is a valid signature for TEXT.  */
1178 gpgme_error_t gpgme_op_verify_start (gpgme_ctx_t ctx, gpgme_data_t sig,
1179                                      gpgme_data_t signed_text,
1180                                      gpgme_data_t plaintext);
1181 gpgme_error_t gpgme_op_verify (gpgme_ctx_t ctx, gpgme_data_t sig,
1182                                gpgme_data_t signed_text,
1183                                gpgme_data_t plaintext);
1184
1185 \f
1186 /* Import.  */
1187 enum
1188   {
1189     /* The key was new.  */
1190     GPGME_IMPORT_NEW = 1,
1191
1192     /* The key contained new user IDs.  */
1193     GPGME_IMPORT_UID = 2,
1194
1195     /* The key contained new signatures.  */
1196     GPGME_IMPORT_SIG = 4,
1197
1198     /* The key contained new sub keys.  */
1199     GPGME_IMPORT_SUBKEY = 8,
1200
1201     /* The key contained a secret key.  */
1202     GPGME_IMPORT_SECRET = 16
1203   };
1204
1205 struct _gpgme_import_status
1206 {
1207   struct _gpgme_import_status *next;
1208
1209   /* Fingerprint.  */
1210   char *fpr;
1211
1212   /* If a problem occured, the reason why the key could not be
1213      imported.  Otherwise GPGME_No_Error.  */
1214   gpgme_error_t result;
1215
1216   /* The result of the import, the GPGME_IMPORT_* values bit-wise
1217      ORed.  0 means the key was already known and no new components
1218      have been added.  */
1219   unsigned int status;
1220 };
1221 typedef struct _gpgme_import_status *gpgme_import_status_t;
1222
1223 /* Import.  */
1224 struct _gpgme_op_import_result
1225 {
1226   /* Number of considered keys.  */
1227   int considered;
1228
1229   /* Keys without user ID.  */
1230   int no_user_id;
1231
1232   /* Imported keys.  */
1233   int imported;
1234
1235   /* Imported RSA keys.  */
1236   int imported_rsa;
1237
1238   /* Unchanged keys.  */
1239   int unchanged;
1240
1241   /* Number of new user ids.  */
1242   int new_user_ids;
1243
1244   /* Number of new sub keys.  */
1245   int new_sub_keys;
1246
1247   /* Number of new signatures.  */
1248   int new_signatures;
1249
1250   /* Number of new revocations.  */
1251   int new_revocations;
1252
1253   /* Number of secret keys read.  */
1254   int secret_read;
1255
1256   /* Number of secret keys imported.  */
1257   int secret_imported;
1258
1259   /* Number of secret keys unchanged.  */
1260   int secret_unchanged;
1261
1262   /* Number of new keys skipped.  */
1263   int skipped_new_keys;
1264
1265   /* Number of keys not imported.  */
1266   int not_imported;
1267
1268   /* List of keys for which an import was attempted.  */
1269   gpgme_import_status_t imports;
1270 };
1271 typedef struct _gpgme_op_import_result *gpgme_import_result_t;
1272
1273 /* Retrieve a pointer to the result of the import operation.  */
1274 gpgme_import_result_t gpgme_op_import_result (gpgme_ctx_t ctx);
1275
1276 /* Import the key in KEYDATA into the keyring.  */
1277 gpgme_error_t gpgme_op_import_start (gpgme_ctx_t ctx, gpgme_data_t keydata);
1278 gpgme_error_t gpgme_op_import (gpgme_ctx_t ctx, gpgme_data_t keydata);
1279 gpgme_error_t gpgme_op_import_ext (gpgme_ctx_t ctx, gpgme_data_t keydata,
1280                                    int *nr) _GPGME_DEPRECATED;
1281
1282 \f
1283 /* Export the keys found by PATTERN into KEYDATA.  */
1284 gpgme_error_t gpgme_op_export_start (gpgme_ctx_t ctx, const char *pattern,
1285                                      unsigned int reserved,
1286                                      gpgme_data_t keydata);
1287 gpgme_error_t gpgme_op_export (gpgme_ctx_t ctx, const char *pattern,
1288                                unsigned int reserved, gpgme_data_t keydata);
1289
1290 gpgme_error_t gpgme_op_export_ext_start (gpgme_ctx_t ctx,
1291                                          const char *pattern[],
1292                                          unsigned int reserved,
1293                                          gpgme_data_t keydata);
1294 gpgme_error_t gpgme_op_export_ext (gpgme_ctx_t ctx, const char *pattern[],
1295                                    unsigned int reserved,
1296                                    gpgme_data_t keydata);
1297
1298 \f
1299 /* Key generation.  */
1300 struct _gpgme_op_genkey_result
1301 {
1302   /* A primary key was generated.  */
1303   unsigned int primary : 1;
1304
1305   /* A sub key was generated.  */
1306   unsigned int sub : 1;
1307
1308   /* Internal to GPGME, do not use.  */
1309   unsigned int _unused : 30;
1310
1311   /* The fingerprint of the generated key.  */
1312   char *fpr;
1313 };
1314 typedef struct _gpgme_op_genkey_result *gpgme_genkey_result_t;
1315
1316 /* Generate a new keypair and add it to the keyring.  PUBKEY and
1317    SECKEY should be null for now.  PARMS specifies what keys should be
1318    generated.  */
1319 gpgme_error_t gpgme_op_genkey_start (gpgme_ctx_t ctx, const char *parms,
1320                                      gpgme_data_t pubkey, gpgme_data_t seckey);
1321 gpgme_error_t gpgme_op_genkey (gpgme_ctx_t ctx, const char *parms,
1322                                gpgme_data_t pubkey, gpgme_data_t seckey);
1323
1324 /* Retrieve a pointer to the result of the genkey operation.  */
1325 gpgme_genkey_result_t gpgme_op_genkey_result (gpgme_ctx_t ctx);
1326
1327 \f
1328 /* Delete KEY from the keyring.  If ALLOW_SECRET is non-zero, secret
1329    keys are also deleted.  */
1330 gpgme_error_t gpgme_op_delete_start (gpgme_ctx_t ctx, const gpgme_key_t key,
1331                                      int allow_secret);
1332 gpgme_error_t gpgme_op_delete (gpgme_ctx_t ctx, const gpgme_key_t key,
1333                                int allow_secret);
1334
1335 \f
1336 /* Edit the key KEY.  Send status and command requests to FNC and
1337    output of edit commands to OUT.  */
1338 gpgme_error_t gpgme_op_edit_start (gpgme_ctx_t ctx, gpgme_key_t key,
1339                                    gpgme_edit_cb_t fnc, void *fnc_value,
1340                                    gpgme_data_t out);
1341 gpgme_error_t gpgme_op_edit (gpgme_ctx_t ctx, gpgme_key_t key,
1342                              gpgme_edit_cb_t fnc, void *fnc_value,
1343                              gpgme_data_t out);
1344
1345 \f
1346 /* Key management functions.  */
1347 struct _gpgme_op_keylist_result
1348 {
1349   unsigned int truncated : 1;
1350
1351   /* Internal to GPGME, do not use.  */
1352   unsigned int _unused : 31;
1353 };
1354 typedef struct _gpgme_op_keylist_result *gpgme_keylist_result_t;
1355
1356 /* Retrieve a pointer to the result of the key listing operation.  */
1357 gpgme_keylist_result_t gpgme_op_keylist_result (gpgme_ctx_t ctx);
1358
1359 /* Start a keylist operation within CTX, searching for keys which
1360    match PATTERN.  If SECRET_ONLY is true, only secret keys are
1361    returned.  */
1362 gpgme_error_t gpgme_op_keylist_start (gpgme_ctx_t ctx, const char *pattern,
1363                                       int secret_only);
1364 gpgme_error_t gpgme_op_keylist_ext_start (gpgme_ctx_t ctx,
1365                                           const char *pattern[],
1366                                           int secret_only, int reserved);
1367
1368 /* Return the next key from the keylist in R_KEY.  */
1369 gpgme_error_t gpgme_op_keylist_next (gpgme_ctx_t ctx, gpgme_key_t *r_key);
1370
1371 /* Terminate a pending keylist operation within CTX.  */
1372 gpgme_error_t gpgme_op_keylist_end (gpgme_ctx_t ctx);
1373
1374 \f
1375 /* Trust items and operations.  */
1376
1377 struct _gpgme_trust_item
1378 {
1379   /* Internal to GPGME, do not use.  */
1380   unsigned int _refs;
1381
1382   /* The key ID to which the trust item belongs.  */
1383   char *keyid;
1384
1385   /* Internal to GPGME, do not use.  */
1386   char _keyid[16 + 1];
1387
1388   /* The type of the trust item, 1 refers to a key, 2 to a user ID.  */
1389   int type;
1390
1391   /* The trust level.  */
1392   int level;
1393
1394   /* The owner trust if TYPE is 1.  */
1395   char *owner_trust;
1396
1397   /* Internal to GPGME, do not use.  */
1398   char _owner_trust[2];
1399
1400   /* The calculated validity.  */
1401   char *validity;
1402  
1403   /* Internal to GPGME, do not use.  */
1404   char _validity[2];
1405
1406   /* The user name if TYPE is 2.  */
1407   char *name;
1408 };
1409 typedef struct _gpgme_trust_item *gpgme_trust_item_t;
1410
1411 /* Start a trustlist operation within CTX, searching for trust items
1412    which match PATTERN.  */
1413 gpgme_error_t gpgme_op_trustlist_start (gpgme_ctx_t ctx,
1414                                         const char *pattern, int max_level);
1415
1416 /* Return the next trust item from the trustlist in R_ITEM.  */
1417 gpgme_error_t gpgme_op_trustlist_next (gpgme_ctx_t ctx,
1418                                        gpgme_trust_item_t *r_item);
1419
1420 /* Terminate a pending trustlist operation within CTX.  */
1421 gpgme_error_t gpgme_op_trustlist_end (gpgme_ctx_t ctx);
1422
1423 /* Acquire a reference to ITEM.  */
1424 void gpgme_trust_item_ref (gpgme_trust_item_t item);
1425
1426 /* Release a reference to ITEM.  If this was the last one the trust
1427    item is destroyed.  */
1428 void gpgme_trust_item_unref (gpgme_trust_item_t item);
1429
1430 /* Release the trust item ITEM.  Deprecated, use
1431    gpgme_trust_item_unref.  */
1432 void gpgme_trust_item_release (gpgme_trust_item_t item) _GPGME_DEPRECATED;
1433
1434 /* Return the value of the attribute WHAT of ITEM, which has to be
1435    representable by a string.  Deprecated, use trust item structure
1436    directly.  */
1437 const char *gpgme_trust_item_get_string_attr (gpgme_trust_item_t item,
1438                                               _gpgme_attr_t what,
1439                                               const void *reserved, int idx)
1440      _GPGME_DEPRECATED;
1441
1442 /* Return the value of the attribute WHAT of KEY, which has to be
1443    representable by an integer.  IDX specifies a running index if the
1444    attribute appears more than once in the key.  Deprecated, use trust
1445    item structure directly.  */
1446 int gpgme_trust_item_get_int_attr (gpgme_trust_item_t item, _gpgme_attr_t what,
1447                                    const void *reserved, int idx)
1448      _GPGME_DEPRECATED;
1449
1450 \f
1451 /* Various functions.  */
1452
1453 /* Check that the library fulfills the version requirement.  */
1454 const char *gpgme_check_version (const char *req_version);
1455
1456 /* Retrieve information about the backend engines.  */
1457 gpgme_error_t gpgme_get_engine_info (gpgme_engine_info_t *engine_info);
1458
1459 \f
1460 /* Engine support functions.  */
1461
1462 /* Verify that the engine implementing PROTO is installed and
1463    available.  */
1464 gpgme_error_t gpgme_engine_check_version (gpgme_protocol_t proto);
1465
1466 \f
1467 /* Deprecated types.  */
1468 typedef gpgme_ctx_t GpgmeCtx _GPGME_DEPRECATED;
1469 typedef gpgme_data_t GpgmeData _GPGME_DEPRECATED;
1470 typedef gpgme_error_t GpgmeError _GPGME_DEPRECATED;
1471 typedef gpgme_data_encoding_t GpgmeDataEncoding _GPGME_DEPRECATED;
1472 typedef gpgme_pubkey_algo_t GpgmePubKeyAlgo _GPGME_DEPRECATED;
1473 typedef gpgme_hash_algo_t GpgmeHashAlgo _GPGME_DEPRECATED;
1474 typedef gpgme_sig_stat_t GpgmeSigStat _GPGME_DEPRECATED;
1475 typedef gpgme_sig_mode_t GpgmeSigMode _GPGME_DEPRECATED;
1476 typedef gpgme_attr_t GpgmeAttr _GPGME_DEPRECATED;
1477 typedef gpgme_validity_t GpgmeValidity _GPGME_DEPRECATED;
1478 typedef gpgme_protocol_t GpgmeProtocol _GPGME_DEPRECATED;
1479 typedef gpgme_engine_info_t GpgmeEngineInfo _GPGME_DEPRECATED;
1480 typedef gpgme_subkey_t GpgmeSubkey _GPGME_DEPRECATED;
1481 typedef gpgme_key_sig_t GpgmeKeySig _GPGME_DEPRECATED;
1482 typedef gpgme_user_id_t GpgmeUserID _GPGME_DEPRECATED;
1483 typedef gpgme_key_t GpgmeKey _GPGME_DEPRECATED;
1484 typedef gpgme_passphrase_cb_t GpgmePassphraseCb _GPGME_DEPRECATED;
1485 typedef gpgme_progress_cb_t GpgmeProgressCb _GPGME_DEPRECATED;
1486 typedef gpgme_io_cb_t GpgmeIOCb _GPGME_DEPRECATED;
1487 typedef gpgme_register_io_cb_t GpgmeRegisterIOCb _GPGME_DEPRECATED;
1488 typedef gpgme_remove_io_cb_t GpgmeRemoveIOCb _GPGME_DEPRECATED;
1489 typedef gpgme_event_io_t GpgmeEventIO _GPGME_DEPRECATED;
1490 typedef gpgme_event_io_cb_t GpgmeEventIOCb _GPGME_DEPRECATED;
1491 #define GpgmeIOCbs gpgme_io_cbs
1492 typedef gpgme_data_read_cb_t GpgmeDataReadCb _GPGME_DEPRECATED;
1493 typedef gpgme_data_write_cb_t GpgmeDataWriteCb _GPGME_DEPRECATED;
1494 typedef gpgme_data_seek_cb_t GpgmeDataSeekCb _GPGME_DEPRECATED;
1495 typedef gpgme_data_release_cb_t GpgmeDataReleaseCb _GPGME_DEPRECATED;
1496 #define GpgmeDataCbs gpgme_data_cbs
1497 typedef gpgme_encrypt_result_t GpgmeEncryptResult _GPGME_DEPRECATED;
1498 typedef gpgme_sig_notation_t GpgmeSigNotation _GPGME_DEPRECATED;
1499 typedef gpgme_signature_t GpgmeSignature _GPGME_DEPRECATED;
1500 typedef gpgme_verify_result_t GpgmeVerifyResult _GPGME_DEPRECATED;
1501 typedef gpgme_import_status_t GpgmeImportStatus _GPGME_DEPRECATED;
1502 typedef gpgme_import_result_t GpgmeImportResult _GPGME_DEPRECATED;
1503 typedef gpgme_genkey_result_t GpgmeGenKeyResult _GPGME_DEPRECATED;
1504 typedef gpgme_trust_item_t GpgmeTrustItem _GPGME_DEPRECATED;
1505 typedef gpgme_status_code_t GpgmeStatusCode _GPGME_DEPRECATED;
1506
1507 #ifdef __cplusplus
1508 }
1509 #endif
1510 #endif /* GPGME_H */