OSSP CVS Repository

ossp - Check-in [529]
Not logged in 		[Honeypot]  [Browse]  [Home]  [Login]  [Reports] 
[Search]  [Ticket]  [Timeline] 
  [Patchset]  [Tagging/Branching] 

Check-in Number: 529
Date: 2001-Jul-03 10:25:24 (local)
2001-Jul-03 08:25:24 (UTC)
User:simons
Branch:
Comment: Added preliminary documentation for xds_init(), xds_destroy(), xds_register(), xds_unregister(), xds_setbuffer(), and xds_getbuffer().
Tickets:
Inspections:
Files:
ossp-pkg/xds/Makefile      added-> 1.4
ossp-pkg/xds/xds.h      added-> 1.12
ossp-pkg/xds/xds.pod      added-> 1.1
ossp-pkg/xds/Makefile -> 1.4 

*** /dev/null    Sat Nov 23 01:05:37 2024
--- -    Sat Nov 23 01:05:41 2024
***************
*** 0 ****
--- 1,34 ----
+ # Build libxds and support/test programs.
+ 
+ CC             = gcc
+ CXX            = g++
+ 
+ WARNFLAGS      = -Wall -ansi -pedantic
+ OPTFLAGS       = -O3 -pipe
+ 
+ CPPFLAGS       =
+ CFLAGS         =
+ CXXFLAGS       =
+ LDFLAGS                =
+ 
+ .c.o:
+        $(CC) $(CPPFLAGS) $(WARNFLAGS) $(OPTFLAGS) $(CFLAGS) -c $<
+ 
+ .cpp.o:
+        $(CXX) $(CPPFLAGS) $(WARNFLAGS) $(OPTFLAGS) $(CXXFLAGS) -c $<
+ 
+ all:   test xds.3
+ 
+ test:          test.o
+        $(CC) $(LDFLAGS) -o $@ test.o
+ 
+ xds.3:         xds.pod
+        pod2man --section=3 --center="XDS Library Programmer API " $< >$@
+ 
+ clean::
+        rm -f test.o test
+        rm -f xds.3
+ 
+ # Dependencies
+ 
+ test.o:        test.c xds.h

ossp-pkg/xds/xds.h -> 1.12 

*** /dev/null    Sat Nov 23 01:05:37 2024
--- -    Sat Nov 23 01:05:41 2024
***************
*** 0 ****
--- 1,71 ----
+ /*
+    XDS - OSSP Extensible Data Serialization Library
+    Copyright (c) 2001 The OSSP Project (http://www.ossp.org/)
+    Copyright (c) 2001 Cable & Wireless Deutschland (http://www.cw.com/de/)
+ 
+    This file is part of OSSP XDS, an extensible data serialization
+    library which can be found at http://www.ossp.com/pkg/xds/.
+ 
+    Permission to use, copy, modify, and distribute this software for
+    any purpose with or without fee is hereby granted, provided that
+    the above copyright notice and this permission notice appear in all
+    copies.
+ 
+    THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
+    WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+    MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+    IN NO EVENT SHALL THE AUTHORS AND COPYRIGHT HOLDERS AND THEIR
+    CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+    SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+    LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
+    USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
+    ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+    OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
+    OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+    SUCH DAMAGE.
+ 
+    xds.h: C API
+ */
+ 
+ #ifndef __LIBXDS_H__
+ #define __LIBXDS_H__
+ 
+ #include <stdlib.h>
+ #include <stdarg.h>
+ 
+ enum
+     {
+     XDS_OK                =  0,
+     XDS_ERR_NO_MEM        = -1,
+     XDS_ERR_OVERFLOW      = -2,
+     XDS_ERR_INVALID_ARG   = -3,
+     XDS_ERR_TYPE_MISMATCH = -4,
+     XDS_ERR_UNKNOW_ENGINE = -5
+     };
+ typedef enum { XDS_ENCODE, XDS_DECODE } xds_mode_t;
+ typedef enum { XDS_LOAN,   XDS_GIFT   } xds_scope_t;
+ 
+ struct xds_context;
+ typedef struct xds_context xds_t;
+ 
+ typedef int (*xds_engine_t)(xds_t* xds,
+                            void* engine_context,
+                            void* buffer,
+                            size_t buffer_size,
+                            va_list args);
+ 
+ xds_t* xds_init(xds_mode_t);
+ void xds_destroy(xds_t* xds);
+ 
+ int xds_register(xds_t* xds, const char* name, xds_engine_t engine, void* engine_context);
+ int xds_unregister(xds_t* xds, const char* name);
+ 
+ int xds_setbuffer(xds_t* xds, xds_scope_t flag, void*  buffer, size_t  buffer_size);
+ int xds_getbuffer(xds_t* xds, xds_scope_t flag, void** buffer, size_t* buffer_size);
+ 
+ int xds_encode(xds_t* xds, const char* fmt, ...);
+ int xds_decode(xds_t* xds, const char* fmt, ...);
+ int xds_vencode(xds_t* xds, const char* fmt, va_list args);
+ int xds_vdecode(xds_t* xds, const char* fmt, va_list args);
+ 
+ #endif /* !defined(__LIBXDS_H__) */

ossp-pkg/xds/xds.pod -> 1.1 

*** /dev/null    Sat Nov 23 01:05:37 2024
--- -    Sat Nov 23 01:05:41 2024
***************
*** 0 ****
--- 1,98 ----
+ =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

CVSTrac 2.0.1