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

GATSoftwareDescription.c Go to the documentation of this file. /** @file GATSoftwareDescription.c * Source file for the GATSoftwareDescription class. * * An instance of this class is a description of a piece of software * (component) which is to be submitted as a job. It currently takes a table * describing this piece of software’s attributes to any underlying job * submission system. * * @date Wed Oct 22 2003 * * @version $Header: /export/cvs-gridlab/wp-1/Codes/GATEngine/C-reference/src/GATSoftwareDescription.c,v 1.9 2004/04/02 12:31:58 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/GATSoftwareDescription.c,v 1.9 2004/04/02 12:31:58 hartmutkaiser Exp $"; /* System Header Files */ #include <stdlib.h> #include <string.h> /* GAT Header Files */ #include "GATInternal.h" #include "GATErrors.h" #include "GATType.h" #include "GATSoftwareDescription.h" #include "GATXdsWrapper.h" /* define the vtable types */ GATOBJECT_DEFINE_VTABLE(GATSoftwareDescription); GATSERIALISABLE_DEFINE_VTABLE(GATSoftwareDescription); /* define the converters to/from GATObject */ GATOBJECT_DEFINE_CONVERTERS(GATSoftwareDescription) /* Macros */ /* Structures, unions and enums */ struct GATSoftwareDescription_S { GATSoftwareDescription_vtable *GATObject__vtable; GATSoftwareDescription_ISerialisable_vtable *GATSerialisable__vtable; GATTable attributes; GATBool isdirty; }; /* Static function prototypes */ static int GATSoftwareDescription_DeSerialise_Create(GATContext context, GATObject stream, GATTable_const attributes, GATSoftwareDescription *new_object); /* File scope variables */ GATSoftwareDescription_vtable GATSoftwareDescription__vtable = { GATSoftwareDescription_GetType, GATSoftwareDescription_Destroy, GATSoftwareDescription_Equals, GATSoftwareDescription_Clone, GATSoftwareDescription_GetInterface }; static GATSoftwareDescription_ISerialisable_vtable GATSoftwareDescription_ISerialisable__vtable = { GATSoftwareDescription_Serialise, GATSoftwareDescription_DeSerialise, GATSoftwareDescription_GetIsDirty, }; /* External functions */ /** GATSoftwareDescription_Register_GATSerialisable * The GATSoftwareDescription_Register_GATSerialisable function registers the serialization * vtable with the GAT engine to allow generic object creation. * This function is called by the GAT engine, there is no need to use it * directly. */ GATResult GATSoftwareDescription_Register_GATSerialisable(void) { return GATObject_Register_GATSerialisable(GATType_GATSoftwareDescription, &GATSoftwareDescription_ISerialisable__vtable); } /** GATSoftwareDescription_Create * @brief Create a new GATSoftwareDescription object * * The function @c GATSoftwareDescription_Create creates a new * GATSoftwareDescription object * * @param attributes The attributes to initially use while initialising the * new GATSoftwareDescription. This parameter may be ommitted (zero). * * @return Returns a handle to the newly created GATSoftwareDescription object. * Returns 0 (zero) if an error occurs. */ GATSoftwareDescription GATSoftwareDescription_Create(GATTable_const attributes) { GATResult err_code = GAT_MEMORYFAILURE; GATSoftwareDescription retval = (GATSoftwareDescription) malloc( sizeof(struct GATSoftwareDescription_S)); if (NULL != retval) { memset(retval, 0, sizeof(struct GATSoftwareDescription_S)); retval->GATObject__vtable = &GATSoftwareDescription__vtable; retval->GATSerialisable__vtable = &GATSoftwareDescription_ISerialisable__vtable; retval->isdirty = GATFalse; if (NULL != attributes) { err_code = GATTable_Clone(attributes, &retval->attributes); } else { retval->attributes = GATTable_Create(); if (NULL != retval->attributes) { err_code = GAT_SUCCESS; } } } /* error handling */ if (GAT_SUCCESS != err_code) { /* FIXME: GATStatus(err_code) */ if (NULL != retval) { GATSoftwareDescription_Destroy(&retval); } } return retval; } /** void GATSoftwareDescription_Destroy(GATSoftwareDescription *resource) * * The function GATSoftwareDescription_Destroy is the destructor used to * free all the memory allocated by an GATSoftwareDescription instance. * * @param description The pointer to the GATSoftwareDescription to destroy */ void GATSoftwareDescription_Destroy(GATSoftwareDescription *object) { if (NULL != object && NULL != *object) { GATTable_Destroy(&(*object)->attributes); free(*object); *object = NULL; } } /** GATSoftwareDescription_Equals * @brief Compare two GATSoftwareDescription objects * * The function @c GATSoftwareDescription_Equals compares two objects of the * @c GATSoftwareDescription type. * * @param lhs The first list to compare * @param rhs The second list to compare * @param isequal The pointer to the location, where the outcome of the * function has to be stored. * * @return An error code. */ GATResult GATSoftwareDescription_Equals(GATSoftwareDescription_const lhs, GATSoftwareDescription_const rhs, GATBool *isequal) { GATResult retval = GAT_INVALID_HANDLE; *isequal = GATFalse; if (NULL != lhs && NULL != rhs) { retval = GAT_INVALID_PARAMETER; if (NULL != isequal) { retval = GATTable_Equals(lhs->attributes, rhs->attributes, isequal); } } return retval; } /** GATSoftwareDescription_Clone * @brief Clone the given GATSoftwareDescription * * The function @c GATSoftwareDescription_Clone generates a (deep) copy of * the given GATSoftwareDescription. * * @param description The object to clone * @param new_object The pointer, through which the result is to be * returned. * * @return An error type. */ GATResult GATSoftwareDescription_Clone(GATSoftwareDescription_const object, GATSoftwareDescription *new_object) { GATResult retval = GAT_INVALID_PARAMETER; if (NULL != new_object) { *new_object = GATSoftwareDescription_Create(object->attributes); if (NULL == *new_object) { retval = GAT_MEMORYFAILURE; } else { retval = GAT_SUCCESS; } } return retval; } /** int GATSoftwareDescription_GetType(GATResourceDescription_const resource) * @brief Return the type of the GATResourceDescription * * The function @c GATSoftwareDescription_GetType always returns * @c #GATType_GATSoftwareDescription. * * @param object The object to inspect * * @return Returns always @c #GATType_GATSoftwareDescription. */ GATType GATSoftwareDescription_GetType(GATSoftwareDescription_const description) { GAT_UNUSED_PARAMETER(description); return GATType_GATSoftwareDescription; } /** GATResult GATSoftwareDescription_GetInterface(GATSoftwareDescription_const file, GATInterface iftype, void const **ifp) * @brief Get an interface supported by a GATObject * * The function GATSoftwareDescription_GetInterface allows to get a pointer to an * additional interface supported by this GATSoftwareDescription. * * @param object The object to be asked for the new interface. * @param iftype The interface the object is to be asked for. * @param ifp The pointer, through which the result is to be returned. * * @return An error type. */ GATResult GATSoftwareDescription_GetInterface(GATSoftwareDescription_const object, GATInterface iftype, void const **ifp) { GATResult retval = GAT_INVALID_PARAMETER; if (NULL != ifp) { *ifp = NULL; if (GATInterface_ISerialisable == iftype) { *ifp = (void const *) &object->GATSerialisable__vtable; retval = GAT_SUCCESS; } else { retval = GAT_NO_INTERFACE; } } return retval; } /* GATSoftwareDescription API */ /** GATSoftwareDescription_GetAttributes * @brief Access the stored set of attributes * * The function @c GATSoftwareDescription_getAttributes allows to access the * attributes stored insoide the given GATSoftwareDescription instance. */ GATTable_const GATSoftwareDescription_GetAttributes(GATSoftwareDescription_const object) { GATTable retval = NULL; if (NULL != object) { retval = object->attributes; } return retval; } /** GATSoftwareDescription_internal_GetAttributesRef * @brief Access the stored set of attributes * * The function @c GATSoftwareDescription_internal_GetAttributesRef allows to * access the attributes stored inside the given GATSoftwareDescription * instance. * * @param object The software description to query for its attributes table. * @param attr The pointer to a variable, which receives the reslting * attributes table. * * @return An error code. */ GATResult GATSoftwareDescription_internal_GetAttributesRef( GATSoftwareDescription_const object, GATTable *attr) { GATResult retval = GAT_INVALID_HANDLE; if (NULL != object) { if (NULL != attr) { *attr = object->attributes; retval = GAT_SUCCESS; } else { retval = GAT_INVALID_PARAMETER; } } return retval; } /* Change the stored set of attributes */ GATResult GATSoftwareDescription_SetAttributes(GATSoftwareDescription object, GATTable_const attributes) { GATResult result = GAT_INVALID_HANDLE; if (NULL != object) { GATTable new_attributes = NULL; result = GATTable_Clone(attributes, &new_attributes); if (GAT_SUCCESS != result || NULL == new_attributes) { GATTable_Destroy(&new_attributes); result = GAT_MEMORYFAILURE; } else { GATTable_Destroy(&object->attributes); object->attributes = new_attributes; result = GAT_SUCCESS; } } return result; } /* GATAdvertiseable API */ /** GATResult GATSoftwareDescription_Serialise(GATSoftwareDescription object, GATObject stream, GATBool clear_dirty) * @brief Serialise a GATSoftwareDescription object * * The function GATSoftwareDescription_Serialise serialises the given * GATSoftwareDescription object into the given stream. * * @param object The GATSoftwareDescription object to serialise. * @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) * * @return An error code. */ GATResult GATSoftwareDescription_Serialise(GATSoftwareDescription object, GATObject stream, GATBool clear_dirty) { GATResult retval = GAT_INVALID_HANDLE; if (NULL != object) { retval = GATXds_SerialiseObject(GATSoftwareDescription_ToGATObject(object), stream, clear_dirty, 0, "uint32 object", GATSOFTWAREDESCRIPTION_VERSION1, object->attributes, clear_dirty); if (GAT_SUCCEEDED(retval) && clear_dirty) { object->isdirty = GATFalse; } } return retval; } /** GATSoftwareDescription_VersionCallback * * The function GATSoftwareDescription_VersionCallback is used as a callback function * during the de-serialisation of a GATSoftwareDescription. It should be * provided to test, whether the de-serialised version matches the expected * version. * * @param version The version number, which was de-serialised from the stream. * * @return This function should return GATTrue, if the version matches the * expected value (version is valid), GATFalse otherwise. * * @remark This function is called from the GAT engine, there is no need to * call it directly. */ static GATBool GATSoftwareDescription_VersionCallback(GATuint32 version) { GATBool retval = GATFalse; if ((version & ~GATSOFTWAREDESCRIPTION_MINOR_MASK) <= GATSOFTWAREDESCRIPTION_LASTVERSION) { retval = GATTrue; } return retval; } /** GATSoftwareDescription_DeSerialiseCallback * * The function GATSoftwareDescription_DeSerialiseCallback is used as a * callback function during the de-serialisation of a GATSoftwareDescription. * It should be provided for the instantiation of the new * GATSoftwareDescription object based on the already de-serialised * data items and the de-serialisation of the associated CPI provider data for * the given object. * * @param context The GAT context to be used for object construction. * @param stream The stream interface to use for the serialisation. * @param object The pointer to the variable, which should receive the newly * constructed object. * @param version The version of the saved data read from the input stream. * @param args This parameter is the pointer to the va_list containing * pointers to the already de-serialised data items accordingly to the * format string, provided during the call to the * GATSoftwareDescription_DeSerialise function. * * @return An error code. * * @remark This function is called from the GAT engine, there is no need to * call it directly. */ static GATResult GATSoftwareDescription_DeSerialiseCallback(GATContext context, GATObject stream, GATObject *new_object, GATuint32 version, va_list args) { /* the version was eaten already */ GATSoftwareDescription object = NULL; GATTable *attributes = va_arg(args, GATTable *); /* construct the new object */ GATResult retval = GATSoftwareDescription_DeSerialise_Create(context, stream, *attributes, &object); if (GAT_SUCCESS == retval) { if (NULL != object) { *new_object = GATSoftwareDescription_ToGATObject(object); } else { GATSoftwareDescription_Destroy(&object); retval = GAT_INVALID_PARAMETER; } } return retval; } /** GATSoftwareDescription GATSoftwareDescription_DeSerialise(GATContext context, GATObject stream, GATBool clear_dirty) * @brief De-serialise a GATSoftwareDescription object * * The function GATSoftwareDescription_DeSerialise de-serialises a streamed * GATSoftwareDescription object from the given stream It constructs a new * instance of the de-serialised object. * * @param context The GAT context to be used for object construction. * @param stream The stream interface to use for the serialisation. * @param result The pointer to a variable, which receives the status code of * the operation. * * @return The newly constructed GATSoftwareDescription object. */ GATSoftwareDescription GATSoftwareDescription_DeSerialise(GATContext context, GATObject stream, GATResult *result) { GAT_USES_STATUS(context, "GATSoftwareDescription_DeSerialise"); GATObject object = NULL; /* the new object will be created here */ /* we must provide all instance data items to be de-serialised for this GATSoftwareDescription object accordingly to the provided format string */ GATuint32 version = 0; GATTable attributes = NULL; /* read the data */ GAT_CREATE_STATUS(GATXds_DeSerialiseObject(context, stream, GATSoftwareDescription_DeSerialiseCallback, GATSoftwareDescription_VersionCallback, &object, "uint32 object", &version, &attributes)); GATTable_Destroy(&attributes); if (NULL != result) { *result = GAT_CURRENT_STATUS(); } else { GAT_CREATE_STATUS(GAT_INVALID_PARAMETER); } GAT_STORE_STATUS(); return GATObject_ToGATSoftwareDescription(object); } /** GATSoftwareDescription_GetIsDirty * * The function GATSoftwareDescription_GetIsDirty retrieves the status of the * dirty flag of this GATSoftwareDescription object. * * @param file The GATSoftwareDescription object to inspect for its dirty status. * @param isdirty The pointer to a variable, which receives the dirty status. * * @return An error code. */ GATResult GATSoftwareDescription_GetIsDirty(GATSoftwareDescription_const object, GATBool *isdirty) { GATResult retval = GAT_INVALID_HANDLE; if (NULL != object) { if (NULL != isdirty) { *isdirty = object->isdirty; retval = GAT_SUCCESS; } else { retval = GAT_INVALID_PARAMETER; } } return retval; } /* Local functions */ /** GATSoftwareDescription_DeSerialise_Create * * The function GATSoftwareDescription_DeSerialise_Create creates a new GATSoftwareDescription object. * * @param context The GAT context to use for creation of the GATSoftwareDescription object. * @param stream The object from which the adaptor should read the streamed * instance data. * @param attributes The attributes to use for inittialisation of the newly * created GATSoftwareDescription * @param new_object The pointer to the variable, which should receive the * newly constructed GATSoftwareDescription object. * * @return An error code. */ static GATResult GATSoftwareDescription_DeSerialise_Create(GATContext context, GATObject stream, GATTable_const attributes, GATSoftwareDescription *object) { GAT_USES_STATUS(context, "GATSoftwareDescription_DeSerialise_Create"); GATSoftwareDescription new_object = (GATSoftwareDescription) malloc(sizeof(struct GATSoftwareDescription_S)); if(NULL != new_object) { memset(new_object, 0, sizeof(struct GATSoftwareDescription_S)); new_object->GATObject__vtable = &GATSoftwareDescription__vtable; new_object->GATSerialisable__vtable = &GATSoftwareDescription_ISerialisable__vtable; new_object->isdirty = GATFalse; GAT_CREATE_STATUS(GATTable_Clone(attributes, &new_object->attributes)); } else { GAT_CREATE_STATUS(GAT_MEMORYFAILURE); } if (GAT_SUCCEEDED(GAT_CURRENT_STATUS())) { if (NULL != new_object) { *object = new_object; } else { GATSoftwareDescription_Destroy(&new_object); GAT_CREATE_STATUS(GAT_INVALID_PARAMETER); } } else { GATSoftwareDescription_Destroy(&new_object); } return GAT_RETURN_STATUS(); }