0b42798cd80c6e5973330bc6ea6f7fb9065a4234
[gpgme.git] / src / gpgme.h.in
1 /* gpgme.h - Public interface to GnuPG Made Easy.                   -*- c -*-
2    Copyright (C) 2000 Werner Koch (dd9jn)
3    Copyright (C) 2001, 2002, 2003, 2004, 2005, 2007, 2009 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 Lesser General Public License as
9    published by the Free Software Foundation; either version 2.1 of
10    the License, or (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    Lesser General Public License for more details.
16    
17    You should have received a copy of the GNU Lesser General Public
18    License along with this program; if not, see <http://www.gnu.org/licenses/>.
19  
20    File: @configure_input@  */
21
22 #ifndef GPGME_H
23 #define GPGME_H
24
25 #ifdef __GNUC__
26 #define _GPGME_INLINE __inline__
27 #elif __STDC_VERSION__ >= 199901L
28 #define _GPGME_INLINE inline
29 #else
30 #define _GPGME_INLINE
31 #endif
32
33 /* Include stdio.h for the FILE type definition.  */
34 #include <stdio.h>
35
36 #ifdef _MSC_VER
37   typedef long off_t;
38   typedef long ssize_t;
39 #else
40 # include <sys/types.h>
41 #endif
42
43 #include <gpg-error.h>
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
53 \f
54 /* Check for compiler features.  */
55 #if __GNUC__
56 #define _GPGME_GCC_VERSION (__GNUC__ * 10000 \
57                             + __GNUC_MINOR__ * 100 \
58                             + __GNUC_PATCHLEVEL__)
59
60 #if _GPGME_GCC_VERSION > 30100
61 #define _GPGME_DEPRECATED       __attribute__ ((__deprecated__))
62 #endif
63 #endif
64
65 #ifndef _GPGME_DEPRECATED
66 #define _GPGME_DEPRECATED
67 #endif
68
69 /* The macro _GPGME_DEPRECATED_OUTSIDE_GPGME suppresses warnings for
70    fields we must access in GPGME for ABI compatibility.  */
71 #ifdef _GPGME_IN_GPGME
72 #define _GPGME_DEPRECATED_OUTSIDE_GPGME
73 #else
74 #define _GPGME_DEPRECATED_OUTSIDE_GPGME _GPGME_DEPRECATED
75 #endif
76
77 \f
78 /* The version of this header should match the one of the library.  Do
79    not use this symbol in your application, use gpgme_check_version
80    instead.  The purpose of this macro is to let autoconf (using the
81    AM_PATH_GPGME macro) check that this header matches the installed
82    library.  */
83 #define GPGME_VERSION "@PACKAGE_VERSION@"
84
85 /* Check for a matching _FILE_OFFSET_BITS definition.  */
86 #if @NEED__FILE_OFFSET_BITS@
87 #ifndef _FILE_OFFSET_BITS
88 #error GPGME was compiled with _FILE_OFFSET_BITS = @NEED__FILE_OFFSET_BITS@, please see the section "Largefile support (LFS)" in the GPGME manual.
89 #else
90 #if (_FILE_OFFSET_BITS) != (@NEED__FILE_OFFSET_BITS@)
91 #error GPGME was compiled with a different value for _FILE_OFFSET_BITS, namely @NEED__FILE_OFFSET_BITS@, please see the section "Largefile support (LFS)" in the GPGME manual.
92 #endif
93 #endif
94 #endif
95
96
97 \f
98 /* Some opaque data types used by GPGME.  */
99
100 /* The context holds some global state and configration options, as
101    well as the results of a crypto operation.  */
102 struct gpgme_context;
103 typedef struct gpgme_context *gpgme_ctx_t;
104
105 /* The data object is used by GPGME to exchange arbitrary data.  */
106 struct gpgme_data;
107 typedef struct gpgme_data *gpgme_data_t;
108
109 \f
110 /* Wrappers for the libgpg-error library.  */
111
112 typedef gpg_error_t gpgme_error_t;
113 typedef gpg_err_code_t gpgme_err_code_t;
114 typedef gpg_err_source_t gpgme_err_source_t;
115
116
117 static _GPGME_INLINE gpgme_error_t
118 gpgme_err_make (gpgme_err_source_t source, gpgme_err_code_t code)
119 {
120   return gpg_err_make (source, code);
121 }
122
123
124 /* The user can define GPGME_ERR_SOURCE_DEFAULT before including this
125    file to specify a default source for gpgme_error.  */
126 #ifndef GPGME_ERR_SOURCE_DEFAULT
127 #define GPGME_ERR_SOURCE_DEFAULT  GPG_ERR_SOURCE_USER_1
128 #endif
129
130 static _GPGME_INLINE gpgme_error_t
131 gpgme_error (gpgme_err_code_t code)
132 {
133   return gpgme_err_make (GPGME_ERR_SOURCE_DEFAULT, code);
134 }
135
136
137 static _GPGME_INLINE gpgme_err_code_t
138 gpgme_err_code (gpgme_error_t err)
139 {
140   return gpg_err_code (err);
141 }
142
143
144 static _GPGME_INLINE gpgme_err_source_t
145 gpgme_err_source (gpgme_error_t err)
146 {
147   return gpg_err_source (err);
148 }
149
150
151 /* Return a pointer to a string containing a description of the error
152    code in the error value ERR.  This function is not thread safe.  */
153 const char *gpgme_strerror (gpgme_error_t err);
154
155 /* Return the error string for ERR in the user-supplied buffer BUF of
156    size BUFLEN.  This function is, in contrast to gpg_strerror,
157    thread-safe if a thread-safe strerror_r() function is provided by
158    the system.  If the function succeeds, 0 is returned and BUF
159    contains the string describing the error.  If the buffer was not
160    large enough, ERANGE is returned and BUF contains as much of the
161    beginning of the error string as fits into the buffer.  */
162 int gpgme_strerror_r (gpg_error_t err, char *buf, size_t buflen);
163
164
165 /* Return a pointer to a string containing a description of the error
166    source in the error value ERR.  */
167 const char *gpgme_strsource (gpgme_error_t err);
168
169
170 /* Retrieve the error code for the system error ERR.  This returns
171    GPG_ERR_UNKNOWN_ERRNO if the system error is not mapped (report
172    this).  */
173 gpgme_err_code_t gpgme_err_code_from_errno (int err);
174
175
176 /* Retrieve the system error for the error code CODE.  This returns 0
177    if CODE is not a system error code.  */
178 int gpgme_err_code_to_errno (gpgme_err_code_t code);
179
180   
181 /* Return an error value with the error source SOURCE and the system
182    error ERR.  */
183 gpgme_error_t gpgme_err_make_from_errno (gpgme_err_source_t source, int err);
184
185
186 /* Return an error value with the system error ERR.  */
187 gpgme_err_code_t gpgme_error_from_errno (int err);
188
189 \f
190 /* The possible encoding mode of gpgme_data_t objects.  */
191 typedef enum
192   {
193     GPGME_DATA_ENCODING_NONE   = 0,     /* Not specified.  */
194     GPGME_DATA_ENCODING_BINARY = 1,
195     GPGME_DATA_ENCODING_BASE64 = 2,
196     GPGME_DATA_ENCODING_ARMOR  = 3,     /* Either PEM or OpenPGP Armor.  */
197     GPGME_DATA_ENCODING_URL    = 4,     /* LF delimited URL list.        */
198     GPGME_DATA_ENCODING_URLESC = 5,     /* Ditto, but percent escaped.   */
199     GPGME_DATA_ENCODING_URL0   = 6      /* Nul delimited URL list.       */
200   }
201 gpgme_data_encoding_t;
202
203 \f
204 /* Public key algorithms from libgcrypt.  */
205 typedef enum
206   {
207     GPGME_PK_RSA   = 1,
208     GPGME_PK_RSA_E = 2,
209     GPGME_PK_RSA_S = 3,
210     GPGME_PK_ELG_E = 16,
211     GPGME_PK_DSA   = 17,
212     GPGME_PK_ELG   = 20
213   }
214 gpgme_pubkey_algo_t;
215
216
217 /* Hash algorithms from libgcrypt.  */
218 typedef enum
219   {
220     GPGME_MD_NONE          = 0,  
221     GPGME_MD_MD5           = 1,
222     GPGME_MD_SHA1          = 2,
223     GPGME_MD_RMD160        = 3,
224     GPGME_MD_MD2           = 5,
225     GPGME_MD_TIGER         = 6,   /* TIGER/192. */
226     GPGME_MD_HAVAL         = 7,   /* HAVAL, 5 pass, 160 bit. */
227     GPGME_MD_SHA256        = 8,
228     GPGME_MD_SHA384        = 9,
229     GPGME_MD_SHA512        = 10,
230     GPGME_MD_MD4           = 301,
231     GPGME_MD_CRC32         = 302,
232     GPGME_MD_CRC32_RFC1510 = 303,
233     GPGME_MD_CRC24_RFC2440 = 304
234   }
235 gpgme_hash_algo_t;
236
237 \f
238 /* The possible signature stati.  Deprecated, use error value in sig
239    status.  */
240 typedef enum
241   {
242     GPGME_SIG_STAT_NONE  = 0,
243     GPGME_SIG_STAT_GOOD  = 1,
244     GPGME_SIG_STAT_BAD   = 2,
245     GPGME_SIG_STAT_NOKEY = 3,
246     GPGME_SIG_STAT_NOSIG = 4,
247     GPGME_SIG_STAT_ERROR = 5,
248     GPGME_SIG_STAT_DIFF  = 6,
249     GPGME_SIG_STAT_GOOD_EXP = 7,
250     GPGME_SIG_STAT_GOOD_EXPKEY = 8
251   }
252 _gpgme_sig_stat_t;
253 typedef _gpgme_sig_stat_t gpgme_sig_stat_t _GPGME_DEPRECATED;
254
255
256 /* The available signature modes.  */
257 typedef enum
258   {
259     GPGME_SIG_MODE_NORMAL = 0,
260     GPGME_SIG_MODE_DETACH = 1,
261     GPGME_SIG_MODE_CLEAR  = 2
262   }
263 gpgme_sig_mode_t;
264
265 \f
266 /* The available key and signature attributes.  Deprecated, use the
267    individual result structures instead.  */
268 typedef enum
269   {
270     GPGME_ATTR_KEYID        = 1,
271     GPGME_ATTR_FPR          = 2,
272     GPGME_ATTR_ALGO         = 3,
273     GPGME_ATTR_LEN          = 4,
274     GPGME_ATTR_CREATED      = 5,
275     GPGME_ATTR_EXPIRE       = 6,
276     GPGME_ATTR_OTRUST       = 7,
277     GPGME_ATTR_USERID       = 8,
278     GPGME_ATTR_NAME         = 9,
279     GPGME_ATTR_EMAIL        = 10,
280     GPGME_ATTR_COMMENT      = 11,
281     GPGME_ATTR_VALIDITY     = 12,
282     GPGME_ATTR_LEVEL        = 13,
283     GPGME_ATTR_TYPE         = 14,
284     GPGME_ATTR_IS_SECRET    = 15,
285     GPGME_ATTR_KEY_REVOKED  = 16,
286     GPGME_ATTR_KEY_INVALID  = 17,
287     GPGME_ATTR_UID_REVOKED  = 18,
288     GPGME_ATTR_UID_INVALID  = 19,
289     GPGME_ATTR_KEY_CAPS     = 20,
290     GPGME_ATTR_CAN_ENCRYPT  = 21,
291     GPGME_ATTR_CAN_SIGN     = 22,
292     GPGME_ATTR_CAN_CERTIFY  = 23,
293     GPGME_ATTR_KEY_EXPIRED  = 24,
294     GPGME_ATTR_KEY_DISABLED = 25,
295     GPGME_ATTR_SERIAL       = 26,
296     GPGME_ATTR_ISSUER       = 27,
297     GPGME_ATTR_CHAINID      = 28,
298     GPGME_ATTR_SIG_STATUS   = 29,
299     GPGME_ATTR_ERRTOK       = 30,
300     GPGME_ATTR_SIG_SUMMARY  = 31,
301     GPGME_ATTR_SIG_CLASS    = 32
302   }
303 _gpgme_attr_t;
304 typedef _gpgme_attr_t gpgme_attr_t _GPGME_DEPRECATED;
305
306 \f
307 /* The available validities for a trust item or key.  */
308 typedef enum
309   {
310     GPGME_VALIDITY_UNKNOWN   = 0,
311     GPGME_VALIDITY_UNDEFINED = 1,
312     GPGME_VALIDITY_NEVER     = 2,
313     GPGME_VALIDITY_MARGINAL  = 3,
314     GPGME_VALIDITY_FULL      = 4,
315     GPGME_VALIDITY_ULTIMATE  = 5
316   }
317 gpgme_validity_t;
318
319 \f
320 /* The available protocols.  */
321 typedef enum
322   {
323     GPGME_PROTOCOL_OpenPGP = 0,  /* The default mode.  */
324     GPGME_PROTOCOL_CMS     = 1,
325     GPGME_PROTOCOL_GPGCONF = 2,  /* Special code for gpgconf.  */
326     GPGME_PROTOCOL_ASSUAN  = 3,  /* Low-level access to an Assuan server.  */
327     GPGME_PROTOCOL_UNKNOWN = 255
328   }
329 gpgme_protocol_t;
330
331 \f
332 /* The available keylist mode flags.  */
333 #define GPGME_KEYLIST_MODE_LOCAL                1
334 #define GPGME_KEYLIST_MODE_EXTERN               2
335 #define GPGME_KEYLIST_MODE_SIGS                 4
336 #define GPGME_KEYLIST_MODE_SIG_NOTATIONS        8
337 #define GPGME_KEYLIST_MODE_EPHEMERAL            128
338 #define GPGME_KEYLIST_MODE_VALIDATE             256
339
340 typedef unsigned int gpgme_keylist_mode_t;
341
342 \f
343 /* The available export mode flags.  */
344 #define GPGME_EXPORT_MODE_EXTERN                2
345
346 typedef unsigned int gpgme_export_mode_t;
347
348 \f
349 /* Flags for the audit log functions.  */
350 #define GPGME_AUDITLOG_HTML      1 
351 #define GPGME_AUDITLOG_WITH_HELP 128
352
353 \f
354 /* Signature notations.  */
355
356 /* The available signature notation flags.  */
357 #define GPGME_SIG_NOTATION_HUMAN_READABLE       1
358 #define GPGME_SIG_NOTATION_CRITICAL             2
359
360 typedef unsigned int gpgme_sig_notation_flags_t;
361
362 struct _gpgme_sig_notation
363 {
364   struct _gpgme_sig_notation *next;
365
366   /* If NAME is a null pointer, then VALUE contains a policy URL
367      rather than a notation.  */
368   char *name;
369
370   /* The value of the notation data.  */
371   char *value;
372
373   /* The length of the name of the notation data.  */
374   int name_len;
375
376   /* The length of the value of the notation data.  */
377   int value_len;
378
379   /* The accumulated flags.  */
380   gpgme_sig_notation_flags_t flags;
381
382   /* Notation data is human-readable.  */
383   unsigned int human_readable : 1;
384
385   /* Notation data is critical.  */
386   unsigned int critical : 1;
387
388   /* Internal to GPGME, do not use.  */
389   int _unused : 30;
390 };
391 typedef struct _gpgme_sig_notation *gpgme_sig_notation_t;
392
393 \f
394 /* The possible stati for the edit operation.  */
395 typedef enum
396   {
397     GPGME_STATUS_EOF = 0,
398     /* mkstatus processing starts here */
399     GPGME_STATUS_ENTER = 1,
400     GPGME_STATUS_LEAVE = 2,
401     GPGME_STATUS_ABORT = 3,
402
403     GPGME_STATUS_GOODSIG = 4,
404     GPGME_STATUS_BADSIG = 5,
405     GPGME_STATUS_ERRSIG = 6,
406
407     GPGME_STATUS_BADARMOR = 7,
408
409     GPGME_STATUS_RSA_OR_IDEA = 8,
410     GPGME_STATUS_KEYEXPIRED = 9,
411     GPGME_STATUS_KEYREVOKED = 10,
412
413     GPGME_STATUS_TRUST_UNDEFINED = 11,
414     GPGME_STATUS_TRUST_NEVER = 12,
415     GPGME_STATUS_TRUST_MARGINAL = 13,
416     GPGME_STATUS_TRUST_FULLY = 14,
417     GPGME_STATUS_TRUST_ULTIMATE = 15,
418
419     GPGME_STATUS_SHM_INFO = 16,
420     GPGME_STATUS_SHM_GET = 17,
421     GPGME_STATUS_SHM_GET_BOOL = 18,
422     GPGME_STATUS_SHM_GET_HIDDEN = 19,
423
424     GPGME_STATUS_NEED_PASSPHRASE = 20,
425     GPGME_STATUS_VALIDSIG = 21,
426     GPGME_STATUS_SIG_ID = 22,
427     GPGME_STATUS_ENC_TO = 23,
428     GPGME_STATUS_NODATA = 24,
429     GPGME_STATUS_BAD_PASSPHRASE = 25,
430     GPGME_STATUS_NO_PUBKEY = 26,
431     GPGME_STATUS_NO_SECKEY = 27,
432     GPGME_STATUS_NEED_PASSPHRASE_SYM = 28,
433     GPGME_STATUS_DECRYPTION_FAILED = 29,
434     GPGME_STATUS_DECRYPTION_OKAY = 30,
435     GPGME_STATUS_MISSING_PASSPHRASE = 31,
436     GPGME_STATUS_GOOD_PASSPHRASE = 32,
437     GPGME_STATUS_GOODMDC = 33,
438     GPGME_STATUS_BADMDC = 34,
439     GPGME_STATUS_ERRMDC = 35,
440     GPGME_STATUS_IMPORTED = 36,
441     GPGME_STATUS_IMPORT_OK = 37,
442     GPGME_STATUS_IMPORT_PROBLEM = 38,
443     GPGME_STATUS_IMPORT_RES = 39,
444     GPGME_STATUS_FILE_START = 40,
445     GPGME_STATUS_FILE_DONE = 41,
446     GPGME_STATUS_FILE_ERROR = 42,
447
448     GPGME_STATUS_BEGIN_DECRYPTION = 43,
449     GPGME_STATUS_END_DECRYPTION = 44,
450     GPGME_STATUS_BEGIN_ENCRYPTION = 45,
451     GPGME_STATUS_END_ENCRYPTION = 46,
452
453     GPGME_STATUS_DELETE_PROBLEM = 47,
454     GPGME_STATUS_GET_BOOL = 48,
455     GPGME_STATUS_GET_LINE = 49,
456     GPGME_STATUS_GET_HIDDEN = 50,
457     GPGME_STATUS_GOT_IT = 51,
458     GPGME_STATUS_PROGRESS = 52,
459     GPGME_STATUS_SIG_CREATED = 53,
460     GPGME_STATUS_SESSION_KEY = 54,
461     GPGME_STATUS_NOTATION_NAME = 55,
462     GPGME_STATUS_NOTATION_DATA = 56,
463     GPGME_STATUS_POLICY_URL = 57,
464     GPGME_STATUS_BEGIN_STREAM = 58,
465     GPGME_STATUS_END_STREAM = 59,
466     GPGME_STATUS_KEY_CREATED = 60,
467     GPGME_STATUS_USERID_HINT = 61,
468     GPGME_STATUS_UNEXPECTED = 62,
469     GPGME_STATUS_INV_RECP = 63,
470     GPGME_STATUS_NO_RECP = 64,
471     GPGME_STATUS_ALREADY_SIGNED = 65,
472     GPGME_STATUS_SIGEXPIRED = 66,
473     GPGME_STATUS_EXPSIG = 67,
474     GPGME_STATUS_EXPKEYSIG = 68,
475     GPGME_STATUS_TRUNCATED = 69,
476     GPGME_STATUS_ERROR = 70,
477     GPGME_STATUS_NEWSIG = 71,
478     GPGME_STATUS_REVKEYSIG = 72,
479     GPGME_STATUS_SIG_SUBPACKET = 73,
480     GPGME_STATUS_NEED_PASSPHRASE_PIN = 74,
481     GPGME_STATUS_SC_OP_FAILURE = 75,
482     GPGME_STATUS_SC_OP_SUCCESS = 76,
483     GPGME_STATUS_CARDCTRL = 77,
484     GPGME_STATUS_BACKUP_KEY_CREATED = 78,
485     GPGME_STATUS_PKA_TRUST_BAD = 79,
486     GPGME_STATUS_PKA_TRUST_GOOD = 80,
487
488     GPGME_STATUS_PLAINTEXT = 81,
489     GPGME_STATUS_INV_SGNR = 82,
490     GPGME_STATUS_NO_SGNR = 83
491   }
492 gpgme_status_code_t;
493
494 \f
495 /* The engine information structure.  */
496 struct _gpgme_engine_info
497 {
498   struct _gpgme_engine_info *next;
499
500   /* The protocol ID.  */
501   gpgme_protocol_t protocol;
502
503   /* The file name of the engine binary.  */
504   char *file_name;
505   
506   /* The version string of the installed engine.  */
507   char *version;
508
509   /* The minimum version required for GPGME.  */
510   const char *req_version;
511
512   /* The home directory used, or NULL if default.  */
513   char *home_dir;
514 };
515 typedef struct _gpgme_engine_info *gpgme_engine_info_t;
516
517 \f
518 /* A subkey from a key.  */
519 struct _gpgme_subkey
520 {
521   struct _gpgme_subkey *next;
522
523   /* True if subkey is revoked.  */
524   unsigned int revoked : 1;
525
526   /* True if subkey is expired.  */
527   unsigned int expired : 1;
528
529   /* True if subkey is disabled.  */
530   unsigned int disabled : 1;
531
532   /* True if subkey is invalid.  */
533   unsigned int invalid : 1;
534
535   /* True if subkey can be used for encryption.  */
536   unsigned int can_encrypt : 1;
537
538   /* True if subkey can be used for signing.  */
539   unsigned int can_sign : 1;
540
541   /* True if subkey can be used for certification.  */
542   unsigned int can_certify : 1;
543
544   /* True if subkey is secret.  */
545   unsigned int secret : 1;
546
547   /* True if subkey can be used for authentication.  */
548   unsigned int can_authenticate : 1;
549
550   /* True if subkey is qualified for signatures according to German law.  */
551   unsigned int is_qualified : 1;
552
553   /* True if the secret key is stored on a smart card.  */
554   unsigned int is_cardkey : 1;
555
556   /* Internal to GPGME, do not use.  */
557   unsigned int _unused : 21;
558   
559   /* Public key algorithm supported by this subkey.  */
560   gpgme_pubkey_algo_t pubkey_algo;
561
562   /* Length of the subkey.  */
563   unsigned int length;
564
565   /* The key ID of the subkey.  */
566   char *keyid;
567
568   /* Internal to GPGME, do not use.  */
569   char _keyid[16 + 1];
570
571   /* The fingerprint of the subkey in hex digit form.  */
572   char *fpr;
573
574   /* The creation timestamp, -1 if invalid, 0 if not available.  */
575   long int timestamp;
576
577   /* The expiration timestamp, 0 if the subkey does not expire.  */
578   long int expires;
579
580   /* The serial number of a smart card holding this key or NULL.  */
581   char *card_number;
582 };
583 typedef struct _gpgme_subkey *gpgme_subkey_t;
584
585
586 /* A signature on a user ID.  */
587 struct _gpgme_key_sig
588 {
589   struct _gpgme_key_sig *next;
590
591   /* True if the signature is a revocation signature.  */
592   unsigned int revoked : 1;
593
594   /* True if the signature is expired.  */
595   unsigned int expired : 1;
596
597   /* True if the signature is invalid.  */
598   unsigned int invalid : 1;
599
600   /* True if the signature should be exported.  */
601   unsigned int exportable : 1;
602
603   /* Internal to GPGME, do not use.  */
604   unsigned int _unused : 28;
605
606   /* The public key algorithm used to create the signature.  */
607   gpgme_pubkey_algo_t pubkey_algo;
608
609   /* The key ID of key used to create the signature.  */
610   char *keyid;
611
612   /* Internal to GPGME, do not use.  */
613   char _keyid[16 + 1];
614
615   /* The creation timestamp, -1 if invalid, 0 if not available.  */
616   long int timestamp;
617
618   /* The expiration timestamp, 0 if the subkey does not expire.  */
619   long int expires;
620
621   /* Same as in gpgme_signature_t.  */
622   gpgme_error_t status;
623
624 #ifdef __cplusplus
625   unsigned int _obsolete_class _GPGME_DEPRECATED;
626 #else
627   /* Must be set to SIG_CLASS below.  */
628   unsigned int class _GPGME_DEPRECATED_OUTSIDE_GPGME;
629 #endif
630
631   /* The user ID string.  */
632   char *uid;
633
634   /* The name part of the user ID.  */
635   char *name;
636
637   /* The email part of the user ID.  */
638   char *email;
639
640   /* The comment part of the user ID.  */
641   char *comment;
642
643   /* Crypto backend specific signature class.  */
644   unsigned int sig_class;
645
646   /* Notation data and policy URLs.  */
647   gpgme_sig_notation_t notations;
648
649   /* Internal to GPGME, do not use.  */
650   gpgme_sig_notation_t _last_notation;
651 };
652 typedef struct _gpgme_key_sig *gpgme_key_sig_t;
653
654
655 /* An user ID from a key.  */
656 struct _gpgme_user_id
657 {
658   struct _gpgme_user_id *next;
659
660   /* True if the user ID is revoked.  */
661   unsigned int revoked : 1;
662
663   /* True if the user ID is invalid.  */
664   unsigned int invalid : 1;
665
666   /* Internal to GPGME, do not use.  */
667   unsigned int _unused : 30;
668
669   /* The validity of the user ID.  */
670   gpgme_validity_t validity; 
671
672   /* The user ID string.  */
673   char *uid;
674
675   /* The name part of the user ID.  */
676   char *name;
677
678   /* The email part of the user ID.  */
679   char *email;
680
681   /* The comment part of the user ID.  */
682   char *comment;
683
684   /* The signatures of the user ID.  */
685   gpgme_key_sig_t signatures;
686
687   /* Internal to GPGME, do not use.  */
688   gpgme_key_sig_t _last_keysig;
689 };
690 typedef struct _gpgme_user_id *gpgme_user_id_t;
691
692
693 /* A key from the keyring.  */
694 struct _gpgme_key
695 {
696   /* Internal to GPGME, do not use.  */
697   unsigned int _refs;
698
699   /* True if key is revoked.  */
700   unsigned int revoked : 1;
701
702   /* True if key is expired.  */
703   unsigned int expired : 1;
704
705   /* True if key is disabled.  */
706   unsigned int disabled : 1;
707
708   /* True if key is invalid.  */
709   unsigned int invalid : 1;
710
711   /* True if key can be used for encryption.  */
712   unsigned int can_encrypt : 1;
713
714   /* True if key can be used for signing.  */
715   unsigned int can_sign : 1;
716
717   /* True if key can be used for certification.  */
718   unsigned int can_certify : 1;
719
720   /* True if key is secret.  */
721   unsigned int secret : 1;
722
723   /* True if key can be used for authentication.  */
724   unsigned int can_authenticate : 1;
725
726   /* True if subkey is qualified for signatures according to German law.  */
727   unsigned int is_qualified : 1;
728
729   /* Internal to GPGME, do not use.  */
730   unsigned int _unused : 22;
731
732   /* This is the protocol supported by this key.  */
733   gpgme_protocol_t protocol;
734
735   /* If protocol is GPGME_PROTOCOL_CMS, this string contains the
736      issuer serial.  */
737   char *issuer_serial;
738
739   /* If protocol is GPGME_PROTOCOL_CMS, this string contains the
740      issuer name.  */
741   char *issuer_name;
742
743   /* If protocol is GPGME_PROTOCOL_CMS, this string contains the chain
744      ID.  */
745   char *chain_id;
746
747   /* If protocol is GPGME_PROTOCOL_OpenPGP, this field contains the
748      owner trust.  */
749   gpgme_validity_t owner_trust;
750
751   /* The subkeys of the key.  */
752   gpgme_subkey_t subkeys;
753
754   /* The user IDs of the key.  */
755   gpgme_user_id_t uids;
756
757   /* Internal to GPGME, do not use.  */
758   gpgme_subkey_t _last_subkey;
759
760   /* Internal to GPGME, do not use.  */
761   gpgme_user_id_t _last_uid;
762
763   /* The keylist mode that was active when listing the key.  */
764   gpgme_keylist_mode_t keylist_mode;
765 };
766 typedef struct _gpgme_key *gpgme_key_t;
767
768
769 \f
770 /* Types for callback functions.  */
771
772 /* Request a passphrase from the user.  */
773 typedef gpgme_error_t (*gpgme_passphrase_cb_t) (void *hook,
774                                                 const char *uid_hint,
775                                                 const char *passphrase_info,
776                                                 int prev_was_bad, int fd);
777
778 /* Inform the user about progress made.  */
779 typedef void (*gpgme_progress_cb_t) (void *opaque, const char *what,
780                                      int type, int current, int total);
781
782 /* Interact with the user about an edit operation.  */
783 typedef gpgme_error_t (*gpgme_edit_cb_t) (void *opaque,
784                                           gpgme_status_code_t status,
785                                           const char *args, int fd);
786
787
788
789 \f
790 /* Context management functions.  */
791
792 /* Create a new context and return it in CTX.  */
793 gpgme_error_t gpgme_new (gpgme_ctx_t *ctx);
794
795 /* Release the context CTX.  */
796 void gpgme_release (gpgme_ctx_t ctx);
797
798 /* Set the protocol to be used by CTX to PROTO.  */
799 gpgme_error_t gpgme_set_protocol (gpgme_ctx_t ctx, gpgme_protocol_t proto);
800
801 /* Get the protocol used with CTX */
802 gpgme_protocol_t gpgme_get_protocol (gpgme_ctx_t ctx);
803
804 /* Get the string describing protocol PROTO, or NULL if invalid.  */
805 const char *gpgme_get_protocol_name (gpgme_protocol_t proto);
806
807 /* If YES is non-zero, enable armor mode in CTX, disable it otherwise.  */
808 void gpgme_set_armor (gpgme_ctx_t ctx, int yes);
809
810 /* Return non-zero if armor mode is set in CTX.  */
811 int gpgme_get_armor (gpgme_ctx_t ctx);
812
813 /* If YES is non-zero, enable text mode in CTX, disable it otherwise.  */
814 void gpgme_set_textmode (gpgme_ctx_t ctx, int yes);
815
816 /* Return non-zero if text mode is set in CTX.  */
817 int gpgme_get_textmode (gpgme_ctx_t ctx);
818
819 /* Use whatever the default of the backend crypto engine is.  */
820 #define GPGME_INCLUDE_CERTS_DEFAULT     -256
821
822 /* Include up to NR_OF_CERTS certificates in an S/MIME message.  */
823 void gpgme_set_include_certs (gpgme_ctx_t ctx, int nr_of_certs);
824
825 /* Return the number of certs to include in an S/MIME message.  */
826 int gpgme_get_include_certs (gpgme_ctx_t ctx);
827
828 /* Set keylist mode in CTX to MODE.  */
829 gpgme_error_t gpgme_set_keylist_mode (gpgme_ctx_t ctx,
830                                       gpgme_keylist_mode_t mode);
831
832 /* Get keylist mode in CTX.  */
833 gpgme_keylist_mode_t gpgme_get_keylist_mode (gpgme_ctx_t ctx);
834
835 /* Set the passphrase callback function in CTX to CB.  HOOK_VALUE is
836    passed as first argument to the passphrase callback function.  */
837 void gpgme_set_passphrase_cb (gpgme_ctx_t ctx,
838                               gpgme_passphrase_cb_t cb, void *hook_value);
839
840 /* Get the current passphrase callback function in *CB and the current
841    hook value in *HOOK_VALUE.  */
842 void gpgme_get_passphrase_cb (gpgme_ctx_t ctx, gpgme_passphrase_cb_t *cb,
843                               void **hook_value);
844
845 /* Set the progress callback function in CTX to CB.  HOOK_VALUE is
846    passed as first argument to the progress callback function.  */
847 void gpgme_set_progress_cb (gpgme_ctx_t c, gpgme_progress_cb_t cb,
848                             void *hook_value);
849
850 /* Get the current progress callback function in *CB and the current
851    hook value in *HOOK_VALUE.  */
852 void gpgme_get_progress_cb (gpgme_ctx_t ctx, gpgme_progress_cb_t *cb,
853                             void **hook_value);
854
855 /* This function sets the locale for the context CTX, or the default
856    locale if CTX is a null pointer.  */
857 gpgme_error_t gpgme_set_locale (gpgme_ctx_t ctx, int category,
858                                 const char *value);
859
860 /* Get the information about the configured engines.  A pointer to the
861    first engine in the statically allocated linked list is returned.
862    The returned data is valid until the next gpgme_ctx_set_engine_info.  */
863 gpgme_engine_info_t gpgme_ctx_get_engine_info (gpgme_ctx_t ctx);
864
865 /* Set the engine info for the context CTX, protocol PROTO, to the
866    file name FILE_NAME and the home directory HOME_DIR.  */
867 gpgme_error_t gpgme_ctx_set_engine_info (gpgme_ctx_t ctx,
868                                          gpgme_protocol_t proto,
869                                          const char *file_name,
870                                          const char *home_dir);
871
872 \f
873 /* Return a statically allocated string with the name of the public
874    key algorithm ALGO, or NULL if that name is not known.  */
875 const char *gpgme_pubkey_algo_name (gpgme_pubkey_algo_t algo);
876
877 /* Return a statically allocated string with the name of the hash
878    algorithm ALGO, or NULL if that name is not known.  */
879 const char *gpgme_hash_algo_name (gpgme_hash_algo_t algo);
880
881 \f
882 /* Delete all signers from CTX.  */
883 void gpgme_signers_clear (gpgme_ctx_t ctx);
884
885 /* Add KEY to list of signers in CTX.  */
886 gpgme_error_t gpgme_signers_add (gpgme_ctx_t ctx, const gpgme_key_t key);
887
888 /* Return the SEQth signer's key in CTX.  */
889 gpgme_key_t gpgme_signers_enum (const gpgme_ctx_t ctx, int seq);
890
891 /* Retrieve the signature status of signature IDX in CTX after a
892    successful verify operation in R_STAT (if non-null).  The creation
893    time stamp of the signature is returned in R_CREATED (if non-null).
894    The function returns a string containing the fingerprint.
895    Deprecated, use verify result directly.  */
896 const char *gpgme_get_sig_status (gpgme_ctx_t ctx, int idx,
897                                   _gpgme_sig_stat_t *r_stat,
898                                   time_t *r_created) _GPGME_DEPRECATED;
899
900 /* Retrieve certain attributes of a signature.  IDX is the index
901    number of the signature after a successful verify operation.  WHAT
902    is an attribute where GPGME_ATTR_EXPIRE is probably the most useful
903    one.  WHATIDX is to be passed as 0 for most attributes . */
904 unsigned long gpgme_get_sig_ulong_attr (gpgme_ctx_t c, int idx,
905                                         _gpgme_attr_t what, int whatidx)
906      _GPGME_DEPRECATED;
907 const char *gpgme_get_sig_string_attr (gpgme_ctx_t c, int idx,
908                                        _gpgme_attr_t what, int whatidx)
909      _GPGME_DEPRECATED;
910
911
912 /* Get the key used to create signature IDX in CTX and return it in
913    R_KEY.  */
914 gpgme_error_t gpgme_get_sig_key (gpgme_ctx_t ctx, int idx, gpgme_key_t *r_key)
915      _GPGME_DEPRECATED;
916
917 \f
918 /* Clear all notation data from the context.  */
919 void gpgme_sig_notation_clear (gpgme_ctx_t ctx);
920
921 /* Add the human-readable notation data with name NAME and value VALUE
922    to the context CTX, using the flags FLAGS.  If NAME is NULL, then
923    VALUE should be a policy URL.  The flag
924    GPGME_SIG_NOTATION_HUMAN_READABLE is forced to be true for notation
925    data, and false for policy URLs.  */
926 gpgme_error_t gpgme_sig_notation_add (gpgme_ctx_t ctx, const char *name,
927                                       const char *value,
928                                       gpgme_sig_notation_flags_t flags);
929
930 /* Get the sig notations for this context.  */
931 gpgme_sig_notation_t gpgme_sig_notation_get (gpgme_ctx_t ctx);
932
933 \f
934 /* Run control.  */
935
936 /* The type of an I/O callback function.  */
937 typedef gpgme_error_t (*gpgme_io_cb_t) (void *data, int fd);
938
939 /* The type of a function that can register FNC as the I/O callback
940    function for the file descriptor FD with direction dir (0: for writing,
941    1: for reading).  FNC_DATA should be passed as DATA to FNC.  The
942    function should return a TAG suitable for the corresponding
943    gpgme_remove_io_cb_t, and an error value.  */
944 typedef gpgme_error_t (*gpgme_register_io_cb_t) (void *data, int fd, int dir,
945                                                  gpgme_io_cb_t fnc,
946                                                  void *fnc_data, void **tag);
947
948 /* The type of a function that can remove a previously registered I/O
949    callback function given TAG as returned by the register
950    function.  */
951 typedef void (*gpgme_remove_io_cb_t) (void *tag);
952
953 typedef enum
954   {
955     GPGME_EVENT_START,
956     GPGME_EVENT_DONE,
957     GPGME_EVENT_NEXT_KEY,
958     GPGME_EVENT_NEXT_TRUSTITEM
959   }
960 gpgme_event_io_t;
961
962 /* The type of a function that is called when a context finished an
963    operation.  */
964 typedef void (*gpgme_event_io_cb_t) (void *data, gpgme_event_io_t type,
965                                      void *type_data);
966
967 struct gpgme_io_cbs
968 {
969   gpgme_register_io_cb_t add;
970   void *add_priv;
971   gpgme_remove_io_cb_t remove;
972   gpgme_event_io_cb_t event;
973   void *event_priv;
974 };
975 typedef struct gpgme_io_cbs *gpgme_io_cbs_t;
976
977 /* Set the I/O callback functions in CTX to IO_CBS.  */
978 void gpgme_set_io_cbs (gpgme_ctx_t ctx, gpgme_io_cbs_t io_cbs);
979
980 /* Get the current I/O callback functions.  */
981 void gpgme_get_io_cbs (gpgme_ctx_t ctx, gpgme_io_cbs_t io_cbs);
982
983 /* Wrappers around the internal I/O functions for use with
984    gpgme_passphrase_cb_t and gpgme_edit_cb_t.  */
985 ssize_t gpgme_io_read (int fd, void *buffer, size_t count);
986 ssize_t gpgme_io_write (int fd, const void *buffer, size_t count);
987
988 /* Process the pending operation and, if HANG is non-zero, wait for
989    the pending operation to finish.  */
990 gpgme_ctx_t gpgme_wait (gpgme_ctx_t ctx, gpgme_error_t *status, int hang);
991
992 \f
993 /* Functions to handle data objects.  */
994
995 /* Read up to SIZE bytes into buffer BUFFER from the data object with
996    the handle HANDLE.  Return the number of characters read, 0 on EOF
997    and -1 on error.  If an error occurs, errno is set.  */
998 typedef ssize_t (*gpgme_data_read_cb_t) (void *handle, void *buffer,
999                                          size_t size);
1000
1001 /* Write up to SIZE bytes from buffer BUFFER to the data object with
1002    the handle HANDLE.  Return the number of characters written, or -1
1003    on error.  If an error occurs, errno is set.  */
1004 typedef ssize_t (*gpgme_data_write_cb_t) (void *handle, const void *buffer,
1005                                           size_t size);
1006
1007 /* Set the current position from where the next read or write starts
1008    in the data object with the handle HANDLE to OFFSET, relativ to
1009    WHENCE.  */
1010 typedef off_t (*gpgme_data_seek_cb_t) (void *handle, off_t offset, int whence);
1011
1012 /* Close the data object with the handle DL.  */
1013 typedef void (*gpgme_data_release_cb_t) (void *handle);
1014
1015 struct gpgme_data_cbs
1016 {
1017   gpgme_data_read_cb_t read;
1018   gpgme_data_write_cb_t write;
1019   gpgme_data_seek_cb_t seek;
1020   gpgme_data_release_cb_t release;
1021 };
1022 typedef struct gpgme_data_cbs *gpgme_data_cbs_t;
1023
1024 /* Read up to SIZE bytes into buffer BUFFER from the data object with
1025    the handle DH.  Return the number of characters read, 0 on EOF and
1026    -1 on error.  If an error occurs, errno is set.  */
1027 ssize_t gpgme_data_read (gpgme_data_t dh, void *buffer, size_t size);
1028
1029 /* Write up to SIZE bytes from buffer BUFFER to the data object with
1030    the handle DH.  Return the number of characters written, or -1 on
1031    error.  If an error occurs, errno is set.  */
1032 ssize_t gpgme_data_write (gpgme_data_t dh, const void *buffer, size_t size);
1033
1034 /* Set the current position from where the next read or write starts
1035    in the data object with the handle DH to OFFSET, relativ to
1036    WHENCE.  */
1037 off_t gpgme_data_seek (gpgme_data_t dh, off_t offset, int whence);
1038
1039 /* Create a new data buffer and return it in R_DH.  */
1040 gpgme_error_t gpgme_data_new (gpgme_data_t *r_dh);
1041
1042 /* Destroy the data buffer DH.  */
1043 void gpgme_data_release (gpgme_data_t dh);
1044
1045 /* Create a new data buffer filled with SIZE bytes starting from
1046    BUFFER.  If COPY is zero, copying is delayed until necessary, and
1047    the data is taken from the original location when needed.  */
1048 gpgme_error_t gpgme_data_new_from_mem (gpgme_data_t *r_dh,
1049                                        const char *buffer, size_t size,
1050                                        int copy);
1051
1052 /* Destroy the data buffer DH and return a pointer to its content.
1053    The memory has be to released with gpgme_free() by the user.  It's
1054    size is returned in R_LEN.  */
1055 char *gpgme_data_release_and_get_mem (gpgme_data_t dh, size_t *r_len);
1056
1057 /* Release the memory returned by gpgme_data_release_and_get_mem().  */
1058 void gpgme_free (void *buffer);
1059
1060 gpgme_error_t gpgme_data_new_from_cbs (gpgme_data_t *dh,
1061                                        gpgme_data_cbs_t cbs,
1062                                        void *handle);
1063
1064 gpgme_error_t gpgme_data_new_from_fd (gpgme_data_t *dh, int fd);
1065
1066 gpgme_error_t gpgme_data_new_from_stream (gpgme_data_t *dh, FILE *stream);
1067
1068 /* Return the encoding attribute of the data buffer DH */
1069 gpgme_data_encoding_t gpgme_data_get_encoding (gpgme_data_t dh);
1070
1071 /* Set the encoding attribute of data buffer DH to ENC */
1072 gpgme_error_t gpgme_data_set_encoding (gpgme_data_t dh,
1073                                        gpgme_data_encoding_t enc);
1074
1075 /* Get the file name associated with the data object with handle DH, or
1076    NULL if there is none.  */
1077 char *gpgme_data_get_file_name (gpgme_data_t dh);
1078
1079 /* Set the file name associated with the data object with handle DH to
1080    FILE_NAME.  */
1081 gpgme_error_t gpgme_data_set_file_name (gpgme_data_t dh,
1082                                         const char *file_name);
1083
1084
1085 /* Create a new data buffer which retrieves the data from the callback
1086    function READ_CB.  Deprecated, please use gpgme_data_new_from_cbs
1087    instead.  */
1088 gpgme_error_t gpgme_data_new_with_read_cb (gpgme_data_t *r_dh,
1089                                            int (*read_cb) (void*,char *,
1090                                                            size_t,size_t*),
1091                                            void *read_cb_value)
1092      _GPGME_DEPRECATED;
1093
1094 /* Create a new data buffer filled with the content of file FNAME.
1095    COPY must be non-zero.  For delayed read, please use
1096    gpgme_data_new_from_fd or gpgme_data_new_from stream instead.  */
1097 gpgme_error_t gpgme_data_new_from_file (gpgme_data_t *r_dh,
1098                                         const char *fname,
1099                                         int copy);
1100
1101 /* Create a new data buffer filled with LENGTH bytes starting from
1102    OFFSET within the file FNAME or stream FP (exactly one must be
1103    non-zero).  */
1104 gpgme_error_t gpgme_data_new_from_filepart (gpgme_data_t *r_dh,
1105                                             const char *fname, FILE *fp,
1106                                             off_t offset, size_t length);
1107
1108 /* Reset the read pointer in DH.  Deprecated, please use
1109    gpgme_data_seek instead.  */
1110 gpgme_error_t gpgme_data_rewind (gpgme_data_t dh) _GPGME_DEPRECATED;
1111
1112 \f
1113 /* Key and trust functions.  */
1114
1115 /* Get the key with the fingerprint FPR from the crypto backend.  If
1116    SECRET is true, get the secret key.  */
1117 gpgme_error_t gpgme_get_key (gpgme_ctx_t ctx, const char *fpr,
1118                              gpgme_key_t *r_key, int secret);
1119
1120 /* Acquire a reference to KEY.  */
1121 void gpgme_key_ref (gpgme_key_t key);
1122
1123 /* Release a reference to KEY.  If this was the last one the key is
1124    destroyed.  */
1125 void gpgme_key_unref (gpgme_key_t key);
1126 void gpgme_key_release (gpgme_key_t key);
1127
1128 /* Return the value of the attribute WHAT of KEY, which has to be
1129    representable by a string.  IDX specifies the sub key or user ID
1130    for attributes related to sub keys or user IDs.  Deprecated, use
1131    key structure directly instead. */
1132 const char *gpgme_key_get_string_attr (gpgme_key_t key, _gpgme_attr_t what,
1133                                        const void *reserved, int idx)
1134      _GPGME_DEPRECATED;
1135
1136 /* Return the value of the attribute WHAT of KEY, which has to be
1137    representable by an unsigned integer.  IDX specifies the sub key or
1138    user ID for attributes related to sub keys or user IDs.
1139    Deprecated, use key structure directly instead.  */
1140 unsigned long gpgme_key_get_ulong_attr (gpgme_key_t key, _gpgme_attr_t what,
1141                                         const void *reserved, int idx)
1142      _GPGME_DEPRECATED;
1143
1144 /* Return the value of the attribute WHAT of a signature on user ID
1145    UID_IDX in KEY, which has to be representable by a string.  IDX
1146    specifies the signature.  Deprecated, use key structure directly
1147    instead.  */
1148 const char *gpgme_key_sig_get_string_attr (gpgme_key_t key, int uid_idx,
1149                                            _gpgme_attr_t what,
1150                                            const void *reserved, int idx)
1151      _GPGME_DEPRECATED;
1152
1153 /* Return the value of the attribute WHAT of a signature on user ID
1154    UID_IDX in KEY, which has to be representable by an unsigned
1155    integer string.  IDX specifies the signature.  Deprecated, use key
1156    structure directly instead.  */
1157 unsigned long gpgme_key_sig_get_ulong_attr (gpgme_key_t key, int uid_idx,
1158                                             _gpgme_attr_t what,
1159                                             const void *reserved, int idx)
1160      _GPGME_DEPRECATED;
1161
1162 \f
1163 /* Crypto Operations.  */
1164
1165 /* Cancel a pending asynchronous operation.  */
1166 gpgme_error_t gpgme_cancel (gpgme_ctx_t ctx);
1167
1168 /* Cancel a pending operation asynchronously.  */
1169 gpgme_error_t gpgme_cancel_async (gpgme_ctx_t ctx);
1170
1171 \f
1172 struct _gpgme_invalid_key
1173 {
1174   struct _gpgme_invalid_key *next;
1175   char *fpr;
1176   gpgme_error_t reason;
1177 };
1178 typedef struct _gpgme_invalid_key *gpgme_invalid_key_t;
1179
1180 \f
1181 /* Encryption.  */
1182 struct _gpgme_op_encrypt_result
1183 {
1184   /* The list of invalid recipients.  */
1185   gpgme_invalid_key_t invalid_recipients;
1186 };
1187 typedef struct _gpgme_op_encrypt_result *gpgme_encrypt_result_t;
1188
1189 /* Retrieve a pointer to the result of the encrypt operation.  */
1190 gpgme_encrypt_result_t gpgme_op_encrypt_result (gpgme_ctx_t ctx);
1191
1192 /* The valid encryption flags.  */
1193 typedef enum
1194   {
1195     GPGME_ENCRYPT_ALWAYS_TRUST = 1,
1196     GPGME_ENCRYPT_NO_ENCRYPT_TO = 2
1197   }
1198 gpgme_encrypt_flags_t;
1199
1200 /* Encrypt plaintext PLAIN within CTX for the recipients RECP and
1201    store the resulting ciphertext in CIPHER.  */
1202 gpgme_error_t gpgme_op_encrypt_start (gpgme_ctx_t ctx, gpgme_key_t recp[],
1203                                       gpgme_encrypt_flags_t flags,
1204                                       gpgme_data_t plain, gpgme_data_t cipher);
1205 gpgme_error_t gpgme_op_encrypt (gpgme_ctx_t ctx, gpgme_key_t recp[],
1206                                 gpgme_encrypt_flags_t flags,
1207                                 gpgme_data_t plain, gpgme_data_t cipher);
1208
1209 /* Encrypt plaintext PLAIN within CTX for the recipients RECP and
1210    store the resulting ciphertext in CIPHER.  Also sign the ciphertext
1211    with the signers in CTX.  */
1212 gpgme_error_t gpgme_op_encrypt_sign_start (gpgme_ctx_t ctx,
1213                                            gpgme_key_t recp[],
1214                                            gpgme_encrypt_flags_t flags,
1215                                            gpgme_data_t plain,
1216                                            gpgme_data_t cipher);
1217 gpgme_error_t gpgme_op_encrypt_sign (gpgme_ctx_t ctx, gpgme_key_t recp[],
1218                                      gpgme_encrypt_flags_t flags,
1219                                      gpgme_data_t plain, gpgme_data_t cipher);
1220
1221 \f
1222 /* Decryption.  */
1223
1224 struct _gpgme_recipient
1225 {
1226   struct _gpgme_recipient *next;
1227
1228   /* The key ID of key for which the text was encrypted.  */
1229   char *keyid;
1230
1231   /* Internal to GPGME, do not use.  */
1232   char _keyid[16 + 1];
1233
1234   /* The public key algorithm of the recipient key.  */
1235   gpgme_pubkey_algo_t pubkey_algo;
1236
1237   /* The status of the recipient.  */
1238   gpgme_error_t status;
1239 };
1240 typedef struct _gpgme_recipient *gpgme_recipient_t;
1241
1242 struct _gpgme_op_decrypt_result
1243 {
1244   char *unsupported_algorithm;
1245
1246   /* Key should not have been used for encryption.  */
1247   unsigned int wrong_key_usage : 1;
1248
1249   /* Internal to GPGME, do not use.  */
1250   int _unused : 31;
1251
1252   gpgme_recipient_t recipients;
1253
1254   /* The original file name of the plaintext message, if
1255      available.  */
1256   char *file_name;
1257 };
1258 typedef struct _gpgme_op_decrypt_result *gpgme_decrypt_result_t;
1259
1260 /* Retrieve a pointer to the result of the decrypt operation.  */
1261 gpgme_decrypt_result_t gpgme_op_decrypt_result (gpgme_ctx_t ctx);
1262
1263 /* Decrypt ciphertext CIPHER within CTX and store the resulting
1264    plaintext in PLAIN.  */
1265 gpgme_error_t gpgme_op_decrypt_start (gpgme_ctx_t ctx, gpgme_data_t cipher,
1266                                       gpgme_data_t plain);
1267 gpgme_error_t gpgme_op_decrypt (gpgme_ctx_t ctx,
1268                                 gpgme_data_t cipher, gpgme_data_t plain);
1269
1270 /* Decrypt ciphertext CIPHER and make a signature verification within
1271    CTX and store the resulting plaintext in PLAIN.  */
1272 gpgme_error_t gpgme_op_decrypt_verify_start (gpgme_ctx_t ctx,
1273                                              gpgme_data_t cipher,
1274                                              gpgme_data_t plain);
1275 gpgme_error_t gpgme_op_decrypt_verify (gpgme_ctx_t ctx, gpgme_data_t cipher,
1276                                        gpgme_data_t plain);
1277
1278 \f
1279 /* Signing.  */
1280 struct _gpgme_new_signature
1281 {
1282   struct _gpgme_new_signature *next;
1283
1284   /* The type of the signature.  */
1285   gpgme_sig_mode_t type;
1286
1287   /* The public key algorithm used to create the signature.  */
1288   gpgme_pubkey_algo_t pubkey_algo;
1289
1290   /* The hash algorithm used to create the signature.  */
1291   gpgme_hash_algo_t hash_algo;
1292
1293   /* Internal to GPGME, do not use.  Must be set to the same value as
1294      CLASS below.  */
1295   unsigned long _obsolete_class;
1296
1297   /* Signature creation time.  */
1298   long int timestamp;
1299
1300   /* The fingerprint of the signature.  */
1301   char *fpr;
1302
1303 #ifdef __cplusplus
1304   unsigned int _obsolete_class_2;
1305 #else
1306   /* Must be set to SIG_CLASS below.  */
1307   unsigned int class _GPGME_DEPRECATED_OUTSIDE_GPGME;
1308 #endif
1309
1310   /* Crypto backend specific signature class.  */
1311   unsigned int sig_class;
1312 };
1313 typedef struct _gpgme_new_signature *gpgme_new_signature_t;
1314
1315 struct _gpgme_op_sign_result
1316 {
1317   /* The list of invalid signers.  */
1318   gpgme_invalid_key_t invalid_signers;
1319   gpgme_new_signature_t signatures;
1320 };
1321 typedef struct _gpgme_op_sign_result *gpgme_sign_result_t;
1322
1323 /* Retrieve a pointer to the result of the signing operation.  */
1324 gpgme_sign_result_t gpgme_op_sign_result (gpgme_ctx_t ctx);
1325
1326 /* Sign the plaintext PLAIN and store the signature in SIG.  */
1327 gpgme_error_t gpgme_op_sign_start (gpgme_ctx_t ctx,
1328                                    gpgme_data_t plain, gpgme_data_t sig,
1329                                    gpgme_sig_mode_t mode);
1330 gpgme_error_t gpgme_op_sign (gpgme_ctx_t ctx,
1331                              gpgme_data_t plain, gpgme_data_t sig,
1332                              gpgme_sig_mode_t mode);
1333
1334 \f
1335 /* Verify.  */
1336
1337 /* Flags used for the SUMMARY field in a gpgme_signature_t.  */
1338 typedef enum
1339   {
1340     GPGME_SIGSUM_VALID       = 0x0001,  /* The signature is fully valid.  */
1341     GPGME_SIGSUM_GREEN       = 0x0002,  /* The signature is good.  */
1342     GPGME_SIGSUM_RED         = 0x0004,  /* The signature is bad.  */
1343     GPGME_SIGSUM_KEY_REVOKED = 0x0010,  /* One key has been revoked.  */
1344     GPGME_SIGSUM_KEY_EXPIRED = 0x0020,  /* One key has expired.  */
1345     GPGME_SIGSUM_SIG_EXPIRED = 0x0040,  /* The signature has expired.  */
1346     GPGME_SIGSUM_KEY_MISSING = 0x0080,  /* Can't verify: key missing.  */
1347     GPGME_SIGSUM_CRL_MISSING = 0x0100,  /* CRL not available.  */
1348     GPGME_SIGSUM_CRL_TOO_OLD = 0x0200,  /* Available CRL is too old.  */
1349     GPGME_SIGSUM_BAD_POLICY  = 0x0400,  /* A policy was not met.  */
1350     GPGME_SIGSUM_SYS_ERROR   = 0x0800   /* A system error occured.  */
1351   }
1352 gpgme_sigsum_t;
1353
1354 struct _gpgme_signature
1355 {
1356   struct _gpgme_signature *next;
1357
1358   /* A summary of the signature status.  */
1359   gpgme_sigsum_t summary;
1360
1361   /* The fingerprint or key ID of the signature.  */
1362   char *fpr;
1363
1364   /* The status of the signature.  */
1365   gpgme_error_t status;
1366
1367   /* Notation data and policy URLs.  */
1368   gpgme_sig_notation_t notations;
1369
1370   /* Signature creation time.  */
1371   unsigned long timestamp;
1372
1373   /* Signature exipration time or 0.  */
1374   unsigned long exp_timestamp;
1375
1376   /* Key should not have been used for signing.  */
1377   unsigned int wrong_key_usage : 1;
1378
1379   /* PKA status: 0 = not available, 1 = bad, 2 = okay, 3 = RFU. */
1380   unsigned int pka_trust : 2;
1381
1382   /* Validity has been verified using the chain model. */
1383   unsigned int chain_model : 1;
1384
1385   /* Internal to GPGME, do not use.  */
1386   int _unused : 28;
1387
1388   gpgme_validity_t validity;
1389   gpgme_error_t validity_reason;
1390
1391   /* The public key algorithm used to create the signature.  */
1392   gpgme_pubkey_algo_t pubkey_algo;
1393
1394   /* The hash algorithm used to create the signature.  */
1395   gpgme_hash_algo_t hash_algo;
1396
1397   /* The mailbox from the PKA information or NULL. */
1398   char *pka_address;
1399 };
1400 typedef struct _gpgme_signature *gpgme_signature_t;
1401
1402 struct _gpgme_op_verify_result
1403 {
1404   gpgme_signature_t signatures;
1405
1406   /* The original file name of the plaintext message, if
1407      available.  */
1408   char *file_name;
1409 };
1410 typedef struct _gpgme_op_verify_result *gpgme_verify_result_t;
1411
1412 /* Retrieve a pointer to the result of the verify operation.  */
1413 gpgme_verify_result_t gpgme_op_verify_result (gpgme_ctx_t ctx);
1414
1415 /* Verify within CTX that SIG is a valid signature for TEXT.  */
1416 gpgme_error_t gpgme_op_verify_start (gpgme_ctx_t ctx, gpgme_data_t sig,
1417                                      gpgme_data_t signed_text,
1418                                      gpgme_data_t plaintext);
1419 gpgme_error_t gpgme_op_verify (gpgme_ctx_t ctx, gpgme_data_t sig,
1420                                gpgme_data_t signed_text,
1421                                gpgme_data_t plaintext);
1422
1423 \f
1424 /* Import.  */
1425
1426 /* The key was new.  */
1427 #define GPGME_IMPORT_NEW        1
1428
1429 /* The key contained new user IDs.  */
1430 #define GPGME_IMPORT_UID        2
1431
1432 /* The key contained new signatures.  */
1433 #define GPGME_IMPORT_SIG        4
1434
1435 /* The key contained new sub keys.  */
1436 #define GPGME_IMPORT_SUBKEY     8
1437
1438 /* The key contained a secret key.  */
1439 #define GPGME_IMPORT_SECRET     16
1440
1441
1442 struct _gpgme_import_status
1443 {
1444   struct _gpgme_import_status *next;
1445
1446   /* Fingerprint.  */
1447   char *fpr;
1448
1449   /* If a problem occured, the reason why the key could not be
1450      imported.  Otherwise GPGME_No_Error.  */
1451   gpgme_error_t result;
1452
1453   /* The result of the import, the GPGME_IMPORT_* values bit-wise
1454      ORed.  0 means the key was already known and no new components
1455      have been added.  */
1456   unsigned int status;
1457 };
1458 typedef struct _gpgme_import_status *gpgme_import_status_t;
1459
1460 /* Import.  */
1461 struct _gpgme_op_import_result
1462 {
1463   /* Number of considered keys.  */
1464   int considered;
1465
1466   /* Keys without user ID.  */
1467   int no_user_id;
1468
1469   /* Imported keys.  */
1470   int imported;
1471
1472   /* Imported RSA keys.  */
1473   int imported_rsa;
1474
1475   /* Unchanged keys.  */
1476   int unchanged;
1477
1478   /* Number of new user ids.  */
1479   int new_user_ids;
1480
1481   /* Number of new sub keys.  */
1482   int new_sub_keys;
1483
1484   /* Number of new signatures.  */
1485   int new_signatures;
1486
1487   /* Number of new revocations.  */
1488   int new_revocations;
1489
1490   /* Number of secret keys read.  */
1491   int secret_read;
1492
1493   /* Number of secret keys imported.  */
1494   int secret_imported;
1495
1496   /* Number of secret keys unchanged.  */
1497   int secret_unchanged;
1498
1499   /* Number of new keys skipped.  */
1500   int skipped_new_keys;
1501
1502   /* Number of keys not imported.  */
1503   int not_imported;
1504
1505   /* List of keys for which an import was attempted.  */
1506   gpgme_import_status_t imports;
1507 };
1508 typedef struct _gpgme_op_import_result *gpgme_import_result_t;
1509
1510 /* Retrieve a pointer to the result of the import operation.  */
1511 gpgme_import_result_t gpgme_op_import_result (gpgme_ctx_t ctx);
1512
1513 /* Import the key in KEYDATA into the keyring.  */
1514 gpgme_error_t gpgme_op_import_start (gpgme_ctx_t ctx, gpgme_data_t keydata);
1515 gpgme_error_t gpgme_op_import (gpgme_ctx_t ctx, gpgme_data_t keydata);
1516 gpgme_error_t gpgme_op_import_ext (gpgme_ctx_t ctx, gpgme_data_t keydata,
1517                                    int *nr) _GPGME_DEPRECATED;
1518
1519 /* Import the keys from the array KEYS into the keyring.  */
1520 gpgme_error_t gpgme_op_import_keys_start (gpgme_ctx_t ctx, gpgme_key_t keys[]);
1521 gpgme_error_t gpgme_op_import_keys (gpgme_ctx_t ctx, gpgme_key_t keys[]);
1522
1523
1524 \f
1525 /* Export the keys found by PATTERN into KEYDATA.  */
1526 gpgme_error_t gpgme_op_export_start (gpgme_ctx_t ctx, const char *pattern,
1527                                      gpgme_export_mode_t mode,
1528                                      gpgme_data_t keydata);
1529 gpgme_error_t gpgme_op_export (gpgme_ctx_t ctx, const char *pattern,
1530                                gpgme_export_mode_t mode,
1531                                gpgme_data_t keydata);
1532
1533 gpgme_error_t gpgme_op_export_ext_start (gpgme_ctx_t ctx,
1534                                          const char *pattern[],
1535                                          gpgme_export_mode_t mode,
1536                                          gpgme_data_t keydata);
1537 gpgme_error_t gpgme_op_export_ext (gpgme_ctx_t ctx, const char *pattern[],
1538                                    gpgme_export_mode_t mode,
1539                                    gpgme_data_t keydata);
1540
1541 /* Export the keys from the array KEYS into KEYDATA.  */
1542 gpgme_error_t gpgme_op_export_keys_start (gpgme_ctx_t ctx,
1543                                           gpgme_key_t keys[],
1544                                           gpgme_export_mode_t mode,
1545                                           gpgme_data_t keydata);
1546 gpgme_error_t gpgme_op_export_keys (gpgme_ctx_t ctx,
1547                                     gpgme_key_t keys[],
1548                                     gpgme_export_mode_t mode,
1549                                     gpgme_data_t keydata);
1550
1551
1552 \f
1553 /* Key generation.  */
1554 struct _gpgme_op_genkey_result
1555 {
1556   /* A primary key was generated.  */
1557   unsigned int primary : 1;
1558
1559   /* A sub key was generated.  */
1560   unsigned int sub : 1;
1561
1562   /* Internal to GPGME, do not use.  */
1563   unsigned int _unused : 30;
1564
1565   /* The fingerprint of the generated key.  */
1566   char *fpr;
1567 };
1568 typedef struct _gpgme_op_genkey_result *gpgme_genkey_result_t;
1569
1570 /* Generate a new keypair and add it to the keyring.  PUBKEY and
1571    SECKEY should be null for now.  PARMS specifies what keys should be
1572    generated.  */
1573 gpgme_error_t gpgme_op_genkey_start (gpgme_ctx_t ctx, const char *parms,
1574                                      gpgme_data_t pubkey, gpgme_data_t seckey);
1575 gpgme_error_t gpgme_op_genkey (gpgme_ctx_t ctx, const char *parms,
1576                                gpgme_data_t pubkey, gpgme_data_t seckey);
1577
1578 /* Retrieve a pointer to the result of the genkey operation.  */
1579 gpgme_genkey_result_t gpgme_op_genkey_result (gpgme_ctx_t ctx);
1580
1581 \f
1582 /* Delete KEY from the keyring.  If ALLOW_SECRET is non-zero, secret
1583    keys are also deleted.  */
1584 gpgme_error_t gpgme_op_delete_start (gpgme_ctx_t ctx, const gpgme_key_t key,
1585                                      int allow_secret);
1586 gpgme_error_t gpgme_op_delete (gpgme_ctx_t ctx, const gpgme_key_t key,
1587                                int allow_secret);
1588
1589 \f
1590 /* Edit the key KEY.  Send status and command requests to FNC and
1591    output of edit commands to OUT.  */
1592 gpgme_error_t gpgme_op_edit_start (gpgme_ctx_t ctx, gpgme_key_t key,
1593                                    gpgme_edit_cb_t fnc, void *fnc_value,
1594                                    gpgme_data_t out);
1595 gpgme_error_t gpgme_op_edit (gpgme_ctx_t ctx, gpgme_key_t key,
1596                              gpgme_edit_cb_t fnc, void *fnc_value,
1597                              gpgme_data_t out);
1598
1599 /* Edit the card for the key KEY.  Send status and command requests to
1600    FNC and output of edit commands to OUT.  */
1601 gpgme_error_t gpgme_op_card_edit_start (gpgme_ctx_t ctx, gpgme_key_t key,
1602                                         gpgme_edit_cb_t fnc, void *fnc_value,
1603                                         gpgme_data_t out);
1604 gpgme_error_t gpgme_op_card_edit (gpgme_ctx_t ctx, gpgme_key_t key,
1605                                   gpgme_edit_cb_t fnc, void *fnc_value,
1606                                   gpgme_data_t out);
1607
1608 \f
1609 /* Key management functions.  */
1610 struct _gpgme_op_keylist_result
1611 {
1612   unsigned int truncated : 1;
1613
1614   /* Internal to GPGME, do not use.  */
1615   unsigned int _unused : 31;
1616 };
1617 typedef struct _gpgme_op_keylist_result *gpgme_keylist_result_t;
1618
1619 /* Retrieve a pointer to the result of the key listing operation.  */
1620 gpgme_keylist_result_t gpgme_op_keylist_result (gpgme_ctx_t ctx);
1621
1622 /* Start a keylist operation within CTX, searching for keys which
1623    match PATTERN.  If SECRET_ONLY is true, only secret keys are
1624    returned.  */
1625 gpgme_error_t gpgme_op_keylist_start (gpgme_ctx_t ctx, const char *pattern,
1626                                       int secret_only);
1627 gpgme_error_t gpgme_op_keylist_ext_start (gpgme_ctx_t ctx,
1628                                           const char *pattern[],
1629                                           int secret_only, int reserved);
1630
1631 /* Return the next key from the keylist in R_KEY.  */
1632 gpgme_error_t gpgme_op_keylist_next (gpgme_ctx_t ctx, gpgme_key_t *r_key);
1633
1634 /* Terminate a pending keylist operation within CTX.  */
1635 gpgme_error_t gpgme_op_keylist_end (gpgme_ctx_t ctx);
1636
1637 \f
1638 /* Trust items and operations.  */
1639
1640 struct _gpgme_trust_item
1641 {
1642   /* Internal to GPGME, do not use.  */
1643   unsigned int _refs;
1644
1645   /* The key ID to which the trust item belongs.  */
1646   char *keyid;
1647
1648   /* Internal to GPGME, do not use.  */
1649   char _keyid[16 + 1];
1650
1651   /* The type of the trust item, 1 refers to a key, 2 to a user ID.  */
1652   int type;
1653
1654   /* The trust level.  */
1655   int level;
1656
1657   /* The owner trust if TYPE is 1.  */
1658   char *owner_trust;
1659
1660   /* Internal to GPGME, do not use.  */
1661   char _owner_trust[2];
1662
1663   /* The calculated validity.  */
1664   char *validity;
1665  
1666   /* Internal to GPGME, do not use.  */
1667   char _validity[2];
1668
1669   /* The user name if TYPE is 2.  */
1670   char *name;
1671 };
1672 typedef struct _gpgme_trust_item *gpgme_trust_item_t;
1673
1674 /* Start a trustlist operation within CTX, searching for trust items
1675    which match PATTERN.  */
1676 gpgme_error_t gpgme_op_trustlist_start (gpgme_ctx_t ctx,
1677                                         const char *pattern, int max_level);
1678
1679 /* Return the next trust item from the trustlist in R_ITEM.  */
1680 gpgme_error_t gpgme_op_trustlist_next (gpgme_ctx_t ctx,
1681                                        gpgme_trust_item_t *r_item);
1682
1683 /* Terminate a pending trustlist operation within CTX.  */
1684 gpgme_error_t gpgme_op_trustlist_end (gpgme_ctx_t ctx);
1685
1686 /* Acquire a reference to ITEM.  */
1687 void gpgme_trust_item_ref (gpgme_trust_item_t item);
1688
1689 /* Release a reference to ITEM.  If this was the last one the trust
1690    item is destroyed.  */
1691 void gpgme_trust_item_unref (gpgme_trust_item_t item);
1692
1693 /* Release the trust item ITEM.  Deprecated, use
1694    gpgme_trust_item_unref.  */
1695 void gpgme_trust_item_release (gpgme_trust_item_t item) _GPGME_DEPRECATED;
1696
1697 /* Return the value of the attribute WHAT of ITEM, which has to be
1698    representable by a string.  Deprecated, use trust item structure
1699    directly.  */
1700 const char *gpgme_trust_item_get_string_attr (gpgme_trust_item_t item,
1701                                               _gpgme_attr_t what,
1702                                               const void *reserved, int idx)
1703      _GPGME_DEPRECATED;
1704
1705 /* Return the value of the attribute WHAT of KEY, which has to be
1706    representable by an integer.  IDX specifies a running index if the
1707    attribute appears more than once in the key.  Deprecated, use trust
1708    item structure directly.  */
1709 int gpgme_trust_item_get_int_attr (gpgme_trust_item_t item, _gpgme_attr_t what,
1710                                    const void *reserved, int idx)
1711      _GPGME_DEPRECATED;
1712
1713 \f
1714 /* Return the auditlog for the current session.  This may be called
1715    after a successful or failed operation.  If no audit log is
1716    available GPG_ERR_NO_DATA is returned.  */
1717 gpgme_error_t gpgme_op_getauditlog_start (gpgme_ctx_t ctx, gpgme_data_t output,
1718                                           unsigned int flags);
1719 gpgme_error_t gpgme_op_getauditlog (gpgme_ctx_t ctx, gpgme_data_t output, 
1720                                     unsigned int flags);
1721
1722
1723 \f
1724 /* Low-level Assuan protocol access.  */
1725 typedef gpgme_error_t (*gpgme_assuan_data_cb_t) 
1726      (void *opaque, const void *data, size_t datalen);
1727
1728 typedef gpgme_error_t (*gpgme_assuan_inquire_cb_t)
1729      (void *opaque, const char *name, const char *args,
1730       gpgme_data_t *r_data);
1731
1732 typedef gpgme_error_t (*gpgme_assuan_status_cb_t)
1733      (void *opaque, const char *status, const char *args);
1734
1735 struct _gpgme_op_assuan_result
1736 {
1737   /* The result of the actual assuan command.  An OK is indicated by a
1738      value of 0 and an ERR by the respective error error value.  */
1739   gpgme_error_t err;
1740 };
1741 typedef struct _gpgme_op_assuan_result *gpgme_assuan_result_t;
1742
1743
1744 /* Return the result of the last Assuan command. */
1745 gpgme_assuan_result_t gpgme_op_assuan_result (gpgme_ctx_t ctx);
1746
1747 /* Send the Assuan COMMAND and return results via the callbacks.
1748    Asynchronous variant. */
1749 gpgme_error_t gpgme_op_assuan_transact_start (gpgme_ctx_t ctx, 
1750                                               const char *command,
1751                                               gpgme_assuan_data_cb_t data_cb,
1752                                               void *data_cb_value,
1753                                               gpgme_assuan_inquire_cb_t inq_cb,
1754                                               void *inq_cb_value,
1755                                               gpgme_assuan_status_cb_t stat_cb,
1756                                               void *stat_cb_value);
1757
1758 /* Send the Assuan COMMAND and return results via the callbacks.
1759    Synchronous variant. */
1760 gpgme_error_t gpgme_op_assuan_transact (gpgme_ctx_t ctx, 
1761                                         const char *command,
1762                                         gpgme_assuan_data_cb_t data_cb,
1763                                         void *data_cb_value,
1764                                         gpgme_assuan_inquire_cb_t inq_cb,
1765                                         void *inq_cb_value,
1766                                         gpgme_assuan_status_cb_t stat_cb,
1767                                         void *stat_cb_value);
1768
1769
1770 \f
1771 /* Interface to gpgconf(1).  */
1772
1773 /* The expert level at which a configuration option or group of
1774    options should be displayed.  See the gpgconf(1) documentation for
1775    more details.  */
1776 typedef enum
1777   {
1778     GPGME_CONF_BASIC = 0,
1779     GPGME_CONF_ADVANCED = 1,
1780     GPGME_CONF_EXPERT = 2,
1781     GPGME_CONF_INVISIBLE = 3,
1782     GPGME_CONF_INTERNAL = 4
1783   }
1784 gpgme_conf_level_t;
1785
1786
1787 /* The data type of a configuration option argument.  See the gpgconf(1)
1788    documentation for more details.  */
1789 typedef enum
1790   {
1791     /* Basic types.  */
1792     GPGME_CONF_NONE = 0,
1793     GPGME_CONF_STRING = 1,
1794     GPGME_CONF_INT32 = 2,
1795     GPGME_CONF_UINT32 = 3,
1796
1797     /* Complex types.  */
1798     GPGME_CONF_FILENAME = 32,
1799     GPGME_CONF_LDAP_SERVER = 33,
1800     GPGME_CONF_KEY_FPR = 34,
1801     GPGME_CONF_PUB_KEY = 35,
1802     GPGME_CONF_SEC_KEY = 36,
1803     GPGME_CONF_ALIAS_LIST = 37
1804   }
1805 gpgme_conf_type_t;
1806
1807 /* For now, compatibility.  */
1808 #define GPGME_CONF_PATHNAME GPGME_CONF_FILENAME
1809
1810
1811 /* This represents a single argument for a configuration option.
1812    Which of the members of value is used depends on the ALT_TYPE.  */
1813 typedef struct gpgme_conf_arg
1814 {
1815   struct gpgme_conf_arg *next;
1816   /* True if the option appears without an (optional) argument.  */
1817   unsigned int no_arg;
1818   union
1819   {
1820     unsigned int count;
1821     unsigned int uint32;
1822     int int32;
1823     char *string;
1824   } value;
1825 } *gpgme_conf_arg_t;
1826
1827
1828 /* The flags of a configuration option.  See the gpg-conf
1829    documentation for details.  */
1830 #define GPGME_CONF_GROUP        (1 << 0)
1831 #define GPGME_CONF_OPTIONAL     (1 << 1)
1832 #define GPGME_CONF_LIST         (1 << 2)
1833 #define GPGME_CONF_RUNTIME      (1 << 3)
1834 #define GPGME_CONF_DEFAULT      (1 << 4)
1835 #define GPGME_CONF_DEFAULT_DESC (1 << 5)
1836 #define GPGME_CONF_NO_ARG_DESC  (1 << 6)
1837 #define GPGME_CONF_NO_CHANGE    (1 << 7)
1838
1839
1840 /* The representation of a single configuration option.  See the
1841    gpg-conf documentation for details.  */
1842 typedef struct gpgme_conf_opt
1843 {
1844   struct gpgme_conf_opt *next;
1845   
1846   /* The option name.  */
1847   char *name;
1848
1849   /* The flags for this option.  */
1850   unsigned int flags;
1851
1852   /* The level of this option.  */
1853   gpgme_conf_level_t level;
1854
1855   /* The localized description of this option.  */
1856   char *description;
1857
1858   /* The type and alternate type of this option.  */
1859   gpgme_conf_type_t type;
1860   gpgme_conf_type_t alt_type;
1861
1862   /* The localized (short) name of the argument, if any.  */
1863   char *argname;
1864
1865   /* The default value.  */
1866   gpgme_conf_arg_t default_value;
1867   char *default_description;
1868   
1869   /* The default value if the option is not set.  */
1870   gpgme_conf_arg_t no_arg_value;
1871   char *no_arg_description;
1872
1873   /* The current value if the option is set.  */
1874   gpgme_conf_arg_t value;
1875
1876   /* The new value, if any.  NULL means reset to default.  */
1877   int change_value;
1878   gpgme_conf_arg_t new_value;
1879
1880   /* Free for application use.  */
1881   void *user_data;
1882 } *gpgme_conf_opt_t;
1883
1884
1885 /* The representation of a component that can be configured.  See the
1886    gpg-conf documentation for details.  */
1887 typedef struct gpgme_conf_comp
1888 {
1889   struct gpgme_conf_comp *next;
1890
1891   /* Internal to GPGME, do not use!  */
1892   gpgme_conf_opt_t *_last_opt_p;
1893
1894   /* The component name.  */
1895   char *name;
1896
1897   /* A human-readable description for the component.  */
1898   char *description;
1899
1900   /* The program name (an absolute path to the program).  */
1901   char *program_name;  
1902
1903   /* A linked list of options for this component.  */
1904   struct gpgme_conf_opt *options;
1905 } *gpgme_conf_comp_t;
1906
1907
1908 /* Allocate a new gpgme_conf_arg_t.  If VALUE is NULL, a "no arg
1909    default" is prepared.  If type is a string type, VALUE should point
1910    to the string.  Else, it should point to an unsigned or signed
1911    integer respectively.  */
1912 gpgme_error_t gpgme_conf_arg_new (gpgme_conf_arg_t *arg_p,
1913                                   gpgme_conf_type_t type, void *value);
1914
1915 /* This also releases all chained argument structures!  */
1916 void gpgme_conf_arg_release (gpgme_conf_arg_t arg, gpgme_conf_type_t type);
1917
1918 /* Register a change for the value of OPT to ARG.  If RESET is 1 (do
1919    not use any values but 0 or 1), ARG is ignored and the option is
1920    not changed (reverting a previous change).  Otherwise, if ARG is
1921    NULL, the option is cleared or reset to its default.  */
1922 gpgme_error_t gpgme_conf_opt_change (gpgme_conf_opt_t opt, int reset,
1923                                      gpgme_conf_arg_t arg);
1924
1925 /* Release a set of configurations.  */
1926 void gpgme_conf_release (gpgme_conf_comp_t conf);
1927  
1928 /* Retrieve the current configurations.  */
1929 gpgme_error_t gpgme_op_conf_load (gpgme_ctx_t ctx, gpgme_conf_comp_t *conf_p);
1930
1931 /* Save the configuration of component comp.  This function does not
1932    follow chained components!  */
1933 gpgme_error_t gpgme_op_conf_save (gpgme_ctx_t ctx, gpgme_conf_comp_t comp);
1934
1935 \f
1936 /* Various functions.  */
1937
1938 /* Check that the library fulfills the version requirement.  Note:
1939    This is here only for the case where a user takes a pointer from
1940    the old version of this function.  The new version and macro for
1941    run-time checks are below.  */
1942 const char *gpgme_check_version (const char *req_version);
1943
1944 /* Check that the library fulfills the version requirement and check
1945    for struct layout mismatch involving bitfields.  */
1946 const char *gpgme_check_version_internal (const char *req_version,
1947                                           size_t offset_sig_validity);
1948
1949 #define gpgme_check_version(req_version)                                \
1950   gpgme_check_version_internal (req_version,                            \
1951                                 offsetof (struct _gpgme_signature, validity))
1952
1953 /* Get the information about the configured and installed engines.  A
1954    pointer to the first engine in the statically allocated linked list
1955    is returned in *INFO.  If an error occurs, it is returned.  The
1956    returned data is valid until the next gpgme_set_engine_info.  */
1957 gpgme_error_t gpgme_get_engine_info (gpgme_engine_info_t *engine_info);
1958
1959 /* Set the default engine info for the protocol PROTO to the file name
1960    FILE_NAME and the home directory HOME_DIR.  */
1961 gpgme_error_t gpgme_set_engine_info (gpgme_protocol_t proto,
1962                                      const char *file_name,
1963                                      const char *home_dir);
1964
1965 \f
1966 /* Engine support functions.  */
1967
1968 /* Verify that the engine implementing PROTO is installed and
1969    available.  */
1970 gpgme_error_t gpgme_engine_check_version (gpgme_protocol_t proto);
1971
1972 \f
1973 void gpgme_result_ref (void *result);
1974 void gpgme_result_unref (void *result);
1975
1976 \f
1977 /* Deprecated types.  */
1978 typedef gpgme_ctx_t GpgmeCtx _GPGME_DEPRECATED;
1979 typedef gpgme_data_t GpgmeData _GPGME_DEPRECATED;
1980 typedef gpgme_error_t GpgmeError _GPGME_DEPRECATED;
1981 typedef gpgme_data_encoding_t GpgmeDataEncoding _GPGME_DEPRECATED;
1982 typedef gpgme_pubkey_algo_t GpgmePubKeyAlgo _GPGME_DEPRECATED;
1983 typedef gpgme_hash_algo_t GpgmeHashAlgo _GPGME_DEPRECATED;
1984 typedef gpgme_sig_stat_t GpgmeSigStat _GPGME_DEPRECATED;
1985 typedef gpgme_sig_mode_t GpgmeSigMode _GPGME_DEPRECATED;
1986 typedef gpgme_attr_t GpgmeAttr _GPGME_DEPRECATED;
1987 typedef gpgme_validity_t GpgmeValidity _GPGME_DEPRECATED;
1988 typedef gpgme_protocol_t GpgmeProtocol _GPGME_DEPRECATED;
1989 typedef gpgme_engine_info_t GpgmeEngineInfo _GPGME_DEPRECATED;
1990 typedef gpgme_subkey_t GpgmeSubkey _GPGME_DEPRECATED;
1991 typedef gpgme_key_sig_t GpgmeKeySig _GPGME_DEPRECATED;
1992 typedef gpgme_user_id_t GpgmeUserID _GPGME_DEPRECATED;
1993 typedef gpgme_key_t GpgmeKey _GPGME_DEPRECATED;
1994 typedef gpgme_passphrase_cb_t GpgmePassphraseCb _GPGME_DEPRECATED;
1995 typedef gpgme_progress_cb_t GpgmeProgressCb _GPGME_DEPRECATED;
1996 typedef gpgme_io_cb_t GpgmeIOCb _GPGME_DEPRECATED;
1997 typedef gpgme_register_io_cb_t GpgmeRegisterIOCb _GPGME_DEPRECATED;
1998 typedef gpgme_remove_io_cb_t GpgmeRemoveIOCb _GPGME_DEPRECATED;
1999 typedef gpgme_event_io_t GpgmeEventIO _GPGME_DEPRECATED;
2000 typedef gpgme_event_io_cb_t GpgmeEventIOCb _GPGME_DEPRECATED;
2001 #define GpgmeIOCbs gpgme_io_cbs
2002 typedef gpgme_data_read_cb_t GpgmeDataReadCb _GPGME_DEPRECATED;
2003 typedef gpgme_data_write_cb_t GpgmeDataWriteCb _GPGME_DEPRECATED;
2004 typedef gpgme_data_seek_cb_t GpgmeDataSeekCb _GPGME_DEPRECATED;
2005 typedef gpgme_data_release_cb_t GpgmeDataReleaseCb _GPGME_DEPRECATED;
2006 #define GpgmeDataCbs gpgme_data_cbs
2007 typedef gpgme_encrypt_result_t GpgmeEncryptResult _GPGME_DEPRECATED;
2008 typedef gpgme_sig_notation_t GpgmeSigNotation _GPGME_DEPRECATED;
2009 typedef gpgme_signature_t GpgmeSignature _GPGME_DEPRECATED;
2010 typedef gpgme_verify_result_t GpgmeVerifyResult _GPGME_DEPRECATED;
2011 typedef gpgme_import_status_t GpgmeImportStatus _GPGME_DEPRECATED;
2012 typedef gpgme_import_result_t GpgmeImportResult _GPGME_DEPRECATED;
2013 typedef gpgme_genkey_result_t GpgmeGenKeyResult _GPGME_DEPRECATED;
2014 typedef gpgme_trust_item_t GpgmeTrustItem _GPGME_DEPRECATED;
2015 typedef gpgme_status_code_t GpgmeStatusCode _GPGME_DEPRECATED;
2016
2017 #ifdef __cplusplus
2018 }
2019 #endif
2020 #endif /* GPGME_H */