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