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.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   /* True if subkey can be used for authentication.  */
425   unsigned int can_authenticate : 1;
426
427   /* Internal to GPGME, do not use.  */
428   unsigned int _unused : 23;
429   
430   /* Public key algorithm supported by this subkey.  */
431   gpgme_pubkey_algo_t pubkey_algo;
432
433   /* Length of the subkey.  */
434   unsigned int length;
435
436   /* The key ID of the subkey.  */
437   char *keyid;
438
439   /* Internal to GPGME, do not use.  */
440   char _keyid[16 + 1];
441
442   /* The fingerprint of the subkey in hex digit form.  */
443   char *fpr;
444
445   /* The creation timestamp, -1 if invalid, 0 if not available.  */
446   long int timestamp;
447
448   /* The expiration timestamp, 0 if the subkey does not expire.  */
449   long int expires;
450 };
451 typedef struct _gpgme_subkey *gpgme_subkey_t;
452
453
454 /* A signature on a user ID.  */
455 struct _gpgme_key_sig
456 {
457   struct _gpgme_key_sig *next;
458
459   /* True if the signature is revoked.  */
460   unsigned int revoked : 1;
461
462   /* True if the signature is expired.  */
463   unsigned int expired : 1;
464
465   /* True if the signature is invalid.  */
466   unsigned int invalid : 1;
467
468   /* True if the signature should be exported.  */
469   unsigned int exportable : 1;
470
471   /* Internal to GPGME, do not use.  */
472   unsigned int _unused : 28;
473
474   /* The public key algorithm used to create the signature.  */
475   gpgme_pubkey_algo_t pubkey_algo;
476
477   /* The key ID of key used to create the signature.  */
478   char *keyid;
479
480   /* Internal to GPGME, do not use.  */
481   char _keyid[16 + 1];
482
483   /* The creation timestamp, -1 if invalid, 0 if not available.  */
484   long int timestamp;
485
486   /* The expiration timestamp, 0 if the subkey does not expire.  */
487   long int expires;
488
489   /* Same as in gpgme_signature_t.  */
490   gpgme_error_t status;
491
492   /* Crypto backend specific signature class.  */
493   unsigned int class;
494
495   /* The user ID string.  */
496   char *uid;
497
498   /* The name part of the user ID.  */
499   char *name;
500
501   /* The email part of the user ID.  */
502   char *email;
503
504   /* The comment part of the user ID.  */
505   char *comment;
506 };
507 typedef struct _gpgme_key_sig *gpgme_key_sig_t;
508
509
510 /* An user ID from a key.  */
511 struct _gpgme_user_id
512 {
513   struct _gpgme_user_id *next;
514
515   /* True if the user ID is revoked.  */
516   unsigned int revoked : 1;
517
518   /* True if the user ID is invalid.  */
519   unsigned int invalid : 1;
520
521   /* Internal to GPGME, do not use.  */
522   unsigned int _unused : 30;
523
524   /* The validity of the user ID.  */
525   gpgme_validity_t validity; 
526
527   /* The user ID string.  */
528   char *uid;
529
530   /* The name part of the user ID.  */
531   char *name;
532
533   /* The email part of the user ID.  */
534   char *email;
535
536   /* The comment part of the user ID.  */
537   char *comment;
538
539   /* The signatures of the user ID.  */
540   gpgme_key_sig_t signatures;
541
542   /* Internal to GPGME, do not use.  */
543   gpgme_key_sig_t _last_keysig;
544 };
545 typedef struct _gpgme_user_id *gpgme_user_id_t;
546
547
548 /* A key from the keyring.  */
549 struct _gpgme_key
550 {
551   /* Internal to GPGME, do not use.  */
552   unsigned int _refs;
553
554   /* True if key is revoked.  */
555   unsigned int revoked : 1;
556
557   /* True if key is expired.  */
558   unsigned int expired : 1;
559
560   /* True if key is disabled.  */
561   unsigned int disabled : 1;
562
563   /* True if key is invalid.  */
564   unsigned int invalid : 1;
565
566   /* True if key can be used for encryption.  */
567   unsigned int can_encrypt : 1;
568
569   /* True if key can be used for signing.  */
570   unsigned int can_sign : 1;
571
572   /* True if key can be used for certification.  */
573   unsigned int can_certify : 1;
574
575   /* True if key is secret.  */
576   unsigned int secret : 1;
577
578   /* True if key can be used for authentication.  */
579   unsigned int can_authenticate : 1;
580
581   /* Internal to GPGME, do not use.  */
582   unsigned int _unused : 23;
583
584   /* This is the protocol supported by this key.  */
585   gpgme_protocol_t protocol;
586
587   /* If protocol is GPGME_PROTOCOL_CMS, this string contains the
588      issuer serial.  */
589   char *issuer_serial;
590
591   /* If protocol is GPGME_PROTOCOL_CMS, this string contains the
592      issuer name.  */
593   char *issuer_name;
594
595   /* If protocol is GPGME_PROTOCOL_CMS, this string contains the chain
596      ID.  */
597   char *chain_id;
598
599   /* If protocol is GPGME_PROTOCOL_OpenPGP, this field contains the
600      owner trust.  */
601   gpgme_validity_t owner_trust;
602
603   /* The subkeys of the key.  */
604   gpgme_subkey_t subkeys;
605
606   /* The user IDs of the key.  */
607   gpgme_user_id_t uids;
608
609   /* Internal to GPGME, do not use.  */
610   gpgme_subkey_t _last_subkey;
611
612   /* Internal to GPGME, do not use.  */
613   gpgme_user_id_t _last_uid;
614 };
615 typedef struct _gpgme_key *gpgme_key_t;
616
617
618 \f
619 /* Types for callback functions.  */
620
621 /* Request a passphrase from the user.  */
622 typedef gpgme_error_t (*gpgme_passphrase_cb_t) (void *hook,
623                                                 const char *uid_hint,
624                                                 const char *passphrase_info,
625                                                 int prev_was_bad, int fd);
626
627 /* Inform the user about progress made.  */
628 typedef void (*gpgme_progress_cb_t) (void *opaque, const char *what,
629                                      int type, int current, int total);
630
631 /* Interact with the user about an edit operation.  */
632 typedef gpgme_error_t (*gpgme_edit_cb_t) (void *opaque,
633                                           gpgme_status_code_t status,
634                                           const char *args, int fd);
635
636 \f
637 /* Context management functions.  */
638
639 /* Create a new context and return it in CTX.  */
640 gpgme_error_t gpgme_new (gpgme_ctx_t *ctx);
641
642 /* Release the context CTX.  */
643 void gpgme_release (gpgme_ctx_t ctx);
644
645 /* Set the protocol to be used by CTX to PROTO.  */
646 gpgme_error_t gpgme_set_protocol (gpgme_ctx_t ctx, gpgme_protocol_t proto);
647
648 /* Get the protocol used with CTX */
649 gpgme_protocol_t gpgme_get_protocol (gpgme_ctx_t ctx);
650
651 /* Get the string describing protocol PROTO, or NULL if invalid.  */
652 const char *gpgme_get_protocol_name (gpgme_protocol_t proto);
653
654 /* If YES is non-zero, enable armor mode in CTX, disable it otherwise.  */
655 void gpgme_set_armor (gpgme_ctx_t ctx, int yes);
656
657 /* Return non-zero if armor mode is set in CTX.  */
658 int gpgme_get_armor (gpgme_ctx_t ctx);
659
660 /* If YES is non-zero, enable text mode in CTX, disable it otherwise.  */
661 void gpgme_set_textmode (gpgme_ctx_t ctx, int yes);
662
663 /* Return non-zero if text mode is set in CTX.  */
664 int gpgme_get_textmode (gpgme_ctx_t ctx);
665
666 /* Include up to NR_OF_CERTS certificates in an S/MIME message.  */
667 void gpgme_set_include_certs (gpgme_ctx_t ctx, int nr_of_certs);
668
669 /* Return the number of certs to include in an S/MIME message.  */
670 int gpgme_get_include_certs (gpgme_ctx_t ctx);
671
672 /* The available keylist mode flags.  */
673 typedef enum
674   {
675     GPGME_KEYLIST_MODE_LOCAL  = 1,
676     GPGME_KEYLIST_MODE_EXTERN = 2,
677     GPGME_KEYLIST_MODE_SIGS   = 4
678   }
679 gpgme_keylist_mode_t;
680
681 /* Set keylist mode in CTX to MODE.  */
682 gpgme_error_t gpgme_set_keylist_mode (gpgme_ctx_t ctx,
683                                       gpgme_keylist_mode_t mode);
684
685 /* Get keylist mode in CTX.  */
686 gpgme_keylist_mode_t gpgme_get_keylist_mode (gpgme_ctx_t ctx);
687
688 /* Set the passphrase callback function in CTX to CB.  HOOK_VALUE is
689    passed as first argument to the passphrase callback function.  */
690 void gpgme_set_passphrase_cb (gpgme_ctx_t ctx,
691                               gpgme_passphrase_cb_t cb, void *hook_value);
692
693 /* Get the current passphrase callback function in *CB and the current
694    hook value in *HOOK_VALUE.  */
695 void gpgme_get_passphrase_cb (gpgme_ctx_t ctx, gpgme_passphrase_cb_t *cb,
696                               void **hook_value);
697
698 /* Set the progress callback function in CTX to CB.  HOOK_VALUE is
699    passed as first argument to the progress callback function.  */
700 void gpgme_set_progress_cb (gpgme_ctx_t c, gpgme_progress_cb_t cb,
701                             void *hook_value);
702
703 /* Get the current progress callback function in *CB and the current
704    hook value in *HOOK_VALUE.  */
705 void gpgme_get_progress_cb (gpgme_ctx_t ctx, gpgme_progress_cb_t *cb,
706                             void **hook_value);
707
708 \f
709 /* Return a statically allocated string with the name of the public
710    key algorithm ALGO, or NULL if that name is not known.  */
711 const char *gpgme_pubkey_algo_name (gpgme_pubkey_algo_t algo);
712
713 /* Return a statically allocated string with the name of the hash
714    algorithm ALGO, or NULL if that name is not known.  */
715 const char *gpgme_hash_algo_name (gpgme_hash_algo_t algo);
716
717 \f
718 /* Delete all signers from CTX.  */
719 void gpgme_signers_clear (gpgme_ctx_t ctx);
720
721 /* Add KEY to list of signers in CTX.  */
722 gpgme_error_t gpgme_signers_add (gpgme_ctx_t ctx, const gpgme_key_t key);
723
724 /* Return the SEQth signer's key in CTX.  */
725 gpgme_key_t gpgme_signers_enum (const gpgme_ctx_t ctx, int seq);
726
727 /* Retrieve the signature status of signature IDX in CTX after a
728    successful verify operation in R_STAT (if non-null).  The creation
729    time stamp of the signature is returned in R_CREATED (if non-null).
730    The function returns a string containing the fingerprint.
731    Deprecated, use verify result directly.  */
732 const char *gpgme_get_sig_status (gpgme_ctx_t ctx, int idx,
733                                   _gpgme_sig_stat_t *r_stat,
734                                   time_t *r_created) _GPGME_DEPRECATED;
735
736 /* Retrieve certain attributes of a signature.  IDX is the index
737    number of the signature after a successful verify operation.  WHAT
738    is an attribute where GPGME_ATTR_EXPIRE is probably the most useful
739    one.  WHATIDX is to be passed as 0 for most attributes . */
740 unsigned long gpgme_get_sig_ulong_attr (gpgme_ctx_t c, int idx,
741                                         _gpgme_attr_t what, int whatidx)
742      _GPGME_DEPRECATED;
743 const char *gpgme_get_sig_string_attr (gpgme_ctx_t c, int idx,
744                                        _gpgme_attr_t what, int whatidx)
745      _GPGME_DEPRECATED;
746
747
748 /* Get the key used to create signature IDX in CTX and return it in
749    R_KEY.  */
750 gpgme_error_t gpgme_get_sig_key (gpgme_ctx_t ctx, int idx, gpgme_key_t *r_key)
751      _GPGME_DEPRECATED;
752
753 \f
754 /* Run control.  */
755
756 /* The type of an I/O callback function.  */
757 typedef gpgme_error_t (*gpgme_io_cb_t) (void *data, int fd);
758
759 /* The type of a function that can register FNC as the I/O callback
760    function for the file descriptor FD with direction dir (0: for writing,
761    1: for reading).  FNC_DATA should be passed as DATA to FNC.  The
762    function should return a TAG suitable for the corresponding
763    gpgme_remove_io_cb_t, and an error value.  */
764 typedef gpgme_error_t (*gpgme_register_io_cb_t) (void *data, int fd, int dir,
765                                                  gpgme_io_cb_t fnc,
766                                                  void *fnc_data, void **tag);
767
768 /* The type of a function that can remove a previously registered I/O
769    callback function given TAG as returned by the register
770    function.  */
771 typedef void (*gpgme_remove_io_cb_t) (void *tag);
772
773 typedef enum
774   {
775     GPGME_EVENT_START,
776     GPGME_EVENT_DONE,
777     GPGME_EVENT_NEXT_KEY,
778     GPGME_EVENT_NEXT_TRUSTITEM
779   }
780 gpgme_event_io_t;
781
782 /* The type of a function that is called when a context finished an
783    operation.  */
784 typedef void (*gpgme_event_io_cb_t) (void *data, gpgme_event_io_t type,
785                                      void *type_data);
786
787 struct gpgme_io_cbs
788 {
789   gpgme_register_io_cb_t add;
790   void *add_priv;
791   gpgme_remove_io_cb_t remove;
792   gpgme_event_io_cb_t event;
793   void *event_priv;
794 };
795 typedef struct gpgme_io_cbs *gpgme_io_cbs_t;
796
797 /* Set the I/O callback functions in CTX to IO_CBS.  */
798 void gpgme_set_io_cbs (gpgme_ctx_t ctx, gpgme_io_cbs_t io_cbs);
799
800 /* Get the current I/O callback functions.  */
801 void gpgme_get_io_cbs (gpgme_ctx_t ctx, gpgme_io_cbs_t io_cbs);
802
803 /* Process the pending operation and, if HANG is non-zero, wait for
804    the pending operation to finish.  */
805 gpgme_ctx_t gpgme_wait (gpgme_ctx_t ctx, gpgme_error_t *status, int hang);
806
807 \f
808 /* Functions to handle data objects.  */
809
810 /* Read up to SIZE bytes into buffer BUFFER from the data object with
811    the handle HANDLE.  Return the number of characters read, 0 on EOF
812    and -1 on error.  If an error occurs, errno is set.  */
813 typedef ssize_t (*gpgme_data_read_cb_t) (void *handle, void *buffer,
814                                          size_t size);
815
816 /* Write up to SIZE bytes from buffer BUFFER to the data object with
817    the handle HANDLE.  Return the number of characters written, or -1
818    on error.  If an error occurs, errno is set.  */
819 typedef ssize_t (*gpgme_data_write_cb_t) (void *handle, const void *buffer,
820                                           size_t size);
821
822 /* Set the current position from where the next read or write starts
823    in the data object with the handle HANDLE to OFFSET, relativ to
824    WHENCE.  */
825 typedef off_t (*gpgme_data_seek_cb_t) (void *handle, off_t offset, int whence);
826
827 /* Close the data object with the handle DL.  */
828 typedef void (*gpgme_data_release_cb_t) (void *handle);
829
830 struct gpgme_data_cbs
831 {
832   gpgme_data_read_cb_t read;
833   gpgme_data_write_cb_t write;
834   gpgme_data_seek_cb_t seek;
835   gpgme_data_release_cb_t release;
836 };
837 typedef struct gpgme_data_cbs *gpgme_data_cbs_t;
838
839 /* Read up to SIZE bytes into buffer BUFFER from the data object with
840    the handle DH.  Return the number of characters read, 0 on EOF and
841    -1 on error.  If an error occurs, errno is set.  */
842 ssize_t gpgme_data_read (gpgme_data_t dh, void *buffer, size_t size);
843
844 /* Write up to SIZE bytes from buffer BUFFER to the data object with
845    the handle DH.  Return the number of characters written, or -1 on
846    error.  If an error occurs, errno is set.  */
847 ssize_t gpgme_data_write (gpgme_data_t dh, const void *buffer, size_t size);
848
849 /* Set the current position from where the next read or write starts
850    in the data object with the handle DH to OFFSET, relativ to
851    WHENCE.  */
852 off_t gpgme_data_seek (gpgme_data_t dh, off_t offset, int whence);
853
854 /* Create a new data buffer and return it in R_DH.  */
855 gpgme_error_t gpgme_data_new (gpgme_data_t *r_dh);
856
857 /* Destroy the data buffer DH.  */
858 void gpgme_data_release (gpgme_data_t dh);
859
860 /* Create a new data buffer filled with SIZE bytes starting from
861    BUFFER.  If COPY is zero, copying is delayed until necessary, and
862    the data is taken from the original location when needed.  */
863 gpgme_error_t gpgme_data_new_from_mem (gpgme_data_t *r_dh,
864                                        const char *buffer, size_t size,
865                                        int copy);
866
867 /* Destroy the data buffer DH and return a pointer to its content.
868    The memory has be to released with free by the user.  It's size is
869    returned in R_LEN.  */
870 char *gpgme_data_release_and_get_mem (gpgme_data_t dh, size_t *r_len);
871
872 gpgme_error_t gpgme_data_new_from_cbs (gpgme_data_t *dh,
873                                        gpgme_data_cbs_t cbs,
874                                        void *handle);
875
876 gpgme_error_t gpgme_data_new_from_fd (gpgme_data_t *dh, int fd);
877
878 gpgme_error_t gpgme_data_new_from_stream (gpgme_data_t *dh, FILE *stream);
879
880 /* Return the encoding attribute of the data buffer DH */
881 gpgme_data_encoding_t gpgme_data_get_encoding (gpgme_data_t dh);
882
883 /* Set the encoding attribute of data buffer DH to ENC */
884 gpgme_error_t gpgme_data_set_encoding (gpgme_data_t dh,
885                                        gpgme_data_encoding_t enc);
886
887
888
889 /* Create a new data buffer which retrieves the data from the callback
890    function READ_CB.  Deprecated, please use gpgme_data_new_from_cbs
891    instead.  */
892 gpgme_error_t gpgme_data_new_with_read_cb (gpgme_data_t *r_dh,
893                                            int (*read_cb) (void*,char *,
894                                                            size_t,size_t*),
895                                            void *read_cb_value)
896      _GPGME_DEPRECATED;
897
898 /* Create a new data buffer filled with the content of file FNAME.
899    COPY must be non-zero.  For delayed read, please use
900    gpgme_data_new_from_fd or gpgme_data_new_from stream instead.  */
901 gpgme_error_t gpgme_data_new_from_file (gpgme_data_t *r_dh,
902                                         const char *fname,
903                                         int copy);
904
905 /* Create a new data buffer filled with LENGTH bytes starting from
906    OFFSET within the file FNAME or stream FP (exactly one must be
907    non-zero).  */
908 gpgme_error_t gpgme_data_new_from_filepart (gpgme_data_t *r_dh,
909                                             const char *fname, FILE *fp,
910                                             off_t offset, size_t length);
911
912 /* Reset the read pointer in DH.  Deprecated, please use
913    gpgme_data_seek instead.  */
914 gpgme_error_t gpgme_data_rewind (gpgme_data_t dh) _GPGME_DEPRECATED;
915
916 \f
917 /* Key and trust functions.  */
918
919 /* Get the key with the fingerprint FPR from the crypto backend.  If
920    SECRET is true, get the secret key.  */
921 gpgme_error_t gpgme_get_key (gpgme_ctx_t ctx, const char *fpr,
922                              gpgme_key_t *r_key, int secret);
923
924 /* Acquire a reference to KEY.  */
925 void gpgme_key_ref (gpgme_key_t key);
926
927 /* Release a reference to KEY.  If this was the last one the key is
928    destroyed.  */
929 void gpgme_key_unref (gpgme_key_t key);
930 void gpgme_key_release (gpgme_key_t key);
931
932 /* Return the value of the attribute WHAT of KEY, which has to be
933    representable by a string.  IDX specifies the sub key or user ID
934    for attributes related to sub keys or user IDs.  Deprecated, use
935    key structure directly instead. */
936 const char *gpgme_key_get_string_attr (gpgme_key_t key, _gpgme_attr_t what,
937                                        const void *reserved, int idx)
938      _GPGME_DEPRECATED;
939
940 /* Return the value of the attribute WHAT of KEY, which has to be
941    representable by an unsigned integer.  IDX specifies the sub key or
942    user ID for attributes related to sub keys or user IDs.
943    Deprecated, use key structure directly instead.  */
944 unsigned long gpgme_key_get_ulong_attr (gpgme_key_t key, _gpgme_attr_t what,
945                                         const void *reserved, int idx)
946      _GPGME_DEPRECATED;
947
948 /* Return the value of the attribute WHAT of a signature on user ID
949    UID_IDX in KEY, which has to be representable by a string.  IDX
950    specifies the signature.  Deprecated, use key structure directly
951    instead.  */
952 const char *gpgme_key_sig_get_string_attr (gpgme_key_t key, int uid_idx,
953                                            _gpgme_attr_t what,
954                                            const void *reserved, int idx)
955      _GPGME_DEPRECATED;
956
957 /* Return the value of the attribute WHAT of a signature on user ID
958    UID_IDX in KEY, which has to be representable by an unsigned
959    integer string.  IDX specifies the signature.  Deprecated, use key
960    structure directly instead.  */
961 unsigned long gpgme_key_sig_get_ulong_attr (gpgme_key_t key, int uid_idx,
962                                             _gpgme_attr_t what,
963                                             const void *reserved, int idx)
964      _GPGME_DEPRECATED;
965
966 \f
967 /* Crypto Operations.  */
968
969 struct _gpgme_invalid_key
970 {
971   struct _gpgme_invalid_key *next;
972   char *fpr;
973   gpgme_error_t reason;
974 };
975 typedef struct _gpgme_invalid_key *gpgme_invalid_key_t;
976
977 \f
978 /* Encryption.  */
979 struct _gpgme_op_encrypt_result
980 {
981   /* The list of invalid recipients.  */
982   gpgme_invalid_key_t invalid_recipients;
983 };
984 typedef struct _gpgme_op_encrypt_result *gpgme_encrypt_result_t;
985
986 /* Retrieve a pointer to the result of the encrypt operation.  */
987 gpgme_encrypt_result_t gpgme_op_encrypt_result (gpgme_ctx_t ctx);
988
989 /* The valid encryption flags.  */
990 typedef enum
991   {
992     GPGME_ENCRYPT_ALWAYS_TRUST = 1
993   }
994 gpgme_encrypt_flags_t;
995
996 /* Encrypt plaintext PLAIN within CTX for the recipients RECP and
997    store the resulting ciphertext in CIPHER.  */
998 gpgme_error_t gpgme_op_encrypt_start (gpgme_ctx_t ctx, gpgme_key_t recp[],
999                                       gpgme_encrypt_flags_t flags,
1000                                       gpgme_data_t plain, gpgme_data_t cipher);
1001 gpgme_error_t gpgme_op_encrypt (gpgme_ctx_t ctx, gpgme_key_t recp[],
1002                                 gpgme_encrypt_flags_t flags,
1003                                 gpgme_data_t plain, gpgme_data_t cipher);
1004
1005 /* Encrypt plaintext PLAIN within CTX for the recipients RECP and
1006    store the resulting ciphertext in CIPHER.  Also sign the ciphertext
1007    with the signers in CTX.  */
1008 gpgme_error_t gpgme_op_encrypt_sign_start (gpgme_ctx_t ctx,
1009                                            gpgme_key_t recp[],
1010                                            gpgme_encrypt_flags_t flags,
1011                                            gpgme_data_t plain,
1012                                            gpgme_data_t cipher);
1013 gpgme_error_t gpgme_op_encrypt_sign (gpgme_ctx_t ctx, gpgme_key_t recp[],
1014                                      gpgme_encrypt_flags_t flags,
1015                                      gpgme_data_t plain, gpgme_data_t cipher);
1016
1017 \f
1018 /* Decryption.  */
1019 struct _gpgme_op_decrypt_result
1020 {
1021   char *unsupported_algorithm;
1022 };
1023 typedef struct _gpgme_op_decrypt_result *gpgme_decrypt_result_t;
1024
1025 /* Retrieve a pointer to the result of the decrypt operation.  */
1026 gpgme_decrypt_result_t gpgme_op_decrypt_result (gpgme_ctx_t ctx);
1027
1028 /* Decrypt ciphertext CIPHER within CTX and store the resulting
1029    plaintext in PLAIN.  */
1030 gpgme_error_t gpgme_op_decrypt_start (gpgme_ctx_t ctx, gpgme_data_t cipher,
1031                                       gpgme_data_t plain);
1032 gpgme_error_t gpgme_op_decrypt (gpgme_ctx_t ctx,
1033                                 gpgme_data_t cipher, gpgme_data_t plain);
1034
1035 /* Decrypt ciphertext CIPHER and make a signature verification within
1036    CTX and store the resulting plaintext in PLAIN.  */
1037 gpgme_error_t gpgme_op_decrypt_verify_start (gpgme_ctx_t ctx,
1038                                              gpgme_data_t cipher,
1039                                              gpgme_data_t plain);
1040 gpgme_error_t gpgme_op_decrypt_verify (gpgme_ctx_t ctx, gpgme_data_t cipher,
1041                                        gpgme_data_t plain);
1042
1043 \f
1044 /* Signing.  */
1045 struct _gpgme_new_signature
1046 {
1047   struct _gpgme_new_signature *next;
1048   gpgme_sig_mode_t type;
1049   gpgme_pubkey_algo_t pubkey_algo;
1050   gpgme_hash_algo_t hash_algo;
1051   unsigned long class;
1052   long int timestamp;
1053   char *fpr;
1054 };
1055 typedef struct _gpgme_new_signature *gpgme_new_signature_t;
1056
1057 struct _gpgme_op_sign_result
1058 {
1059   /* The list of invalid signers.  */
1060   gpgme_invalid_key_t invalid_signers;
1061   gpgme_new_signature_t signatures;
1062 };
1063 typedef struct _gpgme_op_sign_result *gpgme_sign_result_t;
1064
1065 /* Retrieve a pointer to the result of the signing operation.  */
1066 gpgme_sign_result_t gpgme_op_sign_result (gpgme_ctx_t ctx);
1067
1068 /* Sign the plaintext PLAIN and store the signature in SIG.  */
1069 gpgme_error_t gpgme_op_sign_start (gpgme_ctx_t ctx,
1070                                    gpgme_data_t plain, gpgme_data_t sig,
1071                                    gpgme_sig_mode_t mode);
1072 gpgme_error_t gpgme_op_sign (gpgme_ctx_t ctx,
1073                              gpgme_data_t plain, gpgme_data_t sig,
1074                              gpgme_sig_mode_t mode);
1075
1076 \f
1077 /* Verify.  */
1078 struct _gpgme_sig_notation
1079 {
1080   struct _gpgme_sig_notation *next;
1081
1082   /* If NAME is a null pointer, then VALUE contains a policy URL
1083      rather than a notation.  */
1084   char *name;
1085   char *value;
1086 };
1087 typedef struct _gpgme_sig_notation *gpgme_sig_notation_t;
1088
1089 /* Flags used for the SUMMARY field in a gpgme_signature_t.  */
1090 typedef enum
1091   {
1092     GPGME_SIGSUM_VALID       = 0x0001,  /* The signature is fully valid.  */
1093     GPGME_SIGSUM_GREEN       = 0x0002,  /* The signature is good.  */
1094     GPGME_SIGSUM_RED         = 0x0004,  /* The signature is bad.  */
1095     GPGME_SIGSUM_KEY_REVOKED = 0x0010,  /* One key has been revoked.  */
1096     GPGME_SIGSUM_KEY_EXPIRED = 0x0020,  /* One key has expired.  */
1097     GPGME_SIGSUM_SIG_EXPIRED = 0x0040,  /* The signature has expired.  */
1098     GPGME_SIGSUM_KEY_MISSING = 0x0080,  /* Can't verify: key missing.  */
1099     GPGME_SIGSUM_CRL_MISSING = 0x0100,  /* CRL not available.  */
1100     GPGME_SIGSUM_CRL_TOO_OLD = 0x0200,  /* Available CRL is too old.  */
1101     GPGME_SIGSUM_BAD_POLICY  = 0x0400,  /* A policy was not met.  */
1102     GPGME_SIGSUM_SYS_ERROR   = 0x0800   /* A system error occured.  */
1103   }
1104 gpgme_sigsum_t;
1105
1106 struct _gpgme_signature
1107 {
1108   struct _gpgme_signature *next;
1109
1110   /* A summary of the signature status.  */
1111   gpgme_sigsum_t summary;
1112
1113   /* The fingerprint or key ID of the signature.  */
1114   char *fpr;
1115
1116   /* The status of the signature.  */
1117   gpgme_error_t status;
1118
1119   /* Notation data and policy URLs.  */
1120   gpgme_sig_notation_t notations;
1121
1122   /* Signature creation time.  */
1123   unsigned long timestamp;
1124
1125   /* Signature exipration time or 0.  */
1126   unsigned long exp_timestamp;
1127
1128   int wrong_key_usage : 1;
1129
1130   /* Internal to GPGME, do not use.  */
1131   int _unused : 31;
1132
1133   gpgme_validity_t validity;
1134   gpgme_error_t validity_reason;
1135 };
1136 typedef struct _gpgme_signature *gpgme_signature_t;
1137
1138 struct _gpgme_op_verify_result
1139 {
1140   gpgme_signature_t signatures;
1141 };
1142 typedef struct _gpgme_op_verify_result *gpgme_verify_result_t;
1143
1144 /* Retrieve a pointer to the result of the verify operation.  */
1145 gpgme_verify_result_t gpgme_op_verify_result (gpgme_ctx_t ctx);
1146
1147 /* Verify within CTX that SIG is a valid signature for TEXT.  */
1148 gpgme_error_t gpgme_op_verify_start (gpgme_ctx_t ctx, gpgme_data_t sig,
1149                                      gpgme_data_t signed_text,
1150                                      gpgme_data_t plaintext);
1151 gpgme_error_t gpgme_op_verify (gpgme_ctx_t ctx, gpgme_data_t sig,
1152                                gpgme_data_t signed_text,
1153                                gpgme_data_t plaintext);
1154
1155 \f
1156 /* Import.  */
1157 enum
1158   {
1159     /* The key was new.  */
1160     GPGME_IMPORT_NEW = 1,
1161
1162     /* The key contained new user IDs.  */
1163     GPGME_IMPORT_UID = 2,
1164
1165     /* The key contained new signatures.  */
1166     GPGME_IMPORT_SIG = 4,
1167
1168     /* The key contained new sub keys.  */
1169     GPGME_IMPORT_SUBKEY = 8,
1170
1171     /* The key contained a secret key.  */
1172     GPGME_IMPORT_SECRET = 16
1173   };
1174
1175 struct _gpgme_import_status
1176 {
1177   struct _gpgme_import_status *next;
1178
1179   /* Fingerprint.  */
1180   char *fpr;
1181
1182   /* If a problem occured, the reason why the key could not be
1183      imported.  Otherwise GPGME_No_Error.  */
1184   gpgme_error_t result;
1185
1186   /* The result of the import, the GPGME_IMPORT_* values bit-wise
1187      ORed.  0 means the key was already known and no new components
1188      have been added.  */
1189   unsigned int status;
1190 };
1191 typedef struct _gpgme_import_status *gpgme_import_status_t;
1192
1193 /* Import.  */
1194 struct _gpgme_op_import_result
1195 {
1196   /* Number of considered keys.  */
1197   int considered;
1198
1199   /* Keys without user ID.  */
1200   int no_user_id;
1201
1202   /* Imported keys.  */
1203   int imported;
1204
1205   /* Imported RSA keys.  */
1206   int imported_rsa;
1207
1208   /* Unchanged keys.  */
1209   int unchanged;
1210
1211   /* Number of new user ids.  */
1212   int new_user_ids;
1213
1214   /* Number of new sub keys.  */
1215   int new_sub_keys;
1216
1217   /* Number of new signatures.  */
1218   int new_signatures;
1219
1220   /* Number of new revocations.  */
1221   int new_revocations;
1222
1223   /* Number of secret keys read.  */
1224   int secret_read;
1225
1226   /* Number of secret keys imported.  */
1227   int secret_imported;
1228
1229   /* Number of secret keys unchanged.  */
1230   int secret_unchanged;
1231
1232   /* Number of new keys skipped.  */
1233   int skipped_new_keys;
1234
1235   /* Number of keys not imported.  */
1236   int not_imported;
1237
1238   /* List of keys for which an import was attempted.  */
1239   gpgme_import_status_t imports;
1240 };
1241 typedef struct _gpgme_op_import_result *gpgme_import_result_t;
1242
1243 /* Retrieve a pointer to the result of the import operation.  */
1244 gpgme_import_result_t gpgme_op_import_result (gpgme_ctx_t ctx);
1245
1246 /* Import the key in KEYDATA into the keyring.  */
1247 gpgme_error_t gpgme_op_import_start (gpgme_ctx_t ctx, gpgme_data_t keydata);
1248 gpgme_error_t gpgme_op_import (gpgme_ctx_t ctx, gpgme_data_t keydata);
1249 gpgme_error_t gpgme_op_import_ext (gpgme_ctx_t ctx, gpgme_data_t keydata,
1250                                    int *nr) _GPGME_DEPRECATED;
1251
1252 \f
1253 /* Export the keys found by PATTERN into KEYDATA.  */
1254 gpgme_error_t gpgme_op_export_start (gpgme_ctx_t ctx, const char *pattern,
1255                                      unsigned int reserved,
1256                                      gpgme_data_t keydata);
1257 gpgme_error_t gpgme_op_export (gpgme_ctx_t ctx, const char *pattern,
1258                                unsigned int reserved, gpgme_data_t keydata);
1259
1260 gpgme_error_t gpgme_op_export_ext_start (gpgme_ctx_t ctx,
1261                                          const char *pattern[],
1262                                          unsigned int reserved,
1263                                          gpgme_data_t keydata);
1264 gpgme_error_t gpgme_op_export_ext (gpgme_ctx_t ctx, const char *pattern[],
1265                                    unsigned int reserved,
1266                                    gpgme_data_t keydata);
1267
1268 \f
1269 /* Key generation.  */
1270 struct _gpgme_op_genkey_result
1271 {
1272   /* A primary key was generated.  */
1273   unsigned int primary : 1;
1274
1275   /* A sub key was generated.  */
1276   unsigned int sub : 1;
1277
1278   /* Internal to GPGME, do not use.  */
1279   unsigned int _unused : 30;
1280
1281   /* The fingerprint of the generated key.  */
1282   char *fpr;
1283 };
1284 typedef struct _gpgme_op_genkey_result *gpgme_genkey_result_t;
1285
1286 /* Generate a new keypair and add it to the keyring.  PUBKEY and
1287    SECKEY should be null for now.  PARMS specifies what keys should be
1288    generated.  */
1289 gpgme_error_t gpgme_op_genkey_start (gpgme_ctx_t ctx, const char *parms,
1290                                      gpgme_data_t pubkey, gpgme_data_t seckey);
1291 gpgme_error_t gpgme_op_genkey (gpgme_ctx_t ctx, const char *parms,
1292                                gpgme_data_t pubkey, gpgme_data_t seckey);
1293
1294 /* Retrieve a pointer to the result of the genkey operation.  */
1295 gpgme_genkey_result_t gpgme_op_genkey_result (gpgme_ctx_t ctx);
1296
1297 \f
1298 /* Delete KEY from the keyring.  If ALLOW_SECRET is non-zero, secret
1299    keys are also deleted.  */
1300 gpgme_error_t gpgme_op_delete_start (gpgme_ctx_t ctx, const gpgme_key_t key,
1301                                      int allow_secret);
1302 gpgme_error_t gpgme_op_delete (gpgme_ctx_t ctx, const gpgme_key_t key,
1303                                int allow_secret);
1304
1305 \f
1306 /* Edit the key KEY.  Send status and command requests to FNC and
1307    output of edit commands to OUT.  */
1308 gpgme_error_t gpgme_op_edit_start (gpgme_ctx_t ctx, gpgme_key_t key,
1309                                    gpgme_edit_cb_t fnc, void *fnc_value,
1310                                    gpgme_data_t out);
1311 gpgme_error_t gpgme_op_edit (gpgme_ctx_t ctx, gpgme_key_t key,
1312                              gpgme_edit_cb_t fnc, void *fnc_value,
1313                              gpgme_data_t out);
1314
1315 \f
1316 /* Key management functions.  */
1317 struct _gpgme_op_keylist_result
1318 {
1319   unsigned int truncated : 1;
1320
1321   /* Internal to GPGME, do not use.  */
1322   unsigned int _unused : 31;
1323 };
1324 typedef struct _gpgme_op_keylist_result *gpgme_keylist_result_t;
1325
1326 /* Retrieve a pointer to the result of the key listing operation.  */
1327 gpgme_keylist_result_t gpgme_op_keylist_result (gpgme_ctx_t ctx);
1328
1329 /* Start a keylist operation within CTX, searching for keys which
1330    match PATTERN.  If SECRET_ONLY is true, only secret keys are
1331    returned.  */
1332 gpgme_error_t gpgme_op_keylist_start (gpgme_ctx_t ctx, const char *pattern,
1333                                       int secret_only);
1334 gpgme_error_t gpgme_op_keylist_ext_start (gpgme_ctx_t ctx,
1335                                           const char *pattern[],
1336                                           int secret_only, int reserved);
1337
1338 /* Return the next key from the keylist in R_KEY.  */
1339 gpgme_error_t gpgme_op_keylist_next (gpgme_ctx_t ctx, gpgme_key_t *r_key);
1340
1341 /* Terminate a pending keylist operation within CTX.  */
1342 gpgme_error_t gpgme_op_keylist_end (gpgme_ctx_t ctx);
1343
1344 \f
1345 /* Trust items and operations.  */
1346
1347 struct _gpgme_trust_item
1348 {
1349   /* Internal to GPGME, do not use.  */
1350   unsigned int _refs;
1351
1352   /* The key ID to which the trust item belongs.  */
1353   char *keyid;
1354
1355   /* Internal to GPGME, do not use.  */
1356   char _keyid[16 + 1];
1357
1358   /* The type of the trust item, 1 refers to a key, 2 to a user ID.  */
1359   int type;
1360
1361   /* The trust level.  */
1362   int level;
1363
1364   /* The owner trust if TYPE is 1.  */
1365   char *owner_trust;
1366
1367   /* Internal to GPGME, do not use.  */
1368   char _owner_trust[2];
1369
1370   /* The calculated validity.  */
1371   char *validity;
1372  
1373   /* Internal to GPGME, do not use.  */
1374   char _validity[2];
1375
1376   /* The user name if TYPE is 2.  */
1377   char *name;
1378 };
1379 typedef struct _gpgme_trust_item *gpgme_trust_item_t;
1380
1381 /* Start a trustlist operation within CTX, searching for trust items
1382    which match PATTERN.  */
1383 gpgme_error_t gpgme_op_trustlist_start (gpgme_ctx_t ctx,
1384                                         const char *pattern, int max_level);
1385
1386 /* Return the next trust item from the trustlist in R_ITEM.  */
1387 gpgme_error_t gpgme_op_trustlist_next (gpgme_ctx_t ctx,
1388                                        gpgme_trust_item_t *r_item);
1389
1390 /* Terminate a pending trustlist operation within CTX.  */
1391 gpgme_error_t gpgme_op_trustlist_end (gpgme_ctx_t ctx);
1392
1393 /* Acquire a reference to ITEM.  */
1394 void gpgme_trust_item_ref (gpgme_trust_item_t item);
1395
1396 /* Release a reference to ITEM.  If this was the last one the trust
1397    item is destroyed.  */
1398 void gpgme_trust_item_unref (gpgme_trust_item_t item);
1399
1400 /* Release the trust item ITEM.  Deprecated, use
1401    gpgme_trust_item_unref.  */
1402 void gpgme_trust_item_release (gpgme_trust_item_t item) _GPGME_DEPRECATED;
1403
1404 /* Return the value of the attribute WHAT of ITEM, which has to be
1405    representable by a string.  Deprecated, use trust item structure
1406    directly.  */
1407 const char *gpgme_trust_item_get_string_attr (gpgme_trust_item_t item,
1408                                               _gpgme_attr_t what,
1409                                               const void *reserved, int idx)
1410      _GPGME_DEPRECATED;
1411
1412 /* Return the value of the attribute WHAT of KEY, which has to be
1413    representable by an integer.  IDX specifies a running index if the
1414    attribute appears more than once in the key.  Deprecated, use trust
1415    item structure directly.  */
1416 int gpgme_trust_item_get_int_attr (gpgme_trust_item_t item, _gpgme_attr_t what,
1417                                    const void *reserved, int idx)
1418      _GPGME_DEPRECATED;
1419
1420 \f
1421 /* Various functions.  */
1422
1423 /* Check that the library fulfills the version requirement.  */
1424 const char *gpgme_check_version (const char *req_version);
1425
1426 /* Retrieve information about the backend engines.  */
1427 gpgme_error_t gpgme_get_engine_info (gpgme_engine_info_t *engine_info);
1428
1429 \f
1430 /* Engine support functions.  */
1431
1432 /* Verify that the engine implementing PROTO is installed and
1433    available.  */
1434 gpgme_error_t gpgme_engine_check_version (gpgme_protocol_t proto);
1435
1436 \f
1437 /* Deprecated types.  */
1438 typedef gpgme_ctx_t GpgmeCtx _GPGME_DEPRECATED;
1439 typedef gpgme_data_t GpgmeData _GPGME_DEPRECATED;
1440 typedef gpgme_error_t GpgmeError _GPGME_DEPRECATED;
1441 typedef gpgme_data_encoding_t GpgmeDataEncoding _GPGME_DEPRECATED;
1442 typedef gpgme_pubkey_algo_t GpgmePubKeyAlgo _GPGME_DEPRECATED;
1443 typedef gpgme_hash_algo_t GpgmeHashAlgo _GPGME_DEPRECATED;
1444 typedef gpgme_sig_stat_t GpgmeSigStat _GPGME_DEPRECATED;
1445 typedef gpgme_sig_mode_t GpgmeSigMode _GPGME_DEPRECATED;
1446 typedef gpgme_attr_t GpgmeAttr _GPGME_DEPRECATED;
1447 typedef gpgme_validity_t GpgmeValidity _GPGME_DEPRECATED;
1448 typedef gpgme_protocol_t GpgmeProtocol _GPGME_DEPRECATED;
1449 typedef gpgme_engine_info_t GpgmeEngineInfo _GPGME_DEPRECATED;
1450 typedef gpgme_subkey_t GpgmeSubkey _GPGME_DEPRECATED;
1451 typedef gpgme_key_sig_t GpgmeKeySig _GPGME_DEPRECATED;
1452 typedef gpgme_user_id_t GpgmeUserID _GPGME_DEPRECATED;
1453 typedef gpgme_key_t GpgmeKey _GPGME_DEPRECATED;
1454 typedef gpgme_passphrase_cb_t GpgmePassphraseCb _GPGME_DEPRECATED;
1455 typedef gpgme_progress_cb_t GpgmeProgressCb _GPGME_DEPRECATED;
1456 typedef gpgme_io_cb_t GpgmeIOCb _GPGME_DEPRECATED;
1457 typedef gpgme_register_io_cb_t GpgmeRegisterIOCb _GPGME_DEPRECATED;
1458 typedef gpgme_remove_io_cb_t GpgmeRemoveIOCb _GPGME_DEPRECATED;
1459 typedef gpgme_event_io_t GpgmeEventIO _GPGME_DEPRECATED;
1460 typedef gpgme_event_io_cb_t GpgmeEventIOCb _GPGME_DEPRECATED;
1461 #define GpgmeIOCbs gpgme_io_cbs
1462 typedef gpgme_data_read_cb_t GpgmeDataReadCb _GPGME_DEPRECATED;
1463 typedef gpgme_data_write_cb_t GpgmeDataWriteCb _GPGME_DEPRECATED;
1464 typedef gpgme_data_seek_cb_t GpgmeDataSeekCb _GPGME_DEPRECATED;
1465 typedef gpgme_data_release_cb_t GpgmeDataReleaseCb _GPGME_DEPRECATED;
1466 #define GpgmeDataCbs gpgme_data_cbs
1467 typedef gpgme_encrypt_result_t GpgmeEncryptResult _GPGME_DEPRECATED;
1468 typedef gpgme_sig_notation_t GpgmeSigNotation _GPGME_DEPRECATED;
1469 typedef gpgme_signature_t GpgmeSignature _GPGME_DEPRECATED;
1470 typedef gpgme_verify_result_t GpgmeVerifyResult _GPGME_DEPRECATED;
1471 typedef gpgme_import_status_t GpgmeImportStatus _GPGME_DEPRECATED;
1472 typedef gpgme_import_result_t GpgmeImportResult _GPGME_DEPRECATED;
1473 typedef gpgme_genkey_result_t GpgmeGenKeyResult _GPGME_DEPRECATED;
1474 typedef gpgme_trust_item_t GpgmeTrustItem _GPGME_DEPRECATED;
1475 typedef gpgme_status_code_t GpgmeStatusCode _GPGME_DEPRECATED;
1476
1477 #ifdef __cplusplus
1478 }
1479 #endif
1480 #endif /* GPGME_H */