* global.c (gcry_control): Add GCRYCTL_SET_RANDOM_SEED_FILE and
[libgcrypt.git] / README.apichanges
index edd1c44..04f04ce 100644 (file)
@@ -1,15 +1,15 @@
-README.apichanges 2003-07-27
+README.apichanges 2003-07-28
 
 
 We decided to change a couple of annoying things in Libgcrypt and to
 cleanup the API.  The new API better fits into a multi-threaded
-envronment and is more consistent.  One import change is that all
+environment and is more consistent.  One import change is that all
 functions return error codes from a set of error codes shared between
-gnupg, gpgme and libgcrypt.
+GnuPG, GPGME and Libgcrypt.
 
-Here are some hints on how to port your application from libgcrypt <=
-1.1.13 to the current API as of 1.1.42.  We hope that there won't be
-another need for such a major change.
+This file contains some hints on how to port your application from
+libgcrypt <= 1.1.12 to the current API as of 1.1.42.  We hope that
+there won't be another need for such a major change.
 
 
 * Types
@@ -26,10 +26,15 @@ another need for such a major change.
   s/GCRY_MD_HD/gcry_md_hd_t/
   s/GcryMDHd/gcry_md_hd_t/
 
+* Initialization
+
+  For proper initialization of the library, you must call
+  gcry_check_version() before calling any other function.
+
 * Handles
 
-  gcry_cipher_open and gcry_md_open do now return an error code and
-  not a NULL ahandle on return.  The handle is now returned by
+  gcry_cipher_open and gcry_md_open do now return an error code
+  instead of a NULL handle; the handle is now returned by
   asigning it to the first argument.  Example on how to change your
   code:
 
@@ -59,16 +64,43 @@ another need for such a major change.
   i.e. the function makes sure that HD points to NULL in case of an error.
   The required change for gcry_cipher_open is similar.
 
+* Message Digests
+
+  The order of the arguments to gcry_md_copy has been changed in order
+  to be more consistent with other functions of this type.  This means
+  that the new message digest handle will be a copy of the message
+  handle specified by the second argument and stored at the address
+  pointed to by the first argument.
 
 * Error codes
 
   gcry_errno () has been removed because it is hard to use in
   multi-threaded environment.  You need to save the error code
   returned by the functions and use it either numerical or passing it
-  to gcry_strerror (gpg_strerror can also be used becuase the error
-  codes are syncronized with libgpg-error).
+  to gcry_strerror (since gcry_strerror is a wrapper function for
+  gpg_strerror, the latter function can also be used).
+
+  Instead of using the error codes GCRYERR_*, you have to use the
+  GPG_ERR_* names.
+
+* S-expressions
+
+  gcry_sexp_canon_len used to return a `historical' error code in
+  `errcode', this is not the case anymore; the value returned in
+  `errcode' is a simple Libgcrypt error code.
+
+* MPI
 
+  gcry_mpi_scan and gcry_mpi_print need the size of a provided buffer
+  as input and return the number of bytes actually scanned/printed to
+  the user.  The old API used a single size_t Pointer for both tasks,
+  the new API distinguishes between the input and the output values.
 
+* Public Key cryptography
 
-....
+  gcry_pk_decrypt used to return a `simple S-expression part' that
+  contains a single MPI value.  In case the `data' S-expression
+  contains a `flags' element, the result S-expression is filled with a
+  complete S-expression of the following format:
 
+    (value PLAINTEXT)