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