doc/
[gpgme.git] / NEWS
diff --git a/NEWS b/NEWS
index 71388f4..3e66093 100644 (file)
--- a/NEWS
+++ b/NEWS
@@ -1,4 +1,44 @@
-Noteworthy changes in version 0.4.1 (unreleased)
+Noteworthy changes in version 0.4.3 (unreleased)
+------------------------------------------------
+
+ * gpgme_get_key fails with GPG_ERR_AMBIGUOUS_NAME if the key ID
+   provided was not unique, instead returning the first matching key.
+
+ * gpgme_key_t and gpgme_subkey_t have a new field, can_authenticate,
+   that indicates if the key can be used for authentication.
+
+ * gpgme_signature_t's status field is now correctly set to an error
+   with error code GPG_ERR_NO_PUBKEY if public key is not found.
+
+ * gpgme_new_signature_t's class field is now an unsigned int, rather
+   than an unsigned long (the old class field is preserved for
+   backwards compatibility).
+
+ * Interface changes relative to the 0.4.3 release:
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+gpgme_get_key                  CHANGED: Fails correctly if key ID not unique.
+gpgme_key_t                    EXTENDED: New field can_authenticate.
+gpgme_subkey_t                 EXTENDED: New field can_authenticate.
+gpgme_new_signature_t          CHANGED: New type for class field.
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+
+Noteworthy changes in version 0.4.2 (2003-07-30)
+------------------------------------------------
+
+ * Allow gpg-error to be in non-standard place when linking the test suite.
+
+ * Configure will fail now if gpg-error can not be found.
+
+ * Fixed initialized memory backed data objects for writing, which
+   caused the test program to crash (but only on Mac OS, surprisingly).
+
+ * Eliminate use of C99 constructs.
+
+ * Small improvements to the manual.
+
+
+Noteworthy changes in version 0.4.1 (2003-06-06)
 ------------------------------------------------
 
  This is the release that 0.4.0 should have been.  There are many
@@ -9,7 +49,7 @@ Noteworthy changes in version 0.4.1 (unreleased)
  self-consistent.  Here is an overview on the changes:
 
  All types have been renamed to conform to the GNU coding standards,
- most of the time by keeping the whole name in lowercase and insert
+ most of the time by keeping the whole name in lowercase and inserting
  underscores between words.
 
  All operations consistently only accept input parameters in their
@@ -18,6 +58,13 @@ Noteworthy changes in version 0.4.1 (unreleased)
  afterwards by calling one of the result functions.  This unifies the
  synchronous and the asynchronous interface.
 
+ The error values have been completely replaced by a more
+ sophisticated model that allows GPGME to transparently and accurately
+ report all errors from the other GnuPG components, irregardless of
+ process boundaries.  This is achieved by using the library
+ libgpg-errors, which is shared by all GnuPG components.  This library
+ is now required for GPGME.
+
  The results of all operations are now provided by pointers to C
  structs rather than by XML structs or in other ways.
 
@@ -26,20 +73,19 @@ Noteworthy changes in version 0.4.1 (unreleased)
 
  Backward compatibility is provided where it was possible without too
  much effort and did not collide with the overall sanitization effort.
- However, it is recommended to update to the new interfaces soon, so
- the compatibility interfaces can be phased out quickly.
- Recommendations how to replace deprecated or removed functionality can
- be found within the description of each change.
+ However, this is only for ease of transition.  NO DEPRECATED FUNCTION
+ OR DATA TYPE IS CONSIDERED A PART OF THE API OR ABI AND WILL BE
+ DROPPED IN THE FUTURE WITHOUT CHANGING THE SONAME OF THE LIBRARY.
+ Recommendations how to replace deprecated or removed functionality
+ can be found within the description of each change.
 
  What follows are all changes to the interface and behaviour of GPGME
  in detail.
 
  * If gpgme.h is included in sources compiled by GCC 3.1 or later,
    deprecated attributes will warn about use of obsolete functions and
