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