Initial release, version 0.0.0.
[gsasl.git] / doc / gsasl-callback-client-service.texi
blob866e7b121d6988b15075cb239464886af58356d3
1 @deftypefn Prototype int (*Gsasl_client_callback_service) (Gsasl_session_ctx * @var{ctx}, char * @var{service}, size_t * @var{servicelen}, char * @var{hostname}, size_t * @var{hostnamelen}, char * @var{servicename}, size_t * @var{servicenamelen})
3 @var{ctx}:  libgsasl handle.
5 @var{service}:  output array with name of service.
7 @var{servicelen}: on input the maximum size of the service output array,
8 on output contains the actual size of the service output array.
10 @var{hostname}:  output array with hostname of server.
12 @var{hostnamelen}: on input the maximum size of the hostname output
13 array, on output contains the actual size of the hostname output
14 array.
16 @var{servicename}: output array with generic name of server in case of
17 replication (DIGEST-MD5 only).
19 @var{servicenamelen}: on input the maximum size of the servicename
20 output array, on output contains the actual size of the servicename
21 output array.
23 Type of callback function the application implements.  It should
24 retrieve the service (which should be a registered GSSAPI host based
25 service name, such as ``imap'') on the server, hostname of server
26 (usually canoncial DNS hostname) and optionally generic service name
27 of server in case of replication (e.g. ``mail.example.org'' when the
28 hostname is ``mx42.example.org'', see the RFC 2831 for more
29 information).  It should return GSASL_OK, or an error such as
30 GSASL_AUTHENTICATION_ERROR if it fails.
32 If SERVICE, HOSTNAME or SERVICENAME is NULL, the function should only
33 populate SERVICELEN, HOSTNAMELEN or SERVICENAMELEN with the output
34 length of the respective field, and return GSASL_OK.  This usage may
35 be used by the caller to allocate the proper buffer size.
36 Furthermore, SERVICENAMELEN may also be NULL, indicating that the
37 mechanism is not interested in this field.
39 @end deftypefn