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