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