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