New file with hints on changing applications for the new API.

unfinished....

3 files changed, 76 insertions, 2 deletions

diff --git a/Makefile.am b/Makefile.am
index 49cc5788..663bbb56 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -20,7 +20,7 @@
 
 DIST_SUBDIRS = mpi cipher src doc tests w32-dll
 SUBDIRS = mpi cipher src doc tests
-EXTRA_DIST = README-alpha BUGS autogen.sh COPYING.DOC
+EXTRA_DIST = README-alpha BUGS autogen.sh COPYING.DOC README.apichanges
 DISTCLEANFILES = gcrypt-defs.h 
 
 
diff --git a/README b/README
index 9a401494..abde09e7 100644
--- a/README
+++ b/README
@@ -1,6 +1,6 @@
 		    libgcrypt - The GNU crypto library
 		   ------------------------------------
-  			    Version 1.1.13-cvs
+  			    Version 1.1.42
 
     Copyright 2000, 2002, 2003 Free Software Foundation, Inc.
 
diff --git a/README.apichanges b/README.apichanges
new file mode 100644
index 00000000..edd1c44e
--- /dev/null
+++ b/README.apichanges
@@ -0,0 +1,74 @@
+README.apichanges 2003-07-27
+
+
+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
+functions return error codes from a set of error codes shared between
+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.
+
+
+* Types
+
+  All types definitions changed to a foo_t scheme; for some time we
+  will support the old names but you better start to rename them:
+
+  s/GCRY_MPI/gcry_mpi_t/
+  s/GcryMPI/gcry_mpi_t/
+  s/GCRY_SEXP/gcry_sexp_t/
+  s/GcrySexp/gcry_sexp_t/
+  s/GCRY_CIPHER_HD/gcry_cipher_hd_t/
+  s/GcryCipherHd/gcry_cipher_hd_t/
+  s/GCRY_MD_HD/gcry_md_hd_t/
+  s/GcryMDHd/gcry_md_hd_t/
+
+* 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
+  asigning it to the first argument.  Example on how to change your
+  code:
+
+  Old:
+
+    hd = gcry_md_open (algo, flags);
+    if (!hd)
+      {
+         fprintf (stderr, "md_open failed: %s\n", gcry_errno (-1));
+         ....
+
+  New:
+
+    rc = gcry_md_open (&hd, algo, flags);
+    if (rc)
+      {
+         fprintf (stderr, "md_open failed: %s\n", gcry_strerror (rc));
+         ....
+
+  If you are not interested in the error code, you can do it in a
+  simplified way:
+ 
+    gcry_md_open (&hd, algo, flags);
+    if (!hd)
+        abort ();
+
+  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.
+
+
+* 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).
+
+
+
+....
+