Grid Application Toolkit A simple API for Grid Applications

Menu Home API-Specification API-Overview Status C Reference Manual Download Java Java-Reference General GridLab - WP-1 Links

GATXdsWrapper.c Go to the documentation of this file. /** @file GATXds.c * Source file for the GAT xds wrapper functions. * * @date Thu Oct 30 2003 * * @version $Header: /export/cvs-gridlab/wp-1/Codes/GATEngine/C-reference/src/GATXdsWrapper.c,v 1.23 2004/05/10 15:17:32 hartmutkaiser Exp $ * * Copyright (C) Hartmut Kaiser * This file is part of the GAT Engine. * Contributed by Hartmut Kaiser <hartmutkaiser [at] t-online [dot] de>. * * Use, modification and distribution is subject to the Gridlab Software * License. (See accompanying file GLlicense.txt or copy at * http://www.gridlab.org/GLlicense.txt) */ static const char *rcsid = "$Header: /export/cvs-gridlab/wp-1/Codes/GATEngine/C-reference/src/GATXdsWrapper.c,v 1.23 2004/05/10 15:17:32 hartmutkaiser Exp $"; #include <stdio.h> #include <stdlib.h> #include <stdarg.h> #include <string.h> #include <assert.h> #include "xds_p.h" #include "uuid.h" #include "GAT.h" #include "GATXdsWrapper.h" #include "GATMemoryStream.h" /* local function declarations */ static int xml_encode_object(xds_t *xds, void *engine_context, void *buffer, size_t buffer_size, size_t *used_buffer_size, va_list *args); static int xml_decode_object(xds_t *xds, void *engine_context, void *buffer, size_t buffer_size, size_t *used_buffer_size, va_list *args); static int xml_encode_double_fmt(xds_t *xds, void *engine_context, void *buffer, size_t buffer_size, size_t *used_buffer_size, va_list *args); static int xml_decode_double_fmt(xds_t *xds, void *engine_context, void *buffer, size_t buffer_size, size_t *used_buffer_size, va_list *args); /* external functions */ /** GATXds_Init * * The function GATXds_Init initialises a new instance of the * underlying XDS engine and registers all the streaming functions to be used * by subsequent streaming operations via GATXds_Encode or * GATXds_Decode. * * @param xds The pointer to a variable, which receives the initialised xds * handle. * @param type Defines, whether the returned engine is to be used for * serialisation (type == GATXdsType_Encode) or de-serialisation * (type == GATXdsType_Decode). * * @returns An error code. */ GATResult GATXds_Init(GATXds *xds, GATXdsType type) { return GATXds_InitEx(xds, type, 0); } GATResult GATXds_InitEx(GATXds *xds, GATXdsType type, GATContext context) { /* TODO: Register the other required streaming functions too */ GATResult retval = GAT_INVALID_PARAMETER; if (GATXdsType_Encode == type) { if (XDS_OK != (retval = xds_init(xds, XDS_ENCODE)) || XDS_OK != (retval = xds_register(*xds, "object", &xml_encode_object, 0)) || XDS_OK != (retval = xds_register(*xds, "string", &xml_encode_string, 0)) || XDS_OK != (retval = xds_register(*xds, "octet", &xml_encode_octetstream, 0)) || XDS_OK != (retval = xds_register(*xds, "double", &xml_encode_double, 0)) || XDS_OK != (retval = xds_register(*xds, "double_fmt", &xml_encode_double_fmt, 0)) || XDS_OK != (retval = xds_register(*xds, "float", &xml_encode_float, 0)) || XDS_OK != (retval = xds_register(*xds, "int32", &xml_encode_int32, 0)) || XDS_OK != (retval = xds_register(*xds, "uint32", &xml_encode_uint32, 0)) || XDS_OK != (retval = xds_register(*xds, "int64", &xml_encode_int64, 0)) || XDS_OK != (retval = xds_register(*xds, "uint64", &xml_encode_uint64, 0))) { retval = XDS_TO_GAT(retval); } else { retval = GAT_SUCCESS; } } else if (GATXdsType_Decode == type) { if (XDS_OK != (retval = xds_init(xds, XDS_DECODE)) || XDS_OK != (retval = xds_register(*xds, "object", &xml_decode_object, context)) || XDS_OK != (retval = xds_register(*xds, "string", &xml_decode_string, 0)) || XDS_OK != (retval = xds_register(*xds, "octet", &xml_decode_octetstream, 0)) || XDS_OK != (retval = xds_register(*xds, "double", &xml_decode_double, 0)) || XDS_OK != (retval = xds_register(*xds, "float", &xml_decode_float, 0)) || XDS_OK != (retval = xds_register(*xds, "int32", &xml_decode_int32, 0)) || XDS_OK != (retval = xds_register(*xds, "uint32", &xml_decode_uint32, 0)) || XDS_OK != (retval = xds_register(*xds, "int64", &xml_decode_int64, 0)) || XDS_OK != (retval = xds_register(*xds, "uint64", &xml_decode_uint64, 0))) { retval = XDS_TO_GAT(retval); } else { retval = GAT_SUCCESS; } } return retval; } /** GATXds_Destroy * * The function GATXds_Destroy frees all the memory used by the XDS * engine. * * @param xds The XDS engine handle to destroy. */ void GATXds_Destroy(GATXds *xds) { if (NULL != xds && NULL != *xds) { xds_destroy(*xds); *xds = NULL; } } /** GATXds_Encode * * The function GATXds_Encode encodes the given data items accordingly * to the given format description and returns the streamed data through the * supplied buffer variable. * * @param xds The handle of the XDS engine to use. * @param flag This defines the ownership of the returned buffer. If * flag == GATXdsScope_Gift, the returned buffer is to be freed by the * caller, If flag == GATXdsScope_Loan, the returned buffer memory is * maintained by the XDS engine. * @param buffer The pointer to a variable, where the buffer is to be * returned. If this parameter is zero, no buffer is returned and may * be requested in a subsequent call to GATXds_Encode. * @param buffer_len This receives the size of the returned buffer. * @param fmt A format description, which defines the data format of all * subsequent parameters. * @param ... An arbitrary amount of data items to stream. * * @return An error code. */ GATResult GATXds_Encode(GATXds xds, GATXdsScope flag, void **buffer, size_t *buffer_len, const char *fmt, ...) { GATResult retval = XDS_ERR_UNKNOWN; va_list args; va_start(args, fmt); if (XDS_OK != (retval = xds_vencode(xds, fmt, args))) { retval = XDS_TO_GAT(retval); } else if (NULL != buffer) { /* get the buffer from the xds engine only, if requested */ assert(GATXdsScope_Gift == flag || GATXdsScope_Loan == flag); assert(NULL != buffer_len); if (XDS_OK != (retval = xds_getbuffer(xds, (xds_scope_t)flag, buffer, buffer_len))) { retval = XDS_TO_GAT(retval); } else { retval = GAT_SUCCESS; } } else { retval = GAT_SUCCESS; } return retval; } GATResult GATXds_EncodeV(GATXds xds, GATXdsScope flag, void **buffer, size_t *buffer_len, const char *fmt, va_list args) { GATResult retval = XDS_ERR_UNKNOWN; if (XDS_OK != (retval = xds_vencode(xds, fmt, args))) { retval = XDS_TO_GAT(retval); } else if (NULL != buffer) { /* get the buffer from the xds engine only, if requested */ assert(GATXdsScope_Gift == flag || GATXdsScope_Loan == flag); assert(NULL != buffer_len); if (XDS_OK != (retval = xds_getbuffer(xds, (xds_scope_t)flag, buffer, buffer_len))) { retval = XDS_TO_GAT(retval); } else { retval = GAT_SUCCESS; } } else { retval = GAT_SUCCESS; } return retval; } /** GATXds_Decode * * The function GATXds_Decode decodes the required amount of data items * accordingly to the given format description. * * @param xds The handle of the XDS engine to use. * @param flag This defines the ownership of given returned buffer. If * flag == GATXdsScope_Gift, the returned buffer is to be freed by the * XDS engine, If flag == GATXdsScope_Loan, the supplied buffer memory * is maintained by the caller. * @param buffer The buffer containing the streamed data. If this parameter is * zero, the existing buffer is reused and the decoding continues at the * point, where a previous decode ended. * @param buffer_len The size of the supplied buffer. * @param fmt A format description, which defines the data format of all * subsequent parameters. * @param ... An arbitrary amount of data item addresses to decode from the * stream. * * @return An error code. */ GATResult GATXds_Decode(GATXds xds, GATXdsScope flag, void *buffer, size_t buffer_len, const char *fmt, ...) { GATResult retval = XDS_ERR_UNKNOWN; /* set a new buffer only if given */ if (NULL == buffer || XDS_OK == (retval = xds_setbuffer(xds, (xds_scope_t)flag, buffer, buffer_len))) { /* read in the required data */ va_list args; va_start(args, fmt); retval = xds_vdecode(xds, fmt, args); } if (XDS_OK != retval) { retval = XDS_TO_GAT(retval); } else { retval = GAT_SUCCESS; } return retval; } GATResult GATXds_DecodeV(GATXds xds, GATXdsScope flag, void *buffer, size_t buffer_len, const char *fmt, va_list args) { GATResult retval = XDS_ERR_UNKNOWN; /* set a new buffer only if given */ if (NULL == buffer || XDS_OK == (retval = xds_setbuffer(xds, (xds_scope_t)flag, buffer, buffer_len))) { /* read in the required data */ retval = xds_vdecode(xds, fmt, args); } if (XDS_OK != retval) { retval = XDS_TO_GAT(retval); } else { retval = GAT_SUCCESS; } return retval; } /** GATXds_GetBufferLen * * The function GATXds_GetBufferLen may be used to retrieve the real * amount of data decoded by the last call to GATXds_Decode. * * @param xds The handle of the XDS engine to use. * * @return The offset into the buffer, up to which the data was decoded * successful. */ size_t GATXds_GetBufferLen(GATXds xds) { return xds->buffer_len; } /** GATXds_GetBufferLen * * The function GATXds_GetBufferCapacity may be used to retrieve the * capacity of the buffer inside the XDS engine. * * @param xds The handle of the XDS engine to use. * * @return The buffer capacity. */ size_t GATXds_GetBufferCapacity(GATXds xds) { return xds->buffer_capacity; } /** GATXds_GetBuffer * * The GATXds_GetBuffer may be called to get access to the buffer stored * inside the XDS engine. * * @param xds The handle of the XDS engine to use. * @param flag This defines the ownership of given returned buffer. If * flag == GATXdsScope_Gift, the returned buffer is to be freed by the * XDS engine, If flag == GATXdsScope_Loan, the supplied buffer memory * is maintained by the caller. * @param buffer The pointer to a variable, where the buffer is to be * returned. If this parameter is zero, no buffer is returned and may * be requested in a subsequent call to GATXds_Encode. * @param buffer_len This receives the size of the returned buffer. * * @return An error code. */ GATResult GATXds_GetBuffer(GATXds xds, GATXdsScope flag, void **buffer, size_t *buffer_size) { GATResult retval = GAT_FAIL; int xds_error = xds_getbuffer(xds, (xds_scope_t)flag, buffer, buffer_size); if (XDS_OK == xds_error) { retval = GAT_SUCCESS; } else { retval = XDS_TO_GAT(xds_error); } return retval; } /** GATXds_SerialiseObject * * The function GATXds_SerialiseObject is a helper function for serialisation * of a GATObject, which calls back to the caller (through the callback * argument) to serialize the data of the associated CPI provider. * * @param object The object to serialise. This is passed through to the * callback function. * @param stream The stream interface to use for the serialisation. * @param clear_dirty If the clear_dirty parameter is set to GATTrue, the * internal dirty flag of this object is to be reset (no used here) * This is passed through to the callback function. * @param fmt The format string for the serialisation of the supplied * data items. This format should start with "uint32" for the version * of the object. * @param ... The data items to serialise for the given object. The first of * this items should be the version of the object. * * @return An error code. */ GATResult GATXds_SerialiseObject(GATObject object, GATObject stream, GATBool clear_dirty, GATXdsSerialiseCallback callback, char const *fmt, ...) { GATResult retval = GAT_FAIL; GATXds xds = NULL; void *xds_buffer = NULL; GATuint32 xds_buffer_size = 0; va_list args; va_start(args, fmt); if (GAT_SUCCESS == (retval = GATXds_Init(&xds, GATXdsType_Encode)) && GAT_SUCCESS == (retval = GATXds_EncodeV(xds, GATXdsScope_Gift, &xds_buffer, &xds_buffer_size, fmt, args))) { /* write the buffer len to ease de-serialisation */ void *xds_size_buffer = NULL; GATuint32 xds_size_buffer_size = 0; if (GAT_SUCCESS == (retval = GATXds_Encode(xds, GATXdsScope_Gift, &xds_size_buffer, &xds_size_buffer_size, "uint32", xds_buffer_size))) { assert(NULL != xds_size_buffer); retval = GATStreamable_Write(stream, xds_size_buffer, xds_size_buffer_size, 0); if (GAT_SUCCESS == retval) { /* write the buffer itself */ assert(NULL != xds_buffer); retval = GATStreamable_Write(stream, xds_buffer, xds_buffer_size, 0); } if (GAT_SUCCESS == retval && NULL != callback) { /* call the associated CPI provider to save its instance data */ retval = callback(object, stream, clear_dirty); } } free(xds_size_buffer); } GATXds_Destroy(&xds); free(xds_buffer); return retval; } /** GATXds_DeSerialiseObject * * The function GATXds_DeSerialiseObject * * @return An error code. */ GATResult GATXds_DeSerialiseObject(GATContext context, GATObject stream, GATXdsDeSerialiseCallback callback, GATXdsVersionCallback version_callback, GATObject *object, char const *fmt, ...) { char buffer[64]; /* seems to be sufficient for a GATuint32 value */ GATuint32 xds_read_bytes = 0; GATResult retval = GATStreamable_Read(stream, buffer, sizeof(buffer), &xds_read_bytes); if (GAT_SUCCESS == retval) { GATXds xds = NULL; if (GAT_SUCCESS == (retval = GATXds_InitEx(&xds, GATXdsType_Decode, context))) { GATuint32 xds_buffer_size = 0; /* read the expected size of the stream for this object */ retval = GATXds_Decode(xds, GATXdsScope_Loan, buffer, sizeof(buffer), "uint32", &xds_buffer_size); if (GAT_SUCCESS == retval) { /* reposition the input stream to start with the real object data */ retval = GATStreamable_Seek(stream, GATOrigin_Current, GATXds_GetBufferLen(xds) - xds_read_bytes, 0); if (GAT_SUCCESS == retval) { /* read the object data itself */ char *xds_buffer = (char *)malloc(xds_buffer_size+1); if (NULL == xds_buffer) { retval = GAT_MEMORYFAILURE; } else { memset(xds_buffer, 0, xds_buffer_size+1); if (GAT_SUCCESS == (retval = GATStreamable_Read(stream, xds_buffer, xds_buffer_size, 0))) { va_list args; GATuint32 *version = NULL; va_start(args, fmt); /* skip the leading uint32, it's the version item */ if (0 != strncmp(fmt, "uint32", 6)) { /* the format string should start with uint32 for the version item */ retval = GAT_UNKNOWN_FORMAT; } else { /* read the version */ version = va_arg(args, GATuint32 *); retval = GATXds_Decode(xds, GATXdsScope_Gift, xds_buffer, xds_buffer_size, "uint32", version); fmt += 7; /* skip "uint32" and one additional character */ } if (GAT_SUCCESS != retval || GATFalse == version_callback(*version)) { retval = GAT_UNKNOWN_FORMAT; } else { /* de-serialise the requested data items */ retval = GATXds_DecodeV(xds, (GATXdsScope)0, 0, 0, fmt, args); if (GAT_SUCCESS == retval) { /* construct the new object */ retval = callback(context, stream, object, *version, args); } } } } } } } GATXds_Destroy(&xds); /* FIXME: GATStatus(retval); */ } return retval; } /** xml_encode_object * * The function xml_encode_object */ static int xml_encode_object(xds_t *xds, void *engine_context, void *buffer, size_t buffer_size, size_t *used_buffer_size, va_list *args) { int xds_error = XDS_ERR_NO_MEM; GATMemoryStream memory_stream = GATMemoryStream_Create(0, 0, GATFalse); /* Setup the engine. How long the actual content is going to be will be seen soon. */ xds_init_encoding_engine(1); /* passed a '1' here to avoid warnings */ if (NULL != memory_stream) { GATObject object = va_arg(*args, GATObject); GATBool clear_dirty = va_arg(*args, GATBool); GATResult retval = GAT_FAIL; GATObject stream_obj = GATMemoryStream_ToGATObject(memory_stream); retval = GATuint32_Serialise(NULL != object ? GATTrue : GATFalse, stream_obj); if (GAT_SUCCEEDED(retval) && NULL != object) { retval = GATSerialisable_Serialise(object, stream_obj, clear_dirty); } if (GAT_FAILED(retval)) { xds_error = XDS_ERR_UNKNOWN; } else { GATuint32 stream_buffer_size = 0; char *stream_buffer = (char *)GATMemoryStream_GetBuffer(memory_stream, &stream_buffer_size, GATFalse); if (buffer_size > stream_buffer_size) { /* move data into the xds buffer */ memmove(buffer, stream_buffer, stream_buffer_size); *used_buffer_size = stream_buffer_size; xds_error = XDS_OK; } else { /* return required buffer size */ *used_buffer_size = stream_buffer_size; xds_error = XDS_ERR_OVERFLOW; } } GATMemoryStream_Destroy(&memory_stream); } return xds_error; } /** xml_decode_object * * The function xml_decode_object */ static int xml_decode_object(xds_t *xds, void *engine_context, void *buffer, size_t buffer_size, size_t *used_buffer_size, va_list *args) { int xds_error = XDS_ERR_TYPE_MISMATCH; if (NULL == engine_context) { xds_error = XDS_ERR_INVALID_MODE; } else { GATContext context = (GATContext) engine_context; GATMemoryStream memory_stream = GATMemoryStream_Create(buffer, buffer_size, GATFalse); if (NULL == memory_stream) { xds_error = XDS_ERR_NO_MEM; } else { GATResult retval = GAT_SUCCESS; GATObject *object = va_arg(*args, GATObject *); GATObject stream_obj = GATMemoryStream_ToGATObject(memory_stream); GATuint32 hasobject = GATFalse; /* Setup the engine. How long the actual content is going to be will be seen soon. */ xds_init_encoding_engine(1); /* passed a '1' here to avoid warnings */ retval = GATuint32_DeSerialise(stream_obj, &hasobject); /* Decode the representation of the object. */ if (GATTrue == hasobject) { *object = GATSerialisable_DeSerialise(context, stream_obj, &retval); } else { *object = NULL; /* there was no object written */ } if ((GATTrue == hasobject && NULL == *object) || GAT_FAILED(retval)) { xds_error = XDS_ERR_TYPE_MISMATCH; } else { GATuint32 offset = 0; retval = GATMemoryStream_Seek(memory_stream, GATOrigin_Current, 0, &offset); if (GAT_SUCCESS == retval) { *used_buffer_size = offset; xds_error = XDS_OK; } else { xds_error = XDS_ERR_UNKNOWN; } } } GATMemoryStream_Destroy(&memory_stream); } return xds_error; } /* * Encode/decode double-precision floating point values. */ int xml_encode_double_fmt(xds_t *xds, void *engine_context, void *buffer, size_t buffer_size, size_t *used_buffer_size, va_list *args) { int xds_error = XDS_ERR_TYPE_MISMATCH; char format[sizeof("<double>%000.000lf</double>")+1]; /* should suffice */ char *dbl_fmt = va_arg(*args, char *); assert(strlen(dbl_fmt) <= sizeof("%000.000lf")); xds_init_encoding_engine(8 + 9 + 1); snprintf(format, sizeof(format), "<double>%s</double>", dbl_fmt); *used_buffer_size = snprintf(buffer, buffer_size, format, va_arg(*args, double)); if (*used_buffer_size >= buffer_size) { xds_error = XDS_ERR_OVERFLOW; } else { xds_error = XDS_OK; } return xds_error; }