New file with hints on changing applications for the new API.
[libgcrypt.git] / README.apichanges
1 README.apichanges 2003-07-27
2
3
4 We decided to change a couple of annoying things in Libgcrypt and to
5 cleanup the API.  The new API better fits into a multi-threaded
6 envronment and is more consistent.  One import change is that all
7 functions return error codes from a set of error codes shared between
8 gnupg, gpgme and libgcrypt.
9
10 Here are some hints on how to port your application from libgcrypt <=
11 1.1.13 to the current API as of 1.1.42.  We hope that there won't be
12 another need for such a major change.
13
14
15 * Types
16
17   All types definitions changed to a foo_t scheme; for some time we
18   will support the old names but you better start to rename them:
19
20   s/GCRY_MPI/gcry_mpi_t/
21   s/GcryMPI/gcry_mpi_t/
22   s/GCRY_SEXP/gcry_sexp_t/
23   s/GcrySexp/gcry_sexp_t/
24   s/GCRY_CIPHER_HD/gcry_cipher_hd_t/
25   s/GcryCipherHd/gcry_cipher_hd_t/
26   s/GCRY_MD_HD/gcry_md_hd_t/
27   s/GcryMDHd/gcry_md_hd_t/
28
29 * Handles
30
31   gcry_cipher_open and gcry_md_open do now return an error code and
32   not a NULL ahandle on return.  The handle is now returned by
33   asigning it to the first argument.  Example on how to change your
34   code:
35
36   Old:
37
38     hd = gcry_md_open (algo, flags);
39     if (!hd)
40       {
41          fprintf (stderr, "md_open failed: %s\n", gcry_errno (-1));
42          ....
43
44   New:
45
46     rc = gcry_md_open (&hd, algo, flags);
47     if (rc)
48       {
49          fprintf (stderr, "md_open failed: %s\n", gcry_strerror (rc));
50          ....
51
52   If you are not interested in the error code, you can do it in a
53   simplified way:
54  
55     gcry_md_open (&hd, algo, flags);
56     if (!hd)
57         abort ();
58
59   i.e. the function makes sure that HD points to NULL in case of an error.
60   The required change for gcry_cipher_open is similar.
61
62
63 * Error codes
64
65   gcry_errno () has been removed because it is hard to use in
66   multi-threaded environment.  You need to save the error code
67   returned by the functions and use it either numerical or passing it
68   to gcry_strerror (gpg_strerror can also be used becuase the error
69   codes are syncronized with libgpg-error).
70
71
72
73 ....
74