*** /dev/null Tue May 14 13:55:00 2024
--- - Tue May 14 13:56:56 2024
***************
*** 0 ****
--- 1,134 ----
+ =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
|
