doc/
[gpgme.git] / NEWS
diff --git a/NEWS b/NEWS
index 94122af..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,35 +58,40 @@ 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.
 
  Objects which used to be opaque (for example a key) are now pointers
- accessible structs, so no accessor functions are necessary.
to accessible structs, so no accessor functions are necessary.
 
  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:
    Old name:           New name:
    GpgmeCtx            gpgme_ctx_t
    GpgmeData           gpgme_data_t
-   GpgmeRecipients     gpgme_recipients_t
    GpgmeError          gpgme_error_t
    GpgmeDataEncoding   gpgme_data_encoding_t
    GpgmeSigStat                gpgme_sig_stat_t
@@ -71,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
@@ -90,12 +146,28 @@ 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.  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 has been made to the prototypes of gpgme_op_encrypt,
+   gpgme_op_encrypt_start, gpgme_op_encrypt_sign and
+   gpgme_op_encrypt_sign_start.
+
+   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
    stati.
@@ -130,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
@@ -169,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
@@ -212,14 +281,12 @@ 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:
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 GpgmeCtx                       DEPRECATED: Use gpgme_ctx_t.
 GpgmeData                      DEPRECATED: Use gpgme_data_t.
-GpgmeRecipients                        DEPRECATED: Use gpgme_recipients_t.
 GpgmeError                     DEPRECATED: Use gpgme_error_t.
 GpgmeDataEncoding              DEPRECATED: Use gpgme_data_encoding_t.
 GpgmeSigStat                   DEPRECATED: Use gpgme_sig_stat_t.
@@ -269,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.
@@ -279,18 +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
+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
@@ -300,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
@@ -337,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)