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