ossp-pkg/xds/docs/xds.pod
=pod
=head1 NAME
xds - eXtensible 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 the
number of bytes it has written to the buffer. (Note that all xds error
defines are smaller than >0.) 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.
A valid name I<name> for a callback function consists of an arbitrary
number of characters from the class [a-zA-Z0-9_-].
=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 the
B<malloc(3)> API. 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.
B<xds_setbuffer> returns one of the following codes signifying success
or failure: B<XDS_OK> (everything alright), B<XDS_ERR_NO_MEM> (failed
to allocate new internal buffers), and B<XDS_ERR_INVALID_ARG>
(arguments don't make sense).
=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. The application must B<free> the
buffer when it's not needed anymore.
=item int B<xds_encode>(xds_t* I<xds>, const char* I<fmt>, ...);
The B<encode> function call will encode an arbitrary number of values
into the chosen representation. The syntax is very similar to
B<sprintf>: As parameters, it requires the I<xds> handle obtained from
B<xds_init>, a format string I<fmt> describing the following value
parameters, and an arbitrary number of actual values.
The format string lists the names of the callback functions to be used
in order to format the values; it has the format "name name ...". The
names are delimited by any number of characters any of which is not
part of the character set allowed for function names here. Hence, you
can delimit the names by blanks, tabs, dollar signs or pretty much
anyting your want.
B<xds_encode> will return either B<XDS_OK> (everything OK),
B<XDS_ERR_NO_MEM> (failed allocating memory for intenal buffering),
B<XDS_ERR_OVERFLOW> (can't expand internal buffer because it's owned
by the application), B<XDS_ERR_INVALID_ARG> (parameters don't make
sense), B<XDS_ERR_TYPE_MISMATCH> (specified callback can't handle this
data type), and B<XDS_ERR_UNKNOW_ENGINE> (unknown call back name used
in I<fmt>).
=item int B<xds_decode>(xds_t* I<xds>, const char* I<fmt>, ...);
Like B<xds_encode>, only the other way round.
=item int B<xds_vencode>(xds_t* I<xds>, const char* I<fmt>, va_list I<args>);
See B<xds_encode>.
=item int B<xds_vdecode>(xds_t* I<xds>, const char* I<fmt>, va_list I<args>);
See B<xds_decode>.
=back
=cut
