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