doc/
[gpgme.git] / gpgme / gpgme.h
index 3ed71a6..ed1d25b 100644 (file)
@@ -38,6 +38,8 @@ extern "C" {
 #endif
 #endif
 
+#include <gpg-error.h>
+
 \f
 /* Check for compiler features.  */
 #if __GNUC__
@@ -61,7 +63,7 @@ extern "C" {
    AM_PATH_GPGME macro) check that this header matches the installed
    library.  Warning: Do not edit the next line.  configure will do
    that for you!  */
-#define GPGME_VERSION "0.4.1"
+#define GPGME_VERSION "0.4.2"
 
 \f
 /* Some opaque data types used by GPGME.  */
@@ -75,79 +77,76 @@ typedef struct gpgme_context *gpgme_ctx_t;
 struct gpgme_data;
 typedef struct gpgme_data *gpgme_data_t;
 
-/* A list of recipients to be used in an encryption operation.  */
-struct gpgme_recipients;
-typedef struct gpgme_recipients *gpgme_recipients_t;
-
 \f
-/* Public data types provided by GPGME.  */
+/* Wrappers for the libgpg-error library.  */
+
+typedef gpg_error_t gpgme_error_t;
+typedef gpg_err_code_t gpgme_err_code_t;
+typedef gpg_err_source_t gpgme_err_source_t;
+
+
+static __inline__ gpgme_error_t
+gpgme_err_make (gpgme_err_source_t source, gpgme_err_code_t code)
+{
+  return gpg_err_make (source, code);
+}
 
-/* The error numbers used by GPGME.  */
-typedef enum
-  {
-    GPGME_EOF                     = -1,
-    GPGME_No_Error                = 0x0000,
-    GPGME_General_Error           = 0x0001,
-    GPGME_Out_Of_Core             = 0x0002,
-    GPGME_Invalid_Value           = 0x0003,
-    GPGME_Exec_Error              = 0x0004,
-    GPGME_Too_Many_Procs          = 0x0005,
-    GPGME_Pipe_Error              = 0x0006,
-    GPGME_No_Data                 = 0x0007,
-    GPGME_Conflict                = 0x0008,
-    GPGME_Not_Implemented         = 0x0009,
-    GPGME_Read_Error              = 0x000a,
-    GPGME_Write_Error             = 0x000b,
-    GPGME_File_Error              = 0x000c, /* errno is set in this case.  */
-    GPGME_Decryption_Failed       = 0x000d,
-    GPGME_Bad_Passphrase          = 0x000e,
-    GPGME_Canceled                = 0x000f,
-    GPGME_Invalid_Key             = 0x0010,
-    GPGME_Invalid_Engine          = 0x0011,
-    GPGME_No_UserID               = 0x0012,
-    GPGME_Invalid_UserID          = 0x0013,
-
-    /* Reasons for invalid user id.  */
-    GPGME_Unknown_Reason          = 0x0100,
-    GPGME_Not_Found               = 0x0101,
-    GPGME_Ambiguous_Specification = 0x0102,
-    GPGME_Wrong_Key_Usage         = 0x0103,
-    GPGME_Key_Revoked             = 0x0104,
-    GPGME_Key_Expired             = 0x0105,
-    GPGME_No_CRL_Known            = 0x0106,
-    GPGME_CRL_Too_Old             = 0x0107,
-    GPGME_Policy_Mismatch         = 0x0108,
-    GPGME_No_Secret_Key           = 0x0109,
-    GPGME_Key_Not_Trusted         = 0x010a,
-    
-    /* Import problems.  */
-    GPGME_Issuer_Missing          = 0x0200,
-    GPGME_Chain_Too_Long          = 0x0201,
-
-    /* Verification problems.  */
-    GPGME_Unsupported_Algorithm   = 0x0300,
-    GPGME_Sig_Expired             = 0x0301,
-    GPGME_Bad_Signature           = 0x0302,
-    GPGME_No_Public_Key           = 0x0303,
-
-    /* Deprecated, see below.  */
-    GPGME_x_Busy         = -2,
-    GPGME_x_No_Request   = -3,
-    GPGME_x_Invalid_Type = -4,
-    GPGME_x_Invalid_Mode = -5
-  }
-gpgme_error_t;
 
-typedef gpgme_error_t _gpgme_deprecated_error_t _GPGME_DEPRECATED;
+/* The user can define GPG_ERR_SOURCE_DEFAULT before including this
+   file to specify a default source for gpg_error.  */
+#ifndef GPGME_ERR_SOURCE_DEFAULT
+#define GPGME_ERR_SOURCE_DEFAULT  GPG_ERR_SOURCE_USER_1
+#endif
+
+static __inline__ gpgme_error_t
+gpgme_error (gpgme_err_code_t code)
+{
+  return gpgme_err_make (GPGME_ERR_SOURCE_DEFAULT, code);
+}
+
+
+static __inline__ gpgme_err_code_t
+gpgme_err_code (gpgme_error_t err)
+{
+  return gpg_err_code (err);
+}
 
-#define GPGME_Busy         ((_gpgme_deprecated_error_t) GPGME_x_Busy)
-#define GPGME_No_Request    ((_gpgme_deprecated_error_t) GPGME_x_No_Request)
-#define GPGME_Invalid_Type  ((_gpgme_deprecated_error_t) GPGME_x_Invalid_Type)
-#define GPGME_Invalid_Mode  ((_gpgme_deprecated_error_t) GPGME_x_Invalid_Mode)
-#define GPGME_No_Recipients ((_gpgme_deprecated_error_t) GPGME_No_UserID)
-#define GPGME_Invalid_Recipients \
-  ((_gpgme_deprecated_error_t) GPGME_Invalid_UserID)
-#define GPGME_No_Passphrase ((_gpgme_deprecated_error_t) GPGME_Bad_Passphrase)
+
+static __inline__ gpgme_err_source_t
+gpgme_err_source (gpgme_error_t err)
+{
+  return gpg_err_source (err);
+}
+
+
+/* Return a pointer to a string containing a description of the error
+   code in the error value ERR.  */
+const char *gpgme_strerror (gpgme_error_t err);
+
+
+/* Return a pointer to a string containing a description of the error
+   source in the error value ERR.  */
+const char *gpgme_strsource (gpgme_error_t err);
+
+
+/* Retrieve the error code for the system error ERR.  This returns
+   GPG_ERR_UNKNOWN_ERRNO if the system error is not mapped (report
+   this).  */
+gpgme_err_code_t gpgme_err_code_from_errno (int err);
+
+
+/* Retrieve the system error for the error code CODE.  This returns 0
+   if CODE is not a system error code.  */
+int gpgme_err_code_to_errno (gpgme_err_code_t code);
+
+  
+/* Return an error value with the error source SOURCE and the system
+   error ERR.  */
+gpgme_error_t gpgme_err_make_from_errno (gpgme_err_source_t source, int err);
+
+
+/* Return an error value with the system error ERR.  */
+gpgme_err_code_t gpgme_error_from_errno (int err);
 
 \f
 /* The possible encoding mode of gpgme_data_t objects.  */
@@ -422,8 +421,11 @@ struct _gpgme_subkey
   /* True if subkey is secret.  */
   unsigned int secret : 1;
 
+  /* True if subkey can be used for authentication.  */
+  unsigned int can_authenticate : 1;
+
   /* Internal to GPGME, do not use.  */
-  unsigned int _unused : 24;
+  unsigned int _unused : 23;
   
   /* Public key algorithm supported by this subkey.  */
   gpgme_pubkey_algo_t pubkey_algo;
@@ -573,8 +575,11 @@ struct _gpgme_key
   /* True if key is secret.  */
   unsigned int secret : 1;
 
+  /* True if key can be used for authentication.  */
+  unsigned int can_authenticate : 1;
+
   /* Internal to GPGME, do not use.  */
-  unsigned int _unused : 24;
+  unsigned int _unused : 23;
 
   /* This is the protocol supported by this key.  */
   gpgme_protocol_t protocol;
@@ -665,18 +670,20 @@ void gpgme_set_include_certs (gpgme_ctx_t ctx, int nr_of_certs);
 int gpgme_get_include_certs (gpgme_ctx_t ctx);
 
 /* The available keylist mode flags.  */
-enum
+typedef enum
   {
     GPGME_KEYLIST_MODE_LOCAL  = 1,
     GPGME_KEYLIST_MODE_EXTERN = 2,
     GPGME_KEYLIST_MODE_SIGS   = 4
-  };
+  }
+gpgme_keylist_mode_t;
 
 /* Set keylist mode in CTX to MODE.  */
