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

GATResource.c Go to the documentation of this file. /** @file GATResource.c * Source file for the GATResource class. * * @date Thu Oct 23 2003 * * @version $Header: /export/cvs-gridlab/wp-1/Codes/GATEngine/C-reference/src/GATResource.c,v 1.19 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/GATResource.c,v 1.19 2004/05/10 15:17:32 hartmutkaiser Exp $"; /* System Header objects */ #include <stdlib.h> #include <string.h> #include <assert.h> /* GAT Header objects */ #include "GAT.h" #include "GATInternal.h" #include "GATRegistry.h" #include "GATResourceCPI.h" #include "GATXdsWrapper.h" #include "GATMetricEvent.h" /* define the vtable types */ GATOBJECT_DEFINE_VTABLE(GATResource); GATSERIALISABLE_DEFINE_VTABLE(GATResource); GATMONITORABLE_DEFINE_VTABLE(GATResource); GATRESOURCE_DEFINE_VTABLE(GATResource); /* define the converters to/from GATObject */ GATOBJECT_DEFINE_CONVERTERS(GATResource) /* Macros */ #define GATRESOURCE_IMPLEMENTATION(type) \ GATOBJECT_DEFINE_CONVERTERS(type); \ GATOBJECT_DEFINE_CONVERTERS_QUALIFIED_EX(extern, type, GATType_ ## type, \ GATResource); \ \ type type ## _Create(GATContext context, GATPreferences_const prefs, \ void *instance_data) \ { \ return (type) GATResource_Impl_Create(GATType_ ## type, context, prefs, \ instance_data); \ } \ \ void type ## _Destroy(type *object) \ { \ GATResource_Destroy((GATResource *)object); \ } \ \ GATResult type ## _Equals(type ## _const lhs, type ## _const rhs, \ GATBool *isequal) \ { \ return GATResource_Equals((GATResource_const) lhs, \ (GATResource_const) rhs, isequal); \ } \ \ GATResult type ## _Clone(type ## _const object, type *new_object) \ { \ return GATResource_Clone((GATResource_const) object, \ (GATResource *)new_object); \ } \ \ GATType type ## _GetType(type ## _const object) \ { \ return GATResource_GetType((GATResource_const) object); \ } \ \ GATResult type ## _GetInterface(type ## _const object, GATInterface iftype, \ void const **ifp) \ { \ return GATResource_GetInterface((GATResource_const) object, iftype, \ ifp); \ } \ \ GATResult type ## _GetResourceDescription(type ## _const object, \ type ## Description_const *description) \ { \ return GATResource_Impl_GetResourceDescription((GATResource_const) object,\ (GATResourceDescription_const *) description); \ } \ GATResult type ## _GetReservation(type ## _const object, \ GATReservation_const *reservation) \ { \ return GATResource_Impl_GetReservation((GATResource_const) object, \ reservation); \ } \ \ GATResult type ## _AddMetricListener(type object, GATMetricListener listener,\ void *listener_data, GATMetric metric, GATuint32 *cookie) \ { \ return GATResource_Impl_AddMetricListener((GATResource) object, listener, \ listener_data, metric, cookie); \ } \ \ GATResult type ## _RegisterPolling(type object, GATMetric metric, \ GATMetricEvent *event, GATuint32 *cookie) \ { \ return GATResource_Impl_RegisterPolling((GATResource) object, metric, \ event, cookie); \ } \ \ GATResult type ## _RemoveRegisteredMetric(type object, GATMetric metric, \ GATuint32 cookie) \ { \ return GATResource_Impl_RemoveRegisteredMetric((GATResource) object, \ metric, cookie); \ } \ \ GATResult type ## _GetMetrics(type ## _const object, \ GATList_GATMetric *metrics) \ { \ return GATResource_Impl_GetMetrics((GATResource_const) object, metrics); \ } \ \ GATResult type ## _Serialise(type object, GATObject stream, \ GATBool clear_dirty) \ { \ return GATResource_Serialise((GATResource) object, stream, \ clear_dirty); \ } \ \ type type ## _DeSerialise(GATContext context, GATObject stream, \ GATResult *result) \ { \ return (type) GATResource_DeSerialise(context, stream, result); \ } \ \ GATResult type ## _GetIsDirty(type ## _const object, GATBool *isdirty) \ { \ return GATResource_GetIsDirty((GATResource_const) object, isdirty); \ } \ /**/ /* Structures, unions and enums */ struct GATResource_S { /* supported interfaces */ GATResource_vtable *GATObject__vtable; GATResource_ISerialisable_vtable *GATSerialisable__vtable; GATResource_IMonitorable_vtable *GATMonitorable__vtable; GATResource_IResource_vtable *GATResource__vtable; /* instance data */ GATResourceCPI_Instance data; /* instance data of the corresponding CPI object */ GATResourceCPI cpi; /* CPI object to use for all subsequent operations */ GATResourceCPIList cpilist; /* CPI list of appropriate CPI objects */ }; /* Static function prototypes */ static GATResult GATResource_DeSerialise_Create(GATContext context, GATObject stream, GATuint32 type, GATResource *new_object); /* GATObject specific functions */ static GATResource GATResource_Impl_Create(GATType type, GATContext context, GATPreferences_const preferences, void *instance_data); /* GATResource API */ static GATResult GATResource_Impl_GetResourceDescription(GATResource_const object, GATResourceDescription_const *description); static GATResult GATResource_Impl_GetReservation(GATResource_const object, GATReservation_const *reservation); /* GATMonitorable API */ static GATResult GATResource_Impl_AddMetricListener(GATResource object, GATMetricListener listener, void *listener_data, GATMetric metric, GATuint32 *cookie); static GATResult GATResource_Impl_RegisterPolling(GATResource object, GATMetric metric, GATMetricEvent *event, GATuint32 *cookie); static GATResult GATResource_Impl_RemoveRegisteredMetric(GATResource object, GATMetric metric, GATuint32 cookie); static GATResult GATResource_Impl_GetMetrics(GATResource_const object, GATList_GATMetric *metrics); static GATResult GATResource_GetCPIInstanceData(GATResource object, void **data); /* file scope variables */ GATResource_vtable GATResource__vtable = { GATResource_GetType, GATResource_Destroy, GATResource_Equals, GATResource_Clone, GATResource_GetInterface, GATResource_GetCPIInstanceData }; static GATResource_ISerialisable_vtable GATResource_ISerialisable__vtable = { GATResource_Serialise, GATResource_DeSerialise, GATResource_GetIsDirty, }; static GATResource_IMonitorable_vtable GATResource_IMonitorable__vtable = { GATResource_Impl_AddMetricListener, GATResource_Impl_RegisterPolling, GATResource_Impl_RemoveRegisteredMetric, GATResource_Impl_GetMetrics }; static GATResource_IResource_vtable GATResource_IResource__vtable = { GATResource_Impl_GetResourceDescription, GATResource_Impl_GetReservation }; /* External functions */ GATRESOURCE_IMPLEMENTATION(GATSoftwareResource); GATRESOURCE_IMPLEMENTATION(GATHardwareResource); /** GATResource_Impl_Register_GATSerialisable * The GATResource_Impl_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 GATResource_Register_GATSerialisable(void) { GATResult retval = GATObject_Register_GATSerialisable( GATType_GATHardwareResource, &GATResource_ISerialisable__vtable); if (GAT_SUCCESS == retval) { retval = GATObject_Register_GATSerialisable(GATType_GATSoftwareResource, &GATResource_ISerialisable__vtable); } return retval; } /* local functions */ /** GATResource_Impl_Create * @brief Create a new GATResource object * * The function @c GATResource_Impl_Create creates a new * GATResource object. This function is used from an adaptor only and not by * any GATEngine client code. * * @param type The concrete GATType of the implemented object. * @param context The GAT context to use while the initialisation of the * new object. * @param preferences The preferences to use wile selecting the adaptor for * the corresponding CPI. * * @return Returns a handle to the newly created GATResource object. * Returns 0 (zero) if an error occurs. * * @remark The concrete function name to use is determined by the type to be * stored inside the list. For instance, a list containing @c int's * would be destroyed with the function @c GATList_int_Destroy. */ static GATResource GATResource_Impl_Create(GATType type, GATContext context, GATPreferences_const preferences, void *instance_data) { GATResult err_code = GAT_MEMORYFAILURE; GATResource retval = (GATResource) malloc( sizeof(struct GATResource_S)); if (NULL != retval) { memset(retval, 0, sizeof(struct GATResource_S)); retval->GATObject__vtable = &GATResource__vtable; retval->GATSerialisable__vtable = &GATResource_ISerialisable__vtable; retval->GATMonitorable__vtable = &GATResource_IMonitorable__vtable; retval->GATResource__vtable = &GATResource_IResource__vtable; retval->data.context = context; retval->data.type = type; retval->data.isdirty = GATFalse; retval->data.source = GATResource_ToGATObject_const(retval); /* find a CPI object, which can handle this object */ { GATBool found_cpi = GATFalse; GATResourceCPIList current = NULL; GATRegistry_const registry = GATContext_internal_GetRegistry(context); /* use default preferences, if appropriate */ if (NULL == preferences) { preferences = GATContext_GetPreferences(context); } retval->cpilist = GATRegistry_FindGATResourceCPI(registry, preferences); if (NULL == retval->cpilist) { GATResource_Destroy(&retval); /* GATStatus(GAT_NO_REGISTERED_CPI) */ } else { /* create a new instance of the CPI provider */ err_code = GAT_NO_MATCHING_CPI; for(current = retval->cpilist; NULL != current; current = current->next) { err_code = GATResourceCPI_CreateInstance(current->cpi, &retval->data, instance_data); if (GAT_SUCCESS == err_code) { retval->cpi = current->cpi; found_cpi = GATTrue; break; } } if (GATTrue == found_cpi) { /* now, initialise the monitoring framework with the help of the CPI provider found */ GATList_GATMetric metrics = NULL; err_code = GATResourceCPI_GetMetrics(retval->cpi, &retval->data, &metrics); if (GAT_SUCCEEDED(err_code)) { retval->data.monitorable = GATMonitorable_Impl_Create(metrics); if (NULL == retval->data.monitorable) { err_code = GAT_MEMORYFAILURE; } GATList_GATMetric_Destroy(&metrics); } else if (GAT_NOTIMPL == err_code) { err_code = GAT_SUCCESS; /* no monitoring supported here */ } /* register this object with the engine */ if (GAT_SUCCEEDED(retval)) { err_code = GATRegistry_AddGATResourceToCPIList(context, retval->cpi, retval); } } } } } /* error handling */ if (GAT_FAILED(err_code)) { GATResource_Destroy(&retval); } return retval; } /** void GATResource_Destroy(GATResource *resource) * * The function GATResource_Destroy is the destructor used to * free all the memory allocated by an GATResource instance. * * @param description The pointer to the GATResource to destroy * * @remark The concrete function name to use is determined by the type to be * stored inside the list. For instance, a list containing @c int's * would be destroyed with the function @c GATList_int_Destroy. */ void GATResource_Destroy(GATResource *object) { if (NULL != object && NULL != *object) { /* TODO: free your internal object data here */ GATMonitorable_Impl_Destroy(&(*object)->data.monitorable); if (NULL != (*object)->cpi) /* during creation this may be zero */ { GATRegistry_RemoveGATResourceFromCPIList((*object)->data.context, (*object)->cpi, *object); GATResourceCPI_DestroyInstance((*object)->cpi, &(*object)->data); } GATResourceCPIList_Destroy((*object)->cpilist); free(*object); *object = NULL; } } /** GATResource_Equals * @brief Compare two GATResource objects * * The function @c GATResource_Equals compares two objects of the * @c GATResource type. * * @param lhs The first list to compare * @param rhs The second list to compare * @param isequal The pointer to the GATBool variable, which should receive * the result if the comparision * * @return An error code. * * @remark The concrete function name to use is determined by the type to be * stored inside the list. For instance, a list containing @c int's * would be destroyed with the function @c GATList_int_Destroy. */ GATResult GATResource_Equals(GATResource_const lhs, GATResource_const rhs, GATBool *isequal) { GATResult retval = GAT_INVALID_HANDLE; if (NULL != lhs && NULL != rhs) { retval = GAT_INVALID_PARAMETER; if (NULL != isequal) { /* TODO: compare your instance data here */ retval = GATResourceCPI_EqualsInstance(lhs->cpi, &lhs->data, &rhs->data, isequal); } } return retval; } /** GATResource_Clone * @brief Clone the given GATResource * * The function @c GATResource_Clone generates a (deep) copy of * the given GATResource. * * @param description The object to clone * @param new_object The pointer, through which the result is to be * returned. * * @return An error type. * * @remark The concrete function name to use is determined by the type to be * stored inside the list. For instance, a list containing @c int's * would be destroyed with the function @c GATList_int_Destroy. */ GATResult GATResource_Clone(GATResource_const handle, GATResource *new_handle) { GATResult retval = GAT_INVALID_HANDLE; if (NULL != handle) { if (NULL == new_handle) { retval = GAT_INVALID_PARAMETER; } else { struct GATResource_S const *object = handle; GATResource new_object = (GATResource) malloc(sizeof(struct GATResource_S)); *new_handle = NULL; if (NULL == new_object) { retval = GAT_MEMORYFAILURE; } else { memset(new_object, 0, sizeof(struct GATResource_S)); new_object->GATObject__vtable = &GATResource__vtable; new_object->GATSerialisable__vtable = &GATResource_ISerialisable__vtable; new_object->GATMonitorable__vtable = &GATResource_IMonitorable__vtable; new_object->GATResource__vtable = &GATResource_IResource__vtable; new_object->data.context = object->data.context; new_object->data.type = object->data.type; new_object->data.isdirty = GATFalse; new_object->data.source = GATResource_ToGATObject_const(new_object); /* TODO: insert cloning of your constructor supplied data here */ new_object->cpilist = GATRegistry_CloneGATResourceCPIList(object->cpilist); if (NULL == new_object->cpilist) { retval = GAT_MEMORYFAILURE; GATResource_Destroy(&new_object); } else { /* re-find the cpi to use */ GATResourceCPIList current = object->cpilist; GATResourceCPIList new_current = new_object->cpilist; for (/**/; NULL != current; current = current->next, new_current = new_current->next) { if (current->cpi == object->cpi) { new_object->cpi = new_current->cpi; break; } } assert(NULL != new_object->cpi); /* clone the instance data */ retval = GATResourceCPI_CloneInstance(object->cpi, &object->data, &new_object->data); if (GAT_SUCCESS != retval) { GATResource_Destroy(&new_object); } else { /* clone the monitoring data */ if (NULL != object->data.monitorable) { retval = GATMonitorable_Impl_Clone(object->data.monitorable, &new_object->data.monitorable); } /* register this object with the engine */ if (GAT_SUCCEEDED(retval)) { retval = GATRegistry_AddGATResourceToCPIList( new_object->data.context, new_object->cpi, new_object); } if (GAT_FAILED(retval)) { GATResource_Destroy(&new_object); } else { /* return the new object */ *new_handle = new_object; } } } } } } return retval; } /** GATType GATResource_GetType(GATResource_const resource) * @brief Return the type of the GATResource * * The function @c GATResource_GetType always returns * @c #GATType_GATResource. * * @param object The object to inspect * * @return Returns always @c #GATType_GATResource. * * @remark The concrete function name to use is determined by the type to be * stored inside the list. For instance, a list containing @c int's * would be destroyed with the function @c GATList_int_Destroy. */ GATType GATResource_GetType(GATResource_const object) { GATType retval = GATType_NoType; if (NULL != object) { retval = object->data.type; } return retval; } /** int GATResource_GetInterface(GATResource_const file, GATInterface iftype, void const **ifp) * @brief Get an interface supported by a GATObject * * The function GATResource_GetInterface allows to get a pointer to an * additional interface supported by this GATResource. * * @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. * * @remark The concrete function name to use is determined by the type to be * stored inside the list. For instance, a list containing @c int's * would be destroyed with the function @c GATList_int_Destroy. */ GATResult GATResource_GetInterface(GATResource_const object, GATInterface iftype, void const **ifp) { GATResult retval = GAT_INVALID_PARAMETER; if (NULL != ifp) { *ifp = NULL; if (GATInterface_ISerialisable == iftype || GATInterface_IAdvertisable == iftype) { *ifp = (void const *) &object->GATSerialisable__vtable; retval = GAT_SUCCESS; } else if (GATInterface_IResource == iftype) { *ifp = (void const *) &object->GATResource__vtable; retval = GAT_SUCCESS; } else if (GATInterface_IMonitorable == iftype && NULL != object->data.monitorable) { *ifp = (void const *) &object->GATMonitorable__vtable; retval = GAT_SUCCESS; } else { retval = GAT_NO_INTERFACE; } } return retval; } /* GATResource API */ /** int GATResource_Impl_GetResourceDescription(GATResource_const object, GATResourceDescription_const *description) * * The function GATResource_Impl_GetResourceDescription returns the * GATResourceDescription which describes this GATResource instance. * * @param object The GATResource instance to ask for its resource description. * @param description The pointer to the variable, which receives the * resulting resource description. * * @return An error code. * * @remark The concrete function name to use is determined by the type to be * stored inside the list. For instance, a list containing @c int's * would be destroyed with the function @c GATList_int_Destroy. */ static GATResult GATResource_Impl_GetResourceDescription(GATResource_const object, GATResourceDescription_const *description) { return GATResourceCPI_GetResourceDescription(object->cpi, &object->data, description); } /** int GATResource_Impl_GetReservation(GATResource_const object, GATReservation_const *reservation) * * The function GATResource_Impl_GetReservation returns the GATReservation * which is associated with this GATResource. * * @param object The GATResource instance to ask for its associated * reservation. * @param reservation The pointer to a variable, which receives the resulting * reservation. * * @return An error code. * * @remark The concrete function name to use is determined by the type to be * stored inside the list. For instance, a list containing @c int's * would be destroyed with the function @c GATList_int_Destroy. */ static GATResult GATResource_Impl_GetReservation(GATResource_const object, GATReservation_const *reservation) { return GATResourceCPI_GetReservation(object->cpi, &object->data, reservation); } /* GATMonitorable API */ /** GATResource_Impl_AddMetricListener * * The function GATResource_Impl_AddMetricListener adds the passed instance of a * GATMetricListener to the list of GATMetricListeners which are notified of * fired GATMetricEvents of the type described by the provided GATMetric * instance. * * @param object The GATResource instance to add the GATMetricListener to. * @param listener The GATMetricListener to call, when the corresponding * GATMetricEvent is fired. * @param listener_data The client supplied data, which will be passed through * to the GATMetricListener. * @param metric The GATMetric instance describing the GATMetricEvent to pass * to the GATMetricListener. * @param cookie The returned value should be used to remove the * GATMetricListener from this GATMonitorable. * * @return An error code. * * @remark The concrete function name to use is determined by the type to be * stored inside the list. For instance, a list containing @c int's * would be destroyed with the function @c GATList_int_Destroy. */ static GATResult GATResource_Impl_AddMetricListener(GATResource object, GATMetricListener listener, void *listener_data, GATMetric metric, GATuint32 *cookie) { GATResult retval = GAT_INVALID_HANDLE; if (NULL != object) { if (NULL != object->data.monitorable) { retval = GATMonitorable_Impl_AddMetricListener(object->data.monitorable, listener, listener_data, metric, cookie); } else { /* this may happen, if the adaptor has not registered any GATMetrics */ retval = GAT_NO_INTERFACE; } } return retval; } /** GATResource_Impl_RegisterPolling * * The function GATResource_Impl_RegisterPolling registers a continuous * metric with the given GATResource instance. * * @param object The GATResource instance to register the metric with. * @param metric The GATMetric instance describing the GATMetricEvent to pass * to the GATMetricListener. This metric instance must be of type * GATMeasurementType_Continuous, otherwise an error is returned. * @param event The pointer to a variable, which should receive the resulting * GATMetricEvent. The GATMetricEvent instance should be freed by the * caller when it isn't used anymore. * @param cookie The returned value should be used to remove the * GATMetricListener from this GATResource. * * @return An error code. * * @remark The concrete function name to use is determined by the type to be * stored inside the list. For instance, a list containing @c int's * would be destroyed with the function @c GATList_int_Destroy. */ static GATResult GATResource_Impl_RegisterPolling(GATResource object, GATMetric metric, GATMetricEvent *event, GATuint32 *cookie) { GATResult retval = GAT_INVALID_HANDLE; if (NULL != object) { if (NULL != object->data.monitorable) { retval = GATMonitorable_Impl_RegisterPolling(object->data.monitorable, metric, 0, cookie); if (GAT_SUCCESS == retval) { /* ask the CPI provider to return the corresponding metric event */ retval = GATResourceCPI_GetMetricEvent(object->cpi, &object->data, metric, event); if (GAT_SUCCESS != retval) { GATMonitorable_Impl_RemoveRegisteredMetric(object->data.monitorable, metric, *cookie); *cookie = 0; } } } else { /* this may happen, if the adaptor has not registered any GATMetrics */ retval = GAT_NO_INTERFACE; } } return retval; } /** GATResource_Impl_RemoveRegisteredMetric * * The function GATResource_Impl_RemoveRegisteredMetric removes a GATMetricListener, * which was previously registered with GATResource_Impl_AddMetricListener. * * @param object The GATResource instance to remove the GATMetricListener from. * @param listener The GTAMetricListener to call, when the corresponding * GATMetricEvent is fired. * @param metric The GATMetric instance describing the GATMetricEvent to pass * to the GATMetricListener. * @param cookie This value identifies the GATMetricListener to remove, it * was returned from the corresponding GATMonitorable_AddMetricListener * or GATMonitorable_MetricRegisterPolling functions. * * @return An error code. * * @remark The concrete function name to use is determined by the type to be * stored inside the list. For instance, a list containing @c int's * would be destroyed with the function @c GATList_int_Destroy. */ static GATResult GATResource_Impl_RemoveRegisteredMetric(GATResource object, GATMetric metric, GATuint32 cookie) { GATResult retval = GAT_INVALID_HANDLE; if (NULL != object) { if (NULL != object->data.monitorable) { retval = GATMonitorable_Impl_RemoveRegisteredMetric( object->data.monitorable, metric, cookie); } else { /* this may happen, if the adaptor has not registered any GATMetrics */ retval = GAT_NO_INTERFACE; } } return retval; } /** GATResource_Impl_GetMetrics * * The function GATResource_Impl_GetMetrics returns a list of metrics supported * by this GATResource. * * @param object The GATResource instance, for which the supported metrics * should be returned. * @param metrics The pointer to the variable, which receives the resulting * list of metrics. * * @return An error code. * * @remark The concrete function name to use is determined by the type to be * stored inside the list. For instance, a list containing @c int's * would be destroyed with the function @c GATList_int_Destroy. */ static GATResult GATResource_Impl_GetMetrics(GATResource_const object, GATList_GATMetric *metrics) { GATResult retval = GAT_INVALID_HANDLE; if (NULL != object) { if (NULL != object->data.monitorable) { retval = GATMonitorable_Impl_GetMetrics(object->data.monitorable, metrics); } else { /* this may happen, if the adaptor has not registered any GATMetrics */ retval = GAT_NO_INTERFACE; } } return retval; } /* GATAdvertiseable API */ /** GATResourceCPI_SerialiseCallback * * The function GATResourceCPI_SerialiseCallback is used as a callback * function for the serialisation of a GATResource object. * It should be provided to serialise the associated CPI provider data for * the given object. * * @param object The object to serialise. This is the same as the object * passed as the first parameter to the function GATXds_SerialiseObject. * @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. * * @remark This function is called from the GAT engine, there is no need to * call it directly. * * @remark The concrete function name to use is determined by the type to be * stored inside the list. For instance, a list containing @c int's * would be destroyed with the function @c GATList_int_Destroy. */ static GATResult GATResourceCPI_SerialiseCallback(GATObject handle, GATObject stream, GATBool clear_dirty) { GATResult retval = GAT_INVALID_PARAMETER; GATType type = GATObject_GetType(handle); if (GATType_GATSoftwareResource == type) { GATResource object = (GATResource) GATObject_ToGATSoftwareResource(handle); retval = GATResourceCPI_Serialise(object->cpi, &object->data, stream, clear_dirty); if (GAT_SUCCEEDED(retval) && GATTrue == clear_dirty) { object->data.isdirty = GATFalse; } } else if (GATType_GATHardwareResource == type) { GATResource object = (GATResource) GATObject_ToGATHardwareResource(handle); retval = GATResourceCPI_Serialise(object->cpi, &object->data, stream, clear_dirty); if (GAT_SUCCEEDED(retval) && GATTrue == clear_dirty) { object->data.isdirty = GATFalse; } } return retval; } /** int GATResource_Serialise(GATResource object, GATObject stream, GATBool clear_dirty) * @brief Serialise a GATResource object * * The function GATResource_Serialise serialises the given GATFIle object into * the given stream. * * @param object The GATResource 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. * * @remark The concrete function name to use is determined by the type to be * stored inside the list. For instance, a list containing @c int's * would be destroyed with the function @c GATList_int_Destroy. */ GATResult GATResource_Serialise(GATResource object, GATObject stream, GATBool clear_dirty) { GATResult retval = GAT_INVALID_HANDLE; if (NULL != object) { retval = GATXds_SerialiseObject(GATResource_ToGATObject(object), stream, clear_dirty, GATResourceCPI_SerialiseCallback, "uint32 uint32", GATRESOURCE_VERSION1, (GATuint32)object->data.type); if (GAT_SUCCEEDED(retval) && clear_dirty) { object->data.isdirty = GATFalse; } } return retval; } /** GATResource_Impl_VersionCallback * * The function GATResource_Impl_VersionCallback is used as a callback function * during the de-serialisation of a GATResource. 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. * * @remark The concrete function name to use is determined by the type to be * stored inside the list. For instance, a list containing @c int's * would be destroyed with the function @c GATList_int_Destroy. */ static GATBool GATResource_Impl_VersionCallback(GATuint32 version) { GATBool retval = GATFalse; if ((version & ~GATRESOURCE_MINOR_MASK) <= GATRESOURCE_LASTVERSION) { retval = GATTrue; } return retval; } /** GATResource_DeSerialiseCallback * * The function GATResource_DeSerialiseCallback is used as a callback function * during the de-serialisation of a GATResource. It should be provided for the * instantiation of the new GATResource 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 * GATResource_DeSerialise function. * * @return An error code. * * @remark This function is called from the GAT engine, there is no need to * call it directly. * * @remark The concrete function name to use is determined by the type to be * stored inside the list. For instance, a list containing @c int's * would be destroyed with the function @c GATList_int_Destroy. */ static GATResult GATResource_DeSerialiseCallback(GATContext context, GATObject stream, GATObject *new_object, GATuint32 version, va_list args) { /* the version was eaten already */ GATuint32 *type = va_arg(args, GATuint32 *); /* GATType */ GATResource object = NULL; /* construct the new object */ GATResult retval = GATResource_DeSerialise_Create(context, stream, *type, &object); GAT_UNUSED_PARAMETER(version); if (GAT_SUCCESS == retval) { if (NULL != object) { *new_object = GATResource_ToGATObject(object); } else { GATResource_Destroy(&object); retval = GAT_INVALID_PARAMETER; } } return retval; } /** GATResource GATResource_DeSerialise(GATContext context, GATObject stream, GATBool clear_dirty) * @brief De-serialise a GATResource object * * The function GATResource_DeSerialise de-serialises a streamed * GATResource 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 GATResource object. * * @remark The concrete function name to use is determined by the type to be * stored inside the list. For instance, a list containing @c int's * would be destroyed with the function @c GATList_int_Destroy. */ GATResource GATResource_DeSerialise(GATContext context, GATObject stream, GATResult *result) { GATObject object = NULL; /* the new object will be created here */ /* we must provide all instance data items to be de-serialised for this GATResource object accordingly to the provided format string */ GATuint32 version = 0; GATuint32 type = GATType_NoType; /* read the data */ GATResult retval = GATXds_DeSerialiseObject(context, stream, GATResource_DeSerialiseCallback, GATResource_Impl_VersionCallback, &object, "uint32 uint32", &version, &type); /* FIXME: GATStatus(retval); */ if (NULL != result) { *result = retval; } return (GATResource) object; } /** GATResource_GetIsDirty * * The function GATResource_GetIsDirty retrieves the status of the dirty * flag of this GATResource object. * * @param file The GATResource object to inspect for its dirty status. * @param isdirty The pointer to a variable, which receives the dirty status. * * @return An error code. * * @remark The concrete function name to use is determined by the type to be * stored inside the list. For instance, a list containing @c int's * would be destroyed with the function @c GATList_int_Destroy. */ GATResult GATResource_GetIsDirty(GATResource_const object, GATBool *isdirty) { GATResult retval = GAT_INVALID_HANDLE; if (NULL != object) { if (NULL != isdirty) { *isdirty = object->data.isdirty; retval = GAT_SUCCESS; } else { retval = GAT_INVALID_PARAMETER; } } return retval; } /** GATResource_DeSerialise_Create * * The function GATResource_DeSerialise_Create creates a new GATResource * object. * Further it tries find a CPI provider to associate with this file object. * The CPI provider is selected by testing, which adapter is able to handle * the streamed instance data of the original CPI provider. * * @param context The GAT context to use for creation of the GATResource * object. * @param stream The object from which the adaptor should read the streamed * instance data. * @param type The actual type of the object to create. * @param new_object The pointer to the variable, which should receive the * newly constructed GATResource object. * * @return An error code. */ static GATResult GATResource_DeSerialise_Create(GATContext context, GATObject stream, GATuint32 type, GATResource *object) { GATResult retval = GAT_MEMORYFAILURE; GATResource new_object = (GATResource) malloc(sizeof(struct GATResource_S)); if(NULL != new_object) { memset(new_object, 0, sizeof(struct GATResource_S)); new_object->GATObject__vtable = &GATResource__vtable; new_object->GATSerialisable__vtable = &GATResource_ISerialisable__vtable; new_object->GATMonitorable__vtable = &GATResource_IMonitorable__vtable; new_object->GATResource__vtable = &GATResource_IResource__vtable; new_object->data.context = context; new_object->data.type = (GATType)type; new_object->data.isdirty = GATFalse; new_object->data.source = GATResource_ToGATObject_const(new_object); /* find a CPI object, which can handle the data at the given stream location */ { GATRegistry_const registry = GATContext_internal_GetRegistry(context); GATPreferences_const preferences = NULL; /* use default preferences, if appropriate */ if (NULL == preferences) { preferences = GATContext_GetPreferences(context); } new_object->cpilist = GATRegistry_FindGATResourceCPI(registry, preferences); if (NULL == new_object->cpilist) { retval = GAT_NO_REGISTERED_CPI; } else { /* find out the current stream position */ GATuint32 offset = 0; GATBool found_cpi = GATFalse; GATResourceCPIList current = NULL; retval = GATStreamable_Seek(stream, GATOrigin_Current, 0, &offset); if (GAT_SUCCESS == retval) { /* create new instance data of the CPI provider */ for(current = new_object->cpilist; NULL != current; current = current->next) { /* try, whether this CPI can handle the input */ retval = GATResourceCPI_DeSerialise(current->cpi, stream, &new_object->data); if (GAT_SUCCESS == retval) { new_object->cpi = current->cpi; found_cpi = GATTrue; break; } /* reset stream pointer to the beginning of the CPI instance data */ retval = GATStreamable_Seek(stream, GATOrigin_Set, offset, 0); if (GAT_SUCCESS != retval) { break; } } } /* no available CPI object can handle this */ if (GATFalse == found_cpi) { retval = GAT_NO_MATCHING_CPI; } else { /* try to re-init the monitoring support, since the adaptor found may support another set of GATMetric's, than the original one. */ GATList_GATMetric metrics = NULL; retval = GATResourceCPI_GetMetrics(new_object->cpi, &new_object->data, &metrics); if (GAT_SUCCEEDED(retval)) { new_object->data.monitorable = GATMonitorable_Impl_Create(metrics); if (NULL != new_object->data.monitorable) { retval = GAT_MEMORYFAILURE; } GATList_GATMetric_Destroy(&metrics); } else if (GAT_NOTIMPL == retval) { retval = GAT_SUCCESS; /* no monitoring supported here */ } if (GAT_SUCCEEDED(retval)) { retval = GATRegistry_AddGATResourceToCPIList( new_object->data.context, new_object->cpi, new_object); } } } } } if (GAT_SUCCESS == retval) { if (NULL != new_object) { *object = new_object; } else { GATResource_Destroy(&new_object); retval = GAT_INVALID_PARAMETER; } } else { GATResource_Destroy(&new_object); } return retval; } /* GATResource_GetCPIInstanceData * * The function GATResource_GetCPIInstanceData returns the CPI instance data, * associated with the given GATResource object. * * @param object The object, for which to return the CPI instance data. * @param data The pointer to the variable, which should receive the * resulting CPI instance data. * * @return An error code. */ static GATResult GATResource_GetCPIInstanceData(GATResource object, void **data) { GATResult retval = GAT_INVALID_HANDLE; if (NULL != object) { if (NULL != data) { *data = (void *)&object->data; retval = GAT_SUCCESS; } else { retval = GAT_INVALID_PARAMETER; } } return retval; }