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