head	1.23;
access;
symbols;
locks; strict;
comment	@ * @;


1.23
date	2001.07.20.10.42.34;	author simons;	state dead;
branches;
next	1.22;

1.22
date	2001.07.20.09.22.25;	author simons;	state Exp;
branches;
next	1.21;

1.21
date	2001.07.19.15.13.39;	author simons;	state Exp;
branches;
next	1.20;

1.20
date	2001.07.19.14.58.27;	author simons;	state Exp;
branches;
next	1.19;

1.19
date	2001.07.18.18.26.32;	author simons;	state Exp;
branches;
next	1.18;

1.18
date	2001.07.18.16.59.27;	author simons;	state Exp;
branches;
next	1.17;

1.17
date	2001.07.18.11.30.19;	author simons;	state Exp;
branches;
next	1.16;

1.16
date	2001.07.16.17.50.07;	author simons;	state Exp;
branches;
next	1.15;

1.15
date	2001.07.09.19.00.44;	author simons;	state Exp;
branches;
next	1.14;

1.14
date	2001.07.09.17.19.26;	author simons;	state Exp;
branches;
next	1.13;

1.13
date	2001.07.04.15.25.38;	author simons;	state Exp;
branches;
next	1.12;

1.12
date	2001.07.03.08.25.24;	author simons;	state Exp;
branches;
next	1.11;

1.11
date	2001.07.02.14.15.04;	author simons;	state Exp;
branches;
next	1.10;

1.10
date	2001.07.02.14.05.39;	author simons;	state Exp;
branches;
next	1.9;

1.9
date	2001.07.02.14.03.39;	author simons;	state Exp;
branches;
next	1.8;

1.8
date	2001.07.02.12.18.57;	author simons;	state Exp;
branches;
next	1.7;

1.7
date	2001.06.29.13.58.53;	author rse;	state Exp;
branches;
next	1.6;

1.6
date	2001.06.29.13.55.47;	author rse;	state Exp;
branches;
next	1.5;

1.5
date	2001.06.28.16.09.16;	author simons;	state Exp;
branches;
next	1.4;

1.4
date	2001.06.28.15.25.23;	author simons;	state Exp;
branches;
next	1.3;

1.3
date	2001.06.28.14.42.06;	author simons;	state Exp;
branches;
next	1.2;

1.2
date	2001.06.28.12.42.10;	author simons;	state Exp;
branches;
next	1.1;

1.1
date	2001.06.28.12.31.22;	author simons;	state Exp;
branches;
next	;


desc
@@


1.23
log
@- Renamed configure.in to configure.ac for autoconf 2.50 and later.
- Added tests that will find the exact data types and typedef our versions to them.
@
text
@/*
   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_UNKNOWN_ENGINE = -5,
    XDS_ERR_INVALID_MODE   = -6,
    XDS_ERR_UNDERFLOW      = -7
    };
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_len);
int xds_getbuffer(xds_t* xds, xds_scope_t flag, void** buffer, size_t* buffer_len);

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);

int xdr_encode_uint32(xds_t* xds, void* engine_context, void* buffer, size_t buffer_size, va_list* args);
int xdr_encode_int32(xds_t* xds, void* engine_context, void* buffer, size_t buffer_size, va_list* args);
int xdr_encode_uint64(xds_t* xds, void* engine_context, void* buffer, size_t buffer_size, va_list* args);
int xdr_encode_int64(xds_t* xds, void* engine_context, void* buffer, size_t buffer_size, va_list* args);

int xdr_decode_uint32(xds_t* xds, void* engine_context, void* buffer, size_t buffer_size, va_list* args);
int xdr_decode_int32(xds_t* xds, void* engine_context, void* buffer, size_t buffer_size, va_list* args);
int xdr_decode_uint64(xds_t* xds, void* engine_context, void* buffer, size_t buffer_size, va_list* args);
int xdr_decode_int64(xds_t* xds, void* engine_context, void* buffer, size_t buffer_size, va_list* args);

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

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

#endif /* !defined(__LIBXDS_H__) */
@


1.22
log
@People who know how to spell clearly have an advantage.
@
text
@@


1.21
log
@Implemented XDR encoding and decoding of strings.
@
text
@d83 2
a84 2
int xdr_encode_octedstream(xds_t* xds, void* engine_context, void* buffer, size_t buffer_size, va_list* args);
int xdr_decode_octedstream(xds_t* xds, void* engine_context, void* buffer, size_t buffer_size, va_list* args);
@


1.20
log
@Implemented encoding and decoding of variable length octed streams.
@
text
@d86 3
@


1.19
log
@Implemented decoding engines for the integer data types and extended
the existing test suites to verify them.
@
text
@d83 3
@


1.18
log
@Implemented encoding routines for 64 bit integers and added the
apropriate test suites.
@
text
@d78 5
@


