Re: RFC: SASL client library - API

[Mateusz Kocielski <m.kocielski%gmail.com@localhost>]

Sorry for the double post, but it seems that something went wrong. I've
decided to resend the message.

 I'm going to work with christos@ and agc@ on the SASL client library during
the Google Summer of Code, more detailed information about the project is
avaiable at [1]. Below I present draft of the API [2], I'd really appreciate
yours comments or suggestions on my proposal.

References:
[1] http://shm.hard-core.pl/sasl.txt
[2] http://shm.hard-core.pl/libsaslc.3

*snip*
NAME
     saslc create, saslc configure, saslc getprop, saslc setprop, saslc cont,
     saslc destroy, saslc geterror - SASL client library

SYNOPSIS
     #include <saslc.h>

     saslc session t
     saslc create(void);

     int
     saslc configure(saslc session t *sess, const char *mechs,
             const char *configuration);

     void *
     saslc getprop(const saslc session t *sess, const char *attr);

     int
     saslc setprop(saslc session t *sess, const char *attr, const void *var);

     int
     saslc cont(saslc session t *sess, const void *in, const size t inlen,
             void **out, size t *outlen);

     void
     saslc destroy(saslc session t *sess);

     const char *
     saslc geterror(const saslc session t *sess);

DESCRIPTION
     The saslc create() function creates a new SASL session. Function returns
     a pointer to a new session, or NULL if there was error.

     The saslc configure() function configures sess to use one of the mecha-
     nisms listed in mechs string which consists of a comma separated list of
     mechanism names.  Configuration options are defined in the configuration
     file, or NULL for the default settings. It returns 0 on success and -1 on
     failure.

     The saslc getattr() function gets a property from the session. It returns
     pointer to a property on success, or NULL on failure.

     The saslc setattr() function sets a property in the session. It returns 0
     on success and -1 on failure.

     The saslc cont() function performs one step of the SASL authentication.
     Input data of length inlen is passed in the in argument. Function stores
     output of length outlen in the out argument and returns 0 on success, 1
     if more steps of the SASL authentication is needed and -1 on failure.
     Note that user is responsible for deallocate the output data.

     The saslc destroy() function destroys SASL session and deallocates any
     resources used.

     The saslc geterror() function maps last error number in sess to message
     string. Returns pointer to the message string on success and pointer to
     the "unknown error" string on failure.

RETURN VALUES
     The function saslc create() returns a pointer to a SASL session on suc-
     cess and NULL on failure. The saslc configure(), saslc setattr()
     saslc cont() functions return 0 on success and -1 on failure, additional-
     ly saslc cont() returns 1 if more SASL authentication steps are needed.
     The saslc getattr() function returns to the property on success, or NULL
     on failure. Finally, saslc geterror() returns pointer to the message
     string on success and pointer to the "unknown error" string on failure.
*snip*

--
Regards,
Mateusz Kocielski