src/gpgme.h.in

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