README.apichanges
1README.apichanges 2003-07-28
2
3 NOTE: THESE ARE API CHANGES DONE BEFORE THE FIRST STABLE RELEASE SO
4 THEY ARE NOT RELEVANT ANYMORE [stable is 1.2.4 right now]
5
6We decided to change a couple of annoying things in Libgcrypt and to
7cleanup the API. The new API better fits into a multi-threaded
8environment and is more consistent. One import change is that all
9functions return error codes from a set of error codes shared between
10GnuPG, GPGME and Libgcrypt.
11
12This file contains some hints on how to port your application from
13libgcrypt <= 1.1.12 to the current API as of 1.1.42. We hope that
14there won't be another need for such a major change.
15
16
17* Types
18
19 All types definitions changed to a foo_t scheme; for some time we
20 will support the old names but you better start to rename them:
21
22 s/GCRY_MPI/gcry_mpi_t/
23 s/GcryMPI/gcry_mpi_t/
24 s/GCRY_SEXP/gcry_sexp_t/
25 s/GcrySexp/gcry_sexp_t/
26 s/GCRY_CIPHER_HD/gcry_cipher_hd_t/
27 s/GcryCipherHd/gcry_cipher_hd_t/
28 s/GCRY_MD_HD/gcry_md_hd_t/
29 s/GcryMDHd/gcry_md_hd_t/
30
31* Initialization
32
33 For proper initialization of the library, you must call
34 gcry_check_version() before calling any other function except for
35 these gcry_control operations:
36 GCRYCTL_SUSPEND_SECMEM_WARN
37 GCRYCTL_DISABLE_INTERNAL_LOCKING
38 GCRYCTL_ANY_INITIALIZATION_P
39 GCRYCTL_INITIALIZATION_FINISHED_P
40
41
42* Handles
43
44 gcry_cipher_open and gcry_md_open do now return an error code
45 instead of a NULL handle; the handle is now returned by
46 asigning it to the first argument. Example on how to change your
47 code:
48
49 Old:
50
51 hd = gcry_md_open (algo, flags);
52 if (!hd)
53 {
54 fprintf (stderr, "md_open failed: %s\n", gcry_errno (-1));
55 ....
56
57 New:
58
59 rc = gcry_md_open (&hd, algo, flags);
60 if (rc)
61 {
62 fprintf (stderr, "md_open failed: %s\n", gcry_strerror (rc));
63 ....
64
65 If you are not interested in the error code, you can do it in a
66 simplified way:
67
68 gcry_md_open (&hd, algo, flags);
69 if (!hd)
70 abort ();
71
72 i.e. the function makes sure that HD points to NULL in case of an error.
73 The required change for gcry_cipher_open is similar.
74
75* Message Digests
76
77 The order of the arguments to gcry_md_copy has been changed in order
78 to be more consistent with other functions of this type. This means
79 that the new message digest handle will be a copy of the message
80 handle specified by the second argument and stored at the address
81 pointed to by the first argument.
82
83* Error codes
84
85 gcry_errno () has been removed because it is hard to use in
86 multi-threaded environment. You need to save the error code
87 returned by the functions and use it either numerical or passing it
88 to gcry_strerror (since gcry_strerror is a wrapper function for
89 gpg_strerror, the latter function can also be used).
90
91 Instead of using the error codes GCRYERR_*, you have to use the
92 GPG_ERR_* names.
93
94* S-expressions
95
96 gcry_sexp_canon_len used to return a `historical' error code in
97 `errcode', this is not the case anymore; the value returned in
98 `errcode' is now a standard Libgcrypt (i.e. gpg-error) error code.
99
100* MPI
101
102 gcry_mpi_scan and gcry_mpi_print need the size of a provided buffer
103 as input and return the number of bytes actually scanned/printed to
104 the user. The old API used a single size_t Pointer for both tasks,
105 the new API distinguishes between the input and the output values.
106
107* Public Key cryptography
108
109 gcry_pk_decrypt used to return a `simple S-expression part' that
110 contains a single MPI value. In case the `data' S-expression
111 contains a `flags' element, the result S-expression is filled with a
112 complete S-expression of the following format:
113
114 (value PLAINTEXT)
115
116