1.17
log
@Added XDR encoding engines for int32 and uint32.
@
text
@d75 2
@


1.16
log
@Passing va_list parameters by value is fine, unless the called routine
modifies the parameter list and you expect the change to propagate
back to the mother routine. What is what we want. Hence, I changed the
prototype of the engine callback to expect a pointer to va_list.
@
text
@d73 3
@


1.15
log
@Implemented xds_decode().
@
text
@d57 1
a57 1
			    va_list args);
@


1.14
log
@- Added XDS_ERR_INVALID_MODE define.

- Renamed argument in the xds_getbuffer() prototype from buffer_size
  to buffer_len for consistency.
@
text
@d44 2
a45 1
    XDS_ERR_INVALID_MODE   = -6
@


1.13
log
@Fixed typo: The label XDS_ERR_UNKNOWN_ENGINE was spelled incorrectly.
@
text
@d43 2
a44 1
    XDS_ERR_UNKNOWN_ENGINE = -5
d64 2
a65 2
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);
@


1.12
log
@Added XDS_ERR_UNKNOWN_ENGINE label.
@
text
@d38 6
a43 6
    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
@


1.11
log
@Added the standard OSSP copyright header.
@
text
@d42 2
a43 1
    XDS_ERR_TYPE_MISMATCH = -4
@


1.10
log
@Cosmetic changes in the indention.
@
text
@d2 3
a4 2
   $Source: /e/ossp/cvs/ossp-pkg/srpc/libxds/xds.h,v $
   $Revision: 1.9 $
d6 2
a7 1
   Copyright (c) 2001 by Cable & Wireless Deutschland.
d14 14
a27 4
   This software is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
   included license for more details.
d38 1
a38 1
    XDS_OK                = 0,
@


1.9
log
@The interface is final, beautiful and it will never ever be changed
again. Consider this header file to be eternally valid.
@
text
@d3 1
a3 1
   $Revision: 1.8 $
d26 4
a29 4
    XDS_OK = 0,
    XDS_ERR_NO_MEM = -1,
    XDS_ERR_OVERFLOW = -2,
    XDS_ERR_INVALID_ARG = -3,
d50 1
a50 1
int xds_setbuffer(xds_t* xds, xds_scope_t flag, void* buffer, size_t buffer_size);
@


1.8
log
@- The de-/encoding buffer is now of type "void*" rather than "char*".

- getbuffer() and setbuffer() now expect a parameter xds_buf_flag_t,
  which tells them who owns the buffer. If the library owns it
  (XDS_GIFT set at setbuf()-time), the library performs dynamic buffer
  management. If the user owns the buffer, it is static in size.

- xds_init() now ecpects a xds_mode_t parameter, telling it whether to
  initialize in encode or decode mode.

- The xds_register_XXX() functions are gone. We will rather export the
  symbols of the callbacks so that the users can register the ones he
  needs himself.
@
text
@d3 1
a3 1
   $Revision: 1.7 $
d24 18
a41 7
struct xds_st;
typedef struct xds_st xds_t;

