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