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