=pod

=head1 NAME

xds - eXtendable Data Serialization

=head1 SYNOPSIS


=head1 DESCRIPTION

=over 4

=item xds_t* B<xds_init>(xds_mode_t I<mode>);

Valid settings for I<mode> are B<XDS_ENCODE> and B<XDS_DECODE>. If
successful, a valid handle is returned -- B<NULL> otherwise. If the
routine fails, the system variable B<errno> is set apropriately.

=item void B<xds_destroy>(xds_t* I<xds>);

Free all internally allocated resources associated with this context.
I<xds> must be a handle obtained by calling B<xds_init>.

=item int B<xds_register>(xds_t* I<xds>, const char* I<name>, xds_engine_t I<engine>, void* I<engine_context>);

Register the function I<engine> as formatting engine in context I<xds>
under the name I<name>. The function must have the following
prototype:

    int my_engine(xds_t* xds, void* engine_context,
		  void* buffer, size_t buffer_size,
		  va_list args);

It must gather its values from I<args> and encode/decode them into
I<buffer>. The encoded/decoded representation must not take up more
than I<size> byte of memory, because that's the maximum I<buffer> can
hold. If the buffer is too small, I<engine> must return
B<XDS_ERR_OVERFLOW>. In case of no error, I<engine> must return
B<XDS_OK>. The variable I<engine_context> is passed through to the
function every time it is called; it is not touched in any way by the
xds library.

=item int B<xds_unregister>(xds_t* I<xds>, const char* I<name>);

Remove encoding/decoding engine I<name> from context I<xds>. The
function will return B<XDS_OK> if successful and
B<XDS_ERR_UNKNOW_ENGINE> if I<name> is not a registered engine.

=item int B<xds_setbuffer>(xds_t* I<xds>, xds_scope_t I<flag>, void* I<buffer>, size_t I<buffer_size>);

Encoding mode: Set internal buffer used in context I<xds> to
I<buffer>. The buffer has a capacity of I<buffer_size> byte. I<flag>
may be set to B<XDS_LOAN> or B<XDS_GIFT>. A "loaned" buffer is one
that is owned by the application; xds will use it, but it will not
B<free> the buffer nor will it try to B<realloc> it if it's too small.
A buffer given to xds as a "gift" is henceforth owned by xds and may
be B<free>d or B<realloc>ed as the library sees fit. If I<flag> is
B<XDS_GIFT>, I<buffer> must be a pointer obtained from calling
B<malloc> or a comparable system routine. Calling B<xds_setbuffer>
with a I<buffer> of B<NULL> will cause the xds library to allocate a
buffer of its own. I<buffer_size> is ignored in this case.

Decoding mode: I<buffer> contains the encoded representation of the
data to be used for following B<xds_decode> calls. The encoded data is
I<buffer_size> byte long. Unlike in encoding mode, such a buffer is
not modified, hence there is no need to extend the buffer. If I<flag>
is set to B<XDS_GIFT>, the library will B<free> I<buffer> when
the context is destroyed.

=item int B<xds_getbuffer>(xds_t* I<xds>, xds_scope_t flag, void** buffer, size_t* buffer_size);

This routine will write the address and size of the internal buffer in
context I<xds> to I<buffer> and I<buffer_size>. The I<flag> parameter
determines who owns the buffer after that; setting I<flag> to
B<XDS_LOAN> means that the buffer is owned by the xds library and that
the user may not rely on its contents still being there after another
xds library function call. Furthermore, calling B<xds_getbuffer> will
flush the registered buffer, meaning that coming B<xds_encode> calls
will start at the beginning and potentially overwrite the buffer
contents.

Setting I<flag> to B<XDS_GIFT> means that the returned buffer is owned
by the application programmer from now on, it is no longer modified or
used in any way by the library.


=item int B<xds_encode>(xds_t* I<xds>, const char* I<fmt>, ...);

=item int B<xds_decode>(xds_t* I<xds>, const char* I<fmt>, ...);

=item int B<xds_vencode>(xds_t* I<xds>, const char* I<fmt>, va_list I<args>);

=item int B<xds_vdecode>(xds_t* I<xds>, const char* I<fmt>, va_list I<args>);

=back

=cut