-gpgme_error_t gpgme_set_keylist_mode (gpgme_ctx_t ctx, int mode);
+gpgme_error_t gpgme_set_keylist_mode (gpgme_ctx_t ctx,
+                                     gpgme_keylist_mode_t mode);
 
 /* Get keylist mode in CTX.  */
-int gpgme_get_keylist_mode (gpgme_ctx_t ctx);
+gpgme_keylist_mode_t gpgme_get_keylist_mode (gpgme_ctx_t ctx);
 
 /* Set the passphrase callback function in CTX to CB.  HOOK_VALUE is
    passed as first argument to the passphrase callback function.  */
@@ -763,10 +770,14 @@ typedef gpgme_error_t (*gpgme_register_io_cb_t) (void *data, int fd, int dir,
    function.  */
 typedef void (*gpgme_remove_io_cb_t) (void *tag);
 
-typedef enum { GPGME_EVENT_START,
-              GPGME_EVENT_DONE,
-              GPGME_EVENT_NEXT_KEY,
-              GPGME_EVENT_NEXT_TRUSTITEM } gpgme_event_io_t;
+typedef enum
+  {
+    GPGME_EVENT_START,
+    GPGME_EVENT_DONE,
+    GPGME_EVENT_NEXT_KEY,
+    GPGME_EVENT_NEXT_TRUSTITEM
+  }
+gpgme_event_io_t;
 
 /* The type of a function that is called when a context finished an
    operation.  */
@@ -794,40 +805,6 @@ void gpgme_get_io_cbs (gpgme_ctx_t ctx, gpgme_io_cbs_t io_cbs);
 gpgme_ctx_t gpgme_wait (gpgme_ctx_t ctx, gpgme_error_t *status, int hang);
 
 \f
-/* Functions to handle recipients.  */
-
-/* Create a new recipients set and return it in R_RSET.  */
-gpgme_error_t gpgme_recipients_new (gpgme_recipients_t *r_rset);
-
-/* Release the recipients set RSET.  */
-void gpgme_recipients_release (gpgme_recipients_t rset);
-
-/* Add NAME to the recipients set RSET.  */
-gpgme_error_t gpgme_recipients_add_name (gpgme_recipients_t rset, const char *name);
-
-/* Add NAME with validity AL to the recipients set RSET.  */
-gpgme_error_t gpgme_recipients_add_name_with_validity (gpgme_recipients_t rset,
-                                                      const char *name,
-                                                      gpgme_validity_t val);
-
-/* Return the number of recipients in RSET.  */
-unsigned int gpgme_recipients_count (const gpgme_recipients_t rset);
-
-/* Create a new enumeration handle for the recipients set RSET and
-   return it in ITER.  */
-gpgme_error_t gpgme_recipients_enum_open (const gpgme_recipients_t rset,
-                                         void **iter);
-
-/* Return the next recipient from the recipient set RSET in the
-   enumerator ITER.  */
-const char *gpgme_recipients_enum_read (const gpgme_recipients_t rset,
-                                       void **iter);
-
-/* Destroy the enumerator ITER for the recipient set RSET.  */
-gpgme_error_t gpgme_recipients_enum_close (const gpgme_recipients_t rset,
-                                          void **iter);
-
-\f
 /* Functions to handle data objects.  */
 
 /* Read up to SIZE bytes into buffer BUFFER from the data object with
@@ -989,41 +966,52 @@ unsigned long gpgme_key_sig_get_ulong_attr (gpgme_key_t key, int uid_idx,
 \f
 /* Crypto Operations.  */
 
-struct _gpgme_invalid_user_id
+struct _gpgme_invalid_key
 {
-  struct _gpgme_invalid_user_id *next;
-  char *id;
+  struct _gpgme_invalid_key *next;
+  char *fpr;
   gpgme_error_t reason;
 };
-typedef struct _gpgme_invalid_user_id *gpgme_invalid_user_id_t;
+typedef struct _gpgme_invalid_key *gpgme_invalid_key_t;
 
 \f
 /* Encryption.  */
 struct _gpgme_op_encrypt_result
 {
   /* The list of invalid recipients.  */
-  gpgme_invalid_user_id_t invalid_recipients;
+  gpgme_invalid_key_t invalid_recipients;
 };
 typedef struct _gpgme_op_encrypt_result *gpgme_encrypt_result_t;
 
 /* Retrieve a pointer to the result of the encrypt operation.  */
 gpgme_encrypt_result_t gpgme_op_encrypt_result (gpgme_ctx_t ctx);
 
+/* The valid encryption flags.  */
+typedef enum
+  {
+    GPGME_ENCRYPT_ALWAYS_TRUST = 1
+  }
+gpgme_encrypt_flags_t;
+
 /* Encrypt plaintext PLAIN within CTX for the recipients RECP and
    store the resulting ciphertext in CIPHER.  */
-gpgme_error_t gpgme_op_encrypt_start (gpgme_ctx_t ctx, gpgme_recipients_t recp,
+gpgme_error_t gpgme_op_encrypt_start (gpgme_ctx_t ctx, gpgme_key_t recp[],
+                                     gpgme_encrypt_flags_t flags,
                                      gpgme_data_t plain, gpgme_data_t cipher);
-gpgme_error_t gpgme_op_encrypt (gpgme_ctx_t ctx, gpgme_recipients_t recp,
+gpgme_error_t gpgme_op_encrypt (gpgme_ctx_t ctx, gpgme_key_t recp[],
+                               gpgme_encrypt_flags_t flags,
                                gpgme_data_t plain, gpgme_data_t cipher);
 
 /* Encrypt plaintext PLAIN within CTX for the recipients RECP and
    store the resulting ciphertext in CIPHER.  Also sign the ciphertext
    with the signers in CTX.  */
 gpgme_error_t gpgme_op_encrypt_sign_start (gpgme_ctx_t ctx,
-                                          gpgme_recipients_t recp,
+                                          gpgme_key_t recp[],
+                                          gpgme_encrypt_flags_t flags,
                                           gpgme_data_t plain,
                                           gpgme_data_t cipher);
-gpgme_error_t gpgme_op_encrypt_sign (gpgme_ctx_t ctx, gpgme_recipients_t recp,
+gpgme_error_t gpgme_op_encrypt_sign (gpgme_ctx_t ctx, gpgme_key_t recp[],
+                                    gpgme_encrypt_flags_t flags,
                                     gpgme_data_t plain, gpgme_data_t cipher);
 
 \f
@@ -1057,19 +1045,35 @@ gpgme_error_t gpgme_op_decrypt_verify (gpgme_ctx_t ctx, gpgme_data_t cipher,
 struct _gpgme_new_signature
 {
   struct _gpgme_new_signature *next;
+
+  /* The type of the signature.  */
   gpgme_sig_mode_t type;
+
+  /* The public key algorithm used to create the signature.  */
   gpgme_pubkey_algo_t pubkey_algo;
+
+  /* The hash algorithm used to create the signature.  */
   gpgme_hash_algo_t hash_algo;
-  unsigned long class;
+
+  /* Internal to GPGME, do not use.  Must be set to the same value as
+     CLASS below.  */
+  unsigned long _obsolete_class;
+
+  /* Signature creation time.  */
   long int timestamp;
+
+  /* The fingerprint of the signature.  */
   char *fpr;
+
+  /* Crypto backend specific signature class.  */
+  unsigned int class;
 };
 typedef struct _gpgme_new_signature *gpgme_new_signature_t;
 
 struct _gpgme_op_sign_result
 {
   /* The list of invalid signers.  */
-  gpgme_invalid_user_id_t invalid_signers;
+  gpgme_invalid_key_t invalid_signers;
   gpgme_new_signature_t signatures;
 };
 typedef struct _gpgme_op_sign_result *gpgme_sign_result_t;
@@ -1099,7 +1103,7 @@ struct _gpgme_sig_notation
 typedef struct _gpgme_sig_notation *gpgme_sig_notation_t;
 
 /* Flags used for the SUMMARY field in a gpgme_signature_t.  */
-enum
+typedef enum
   {
     GPGME_SIGSUM_VALID       = 0x0001,  /* The signature is fully valid.  */
     GPGME_SIGSUM_GREEN       = 0x0002,  /* The signature is good.  */
@@ -1112,14 +1116,15 @@ enum
     GPGME_SIGSUM_CRL_TOO_OLD = 0x0200,  /* Available CRL is too old.  */
     GPGME_SIGSUM_BAD_POLICY  = 0x0400,  /* A policy was not met.  */
     GPGME_SIGSUM_SYS_ERROR   = 0x0800   /* A system error occured.  */
-  };
+  }
+gpgme_sigsum_t;
 
 struct _gpgme_signature
 {
   struct _gpgme_signature *next;
 
   /* A summary of the signature status.  */
-  unsigned int summary;
+  gpgme_sigsum_t summary;
 
   /* The fingerprint or key ID of the signature.  */
   char *fpr;
@@ -1240,6 +1245,9 @@ struct _gpgme_op_import_result
   /* Number of secret keys unchanged.  */
   int secret_unchanged;
 
+  /* Number of new keys skipped.  */
+  int skipped_new_keys;
+
   /* Number of keys not imported.  */
   int not_imported;
 
@@ -1258,11 +1266,20 @@ gpgme_error_t gpgme_op_import_ext (gpgme_ctx_t ctx, gpgme_data_t keydata,
                                   int *nr) _GPGME_DEPRECATED;
 
 \f
-/* Export the keys listed in RECP into KEYDATA.  */
-gpgme_error_t gpgme_op_export_start (gpgme_ctx_t ctx, gpgme_recipients_t recp,
+/* Export the keys found by PATTERN into KEYDATA.  */
+gpgme_error_t gpgme_op_export_start (gpgme_ctx_t ctx, const char *pattern,
+                                    unsigned int reserved,
                                     gpgme_data_t keydata);
-gpgme_error_t gpgme_op_export (gpgme_ctx_t ctx, gpgme_recipients_t recp,
-                              gpgme_data_t keydata);
+gpgme_error_t gpgme_op_export (gpgme_ctx_t ctx, const char *pattern,
+                              unsigned int reserved, gpgme_data_t keydata);
+
+gpgme_error_t gpgme_op_export_ext_start (gpgme_ctx_t ctx,
+                                        const char *pattern[],
+                                        unsigned int reserved,
+                                        gpgme_data_t keydata);
+gpgme_error_t gpgme_op_export_ext (gpgme_ctx_t ctx, const char *pattern[],
+                                  unsigned int reserved,
+                                  gpgme_data_t keydata);
 
 \f
 /* Key generation.  */
@@ -1312,7 +1329,7 @@ gpgme_error_t gpgme_op_edit (gpgme_ctx_t ctx, gpgme_key_t key,
                             gpgme_data_t out);
 
 \f
-/* Key management functions */
+/* Key management functions */
 struct _gpgme_op_keylist_result
 {
   unsigned int truncated : 1;
@@ -1425,9 +1442,6 @@ const char *gpgme_check_version (const char *req_version);
 /* Retrieve information about the backend engines.  */
 gpgme_error_t gpgme_get_engine_info (gpgme_engine_info_t *engine_info);
 
-/* Return a string describing ERR.  */
-const char *gpgme_strerror (gpgme_error_t err);
-
 \f
 /* Engine support functions.  */
 
@@ -1439,7 +1453,6 @@ gpgme_error_t gpgme_engine_check_version (gpgme_protocol_t proto);
 /* Deprecated types.  */
 typedef gpgme_ctx_t GpgmeCtx _GPGME_DEPRECATED;
 typedef gpgme_data_t GpgmeData _GPGME_DEPRECATED;
-typedef gpgme_recipients_t GpgmeRecipients _GPGME_DEPRECATED;
 typedef gpgme_error_t GpgmeError _GPGME_DEPRECATED;
 typedef gpgme_data_encoding_t GpgmeDataEncoding _GPGME_DEPRECATED;
 typedef gpgme_pubkey_algo_t GpgmePubKeyAlgo _GPGME_DEPRECATED;
@@ -1467,7 +1480,6 @@ typedef gpgme_data_write_cb_t GpgmeDataWriteCb _GPGME_DEPRECATED;
 typedef gpgme_data_seek_cb_t GpgmeDataSeekCb _GPGME_DEPRECATED;
 typedef gpgme_data_release_cb_t GpgmeDataReleaseCb _GPGME_DEPRECATED;
 #define GpgmeDataCbs gpgme_data_cbs
-typedef gpgme_invalid_user_id_t GpgmeInvalidUserID _GPGME_DEPRECATED;
 typedef gpgme_encrypt_result_t GpgmeEncryptResult _GPGME_DEPRECATED;
 typedef gpgme_sig_notation_t GpgmeSigNotation _GPGME_DEPRECATED;
 typedef        gpgme_signature_t GpgmeSignature _GPGME_DEPRECATED;