[gnutls-dev] API comment

[Simon Josefsson]

typedef int gnutls_certificate_client_callback_func(GNUTLS_STATE, const 
gnutls_datum *, int, const gnutls_datum *, int);
typedef int gnutls_certificate_server_callback_func(GNUTLS_STATE, const 
gnutls_datum *, int);
...
void gnutls_certificate_client_set_select_func( GNUTLS_CERTIFICATE_CREDENTIALS, 
gnutls_certificate_client_callback_func *);
void gnutls_certificate_server_set_select_func( GNUTLS_CERTIFICATE_CREDENTIALS, 
gnutls_certificate_server_callback_func *);

It is difficult to use these callbacks in a multithreaded application,
and even single threaded applications with multiple connections, since
it is difficult for the invoked callback to know from where it was
called.  You need a global variable, containing e.g. GNUTLS_STATE*,
mapping to the application-specific structure for each connections
that the callback should use as context.

Solution: Do like all other TLS libraries, add a `void*' argument to
the callback, which is passed unmodified from the set-callback
function back to the calling application.  The application can use it
to store whatever context information it wants:

typedef int gnutls_certificate_client_callback_func(GNUTLS_STATE, const 
gnutls_datum *, int, const gnutls_datum *, int, void *);
typedef int gnutls_certificate_server_callback_func(GNUTLS_STATE, const 
gnutls_datum *, int, void *);
...
void gnutls_certificate_client_set_select_func( GNUTLS_CERTIFICATE_CREDENTIALS, 
gnutls_certificate_client_callback_func *, void *);
void gnutls_certificate_server_set_select_func( GNUTLS_CERTIFICATE_CREDENTIALS, 
gnutls_certificate_server_callback_func *, void *);