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