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