-   typedefs.  The use of obsolete error values will appear as the use
-   of an obsolete type _gpgme_deprecated_error_t.  You can suppress
-   these warnings by passing -Wno-deprecated-declarations to the gcc
-   command.
+   type definitions.  You can suppress these warnings by passing
+   -Wno-deprecated-declarations to the gcc command.
 
  * The following types have been renamed.  The old types are still
    available as aliases, but they are deprecated now:
@@ -70,6 +116,17 @@ Noteworthy changes in version 0.4.1 (unreleased)
    GpgmeTrustItem      gpgme_trust_item_t
    GpgmeStatusCode     gpgme_status_code_t
 
+ * gpgme_error_t is now identical to gpg_error_t, the error type
+   provided by libgpg-error.  More about using libgpg-error with GPGME
+   can be found in the manual.  All error symbols have been removed!
+
+ * All functions and types in libgpg-error have been wrapped in GPGME.
+   The new types are gpgme_err_code_t and gpgme_err_source_t.  The new
+   functions are gpgme_err_code, gpgme_err_source, gpgme_error,
+   gpgme_err_make, gpgme_error_from_errno, gpgme_err_make_from_errno,
+   gpgme_err_code_from_errno, gpgme_err_code_to_errno,
+   gpgme_strsource.
+
  * GPGME_ATTR_IS_SECRET is not anymore representable as a string.
 
  * GnuPG 1.2.2 is required.  The progress callback is now also invoked
@@ -89,42 +146,27 @@ Noteworthy changes in version 0.4.1 (unreleased)
 
    The return type has been changed to gpgme_error_t value.  This
    allowed to remove the gpgme_cancel function; just return
-   GPGME_Canceled in the passphrase callback directly.
+   the error code GPG_ERR_CANCELED in the passphrase callback directly.
 
  * gpgme_edit_cb_t has been changed to take a file descriptor argument.
    The user is expected to write the response to the file descriptor,
    followed by a newline.
 
- * The recipients interface has been removed and replaced by a more
-   generic and light gpgme_user_ids_* interface, which only provides
-   two functions: gpgme_user_ids_append adds a new user ID at the end
-   of the linked list, and gpgme_user_ids_release releases all user
-   IDs in the linked list.  The resulting user ID object is free for
-   the user to change (note however that gpgme_user_ids_release only
-   releases resources allocated by GPGME).
+ * The recipients interface has been removed.  Instead, you use
+   NULL-terminated lists of keys for specifying the recipients of an
+   encryption operation.  Use the new encryption flag
+   GPGME_ENCRYPT_ALWAYS_TRUST if you want to override the validity of
+   the keys (but note that in general this is not a good idea).
 
-   This change propagates to the prototypes of gpgme_op_encrypt,
+   This change has been made to the prototypes of gpgme_op_encrypt,
    gpgme_op_encrypt_start, gpgme_op_encrypt_sign and
-   gpgme_op_encrypt_sign_start.  Also the prototypes of
-   gpgme_op_export_start and gpgme_op_export finally make sense.
+   gpgme_op_encrypt_sign_start.
 
-   Here is an example how to use the new interface:
-
-   gpgme_user_id_t rset = NULL;
-   gpgme_user_id_t *rset_lastp = &rset;
-
-   err = gpgme_user_ids_append (rset_lastp, "Alpha");
-   fail_if_err (err);
-   (*rset_lastp)->validity = GPGME_VALIDITY_FULL;
-
-   rset_lastp = &(*rset_lastp)->next;
-   err = gpgme_user_ids_append (rset_lastp, "Bob");
-   fail_if_err (err);
-   (*rset_lastp)->validity = GPGME_VALIDITY_FULL;
-
-   [...]
-
-   gpgme_user_ids_release (rset);
+   The export interface has been changed to use pattern strings like
+   the keylist interface.  Thus, new functions gpgme_op_export_ext and
+   gpgme_op_export_ext_start have been added as well.  Now the
+   prototypes of gpgme_op_export_start and gpgme_op_export finally
+   make sense.
 
  * gpgme_op_verify and gpgme_op_decrypt_verify don't return a status
    summary anymore.  Use gpgme_get_sig_status to retrieve the individual
