2009-06-22 Marcus Brinkmann <marcus@g10code.de>
[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   }
490 gpgme_status_code_t;
491
492 \f
493 /* The engine information structure.  */
494 struct _gpgme_engine_info
495 {
496   struct _gpgme_engine_info *next;
497
498   /* The protocol ID.  */
499   gpgme_protocol_t protocol;
500
501   /* The file name of the engine binary.  */
502   char *file_name;
503   
504   /* The version string of the installed engine.  */
505   char *version;
506
507   /* The minimum version required for GPGME.  */
508   const char *req_version;
509
510   /* The home directory used, or NULL if default.  */
511   char *home_dir;
512 };
513 typedef struct _gpgme_engine_info *gpgme_engine_info_t;
514
515 \f
516 /* A subkey from a key.  */
517 struct _gpgme_subkey
518 {
519   struct _gpgme_subkey *next;
520
521   /* True if subkey is revoked.  */
522   unsigned int revoked : 1;
523
524   /* True if subkey is expired.  */
525   unsigned int expired : 1;
526
527   /* True if subkey is disabled.  */
528   unsigned int disabled : 1;
529
530   /* True if subkey is invalid.  */
531   unsigned int invalid : 1;
532
533   /* True if subkey can be used for encryption.  */
534   unsigned int can_encrypt : 1;
535
536   /* True if subkey can be used for signing.  */
537   unsigned int can_sign : 1;
538
539   /* True if subkey can be used for certification.  */
540   unsigned int can_certify : 1;
541
542   /* True if subkey is secret.  */
543   unsigned int secret : 1;
544
545   /* True if subkey can be used for authentication.  */
546   unsigned int can_authenticate : 1;
547
548   /* True if subkey is qualified for signatures according to German law.  */
549   unsigned int is_qualified : 1;
550
551   /* True if the secret key is stored on a smart card.  */
552   unsigned int is_cardkey : 1;
553
554   /* Internal to GPGME, do not use.  */
555   unsigned int _unused : 21;
556   
557   /* Public key algorithm supported by this subkey.  */
558   gpgme_pubkey_algo_t pubkey_algo;
559
560   /* Length of the subkey.  */
561   unsigned int length;
562
563   /* The key ID of the subkey.  */
564   char *keyid;
565
566   /* Internal to GPGME, do not use.  */
567   char _keyid[16 + 1];
568
569   /* The fingerprint of the subkey in hex digit form.  */
570   char *fpr;
571
572   /* The creation timestamp, -1 if invalid, 0 if not available.  */
573   long int timestamp;
574
575   /* The expiration timestamp, 0 if the subkey does not expire.  */
576   long int expires;
577
578   /* The serial number of a smart card holding this key or NULL.  */
579   char *card_number;
580 };
581 typedef struct _gpgme_subkey *gpgme_subkey_t;
582
583
584 /* A signature on a user ID.  */
585 struct _gpgme_key_sig
586 {
587   struct _gpgme_key_sig *next;
588
589   /* True if the signature is a revocation signature.  */
590   unsigned int revoked : 1;
591
592   /* True if the signature is expired.  */
593   unsigned int expired : 1;
594
595   /* True if the signature is invalid.  */
596   unsigned int invalid : 1;
597
598   /* True if the signature should be exported.  */
599   unsigned int exportable : 1;
600
601   /* Internal to GPGME, do not use.  */
602   unsigned int _unused : 28;
603
604   /* The public key algorithm used to create the signature.  */
605   gpgme_pubkey_algo_t pubkey_algo;
606
607   /* The key ID of key used to create the signature.  */
608   char *keyid;
609
610   /* Internal to GPGME, do not use.  */
611   char _keyid[16 + 1];
612
613   /* The creation timestamp, -1 if invalid, 0 if not available.  */
614   long int timestamp;
615
616   /* The expiration timestamp, 0 if the subkey does not expire.  */
617   long int expires;
618
619   /* Same as in gpgme_signature_t.  */
620   gpgme_error_t status;
621
622 #ifdef __cplusplus
623   unsigned int _obsolete_class _GPGME_DEPRECATED;
624 #else
625   /* Must be set to SIG_CLASS below.  */
626   unsigned int class _GPGME_DEPRECATED_OUTSIDE_GPGME;
627 #endif
628
629   /* The user ID string.  */
630   char *uid;
631
632   /* The name part of the user ID.  */
633   char *name;
634
635   /* The email part of the user ID.  */
636   char *email;
637
638   /* The comment part of the user ID.  */
639   char *comment;
640
641   /* Crypto backend specific signature class.  */
642   unsigned int sig_class;
643
644   /* Notation data and policy URLs.  */
645   gpgme_sig_notation_t notations;
646
647   /* Internal to GPGME, do not use.  */
648   gpgme_sig_notation_t _last_notation;
649 };
650 typedef struct _gpgme_key_sig *gpgme_key_sig_t;
651
652
653 /* An user ID from a key.  */
654 struct _gpgme_user_id
655 {
656   struct _gpgme_user_id *next;
657
658   /* True if the user ID is revoked.  */
659   unsigned int revoked : 1;
660
661   /* True if the user ID is invalid.  */
662   unsigned int invalid : 1;
663
664   /* Internal to GPGME, do not use.  */
665   unsigned int _unused : 30;
666
667   /* The validity of the user ID.  */
668   gpgme_validity_t validity; 
669
670   /* The user ID string.  */
671   char *uid;
672
673   /* The name part of the user ID.  */
674   char *name;
675
676   /* The email part of the user ID.  */
677   char *email;
678
679   /* The comment part of the user ID.  */
680   char *comment;
681
682   /* The signatures of the user ID.  */
683   gpgme_key_sig_t signatures;
684
685   /* Internal to GPGME, do not use.  */
686   gpgme_key_sig_t _last_keysig;
687 };
688 typedef struct _gpgme_user_id *gpgme_user_id_t;
689
690
691 /* A key from the keyring.  */
692 struct _gpgme_key
693 {
694   /* Internal to GPGME, do not use.  */
695   unsigned int _refs;
696
697   /* True if key is revoked.  */
698   unsigned int revoked : 1;
699
700   /* True if key is expired.  */
701   unsigned int expired : 1;
702
703   /* True if key is disabled.  */
704   unsigned int disabled : 1;
705
706   /* True if key is invalid.  */
707   unsigned int invalid : 1;
708
709   /* True if key can be used for encryption.  */
710   unsigned int can_encrypt : 1;
711
712   /* True if key can be used for signing.  */
713   unsigned int can_sign : 1;
714
715   /* True if key can be used for certification.  */
716   unsigned int can_certify : 1;
717
718   /* True if key is secret.  */
719   unsigned int secret : 1;
720
721   /* True if key can be used for authentication.  */
722   unsigned int can_authenticate : 1;
723
724   /* True if subkey is qualified for signatures according to German law.  */
725   unsigned int is_qualified : 1;
726
727   /* Internal to GPGME, do not use.  */
728   unsigned int _unused : 22;
729
730   /* This is the protocol supported by this key.  */
731   gpgme_protocol_t protocol;
732
733   /* If protocol is GPGME_PROTOCOL_CMS, this string contains the
734      issuer serial.  */
735   char *issuer_serial;
736
737   /* If protocol is GPGME_PROTOCOL_CMS, this string contains the
738      issuer name.  */
739   char *issuer_name;
740
741   /* If protocol is GPGME_PROTOCOL_CMS, this string contains the chain
742      ID.  */
743   char *chain_id;
744
745   /* If protocol is GPGME_PROTOCOL_OpenPGP, this field contains the
746      owner trust.  */
747   gpgme_validity_t owner_trust;
748
749   /* The subkeys of the key.  */
750   gpgme_subkey_t subkeys;
751
752   /* The user IDs of the key.  */
753   gpgme_user_id_t uids;
754
755   /* Internal to GPGME, do not use.  */
756   gpgme_subkey_t _last_subkey;
757
758   /* Internal to GPGME, do not use.  */
759   gpgme_user_id_t _last_uid;
760
761   /* The keylist mode that was active when listing the key.  */
762   gpgme_keylist_mode_t keylist_mode;
763 };
764 typedef struct _gpgme_key *gpgme_key_t;
765
766
767 \f
768 /* Types for callback functions.  */
769
770 /* Request a passphrase from the user.  */
771 typedef gpgme_error_t (*gpgme_passphrase_cb_t) (void *hook,
772                                                 const char *uid_hint,
773                                                 const char *passphrase_info,
774                                                 int prev_was_bad, int fd);
775
776 /* Inform the user about progress made.  */
777 typedef void (*gpgme_progress_cb_t) (void *opaque, const char *what,
778                                      int type, int current, int total);
779
780 /* Interact with the user about an edit operation.  */
781 typedef gpgme_error_t (*gpgme_edit_cb_t) (void *opaque,
782                                           gpgme_status_code_t status,
783                                           const char *args, int fd);
784
785
786
787 \f
788 /* Context management functions.  */
789
790 /* Create a new context and return it in CTX.  */
791 gpgme_error_t gpgme_new (gpgme_ctx_t *ctx);
792
793 /* Release the context CTX.  */
794 void gpgme_release (gpgme_ctx_t ctx);
795
796 /* Set the protocol to be used by CTX to PROTO.  */
797 gpgme_error_t gpgme_set_protocol (gpgme_ctx_t ctx, gpgme_protocol_t proto);
798
799 /* Get the protocol used with CTX */
800 gpgme_protocol_t gpgme_get_protocol (gpgme_ctx_t ctx);
801
802 /* Get the string describing protocol PROTO, or NULL if invalid.  */
803 const char *gpgme_get_protocol_name (gpgme_protocol_t proto);
804
805 /* If YES is non-zero, enable armor mode in CTX, disable it otherwise.  */
806 void gpgme_set_armor (gpgme_ctx_t ctx, int yes);
807
808 /* Return non-zero if armor mode is set in CTX.  */
809 int gpgme_get_armor (gpgme_ctx_t ctx);
810
811 /* If YES is non-zero, enable text mode in CTX, disable it otherwise.  */
812 void gpgme_set_textmode (gpgme_ctx_t ctx, int yes);
813
814 /* Return non-zero if text mode is set in CTX.  */
815 int gpgme_get_textmode (gpgme_ctx_t ctx);
816
817 /* Use whatever the default of the backend crypto engine is.  */
818 #define GPGME_INCLUDE_CERTS_DEFAULT     -256
819
820 /* Include up to NR_OF_CERTS certificates in an S/MIME message.  */
821 void gpgme_set_include_certs (gpgme_ctx_t ctx, int nr_of_certs);
822
823 /* Return the number of certs to include in an S/MIME message.  */
824 int gpgme_get_include_certs (gpgme_ctx_t ctx);
825
826 /* Set keylist mode in CTX to MODE.  */
827 gpgme_error_t gpgme_set_keylist_mode (gpgme_ctx_t ctx,
828                                       gpgme_keylist_mode_t mode);
829
830 /* Get keylist mode in CTX.  */
831 gpgme_keylist_mode_t gpgme_get_keylist_mode (gpgme_ctx_t ctx);
832
833 /* Set the passphrase callback function in CTX to CB.  HOOK_VALUE is
834    passed as first argument to the passphrase callback function.  */
835 void gpgme_set_passphrase_cb (gpgme_ctx_t ctx,
836                               gpgme_passphrase_cb_t cb, void *hook_value);
837
838 /* Get the current passphrase callback function in *CB and the current
839    hook value in *HOOK_VALUE.  */
840 void gpgme_get_passphrase_cb (gpgme_ctx_t ctx, gpgme_passphrase_cb_t *cb,
841                               void **hook_value);
842
843 /* Set the progress callback function in CTX to CB.  HOOK_VALUE is
844    passed as first argument to the progress callback function.  */
845 void gpgme_set_progress_cb (gpgme_ctx_t c, gpgme_progress_cb_t cb,
846                             void *hook_value);
847
848 /* Get the current progress callback function in *CB and the current
849    hook value in *HOOK_VALUE.  */
850 void gpgme_get_progress_cb (gpgme_ctx_t ctx, gpgme_progress_cb_t *cb,
851                             void **hook_value);
852
853 /* This function sets the locale for the context CTX, or the default
854    locale if CTX is a null pointer.  */
855 gpgme_error_t gpgme_set_locale (gpgme_ctx_t ctx, int category,
856                                 const char *value);
857
858 /* Get the information about the configured engines.  A pointer to the
859    first engine in the statically allocated linked list is returned.
860    The returned data is valid until the next gpgme_ctx_set_engine_info.  */
861 gpgme_engine_info_t gpgme_ctx_get_engine_info (gpgme_ctx_t ctx);
862
863 /* Set the engine info for the context CTX, protocol PROTO, to the
864    file name FILE_NAME and the home directory HOME_DIR.  */
865 gpgme_error_t gpgme_ctx_set_engine_info (gpgme_ctx_t ctx,
866                                          gpgme_protocol_t proto,
867                                          const char *file_name,
868                                          const char *home_dir);
869
870 \f
871 /* Return a statically allocated string with the name of the public
872    key algorithm ALGO, or NULL if that name is not known.  */
873 const char *gpgme_pubkey_algo_name (gpgme_pubkey_algo_t algo);
874
875 /* Return a statically allocated string with the name of the hash
876    algorithm ALGO, or NULL if that name is not known.  */
877 const char *gpgme_hash_algo_name (gpgme_hash_algo_t algo);
878
879 \f
880 /* Delete all signers from CTX.  */
881 void gpgme_signers_clear (gpgme_ctx_t ctx);
882
883 /* Add KEY to list of signers in CTX.  */
884 gpgme_error_t gpgme_signers_add (gpgme_ctx_t ctx, const gpgme_key_t key);
885
886 /* Return the SEQth signer's key in CTX.  */
887 gpgme_key_t gpgme_signers_enum (const gpgme_ctx_t ctx, int seq);
888
889 /* Retrieve the signature status of signature IDX in CTX after a
890    successful verify operation in R_STAT (if non-null).  The creation
891    time stamp of the signature is returned in R_CREATED (if non-null).
892    The function returns a string containing the fingerprint.
893    Deprecated, use verify result directly.  */
894 const char *gpgme_get_sig_status (gpgme_ctx_t ctx, int idx,
895                                   _gpgme_sig_stat_t *r_stat,
896                                   time_t *r_created) _GPGME_DEPRECATED;
897
898 /* Retrieve certain attributes of a signature.  IDX is the index
899    number of the signature after a successful verify operation.  WHAT
900    is an attribute where GPGME_ATTR_EXPIRE is probably the most useful
901    one.  WHATIDX is to be passed as 0 for most attributes . */
902 unsigned long gpgme_get_sig_ulong_attr (gpgme_ctx_t c, int idx,
903                                         _gpgme_attr_t what, int whatidx)
904      _GPGME_DEPRECATED;
905 const char *gpgme_get_sig_string_attr (gpgme_ctx_t c, int idx,
906                                        _gpgme_attr_t what, int whatidx)
907      _GPGME_DEPRECATED;
908
909
910 /* Get the key used to create signature IDX in CTX and return it in
911    R_KEY.  */
912 gpgme_error_t gpgme_get_sig_key (gpgme_ctx_t ctx, int idx, gpgme_key_t *r_key)
913      _GPGME_DEPRECATED;
914
915 \f
916 /* Clear all notation data from the context.  */
917 void gpgme_sig_notation_clear (gpgme_ctx_t ctx);
918
919 /* Add the human-readable notation data with name NAME and value VALUE
920    to the context CTX, using the flags FLAGS.  If NAME is NULL, then
921    VALUE should be a policy URL.  The flag
922    GPGME_SIG_NOTATION_HUMAN_READABLE is forced to be true for notation
923    data, and false for policy URLs.  */
924 gpgme_error_t gpgme_sig_notation_add (gpgme_ctx_t ctx, const char *name,
925                                       const char *value,
926                                       gpgme_sig_notation_flags_t flags);
927
928 /* Get the sig notations for this context.  */
929 gpgme_sig_notation_t gpgme_sig_notation_get (gpgme_ctx_t ctx);
930
931 \f
932 /* Run control.  */
933
934 /* The type of an I/O callback function.  */
935 typedef gpgme_error_t (*gpgme_io_cb_t) (void *data, int fd);
936
937 /* The type of a function that can register FNC as the I/O callback
938    function for the file descriptor FD with direction dir (0: for writing,
939    1: for reading).  FNC_DATA should be passed as DATA to FNC.  The
940    function should return a TAG suitable for the corresponding
941    gpgme_remove_io_cb_t, and an error value.  */
942 typedef gpgme_error_t (*gpgme_register_io_cb_t) (void *data, int fd, int dir,
943                                                  gpgme_io_cb_t fnc,
944                                                  void *fnc_data, void **tag);
945
946 /* The type of a function that can remove a previously registered I/O
947    callback function given TAG as returned by the register
948    function.  */
949 typedef void (*gpgme_remove_io_cb_t) (void *tag);
950
951 typedef enum
952   {
953     GPGME_EVENT_START,
954     GPGME_EVENT_DONE,
955     GPGME_EVENT_NEXT_KEY,
956     GPGME_EVENT_NEXT_TRUSTITEM
957   }
958 gpgme_event_io_t;
959
960 /* The type of a function that is called when a context finished an
961    operation.  */
962 typedef void (*gpgme_event_io_cb_t) (void *data, gpgme_event_io_t type,
963                                      void *type_data);
964
965 struct gpgme_io_cbs
966 {
967   gpgme_register_io_cb_t add;
968   void *add_priv;
969   gpgme_remove_io_cb_t remove;
970   gpgme_event_io_cb_t event;
971   void *event_priv;
972 };
973 typedef struct gpgme_io_cbs *gpgme_io_cbs_t;
974
975 /* Set the I/O callback functions in CTX to IO_CBS.  */
976 void gpgme_set_io_cbs (gpgme_ctx_t ctx, gpgme_io_cbs_t io_cbs);
977
978 /* Get the current I/O callback functions.  */
979 void gpgme_get_io_cbs (gpgme_ctx_t ctx, gpgme_io_cbs_t io_cbs);
980
981 /* Wrappers around the internal I/O functions for use with
982    gpgme_passphrase_cb_t and gpgme_edit_cb_t.  */
983 ssize_t gpgme_io_read (int fd, void *buffer, size_t count);
984 ssize_t gpgme_io_write (int fd, const void *buffer, size_t count);
985
986 /* Process the pending operation and, if HANG is non-zero, wait for
987    the pending operation to finish.  */
988 gpgme_ctx_t gpgme_wait (gpgme_ctx_t ctx, gpgme_error_t *status, int hang);
989
990 \f
991 /* Functions to handle data objects.  */
992
993 /* Read up to SIZE bytes into buffer BUFFER from the data object with
994    the handle HANDLE.  Return the number of characters read, 0 on EOF
995    and -1 on error.  If an error occurs, errno is set.  */
996 typedef ssize_t (*gpgme_data_read_cb_t) (void *handle, void *buffer,
997                                          size_t size);
998
999 /* Write up to SIZE bytes from buffer BUFFER to the data object with
1000    the handle HANDLE.  Return the number of characters written, or -1
1001    on error.  If an error occurs, errno is set.  */
1002 typedef ssize_t (*gpgme_data_write_cb_t) (void *handle, const void *buffer,
1003                                           size_t size);
1004
1005 /* Set the current position from where the next read or write starts
1006    in the data object with the handle HANDLE to OFFSET, relativ to
1007    WHENCE.  */
1008 typedef off_t (*gpgme_data_seek_cb_t) (void *handle, off_t offset, int whence);
1009
1010 /* Close the data object with the handle DL.  */
1011 typedef void (*gpgme_data_release_cb_t) (void *handle);
1012
1013 struct gpgme_data_cbs
1014 {
1015   gpgme_data_read_cb_t read;
1016   gpgme_data_write_cb_t write;
1017   gpgme_data_seek_cb_t seek;
1018   gpgme_data_release_cb_t release;
1019 };
1020 typedef struct gpgme_data_cbs *gpgme_data_cbs_t;
1021
1022 /* Read up to SIZE bytes into buffer BUFFER from the data object with
1023    the handle DH.  Return the number of characters read, 0 on EOF and
1024    -1 on error.  If an error occurs, errno is set.  */
1025 ssize_t gpgme_data_read (gpgme_data_t dh, void *buffer, size_t size);
1026
1027 /* Write up to SIZE bytes from buffer BUFFER to the data object with
1028    the handle DH.  Return the number of characters written, or -1 on
1029    error.  If an error occurs, errno is set.  */
1030 ssize_t gpgme_data_write (gpgme_data_t dh, const void *buffer, size_t size);
1031
1032 /* Set the current position from where the next read or write starts
1033    in the data object with the handle DH to OFFSET, relativ to
1034    WHENCE.  */
1035 off_t gpgme_data_seek (gpgme_data_t dh, off_t offset, int whence);
1036
1037 /* Create a new data buffer and return it in R_DH.  */
1038 gpgme_error_t gpgme_data_new (gpgme_data_t *r_dh);
1039
1040 /* Destroy the data buffer DH.  */
1041 void gpgme_data_release (gpgme_data_t dh);
1042
1043 /* Create a new data buffer filled with SIZE bytes starting from
1044    BUFFER.  If COPY is zero, copying is delayed until necessary, and
1045    the data is taken from the original location when needed.  */
1046 gpgme_error_t gpgme_data_new_from_mem (gpgme_data_t *r_dh,
1047                                        const char *buffer, size_t size,
1048                                        int copy);
1049
1050 /* Destroy the data buffer DH and return a pointer to its content.
1051    The memory has be to released with gpgme_free() by the user.  It's
1052    size is returned in R_LEN.  */
1053 char *gpgme_data_release_and_get_mem (gpgme_data_t dh, size_t *r_len);
1054
1055 /* Release the memory returned by gpgme_data_release_and_get_mem().  */
1056 void gpgme_free (void *buffer);
1057
1058 gpgme_error_t gpgme_data_new_from_cbs (gpgme_data_t *dh,
1059                                        gpgme_data_cbs_t cbs,
1060                                        void *handle);
1061
1062 gpgme_error_t gpgme_data_new_from_fd (gpgme_data_t *dh, int fd);
1063
1064 gpgme_error_t gpgme_data_new_from_stream (gpgme_data_t *dh, FILE *stream);
1065
1066 /* Return the encoding attribute of the data buffer DH */
1067 gpgme_data_encoding_t gpgme_data_get_encoding (gpgme_data_t dh);
1068
1069 /* Set the encoding attribute of data buffer DH to ENC */
1070 gpgme_error_t gpgme_data_set_encoding (gpgme_data_t dh,
1071                                        gpgme_data_encoding_t enc);
1072
1073 /* Get the file name associated with the data object with handle DH, or
1074    NULL if there is none.  */
1075 char *gpgme_data_get_file_name (gpgme_data_t dh);
1076
1077 /* Set the file name associated with the data object with handle DH to
1078    FILE_NAME.  */
1079 gpgme_error_t gpgme_data_set_file_name (gpgme_data_t dh,
1080                                         const char *file_name);
1081
1082
1083 /* Create a new data buffer which retrieves the data from the callback
1084    function READ_CB.  Deprecated, please use gpgme_data_new_from_cbs
1085    instead.  */
1086 gpgme_error_t gpgme_data_new_with_read_cb (gpgme_data_t *r_dh,
1087                                            int (*read_cb) (void*,char *,
1088                                                            size_t,size_t*),
1089                                            void *read_cb_value)
1090      _GPGME_DEPRECATED;
1091
1092 /* Create a new data buffer filled with the content of file FNAME.
1093    COPY must be non-zero.  For delayed read, please use
1094    gpgme_data_new_from_fd or gpgme_data_new_from stream instead.  */
1095 gpgme_error_t gpgme_data_new_from_file (gpgme_data_t *r_dh,
1096                                         const char *fname,
1097                                         int copy);
1098
1099 /* Create a new data buffer filled with LENGTH bytes starting from
1100    OFFSET within the file FNAME or stream FP (exactly one must be
1101    non-zero).  */
1102 gpgme_error_t gpgme_data_new_from_filepart (gpgme_data_t *r_dh,
1103                                             const char *fname, FILE *fp,
1104                                             off_t offset, size_t length);
1105
1106 /* Reset the read pointer in DH.  Deprecated, please use
1107    gpgme_data_seek instead.  */
1108 gpgme_error_t gpgme_data_rewind (gpgme_data_t dh) _GPGME_DEPRECATED;
1109
1110 \f
1111 /* Key and trust functions.  */
1112
1113 /* Get the key with the fingerprint FPR from the crypto backend.  If
1114    SECRET is true, get the secret key.  */
1115 gpgme_error_t gpgme_get_key (gpgme_ctx_t ctx, const char *fpr,
1116                              gpgme_key_t *r_key, int secret);
1117
1118 /* Acquire a reference to KEY.  */
1119 void gpgme_key_ref (gpgme_key_t key);
1120
1121 /* Release a reference to KEY.  If this was the last one the key is
1122    destroyed.  */
1123 void gpgme_key_unref (gpgme_key_t key);
1124 void gpgme_key_release (gpgme_key_t key);
1125
1126 /* Return the value of the attribute WHAT of KEY, which has to be
1127    representable by a string.  IDX specifies the sub key or user ID
1128    for attributes related to sub keys or user IDs.  Deprecated, use
1129    key structure directly instead. */
1130 const char *gpgme_key_get_string_attr (gpgme_key_t key, _gpgme_attr_t what,
1131                                        const void *reserved, int idx)
1132      _GPGME_DEPRECATED;
1133
1134 /* Return the value of the attribute WHAT of KEY, which has to be
1135    representable by an unsigned integer.  IDX specifies the sub key or
1136    user ID for attributes related to sub keys or user IDs.
1137    Deprecated, use key structure directly instead.  */
1138 unsigned long gpgme_key_get_ulong_attr (gpgme_key_t key, _gpgme_attr_t what,
1139                                         const void *reserved, int idx)
1140      _GPGME_DEPRECATED;
1141
1142 /* Return the value of the attribute WHAT of a signature on user ID
1143    UID_IDX in KEY, which has to be representable by a string.  IDX
1144    specifies the signature.  Deprecated, use key structure directly
1145    instead.  */
1146 const char *gpgme_key_sig_get_string_attr (gpgme_key_t key, int uid_idx,
1147                                            _gpgme_attr_t what,
1148                                            const void *reserved, int idx)
1149      _GPGME_DEPRECATED;
1150
1151 /* Return the value of the attribute WHAT of a signature on user ID
1152    UID_IDX in KEY, which has to be representable by an unsigned
1153    integer string.  IDX specifies the signature.  Deprecated, use key
1154    structure directly instead.  */
1155 unsigned long gpgme_key_sig_get_ulong_attr (gpgme_key_t key, int uid_idx,
1156                                             _gpgme_attr_t what,
1157                                             const void *reserved, int idx)
1158      _GPGME_DEPRECATED;
1159
1160 \f
1161 /* Crypto Operations.  */
1162
1163 /* Cancel a pending asynchronous operation.  */
1164 gpgme_error_t gpgme_cancel (gpgme_ctx_t ctx);
1165
1166 /* Cancel a pending operation asynchronously.  */
1167 gpgme_error_t gpgme_cancel_async (gpgme_ctx_t ctx);
1168
1169 \f
1170 struct _gpgme_invalid_key
1171 {
1172   struct _gpgme_invalid_key *next;
1173   char *fpr;
1174   gpgme_error_t reason;
1175 };
1176 typedef struct _gpgme_invalid_key *gpgme_invalid_key_t;
1177
1178 \f
1179 /* Encryption.  */
1180 struct _gpgme_op_encrypt_result
1181 {
1182   /* The list of invalid recipients.  */
1183   gpgme_invalid_key_t invalid_recipients;
1184 };
1185 typedef struct _gpgme_op_encrypt_result *gpgme_encrypt_result_t;
1186
1187 /* Retrieve a pointer to the result of the encrypt operation.  */
1188 gpgme_encrypt_result_t gpgme_op_encrypt_result (gpgme_ctx_t ctx);
1189
1190 /* The valid encryption flags.  */
1191 typedef enum
1192   {
1193     GPGME_ENCRYPT_ALWAYS_TRUST = 1,
1194     GPGME_ENCRYPT_NO_ENCRYPT_TO = 2
1195   }
1196 gpgme_encrypt_flags_t;
1197
1198 /* Encrypt plaintext PLAIN within CTX for the recipients RECP and
1199    store the resulting ciphertext in CIPHER.  */
1200 gpgme_error_t gpgme_op_encrypt_start (gpgme_ctx_t ctx, gpgme_key_t recp[],
1201                                       gpgme_encrypt_flags_t flags,
1202                                       gpgme_data_t plain, gpgme_data_t cipher);
1203 gpgme_error_t gpgme_op_encrypt (gpgme_ctx_t ctx, gpgme_key_t recp[],
1204                                 gpgme_encrypt_flags_t flags,
1205                                 gpgme_data_t plain, gpgme_data_t cipher);
1206
1207 /* Encrypt plaintext PLAIN within CTX for the recipients RECP and
1208    store the resulting ciphertext in CIPHER.  Also sign the ciphertext
1209    with the signers in CTX.  */
1210 gpgme_error_t gpgme_op_encrypt_sign_start (gpgme_ctx_t ctx,
1211                                            gpgme_key_t recp[],
1212                                            gpgme_encrypt_flags_t flags,
1213                                            gpgme_data_t plain,
1214                                            gpgme_data_t cipher);
1215 gpgme_error_t gpgme_op_encrypt_sign (gpgme_ctx_t ctx, gpgme_key_t recp[],
1216                                      gpgme_encrypt_flags_t flags,
1217                                      gpgme_data_t plain, gpgme_data_t cipher);
1218
1219 \f
1220 /* Decryption.  */
1221
1222 struct _gpgme_recipient
1223 {
1224   struct _gpgme_recipient *next;
1225
1226   /* The key ID of key for which the text was encrypted.  */
1227   char *keyid;
1228
1229   /* Internal to GPGME, do not use.  */
1230   char _keyid[16 + 1];
1231
1232   /* The public key algorithm of the recipient key.  */
1233   gpgme_pubkey_algo_t pubkey_algo;
1234
1235   /* The status of the recipient.  */
1236   gpgme_error_t status;
1237 };
1238 typedef struct _gpgme_recipient *gpgme_recipient_t;
1239
1240 struct _gpgme_op_decrypt_result
1241 {
1242   char *unsupported_algorithm;
1243
1244   /* Key should not have been used for encryption.  */
1245   unsigned int wrong_key_usage : 1;
1246
1247   /* Internal to GPGME, do not use.  */
1248   int _unused : 31;
1249
1250   gpgme_recipient_t recipients;
1251
1252   /* The original file name of the plaintext message, if
1253      available.  */
1254   char *file_name;
1255 };
1256 typedef struct _gpgme_op_decrypt_result *gpgme_decrypt_result_t;
1257
1258 /* Retrieve a pointer to the result of the decrypt operation.  */
1259 gpgme_decrypt_result_t gpgme_op_decrypt_result (gpgme_ctx_t ctx);
1260
1261 /* Decrypt ciphertext CIPHER within CTX and store the resulting
1262    plaintext in PLAIN.  */
1263 gpgme_error_t gpgme_op_decrypt_start (gpgme_ctx_t ctx, gpgme_data_t cipher,
1264                                       gpgme_data_t plain);
1265 gpgme_error_t gpgme_op_decrypt (gpgme_ctx_t ctx,
1266                                 gpgme_data_t cipher, gpgme_data_t plain);
1267
1268 /* Decrypt ciphertext CIPHER and make a signature verification within
1269    CTX and store the resulting plaintext in PLAIN.  */
1270 gpgme_error_t gpgme_op_decrypt_verify_start (gpgme_ctx_t ctx,
1271                                              gpgme_data_t cipher,
1272                                              gpgme_data_t plain);
1273 gpgme_error_t gpgme_op_decrypt_verify (gpgme_ctx_t ctx, gpgme_data_t cipher,
1274                                        gpgme_data_t plain);
1275
1276 \f
1277 /* Signing.  */
1278 struct _gpgme_new_signature
1279 {
1280   struct _gpgme_new_signature *next;
1281
1282   /* The type of the signature.  */
1283   gpgme_sig_mode_t type;
1284
1285   /* The public key algorithm used to create the signature.  */
1286   gpgme_pubkey_algo_t pubkey_algo;
1287
1288   /* The hash algorithm used to create the signature.  */
1289   gpgme_hash_algo_t hash_algo;
1290
1291   /* Internal to GPGME, do not use.  Must be set to the same value as
1292      CLASS below.  */
1293   unsigned long _obsolete_class;
1294
1295   /* Signature creation time.  */
1296   long int timestamp;
1297
1298   /* The fingerprint of the signature.  */
1299   char *fpr;
1300
1301 #ifdef __cplusplus
1302   unsigned int _obsolete_class_2;
1303 #else
1304   /* Must be set to SIG_CLASS below.  */
1305   unsigned int class _GPGME_DEPRECATED_OUTSIDE_GPGME;
1306 #endif
1307
1308   /* Crypto backend specific signature class.  */
1309   unsigned int sig_class;
1310 };
1311 typedef struct _gpgme_new_signature *gpgme_new_signature_t;
1312
1313 struct _gpgme_op_sign_result
1314 {
1315   /* The list of invalid signers.  */
1316   gpgme_invalid_key_t invalid_signers;
1317   gpgme_new_signature_t signatures;
1318 };
1319 typedef struct _gpgme_op_sign_result *gpgme_sign_result_t;
1320
1321 /* Retrieve a pointer to the result of the signing operation.  */
1322 gpgme_sign_result_t gpgme_op_sign_result (gpgme_ctx_t ctx);
1323
1324 /* Sign the plaintext PLAIN and store the signature in SIG.  */
1325 gpgme_error_t gpgme_op_sign_start (gpgme_ctx_t ctx,
1326                                    gpgme_data_t plain, gpgme_data_t sig,
1327                                    gpgme_sig_mode_t mode);
1328 gpgme_error_t gpgme_op_sign (gpgme_ctx_t ctx,
1329                              gpgme_data_t plain, gpgme_data_t sig,
1330                              gpgme_sig_mode_t mode);
1331
1332 \f
1333 /* Verify.  */
1334
1335 /* Flags used for the SUMMARY field in a gpgme_signature_t.  */
1336 typedef enum
1337   {
1338     GPGME_SIGSUM_VALID       = 0x0001,  /* The signature is fully valid.  */
1339     GPGME_SIGSUM_GREEN       = 0x0002,  /* The signature is good.  */
1340     GPGME_SIGSUM_RED         = 0x0004,  /* The signature is bad.  */
1341     GPGME_SIGSUM_KEY_REVOKED = 0x0010,  /* One key has been revoked.  */
1342     GPGME_SIGSUM_KEY_EXPIRED = 0x0020,  /* One key has expired.  */
1343     GPGME_SIGSUM_SIG_EXPIRED = 0x0040,  /* The signature has expired.  */
1344     GPGME_SIGSUM_KEY_MISSING = 0x0080,  /* Can't verify: key missing.  */
1345     GPGME_SIGSUM_CRL_MISSING = 0x0100,  /* CRL not available.  */
1346     GPGME_SIGSUM_CRL_TOO_OLD = 0x0200,  /* Available CRL is too old.  */
1347     GPGME_SIGSUM_BAD_POLICY  = 0x0400,  /* A policy was not met.  */
1348     GPGME_SIGSUM_SYS_ERROR   = 0x0800   /* A system error occured.  */
1349   }
1350 gpgme_sigsum_t;
1351
1352 struct _gpgme_signature
1353 {
1354   struct _gpgme_signature *next;
1355
1356   /* A summary of the signature status.  */
1357   gpgme_sigsum_t summary;
1358
1359   /* The fingerprint or key ID of the signature.  */
1360   char *fpr;
1361
1362   /* The status of the signature.  */
1363   gpgme_error_t status;
1364
1365   /* Notation data and policy URLs.  */
1366   gpgme_sig_notation_t notations;
1367
1368   /* Signature creation time.  */
1369   unsigned long timestamp;
1370
1371   /* Signature exipration time or 0.  */
1372   unsigned long exp_timestamp;
1373
1374   /* Key should not have been used for signing.  */
1375   unsigned int wrong_key_usage : 1;
1376
1377   /* PKA status: 0 = not available, 1 = bad, 2 = okay, 3 = RFU. */
1378   unsigned int pka_trust : 2;
1379
1380   /* Validity has been verified using the chain model. */
1381   unsigned int chain_model : 1;
1382
1383   /* Internal to GPGME, do not use.  */
1384   int _unused : 28;
1385
1386   gpgme_validity_t validity;
1387   gpgme_error_t validity_reason;
1388
1389   /* The public key algorithm used to create the signature.  */
1390   gpgme_pubkey_algo_t pubkey_algo;
1391
1392   /* The hash algorithm used to create the signature.  */
1393   gpgme_hash_algo_t hash_algo;
1394
1395   /* The mailbox from the PKA information or NULL. */
1396   char *pka_address;
1397 };
1398 typedef struct _gpgme_signature *gpgme_signature_t;
1399
1400 struct _gpgme_op_verify_result
1401 {
1402   gpgme_signature_t signatures;
1403
1404   /* The original file name of the plaintext message, if
1405      available.  */
1406   char *file_name;
1407 };
1408 typedef struct _gpgme_op_verify_result *gpgme_verify_result_t;
1409
1410 /* Retrieve a pointer to the result of the verify operation.  */
1411 gpgme_verify_result_t gpgme_op_verify_result (gpgme_ctx_t ctx);
1412
1413 /* Verify within CTX that SIG is a valid signature for TEXT.  */
1414 gpgme_error_t gpgme_op_verify_start (gpgme_ctx_t ctx, gpgme_data_t sig,
1415                                      gpgme_data_t signed_text,
1416                                      gpgme_data_t plaintext);
1417 gpgme_error_t gpgme_op_verify (gpgme_ctx_t ctx, gpgme_data_t sig,
1418                                gpgme_data_t signed_text,
1419                                gpgme_data_t plaintext);
1420
1421 \f
1422 /* Import.  */
1423
1424 /* The key was new.  */
1425 #define GPGME_IMPORT_NEW        1
1426
1427 /* The key contained new user IDs.  */
1428 #define GPGME_IMPORT_UID        2
1429
1430 /* The key contained new signatures.  */
1431 #define GPGME_IMPORT_SIG        4
1432
1433 /* The key contained new sub keys.  */
1434 #define GPGME_IMPORT_SUBKEY     8
1435
1436 /* The key contained a secret key.  */
1437 #define GPGME_IMPORT_SECRET     16
1438
1439
1440 struct _gpgme_import_status
1441 {
1442   struct _gpgme_import_status *next;
1443
1444   /* Fingerprint.  */
1445   char *fpr;
1446
1447   /* If a problem occured, the reason why the key could not be
1448      imported.  Otherwise GPGME_No_Error.  */
1449   gpgme_error_t result;
1450
1451   /* The result of the import, the GPGME_IMPORT_* values bit-wise
1452      ORed.  0 means the key was already known and no new components
1453      have been added.  */
1454   unsigned int status;
1455 };
1456 typedef struct _gpgme_import_status *gpgme_import_status_t;
1457
1458 /* Import.  */
1459 struct _gpgme_op_import_result
1460 {
1461   /* Number of considered keys.  */
1462   int considered;
1463
1464   /* Keys without user ID.  */
1465   int no_user_id;
1466
1467   /* Imported keys.  */
1468   int imported;
1469
1470   /* Imported RSA keys.  */
1471   int imported_rsa;
1472
1473   /* Unchanged keys.  */
1474   int unchanged;
1475
1476   /* Number of new user ids.  */
1477   int new_user_ids;
1478
1479   /* Number of new sub keys.  */
1480   int new_sub_keys;
1481
1482   /* Number of new signatures.  */
1483   int new_signatures;
1484
1485   /* Number of new revocations.  */
1486   int new_revocations;
1487
1488   /* Number of secret keys read.  */
1489   int secret_read;
1490
1491   /* Number of secret keys imported.  */
1492   int secret_imported;
1493
1494   /* Number of secret keys unchanged.  */
1495   int secret_unchanged;
1496
1497   /* Number of new keys skipped.  */
1498   int skipped_new_keys;
1499
1500   /* Number of keys not imported.  */
1501   int not_imported;
1502
1503   /* List of keys for which an import was attempted.  */
1504   gpgme_import_status_t imports;
1505 };
1506 typedef struct _gpgme_op_import_result *gpgme_import_result_t;
1507
1508 /* Retrieve a pointer to the result of the import operation.  */
1509 gpgme_import_result_t gpgme_op_import_result (gpgme_ctx_t ctx);
1510
1511 /* Import the key in KEYDATA into the keyring.  */
1512 gpgme_error_t gpgme_op_import_start (gpgme_ctx_t ctx, gpgme_data_t keydata);
1513 gpgme_error_t gpgme_op_import (gpgme_ctx_t ctx, gpgme_data_t keydata);
1514 gpgme_error_t gpgme_op_import_ext (gpgme_ctx_t ctx, gpgme_data_t keydata,
1515                                    int *nr) _GPGME_DEPRECATED;
1516
1517 /* Import the keys from the array KEYS into the keyring.  */
1518 gpgme_error_t gpgme_op_import_keys_start (gpgme_ctx_t ctx, gpgme_key_t keys[]);
1519 gpgme_error_t gpgme_op_import_keys (gpgme_ctx_t ctx, gpgme_key_t keys[]);
1520
1521
1522 \f
1523 /* Export the keys found by PATTERN into KEYDATA.  */
1524 gpgme_error_t gpgme_op_export_start (gpgme_ctx_t ctx, const char *pattern,
1525                                      gpgme_export_mode_t mode,
1526                                      gpgme_data_t keydata);
1527 gpgme_error_t gpgme_op_export (gpgme_ctx_t ctx, const char *pattern,
1528                                gpgme_export_mode_t mode,
1529                                gpgme_data_t keydata);
1530
1531 gpgme_error_t gpgme_op_export_ext_start (gpgme_ctx_t ctx,
1532                                          const char *pattern[],
1533                                          gpgme_export_mode_t mode,
1534                                          gpgme_data_t keydata);
1535 gpgme_error_t gpgme_op_export_ext (gpgme_ctx_t ctx, const char *pattern[],
1536                                    gpgme_export_mode_t mode,
1537                                    gpgme_data_t keydata);
1538
1539 /* Export the keys from the array KEYS into KEYDATA.  */
1540 gpgme_error_t gpgme_op_export_keys_start (gpgme_ctx_t ctx,
1541                                           gpgme_key_t keys[],
1542                                           gpgme_export_mode_t mode,
1543                                           gpgme_data_t keydata);
1544 gpgme_error_t gpgme_op_export_keys (gpgme_ctx_t ctx,
1545                                     gpgme_key_t keys[],
1546                                     gpgme_export_mode_t mode,
1547                                     gpgme_data_t keydata);
1548
1549
1550 \f
1551 /* Key generation.  */
1552 struct _gpgme_op_genkey_result
1553 {
1554   /* A primary key was generated.  */
1555   unsigned int primary : 1;
1556
1557   /* A sub key was generated.  */
1558   unsigned int sub : 1;
1559
1560   /* Internal to GPGME, do not use.  */
1561   unsigned int _unused : 30;
1562
1563   /* The fingerprint of the generated key.  */
1564   char *fpr;
1565 };
1566 typedef struct _gpgme_op_genkey_result *gpgme_genkey_result_t;
1567
1568 /* Generate a new keypair and add it to the keyring.  PUBKEY and
1569    SECKEY should be null for now.  PARMS specifies what keys should be
1570    generated.  */
1571 gpgme_error_t gpgme_op_genkey_start (gpgme_ctx_t ctx, const char *parms,
1572                                      gpgme_data_t pubkey, gpgme_data_t seckey);
1573 gpgme_error_t gpgme_op_genkey (gpgme_ctx_t ctx, const char *parms,
1574                                gpgme_data_t pubkey, gpgme_data_t seckey);
1575
1576 /* Retrieve a pointer to the result of the genkey operation.  */
1577 gpgme_genkey_result_t gpgme_op_genkey_result (gpgme_ctx_t ctx);
1578
1579 \f
1580 /* Delete KEY from the keyring.  If ALLOW_SECRET is non-zero, secret
1581    keys are also deleted.  */
1582 gpgme_error_t gpgme_op_delete_start (gpgme_ctx_t ctx, const gpgme_key_t key,
1583                                      int allow_secret);
1584 gpgme_error_t gpgme_op_delete (gpgme_ctx_t ctx, const gpgme_key_t key,
1585                                int allow_secret);
1586
1587 \f
1588 /* Edit the key KEY.  Send status and command requests to FNC and
1589    output of edit commands to OUT.  */
1590 gpgme_error_t gpgme_op_edit_start (gpgme_ctx_t ctx, gpgme_key_t key,
1591                                    gpgme_edit_cb_t fnc, void *fnc_value,
1592                                    gpgme_data_t out);
1593 gpgme_error_t gpgme_op_edit (gpgme_ctx_t ctx, gpgme_key_t key,
1594                              gpgme_edit_cb_t fnc, void *fnc_value,
1595                              gpgme_data_t out);
1596
1597 /* Edit the card for the key KEY.  Send status and command requests to
1598    FNC and output of edit commands to OUT.  */
1599 gpgme_error_t gpgme_op_card_edit_start (gpgme_ctx_t ctx, gpgme_key_t key,
1600                                         gpgme_edit_cb_t fnc, void *fnc_value,
1601                                         gpgme_data_t out);
1602 gpgme_error_t gpgme_op_card_edit (gpgme_ctx_t ctx, gpgme_key_t key,
1603                                   gpgme_edit_cb_t fnc, void *fnc_value,
1604                                   gpgme_data_t out);
1605
1606 \f
1607 /* Key management functions.  */
1608 struct _gpgme_op_keylist_result
1609 {
1610   unsigned int truncated : 1;
1611
1612   /* Internal to GPGME, do not use.  */
1613   unsigned int _unused : 31;
1614 };
1615 typedef struct _gpgme_op_keylist_result *gpgme_keylist_result_t;
1616
1617 /* Retrieve a pointer to the result of the key listing operation.  */
1618 gpgme_keylist_result_t gpgme_op_keylist_result (gpgme_ctx_t ctx);
1619
1620 /* Start a keylist operation within CTX, searching for keys which
1621    match PATTERN.  If SECRET_ONLY is true, only secret keys are
1622    returned.  */
1623 gpgme_error_t gpgme_op_keylist_start (gpgme_ctx_t ctx, const char *pattern,
1624                                       int secret_only);
1625 gpgme_error_t gpgme_op_keylist_ext_start (gpgme_ctx_t ctx,
1626                                           const char *pattern[],
1627                                           int secret_only, int reserved);
1628
1629 /* Return the next key from the keylist in R_KEY.  */
1630 gpgme_error_t gpgme_op_keylist_next (gpgme_ctx_t ctx, gpgme_key_t *r_key);
1631
1632 /* Terminate a pending keylist operation within CTX.  */
1633 gpgme_error_t gpgme_op_keylist_end (gpgme_ctx_t ctx);
1634
1635 \f
1636 /* Trust items and operations.  */
1637
1638 struct _gpgme_trust_item
1639 {
1640   /* Internal to GPGME, do not use.  */
1641   unsigned int _refs;
1642
1643   /* The key ID to which the trust item belongs.  */
1644   char *keyid;
1645
1646   /* Internal to GPGME, do not use.  */
1647   char _keyid[16 + 1];
1648
1649   /* The type of the trust item, 1 refers to a key, 2 to a user ID.  */
1650   int type;
1651
1652   /* The trust level.  */
1653   int level;
1654
1655   /* The owner trust if TYPE is 1.  */
1656   char *owner_trust;
1657
1658   /* Internal to GPGME, do not use.  */
1659   char _owner_trust[2];
1660
1661   /* The calculated validity.  */
1662   char *validity;
1663  
1664   /* Internal to GPGME, do not use.  */
1665   char _validity[2];
1666
1667   /* The user name if TYPE is 2.  */
1668   char *name;
1669 };
1670 typedef struct _gpgme_trust_item *gpgme_trust_item_t;
1671
1672 /* Start a trustlist operation within CTX, searching for trust items
1673    which match PATTERN.  */
1674 gpgme_error_t gpgme_op_trustlist_start (gpgme_ctx_t ctx,
1675                                         const char *pattern, int max_level);
1676
1677 /* Return the next trust item from the trustlist in R_ITEM.  */
1678 gpgme_error_t gpgme_op_trustlist_next (gpgme_ctx_t ctx,
1679                                        gpgme_trust_item_t *r_item);
1680
1681 /* Terminate a pending trustlist operation within CTX.  */
1682 gpgme_error_t gpgme_op_trustlist_end (gpgme_ctx_t ctx);
1683
1684 /* Acquire a reference to ITEM.  */
1685 void gpgme_trust_item_ref (gpgme_trust_item_t item);
1686
1687 /* Release a reference to ITEM.  If this was the last one the trust
1688    item is destroyed.  */
1689 void gpgme_trust_item_unref (gpgme_trust_item_t item);
1690
1691 /* Release the trust item ITEM.  Deprecated, use
1692    gpgme_trust_item_unref.  */
1693 void gpgme_trust_item_release (gpgme_trust_item_t item) _GPGME_DEPRECATED;
1694
1695 /* Return the value of the attribute WHAT of ITEM, which has to be
1696    representable by a string.  Deprecated, use trust item structure
1697    directly.  */
1698 const char *gpgme_trust_item_get_string_attr (gpgme_trust_item_t item,
1699                                               _gpgme_attr_t what,
1700                                               const void *reserved, int idx)
1701      _GPGME_DEPRECATED;
1702
1703 /* Return the value of the attribute WHAT of KEY, which has to be
1704    representable by an integer.  IDX specifies a running index if the
1705    attribute appears more than once in the key.  Deprecated, use trust
1706    item structure directly.  */
1707 int gpgme_trust_item_get_int_attr (gpgme_trust_item_t item, _gpgme_attr_t what,
1708                                    const void *reserved, int idx)
1709      _GPGME_DEPRECATED;
1710
1711 \f
1712 /* Return the auditlog for the current session.  This may be called
1713    after a successful or failed operation.  If no audit log is
1714    available GPG_ERR_NO_DATA is returned.  */
1715 gpgme_error_t gpgme_op_getauditlog_start (gpgme_ctx_t ctx, gpgme_data_t output,
1716                                           unsigned int flags);
1717 gpgme_error_t gpgme_op_getauditlog (gpgme_ctx_t ctx, gpgme_data_t output, 
1718                                     unsigned int flags);
1719
1720
1721 \f
1722 /* Low-level Assuan protocol access.  */
1723 typedef gpgme_error_t (*gpgme_assuan_data_cb_t) 
1724      (void *opaque, const void *data, size_t datalen);
1725
1726 typedef gpgme_error_t (*gpgme_assuan_inquire_cb_t)
1727      (void *opaque, const char *name, const char *args,
1728       gpgme_data_t *r_data);
1729
1730 typedef gpgme_error_t (*gpgme_assuan_status_cb_t)
1731      (void *opaque, const char *status, const char *args);
1732
1733 struct _gpgme_op_assuan_result
1734 {
1735   /* The result of the actual assuan command.  An OK is indicated by a
1736      value of 0 and an ERR by the respective error error value.  */
1737   gpgme_error_t err;
1738 };
1739 typedef struct _gpgme_op_assuan_result *gpgme_assuan_result_t;
1740
1741
1742 /* Return the result of the last Assuan command. */
1743 gpgme_assuan_result_t gpgme_op_assuan_result (gpgme_ctx_t ctx);
1744
1745 /* Send the Assuan COMMAND and return results via the callbacks.
1746    Asynchronous variant. */
1747 gpgme_error_t gpgme_op_assuan_transact_start (gpgme_ctx_t ctx, 
1748                                               const char *command,
1749                                               gpgme_assuan_data_cb_t data_cb,
1750                                               void *data_cb_value,
1751                                               gpgme_assuan_inquire_cb_t inq_cb,
1752                                               void *inq_cb_value,
1753                                               gpgme_assuan_status_cb_t stat_cb,
1754                                               void *stat_cb_value);
1755
1756 /* Send the Assuan COMMAND and return results via the callbacks.
1757    Synchronous variant. */
1758 gpgme_error_t gpgme_op_assuan_transact (gpgme_ctx_t ctx, 
1759                                         const char *command,
1760                                         gpgme_assuan_data_cb_t data_cb,
1761                                         void *data_cb_value,
1762                                         gpgme_assuan_inquire_cb_t inq_cb,
1763                                         void *inq_cb_value,
1764                                         gpgme_assuan_status_cb_t stat_cb,
1765                                         void *stat_cb_value);
1766
1767
1768 \f
1769 /* Interface to gpgconf(1).  */
1770
1771 /* The expert level at which a configuration option or group of
1772    options should be displayed.  See the gpgconf(1) documentation for
1773    more details.  */
1774 typedef enum
1775   {
1776     GPGME_CONF_BASIC = 0,
1777     GPGME_CONF_ADVANCED = 1,
1778     GPGME_CONF_EXPERT = 2,
1779     GPGME_CONF_INVISIBLE = 3,
1780     GPGME_CONF_INTERNAL = 4
1781   }
1782 gpgme_conf_level_t;
1783
1784
1785 /* The data type of a configuration option argument.  See the gpgconf(1)
1786    documentation for more details.  */
1787 typedef enum
1788   {
1789     /* Basic types.  */
1790     GPGME_CONF_NONE = 0,
1791     GPGME_CONF_STRING = 1,
1792     GPGME_CONF_INT32 = 2,
1793     GPGME_CONF_UINT32 = 3,
1794
1795     /* Complex types.  */
1796     GPGME_CONF_FILENAME = 32,
1797     GPGME_CONF_LDAP_SERVER = 33,
1798     GPGME_CONF_KEY_FPR = 34,
1799     GPGME_CONF_PUB_KEY = 35,
1800     GPGME_CONF_SEC_KEY = 36,
1801     GPGME_CONF_ALIAS_LIST = 37
1802   }
1803 gpgme_conf_type_t;
1804
1805 /* For now, compatibility.  */
1806 #define GPGME_CONF_PATHNAME GPGME_CONF_FILENAME
1807
1808
1809 /* This represents a single argument for a configuration option.
1810    Which of the members of value is used depends on the ALT_TYPE.  */
1811 typedef struct gpgme_conf_arg
1812 {
1813   struct gpgme_conf_arg *next;
1814   /* True if the option appears without an (optional) argument.  */
1815   unsigned int no_arg;
1816   union
1817   {
1818     unsigned int count;
1819     unsigned int uint32;
1820     int int32;
1821     char *string;
1822   } value;
1823 } *gpgme_conf_arg_t;
1824
1825
1826 /* The flags of a configuration option.  See the gpg-conf
1827    documentation for details.  */
1828 #define GPGME_CONF_GROUP        (1 << 0)
1829 #define GPGME_CONF_OPTIONAL     (1 << 1)
1830 #define GPGME_CONF_LIST         (1 << 2)
1831 #define GPGME_CONF_RUNTIME      (1 << 3)
1832 #define GPGME_CONF_DEFAULT      (1 << 4)
1833 #define GPGME_CONF_DEFAULT_DESC (1 << 5)
1834 #define GPGME_CONF_NO_ARG_DESC  (1 << 6)
1835 #define GPGME_CONF_NO_CHANGE    (1 << 7)
1836
1837
1838 /* The representation of a single configuration option.  See the
1839    gpg-conf documentation for details.  */
1840 typedef struct gpgme_conf_opt
1841 {
1842   struct gpgme_conf_opt *next;
1843   
1844   /* The option name.  */
1845   char *name;
1846
1847   /* The flags for this option.  */
1848   unsigned int flags;
1849
1850   /* The level of this option.  */
1851   gpgme_conf_level_t level;
1852
1853   /* The localized description of this option.  */
1854   char *description;
1855
1856   /* The type and alternate type of this option.  */
1857   gpgme_conf_type_t type;
1858   gpgme_conf_type_t alt_type;
1859
1860   /* The localized (short) name of the argument, if any.  */
1861   char *argname;
1862
1863   /* The default value.  */
1864   gpgme_conf_arg_t default_value;
1865   char *default_description;
1866   
1867   /* The default value if the option is not set.  */
1868   gpgme_conf_arg_t no_arg_value;
1869   char *no_arg_description;
1870
1871   /* The current value if the option is set.  */
1872   gpgme_conf_arg_t value;
1873
1874   /* The new value, if any.  NULL means reset to default.  */
1875   int change_value;
1876   gpgme_conf_arg_t new_value;
1877
1878   /* Free for application use.  */
1879   void *user_data;
1880 } *gpgme_conf_opt_t;
1881
1882
1883 /* The representation of a component that can be configured.  See the
1884    gpg-conf documentation for details.  */
1885 typedef struct gpgme_conf_comp
1886 {
1887   struct gpgme_conf_comp *next;
1888
1889   /* Internal to GPGME, do not use!  */
1890   gpgme_conf_opt_t *_last_opt_p;
1891
1892   /* The component name.  */
1893   char *name;
1894
1895   /* A human-readable description for the component.  */
1896   char *description;
1897
1898   /* The program name (an absolute path to the program).  */
1899   char *program_name;  
1900
1901   /* A linked list of options for this component.  */
1902   struct gpgme_conf_opt *options;
1903 } *gpgme_conf_comp_t;
1904
1905
1906 /* Allocate a new gpgme_conf_arg_t.  If VALUE is NULL, a "no arg
1907    default" is prepared.  If type is a string type, VALUE should point
1908    to the string.  Else, it should point to an unsigned or signed
1909    integer respectively.  */
1910 gpgme_error_t gpgme_conf_arg_new (gpgme_conf_arg_t *arg_p,
1911                                   gpgme_conf_type_t type, void *value);
1912
1913 /* This also releases all chained argument structures!  */
1914 void gpgme_conf_arg_release (gpgme_conf_arg_t arg, gpgme_conf_type_t type);
1915
1916 /* Register a change for the value of OPT to ARG.  If RESET is 1 (do
1917    not use any values but 0 or 1), ARG is ignored and the option is
1918    not changed (reverting a previous change).  Otherwise, if ARG is
1919    NULL, the option is cleared or reset to its default.  */
1920 gpgme_error_t gpgme_conf_opt_change (gpgme_conf_opt_t opt, int reset,
1921                                      gpgme_conf_arg_t arg);
1922
1923 /* Release a set of configurations.  */
1924 void gpgme_conf_release (gpgme_conf_comp_t conf);
1925  
1926 /* Retrieve the current configurations.  */
1927 gpgme_error_t gpgme_op_conf_load (gpgme_ctx_t ctx, gpgme_conf_comp_t *conf_p);
1928
1929 /* Save the configuration of component comp.  This function does not
1930    follow chained components!  */
1931 gpgme_error_t gpgme_op_conf_save (gpgme_ctx_t ctx, gpgme_conf_comp_t comp);
1932
1933 \f
1934 /* Various functions.  */
1935
1936 /* Check that the library fulfills the version requirement.  Note:
1937    This is here only for the case where a user takes a pointer from
1938    the old version of this function.  The new version and macro for
1939    run-time checks are below.  */
1940 const char *gpgme_check_version (const char *req_version);
1941
1942 /* Check that the library fulfills the version requirement and check
1943    for struct layout mismatch involving bitfields.  */
1944 const char *gpgme_check_version_internal (const char *req_version,
1945                                           size_t offset_sig_validity);
1946
1947 #define gpgme_check_version(req_version)                                \
1948   gpgme_check_version_internal (req_version,                            \
1949                                 offsetof (struct _gpgme_signature, validity))
1950
1951 /* Get the information about the configured and installed engines.  A
1952    pointer to the first engine in the statically allocated linked list
1953    is returned in *INFO.  If an error occurs, it is returned.  The
1954    returned data is valid until the next gpgme_set_engine_info.  */
1955 gpgme_error_t gpgme_get_engine_info (gpgme_engine_info_t *engine_info);
1956
1957 /* Set the default engine info for the protocol PROTO to the file name
1958    FILE_NAME and the home directory HOME_DIR.  */
1959 gpgme_error_t gpgme_set_engine_info (gpgme_protocol_t proto,
1960                                      const char *file_name,
1961                                      const char *home_dir);
1962
1963 \f
1964 /* Engine support functions.  */
1965
1966 /* Verify that the engine implementing PROTO is installed and
1967    available.  */
1968 gpgme_error_t gpgme_engine_check_version (gpgme_protocol_t proto);
1969
1970 \f
1971 void gpgme_result_ref (void *result);
1972 void gpgme_result_unref (void *result);
1973
1974 \f
1975 /* Deprecated types.  */
1976 typedef gpgme_ctx_t GpgmeCtx _GPGME_DEPRECATED;
1977 typedef gpgme_data_t GpgmeData _GPGME_DEPRECATED;
1978 typedef gpgme_error_t GpgmeError _GPGME_DEPRECATED;
1979 typedef gpgme_data_encoding_t GpgmeDataEncoding _GPGME_DEPRECATED;
1980 typedef gpgme_pubkey_algo_t GpgmePubKeyAlgo _GPGME_DEPRECATED;
1981 typedef gpgme_hash_algo_t GpgmeHashAlgo _GPGME_DEPRECATED;
1982 typedef gpgme_sig_stat_t GpgmeSigStat _GPGME_DEPRECATED;
1983 typedef gpgme_sig_mode_t GpgmeSigMode _GPGME_DEPRECATED;
1984 typedef gpgme_attr_t GpgmeAttr _GPGME_DEPRECATED;
1985 typedef gpgme_validity_t GpgmeValidity _GPGME_DEPRECATED;
1986 typedef gpgme_protocol_t GpgmeProtocol _GPGME_DEPRECATED;
1987 typedef gpgme_engine_info_t GpgmeEngineInfo _GPGME_DEPRECATED;
1988 typedef gpgme_subkey_t GpgmeSubkey _GPGME_DEPRECATED;
1989 typedef gpgme_key_sig_t GpgmeKeySig _GPGME_DEPRECATED;
1990 typedef gpgme_user_id_t GpgmeUserID _GPGME_DEPRECATED;
1991 typedef gpgme_key_t GpgmeKey _GPGME_DEPRECATED;
1992 typedef gpgme_passphrase_cb_t GpgmePassphraseCb _GPGME_DEPRECATED;
1993 typedef gpgme_progress_cb_t GpgmeProgressCb _GPGME_DEPRECATED;
1994 typedef gpgme_io_cb_t GpgmeIOCb _GPGME_DEPRECATED;
1995 typedef gpgme_register_io_cb_t GpgmeRegisterIOCb _GPGME_DEPRECATED;
1996 typedef gpgme_remove_io_cb_t GpgmeRemoveIOCb _GPGME_DEPRECATED;
1997 typedef gpgme_event_io_t GpgmeEventIO _GPGME_DEPRECATED;
1998 typedef gpgme_event_io_cb_t GpgmeEventIOCb _GPGME_DEPRECATED;
1999 #define GpgmeIOCbs gpgme_io_cbs
2000 typedef gpgme_data_read_cb_t GpgmeDataReadCb _GPGME_DEPRECATED;
2001 typedef gpgme_data_write_cb_t GpgmeDataWriteCb _GPGME_DEPRECATED;
2002 typedef gpgme_data_seek_cb_t GpgmeDataSeekCb _GPGME_DEPRECATED;
2003 typedef gpgme_data_release_cb_t GpgmeDataReleaseCb _GPGME_DEPRECATED;
2004 #define GpgmeDataCbs gpgme_data_cbs
2005 typedef gpgme_encrypt_result_t GpgmeEncryptResult _GPGME_DEPRECATED;
2006 typedef gpgme_sig_notation_t GpgmeSigNotation _GPGME_DEPRECATED;
2007 typedef gpgme_signature_t GpgmeSignature _GPGME_DEPRECATED;
2008 typedef gpgme_verify_result_t GpgmeVerifyResult _GPGME_DEPRECATED;
2009 typedef gpgme_import_status_t GpgmeImportStatus _GPGME_DEPRECATED;
2010 typedef gpgme_import_result_t GpgmeImportResult _GPGME_DEPRECATED;
2011 typedef gpgme_genkey_result_t GpgmeGenKeyResult _GPGME_DEPRECATED;
2012 typedef gpgme_trust_item_t GpgmeTrustItem _GPGME_DEPRECATED;
2013 typedef gpgme_status_code_t GpgmeStatusCode _GPGME_DEPRECATED;
2014
2015 #ifdef __cplusplus
2016 }
2017 #endif
2018 #endif /* GPGME_H */