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