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.h Go to the documentation of this file. /** @file GATXds.h * Header 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.h,v 1.6 2004/04/18 15:12:49 merzky 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) */ #ifndef _GATXds_H_ #define _GATXds_H_ 1 /* System Header Files */ #include <stdarg.h> /* GAT Header Files */ #include "GATType.h" #include "GATContext.h" /* Macros */ /* Structures, unions and enums */ typedef xds_t *GATXds; typedef enum { GATXdsType_Encode = XDS_ENCODE, GATXdsType_Decode = XDS_DECODE } GATXdsType; typedef enum { GATXdsScope_Gift = XDS_GIFT, GATXdsScope_Loan = XDS_LOAN } GATXdsScope; typedef GATResult (* GATXdsSerialiseCallback)(GATObject, GATObject, GATBool); typedef GATResult (* GATXdsDeSerialiseCallback)(GATContext, GATObject, GATObject *, GATuint32, va_list); typedef GATBool (* GATXdsVersionCallback)(GATuint32); #ifdef __cplusplus extern "C" { #endif /* 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). * @param context The GAT context for which any GATObjects should be * de-serialised (optional, needed for GATXdsType_Decode only) * * @returns An error code. */ GATResult GATXds_Init (GATXds *xds, GATXdsType type); GATResult GATXds_InitEx (GATXds *xds, GATXdsType type, GATContext context); /** 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); /** 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 GATXds_EncodeV(GATXds xds, GATXdsScope flag, void **buffer, size_t *buffer_len, const char *fmt, va_list args); /** 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 GATXds_DecodeV(GATXds xds, GATXdsScope flag, void *buffer, size_t buffer_len, const char *fmt, va_list args); /** 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); /** 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); /** 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); /* Helper function to serialise a GATObject with its associated CPI provider */ GATResult GATXds_SerialiseObject(GATObject object, GATObject stream, GATBool clear_dirty, GATXdsSerialiseCallback callback, char const *fmt, ...); GATResult GATXds_DeSerialiseObject(GATContext context, GATObject stream, GATXdsDeSerialiseCallback callback, GATXdsVersionCallback version_callback, GATObject *object, char const *fmt, ...); #ifdef __cplusplus } #endif #endif /* _GATXds_H_ */