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