Index: ossp-pkg/xds/docs/xds.pod
RCS File: /v/ossp/cvs/ossp-pkg/xds/docs/Attic/xds.pod,v
co -q -kk -p'1.1' '/v/ossp/cvs/ossp-pkg/xds/docs/Attic/xds.pod,v' | diff -u /dev/null - -L'ossp-pkg/xds/docs/xds.pod' 2>/dev/null
--- ossp-pkg/xds/docs/xds.pod
+++ -	2025-04-04 22:40:15.739191572 +0200
@@ -0,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