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