@@ -160,13 +202,10 @@ Noteworthy changes in version 0.4.1 (unreleased)
  * The new function gpgme_get_protocol_name can be used to convert a
    gpgme_protocol_t value into a string.
 
- * The status of a context operation is not checked anymore, so the
-   errors GPGME_Busy and GPGME_No_Request can not occur anymore.
-
- * For clarity and better reusability, the error codes
-   GPGME_No_Recipients, GPGME_Invalid_Recipient and
-   GPGME_No_Passphrase have been renamed to GPGME_No_UserID,
-   GPGME_Invalid_UserID and GPGME_Bad_Passphrase resp.
+ * The status of a context operation is not checked anymore.  Starting
+   a new operation will silently cancel the previous one.  Calling a
+   function that requires you to have started an operation before without
+   doing so is undefined.
 
  * The FPR argument to gpgme_op_genkey was removed.  Instead, use the
    gpgme_op_genkey_result function to retrieve a gpgme_genkey_result_t
@@ -199,7 +238,7 @@ Noteworthy changes in version 0.4.1 (unreleased)
 
  * The new gpgme_op_sign_result function provides detailed information
    about the result of a signing operation in gpgme_sign_result_t,
-   gpgme_invalid_user_id_t and gpgme_new_signature_t objects.
+   gpgme_invalid_key_t and gpgme_new_signature_t objects.
 
  * The new gpgme_op_encrypt_result function provides detailed
    information about the result of an encryption operation in
@@ -242,8 +281,7 @@ Noteworthy changes in version 0.4.1 (unreleased)
    interface, the generic gpgme_get_op_info interface is not useful
    anymore and dropped.
 
- * The error values GPGME_Invalid_Type and GPGME_Invalid_Mode can not
-   occur anymore and are thus deprecated.
+ * The type and mode of data objects is not available anymore.
 
  * Interface changes relative to the 0.4.0 release:
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -298,6 +336,18 @@ gpgme_data_release_cb_t            NEW
 gpgme_data_cbs_t               NEW
 gpgme_trust_item_t             NEW
 gpgme_status_code_t            NEW
+GPGME_{some error code}                REMOVED! Use GPG_ERR_* from libgpg-error.
+gpgme_err_code_t               NEW
+gpgme_err_source_t             NEW
+gpgme_err_code                 NEW
+gpgme_err_source               NEW
+gpgme_error                    NEW
+gpgme_err_make                 NEW
+gpgme_error_from_errno         NEW
+gpgme_err_make_from_errno      NEW
+gpgme_err_code_from_errno      NEW
+gpgme_err_code_to_errno                NEW
+gpgme_strsource                        NEW
 gpgme_io_cb_t                  CHANGED: Return type from void to GpgmeError.
 gpgme_event_io_t               CHANGED: New event type (all numbers changed).
 gpgme_passphrase_cb_t          CHANGED: Desc decomposed, write directly to FD.
@@ -308,35 +358,31 @@ gpgme_op_decrypt_verify           CHANGED: Drop R_STAT argument.
 gpgme_wait                     CHANGED: Can return NULL even if hang is true.
 GpgmeIdleFunc                   REMOVED
 gpgme_register_idle             REMOVED
