README.apichanges 2003-07-28

  NOTE: THESE ARE API CHANGES DONE BEFORE THE FIRST STABLE RELEASE SO
  THEY ARE NOT RELEVANT ANYMORE [stable is 1.2.4 right now]

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
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.

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

  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/

* Initialization

  For proper initialization of the library, you must call
  gcry_check_version() before calling any other function except for
  these gcry_control operations:
     GCRYCTL_SUSPEND_SECMEM_WARN
     GCRYCTL_DISABLE_INTERNAL_LOCKING
     GCRYCTL_ANY_INITIALIZATION_P
     GCRYCTL_INITIALIZATION_FINISHED_P


* Handles

  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:

  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.

* 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 (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 now a standard Libgcrypt (i.e. gpg-error) 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)