typedef int (*xds_fmt_cb_t)(xds_t* context,
			    void* fmt_context,
			    void* buf,
			    size_t buf_size,
a43 14
typedef enum
    {
    XDS_ENCODE,
    XDS_DECODE
    }
xds_mode_t;

typedef enum
    {
    XDS_LOAN,
    XDS_GIFT
    }
xds_buf_flag_t;

d45 1
a45 1
void xds_destroy(xds_t* context);
d47 2
a48 2
int xds_register(xds_t* context, const char* name, xds_fmt_cb_t callback, void* formatter_context);
int xds_unregister(xds_t* context, const char* name);
d50 2
a51 2
int xds_set_buffer(xds_t* context, xds_buf_flag_t flag, void* buf, size_t buf_size);
int xds_get_buffer(xds_t* context, xds_buf_flag_t flag, void** buf, size_t* buf_size);
d53 4
a56 2
int xds_encode(xds_t* context, const char* fmt, ...);
int xds_decode(xds_t* context, const char* fmt, ...);
@


1.7
log
@We still have not finally determined whether xds_decode() receives a
particular buffer or whether the buffer is attached to the XDS handle,
but nevertheless xds_vdecode() has to match xds_decode(), so currently
we have to add "const char* buf" also to xds_vdecode() to make the API
consistent up to now.
@
text
@d3 1
a3 1
   $Revision: 1.6 $
d29 2
a30 1
			    char* buf, size_t buf_size,
d33 13
a45 2
xds_t*  xds_init(void);
void    xds_destroy(xds_t* context);
d47 4
a50 6
int xds_register(xds_t* context,
		 const char* name, xds_fmt_cb_t callback,
		 void* formatter_context);
int xds_register_xdr(xds_t* context);
int xds_register_xml(xds_t* context);
int xds_register_asn1(xds_t* context);
d53 2
a54 3
int xds_set_encode_buffer(xds_t* context, char* buf, size_t buf_size);
int xds_set_decode_buffer(xds_t* context, const char* buf, size_t buf_size);
int xds_get_encode_buffer(xds_t* context, char** buf, size_t* buf_size);
d57 1
a57 4
int xds_decode(xds_t* context, const char* buf, const char* fmt, ...);

int xds_vencode(xds_t* context, const char* fmt, va_list args);
int xds_vdecode(xds_t* context, const char* buf, const char* fmt, va_list args);
@


1.6
log
@As we still discovered with Thomas yesterday, the
xds_set_decode_buffer() really needs a "buf_size" argument. Because
incoming (to be decoded) buffers are usually "input bufferes" which were
received from external sources, so we cannot safely assume it really
contains a correct encoding. Hence we have to provide a way in XDS to
protect the library from segfaulting the application in case the buffer
is destroyed and XDS still would like something to decode.
@
text
@d3 1
a3 1
   $Revision: 1.5 $
d51 1
a51 1
int xds_vdecode(xds_t* context, const char* fmt, va_list args);
@


1.5
log
@And now we have the result of the third review ...
@
text
@d3 1
a3 1
   $Revision: 1.4 $
d44 1
a44 1
int xds_set_decode_buffer(xds_t* context, const char* buf);
@


1.4
log
@The API after the seconds review with RSE.
@
text
@d3 1
a3 1
   $Revision: 1.3 $
d24 2
a25 2
struct xds_ctx;
typedef struct xds_ctx xds_ctx_t;
d27 1
a27 1
typedef int (*xds_fmt_cb_t)(xds_ctx_t* context,
d32 2
a33 2
xds_ctx_t*  xds_init(void);
void        xds_destroy(xds_ctx_t* context);
d35 1
a35 1
int xds_register(xds_ctx_t* context,
d38 14
a51 12
int xds_register_xdr(xds_ctx_t* context);
int xds_register_xml(xds_ctx_t* context);
int xds_register_asn1(xds_ctx_t* context);
int xds_unregister(xds_ctx_t* context, const char* name);

char* xds_get_buffer(xds_ctx_t* context);
int xds_set_buffer(xds_ctx_t* context, char* buf, size_t buf_size);

int xds_encode(xds_ctx_t* context, const char* fmt, ...);
int xds_decode(xds_ctx_t* context, const char* buf, const char* fmt, ...);
int xds_vdecode(xds_ctx_t* context, const char* buf, const char* fmt, va_list args);
int xds_vencode(xds_ctx_t* context, const char* fmt, va_list args);
@


1.3
log
@Revised the interface after reviewing it with RSE.
@
text
@d3 1
a3 1
   $Revision: 1.2 $
d25 1
d27 1
a27 1
typedef int (*xds_fmt_cb_t)(struct xds_ctx* context,
d30 1
a30 14
			    va_list val);

struct fmt_cb
    {
    char*          name;
    xds_fmt_cb_t   callback;
    void*          fmt_context;
    };

struct xds_ctx
    {
    struct fmt_cb* formatters;
    };
typedef struct xds_ctx xds_ctx_t;
d38 3
d43 2
a44 2
int xds_encode(xds_ctx_t* context, char* buf, size_t buf_size, const char* fmt, ...);
char* xds_aencode(xds_ctx_t* context, const char* fmt, ...);
d46 1
d48 2
@


1.2
log
@Added mechanism for adding an array of formatter callbacks with one
function call.
@
text
@d3 1
a3 1
   $Revision: 1.1 $
d22 1
d24 8
a31 2
typedef int (*xds_formatter_cb)(char* buf, size_t buf_size, void* val);
typedef struct
d33 4
a36 4
    char* name;
    xds_formatter_cb callback;
    }
xds_formatter_cb_desc;
d38 1
a38 1
typedef struct
d40 16
a55 14
    xds_formatter_cb_desc* formatters;
    size_t formatters_size;
    }
xds_ctx;

xds_ctx* xds_init(void);
void     xds_destroy(xds_ctx* context);

int xds_register(xds_ctx* context, const char* name, xds_formatter_cb callback);
int xds_vregister(xds_ctx* context, const xds_formatter_cb_desc* callbacks, size_t size);

int xds_mashal(xds_ctx* context, const char* fmt, ...);
int xds_snmashal(xds_ctx* context, char* buf, size_t buf_size, const char* fmt, ...);
int xds_amashal(xds_ctx* context, char** buf_p, size_t buf_size, const char* fmt, ...);
@


1.1
log
@First attempt of an interface definition for the library.
@
text
@d2 2
a3 2
   $Source$
   $Revision$
d23 8
d33 2
a40 1
typedef int (*xds_formatter_cb)(char* buf, size_t buf_size, void* val);
d42 1
@