-GpgmeRecipients                        REMOVED: Use gpgme_user_id_t.
-gpgme_recipients_new           REMOVED: Initialize gpgme_user_id_t with NULL.
-gpgme_recipients_release       REMOVED: Use gpgme_user_ids_release.
-gpgme_recipients_add_name      REMOVED: Use gpgme_user_ids_append
-gpgme_recipients_add_name_with_validity        REMOVED: Set validity directly.
-gpgme_recipients_count         REMOVED: You can count them yourself.
-gpgme_recipients_enum_open     REMOVED: gpgme_user_id_t is a linked list.
-gpgme_recipients_enum_read     REMOVED: See gpgme_recipients_enum_open.
-gpgme_recipients_enum_close    REMOVED: See gpgme_recipients_enum_read.
-gpgme_user_ids_append          NEW
-gpgme_user_ids_release         NEW
-gpgme_op_encrypt               CHANGED: Recipients passed as gpgme_user_id_t.
-gpgme_op_encrypt_start         CHANGED: Recipients passed as gpgme_user_id_t.
-gpgme_op_encrypt_sign          CHANGED: Recipients passed as gpgme_user_id_t.
-gpgme_op_encrypt_sign_start    CHANGED: Recipients passed as gpgme_user_id_t.
-gpgme_op_export_start          CHANGED: User IDs passed as gpgme_user_id_t.
-gpgme_op_export                        CHANGED: User IDs passed as gpgme_user_id_t.
+GpgmeRecipients                        REMOVED
+gpgme_recipients_new           REMOVED
+gpgme_recipients_release       REMOVED
+gpgme_recipients_add_name      REMOVED
+gpgme_recipients_add_name_with_validity        REMOVED
+gpgme_recipients_count         REMOVED
+gpgme_recipients_enum_open     REMOVED
+gpgme_recipients_enum_read     REMOVED
+gpgme_recipients_enum_close    REMOVED
+gpgme_encrypt_flags_t          NEW
+GPGME_ENCRYPT_ALWAYS_TRUST     NEW
+gpgme_op_encrypt               CHANGED: Recipients passed as gpgme_key_t[].
+gpgme_op_encrypt_start         CHANGED: Recipients passed as gpgme_key_t[].
+gpgme_op_encrypt_sign          CHANGED: Recipients passed as gpgme_key_t[].
+gpgme_op_encrypt_sign_start    CHANGED: Recipients passed as gpgme_key_t[].
+gpgme_op_export_start          CHANGED: User IDs passed as patterns.
+gpgme_op_export                        CHANGED: User IDs passed as patterns.
+gpgme_op_export_ext_start      NEW
+gpgme_op_export_ext            NEW
+gpgme_keylist_mode_t           NEW
+gpgme_sigsum_t                 NEW
 gpgme_engine_info_t            NEW
 gpgme_get_engine_info          CHANGED: Return info structure instead XML.
 gpgme_get_protocol_name                NEW
 gpgme_cancel                   REMOVED: Return error in callback directly.
-GPGME_Busy                     DEPRECATED: Not in use.
-GPGME_No_Request               DEPRECATED: Not in use.
-GPGME_No_Recipients            DEPRECATED: Use GPGME_No_UserID.
-GPGME_No_UserID                        NEW
-GPGME_Invalid_Recipient                DEPRECATED: Use GPGME_Invalid_UserID.
-GPGME_Invalid_UserID           NEW
-GPGME_No_Passphrase            DEPRECATED: Use GPGME_Bad_Passphrase.
-GPGME_Bad_Passphrase           NEW
 gpgme_op_genkey                        CHANGED: FPR argument dropped.
 gpgme_op_genkey_result         NEW
 gpgme_genkey_result_t          NEW
@@ -346,7 +392,7 @@ gpgme_import_status_t               NEW
 gpgme_import_result_t          NEW
 gpgme_pubkey_algo_t            NEW
 gpgme_hash_algo_t              NEW
-gpgme_invalid_user_id_t                NEW
+gpgme_invalid_key_t            NEW
 gpgme_new_signature_t          NEW
 gpgme_sign_result_t            NEW
 gpgme_op_sign_result           NEW
@@ -383,8 +429,6 @@ gpgme_key_get_as_xml                REMOVED
 gpgme_key_list_result_t                NEW
 gpgme_op_keylist_result                NEW
 gpgme_get_op_info              REMOVED
-GPGME_Invalid_Type             DEPRECATED
-GPGME_Invalid_Mode             DEPRECATED
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Noteworthy changes in version 0.4.0 (2002-12-23)