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

GATFile.c Go to the documentation of this file. /** @file GATTable.c * Main file for the GATFile class. * * A GATFile is an abstract representation of a physical file. * * @date Wed Sep 24 2003 * * @version $Header: /export/cvs-gridlab/wp-1/Codes/GATEngine/C-reference/src/GATFile.c,v 1.61 2004/04/20 12:33:22 hartmutkaiser Exp $ * * Copyright (C) Tom Goodale * Copyright (C) Hartmut Kaiser * This file is part of the GAT Engine. * Contributed by Tom Goodale <goodale@aei.mpg.de> and * 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/GATFile.c,v 1.61 2004/04/20 12:33:22 hartmutkaiser Exp $"; /* System Header Files */ #include <stdio.h> #include <stdlib.h> #include <string.h> #include <assert.h> /* GAT Header Files */ #include "GAT.h" #include "GATRegistry.h" #include "GATInternal.h" #include "GATFileCPI.h" #include "GATMetricEvent.h" #include "GATXdsWrapper.h" /* define the vtable types */ GATOBJECT_DEFINE_VTABLE(GATFile); GATSERIALISABLE_DEFINE_VTABLE(GATFile); GATMONITORABLE_DEFINE_VTABLE(GATFile); /* Declare the converters to/from GATObject */ GATOBJECT_DEFINE_CONVERTERS(GATFile); /* Macros */ /* Structures, unions and enums */ struct GATFile_S { /* supported interfaces */ GATFile_vtable *GATObject__vtable; GATFile_ISerialisable_vtable *GATSerialisable__vtable; GATFile_IMonitorable_vtable *GATMonitorable__vtable; /* instance data */ GATFileCPI_Instance data; /* instance data of the corresponding CPI object */ GATFileCPI cpi; /* CPI object to use for all subsequent operations */ GATFileCPIList cpilist; /* CPI list of appropriate CPI objects */ }; /* Static function prototypes */ static GATResult GATFile_DeSerialise_Create(GATContext context, GATObject stream, char const *name, GATFile *new_file); static GATResult GATFile_GetCPIInstanceData(GATFile file, void **data); /* File scope variables */ static GATFile_vtable GATFile__vtable = { GATFile_GetType, GATFile_Destroy, GATFile_Equals, GATFile_Clone, GATFile_GetInterface, GATFile_GetCPIInstanceData, }; static GATFile_ISerialisable_vtable GATFile_ISerialisable__vtable = { GATFile_Serialise, GATFile_DeSerialise, GATFile_GetIsDirty }; static GATFile_IMonitorable_vtable GATFile_IMonitorable__vtable = { GATFile_AddMetricListener, GATFile_RegisterPolling, GATFile_RemoveRegisteredMetric, GATFile_GetMetrics }; /* External functions */ /** GATFile_Register_GATSerialisable * The GATFile_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 GATFile_Register_GATSerialisable(void) { return GATObject_Register_GATSerialisable(GATType_GATFile, &GATFile_ISerialisable__vtable); } /** GATFile_Create * The GATFile constructor. * This is the constructor for GATFile objects. * * @return A new GATFile */ GATFile GATFile_Create(GATContext context, GATLocation_const location, GATPreferences_const preferences) { GAT_STATUS_APIENTRY(context, "GATFile_Create"); GATFile new_file = (GATFile) malloc(sizeof(struct GATFile_S)); if(NULL != new_file) { memset(new_file, 0, sizeof(struct GATFile_S)); new_file->GATObject__vtable = &GATFile__vtable; new_file->GATSerialisable__vtable = &GATFile_ISerialisable__vtable; new_file->GATMonitorable__vtable = &GATFile_IMonitorable__vtable; new_file->data.context = context; new_file->data.isdirty = GATFalse; new_file->data.source = GATFile_ToGATObject_const(new_file); GAT_CREATE_STATUS(GATLocation_Clone(location, &new_file->data.location)); /* find a CPI object, which can handle the file at the given location */ if (GAT_SUCCEEDED(GAT_CURRENT_STATUS())) { GATRegistry_const registry = GATContext_internal_GetRegistry(context); /* use default preferences, if appropriate */ if (NULL == preferences) { preferences = GATContext_GetPreferences(context); } new_file->cpilist = GATRegistry_FindGATFileCPI(registry, preferences); if (NULL == new_file->cpilist) { GAT_CREATE_STATUS(GAT_NO_REGISTERED_CPI); } else { /* create a new instance of the CPI provider */ GATBool found_cpi = GATFalse; GATFileCPIList current = NULL; for(current = new_file->cpilist; NULL != current; current = current->next) { GAT_CREATE_STATUS(GATFileCPI_CreateInstance(current->cpi, &new_file->data)); if (GAT_SUCCEEDED(GAT_CURRENT_STATUS())) { new_file->cpi = current->cpi; found_cpi = GATTrue; break; } } /* no available CPI object can handle this */ if (GATFalse == found_cpi) { GAT_CREATE_STATUS(GAT_NO_REGISTERED_CPI); } else { /* now, initialise the monitoring framework with the help of the CPI provider found */ GATList_GATMetric metrics = NULL; GATResult retval = GATFileCPI_GetMetrics(new_file->cpi, &new_file->data, &metrics); if (GAT_SUCCEEDED(retval)) { new_file->data.monitorable = GATMonitorable_Impl_Create(metrics); if (NULL == new_file->data.monitorable) { GAT_CREATE_STATUS(GAT_MEMORYFAILURE); } GATList_GATMetric_Destroy(&metrics); } else if (GAT_NOTIMPL == retval) { retval = GAT_SUCCESS; /* no monitoring supported here */ } else { GAT_CREATE_STATUS(retval); } /* register this object with the engine */ GAT_CREATE_STATUS(GATRegistry_AddGATFileToCPIList(context, new_file->cpi, new_file)); } } } } else { GAT_CREATE_STATUS(GAT_MEMORYFAILURE); } /* error handling */ if (GAT_FAILED(GAT_CURRENT_STATUS())) { GATFile_Destroy(&new_file); } GAT_STORE_STATUS(); return new_file; } /** GATFile_Create_Name * The GATFile constructor. * This is the constructor for GATFile objects. * * @return A new GATFile */ GATFile GATFile_Create_Name(GATContext context, char const *name, GATPreferences preferences) { GATFile file = NULL; GATLocation location = GATLocation_Create(name); if (NULL != location) { file = GATFile_Create(context, location, preferences); GATLocation_Destroy(&location); } else { GAT_STATUS_APIENTRY(context, "GATFile_Create_Name"); GAT_CREATE_STATUS(GAT_MEMORYFAILURE); GAT_STORE_STATUS(); } return file; } /** GATFile_Destroy * The GATFile destructor. * This is the destructor for GATFile objects. * * @param this An old GATFile */ void GATFile_Destroy(GATFile *file) { if(NULL != file && NULL != *file) { GATMonitorable_Impl_Destroy(&(*file)->data.monitorable); if (NULL != (*file)->cpi) { GATRegistry_RemoveGATFileFromCPIList((*file)->data.context, (*file)->cpi, *file); GATFileCPI_DestroyInstance((*file)->cpi, &(*file)->data); } GATLocation_Destroy(&(*file)->data.location); GATFileCPIList_Destroy((*file)->cpilist); free(*file); *file = NULL; } } /** int GATFile_GetType(GATFile_const file) * @brief Return the type of the GATFile * * The function @c GATFile_GetType always returns GATType_GATFile. * * @param object The object to inspect * * @return returns always @c #GATType_GATFile. */ GATType GATFile_GetType(GATFile_const file) { GAT_UNUSED_PARAMETER(file); return GATType_GATFile; } /** int GATFile_Clone(GATFile_const filehandle, GATFile *new_file) * @brief Clone the given GATFile * * The function @c GATFile_Clone generates a (deep) copy of the given * GATFile. * * @param filehandle The object to clone * @param new_file The pointer, through which the result is to be * returned. * * @return An error type. */ GATResult GATFile_Clone(GATFile_const filehandle, GATFile *new_object) { if (NULL != filehandle) { GAT_USES_STATUS(filehandle->data.context, "GATFile_Clone"); if (NULL != new_object) { struct GATFile_S const *file = filehandle; GATFile new_file = (GATFile) malloc(sizeof(struct GATFile_S)); *new_object = NULL; if (NULL == new_file) { GAT_CREATE_STATUS(GAT_MEMORYFAILURE); } else { memset(new_file, 0, sizeof(struct GATFile_S)); new_file->GATObject__vtable = &GATFile__vtable; new_file->GATSerialisable__vtable = &GATFile_ISerialisable__vtable; new_file->GATMonitorable__vtable = &GATFile_IMonitorable__vtable; new_file->data.context = file->data.context; new_file->data.isdirty = GATFalse; new_file->data.source = GATFile_ToGATObject_const(new_file); new_file->cpilist = GATRegistry_CloneGATFileCPIList(file->cpilist); if (NULL == new_file->cpilist) { GAT_CREATE_STATUS(GAT_MEMORYFAILURE); } GAT_CREATE_STATUS(GATLocation_Clone(file->data.location, &new_file->data.location)); if (GAT_SUCCEEDED(GAT_CURRENT_STATUS())) { /* re-find the cpi to use */ GATFileCPIList current = file->cpilist; GATFileCPIList new_current = new_file->cpilist; for (/**/; NULL != current; current = current->next, new_current = new_current->next) { if (current->cpi == file->cpi) { new_file->cpi = new_current->cpi; break; } } assert(NULL != new_file->cpi); /* clone the instance data */ GAT_CREATE_STATUS(GATFileCPI_CloneInstance(file->cpi, &file->data, &new_file->data)); /* clone the monitoring data */ if (NULL != file->data.monitorable) { GAT_CREATE_STATUS(GATMonitorable_Impl_Clone(file->data.monitorable, &new_file->data.monitorable)); } /* register this object with the engine */ GAT_CREATE_STATUS(GATRegistry_AddGATFileToCPIList( new_file->data.context, new_file->cpi, new_file)); } } /* destroy the newly allocated object, if some error occured */ if (GAT_FAILED(GAT_CURRENT_STATUS())) { GATFile_Destroy(&new_file); } else { /* return the new object */ *new_object = new_file; } } else { GAT_CREATE_STATUS(GAT_INVALID_PARAMETER); } return GAT_RETURN_STATUS(); } return GAT_INVALID_HANDLE; } /** int GATFile_Equals(GATFile_const lhs, GATFile_const rhs, GATBool *isequal) * @brief Compares two GATFile objects * * The function @c GATFile_Equals compares two file objects of type * @c #GATFile. * * @param lhs The first file object to compare * @param rhs The second file object to compare * @param isequal The pointer to the GATBool variable, which should receive * the result if the comparision * * @return An error code. */ GATResult GATFile_Equals(GATFile_const lhs, GATFile_const rhs, GATBool *isequal) { if (NULL != lhs && NULL != rhs) { GAT_STATUS_APIENTRY(lhs->data.context, "GATFile_Equals"); if (NULL != isequal) { GAT_CREATE_STATUS(GATLocation_Equals(lhs->data.location, rhs->data.location, isequal)); if (GATTrue == *isequal) { GAT_CREATE_STATUS(GATFileCPI_EqualsInstance(lhs->cpi, &lhs->data, &rhs->data, isequal)); } } else { GAT_CREATE_STATUS(GAT_INVALID_PARAMETER); } return GAT_RETURN_STATUS(); } return GAT_INVALID_HANDLE; } /** int GATFile_GetInterface(GATFile_const file, GATInterface iftype, void const **ifp) * @brief Get an interface supported by a GATObject * * The function GATFile_GetInterface allows to get a pointer to an * additional interface supported by this GATFile. * * @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 GATFile_GetInterface(GATFile_const file, GATInterface iftype, void const **ifp) { if (NULL != file) { GAT_STATUS_APIENTRY(file->data.context, "GATFile_GetInterface"); if (NULL != ifp) { if (GATInterface_ISerialisable == iftype || GATInterface_IAdvertisable == iftype) { *ifp = (void const *) &file->GATSerialisable__vtable; } else if (GATInterface_IMonitorable == iftype && NULL != file->data.monitorable) { *ifp = (void const *) &file->GATMonitorable__vtable; } else { *ifp = NULL; GAT_CREATE_STATUS(GAT_NO_INTERFACE); } } else { GAT_CREATE_STATUS(GAT_INVALID_PARAMETER); } return GAT_RETURN_STATUS(); } return GAT_INVALID_HANDLE; } /** GATFile_GetLocation * This method returns the Location of this File * * @return The Location of this File */ GATLocation_const GATFile_GetLocation(GATFile_const file) { if (NULL != file) { return file->data.location; } return 0; } /** GATFile_Copy * @brief Copy a file from one location to another. * * The function GATFile_Copy copies the given file to another location. For * this it tries to call through its CPI's all matching adapters registered * for the file CPI. * * @param this The file to be copied to the new location * @param targetLocation The location the file has to be copied to. * * @return An error code */ GATResult GATFile_Copy(GATFile_const file, GATLocation_const targetLocation, GATFileMode mode) { if (NULL != file) { GAT_STATUS_APIENTRY(file->data.context, "GATFile_Copy"); GAT_CREATE_STATUS(GATFileCPI_Copy(file->cpi, &file->data, targetLocation, mode)); return GAT_RETURN_STATUS(); } return GAT_INVALID_HANDLE; } /** GATFile_Move * @brief Move a file from one location to another. * * The function GATFile_Move moves the given file to another location. For * this it tries to call through its CPI's all matching adapters registered * for the file CPI. * * @param this The file to be moved to the new location * @param targetLocation The location the file has to be moved to. * * @return An error code */ GATResult GATFile_Move(GATFile_const file, GATLocation_const targetLocation, GATFileMode mode) { if (NULL != file) { GAT_STATUS_APIENTRY(file->data.context, "GATFile_Move"); GAT_CREATE_STATUS(GATFileCPI_Move(file->cpi, &file->data, targetLocation, mode)); return GAT_RETURN_STATUS(); } return GAT_INVALID_HANDLE; } /** GATFile_Delete * @brief Delete a file. * * The function GATFile_Delete deletes the given file. For * this it tries to call through its CPI's all matching adapters registered * for the file CPI. * * @param this The file to be moved to the new location * * @return An error code */ GATResult GATFile_Delete(GATFile_const file) { if (NULL != file) { GAT_STATUS_APIENTRY(file->data.context, "GATFile_Delete"); GAT_CREATE_STATUS(GATFileCPI_Delete(file->cpi, &file->data)); return GAT_RETURN_STATUS(); } return GAT_INVALID_HANDLE; } /** GATFile_IsReadable * @brief Check the file attributes for the readable flag * * The function GATFile_IsReadable checks the file attributes of the given * file and returns, whether it is readable. * * @param this The file to be inspected for its readability attribute. * * @return If the inspected file is readable, the function returns * @c #GAT_SUCCESS, if it is not readable, @c #GAT_FALSE is returned. * Otherwise the function returns any of the possible errorcodes. */ GATResult GATFile_IsReadable(GATFile_const file) { if (NULL != file) { GAT_STATUS_APIENTRY(file->data.context, "GATFile_IsReadable"); GAT_CREATE_STATUS(GATFileCPI_IsReadable(file->cpi, &file->data)); return GAT_RETURN_STATUS(); } return GAT_INVALID_HANDLE; } /** GATFile_IsWritable * @brief Check the file attributes for the writable flag * * The function GATFile_IsWritable checks the file attributes of the given * file and returns, whether it is writable. * * @param this The file to be inspected for its writability attribute. * * @return If the inspected file is writable, the function returns * @c #GAT_SUCCESS, if it is not writable, @c #GAT_FALSE is returned. * Otherwise the function returns any of the possible errorcodes. */ GATResult GATFile_IsWritable(GATFile_const file) { if (NULL != file) { GAT_STATUS_APIENTRY(file->data.context, "GATFile_IsWritable"); GAT_CREATE_STATUS(GATFileCPI_IsWritable(file->cpi, &file->data)); return GAT_RETURN_STATUS(); } return GAT_INVALID_HANDLE; } /** GATFile_GetLength * @brief Returns the size of the given file * * The function GATFile_GetLength returns the file size of the given size * measured in bytes. * * @param this The file to be inspected for its size. * @param length The pointer to the variable, where the length of the file is * to be returned to. * * @return An error code */ GATResult GATFile_GetLength(GATFile_const file, unsigned long *length) { if (NULL != file) { GAT_STATUS_APIENTRY(file->data.context, "GATFile_GetLength"); GAT_CREATE_STATUS(GATFileCPI_GetLength(file->cpi, &file->data, length)); return GAT_RETURN_STATUS(); } return GAT_INVALID_HANDLE; } /** GATFile_LastWriteTime * @brief Returns the time of last modification of the given file * * The function GATFile_LastWriteTime returns the time of last modification of * the inspected file. * * @param this The file to be inspected for its modification time. * @param lw_time The pointer to the variable, where the last write time is * to returned to. * * @return An error code */ GATResult GATFile_LastWriteTime(GATFile_const file, GATTime *lw_time) { if (NULL != file) { GAT_STATUS_APIENTRY(file->data.context, "GATFile_LastWriteTime"); GAT_CREATE_STATUS(GATFileCPI_LastWriteTime(file->cpi, &file->data, lw_time)); return GAT_RETURN_STATUS(); } return GAT_INVALID_HANDLE; } /* GATMonitorable */ /** GATFile_AddMetricListener * * The function GATFile_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 file The GATFile instance to add the GATMetricListener to. * @param listener The GTAMetricListener 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. */ GATResult GATFile_AddMetricListener(GATFile file, GATMetricListener listener, void *listener_data, GATMetric metric, GATuint32 *cookie) { if (NULL != file) { GAT_STATUS_APIENTRY(file->data.context, "GATFile_AddMetricListener"); if (NULL != file->data.monitorable) { GAT_CREATE_STATUS(GATMonitorable_Impl_AddMetricListener( file->data.monitorable, listener, listener_data, metric, cookie)); } else { /* this may happen, if the adaptor has not registered any GATMetrics */ GAT_CREATE_STATUS(GAT_NO_INTERFACE); } return GAT_RETURN_STATUS(); } return GAT_INVALID_HANDLE; } /** GATFile_RegisterPolling * * The function GATFile_RegisterPolling registers a continuous * metric with the given GATFile instance. * * @param file The GATFile 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 GATFile. * * @return An error code. */ GATResult GATFile_RegisterPolling(GATFile file, GATMetric metric, GATMetricEvent *event, GATuint32 *cookie) { if (NULL != file) { GAT_STATUS_APIENTRY(file->data.context, "GATFile_RegisterPolling"); if (NULL != file->data.monitorable) { GAT_CREATE_STATUS(GATMonitorable_Impl_RegisterPolling(file->data.monitorable, metric, 0, cookie)); /* ask the CPI provider to return the corresponding metric event */ GAT_CREATE_STATUS(GATFileCPI_GetMetricEvent(file->cpi, &file->data, metric, event)); if (GAT_FAILED(GAT_CURRENT_STATUS()) && NULL != cookie && 0 != *cookie) { GATMonitorable_Impl_RemoveRegisteredMetric(file->data.monitorable, metric, *cookie); *cookie = 0; } } else { /* this may happen, if the adaptor has not registered any GATMetrics */ GAT_CREATE_STATUS(GAT_NO_INTERFACE); } return GAT_RETURN_STATUS(); } return GAT_INVALID_HANDLE; } /** GATFile_RemoveRegisteredMetric * * The function GATFile_RemoveRegisteredMetric removes a GATMetricListener, * which was previously registered with GATFile_AddMetricListener. * * @param file The GATFile instance to remove the GATMetricListener from. * @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. */ GATResult GATFile_RemoveRegisteredMetric(GATFile file, GATMetric metric, GATuint32 cookie) { if (NULL != file) { GAT_STATUS_APIENTRY(file->data.context, "GATFile_RemoveRegisteredMetric"); if (NULL != file->data.monitorable) { GAT_CREATE_STATUS(GATMonitorable_Impl_RemoveRegisteredMetric( file->data.monitorable, metric, cookie)); } else { /* this may happen, if the adaptor has not registered any GATMetrics */ GAT_CREATE_STATUS(GAT_NO_INTERFACE); } return GAT_RETURN_STATUS(); } return GAT_INVALID_HANDLE; } /** GATFile_GetMetrics * * The function GATFile_GetMetrics returns a list of metrics supported by this * GATFile. * * @param file The GATFile 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. */ GATResult GATFile_GetMetrics(GATFile_const file, GATList_GATMetric *metrics) { if (NULL != file) { GAT_STATUS_APIENTRY(file->data.context, "GATFile_GetMetrics"); if (NULL != file->data.monitorable) { GAT_CREATE_STATUS(GATMonitorable_Impl_GetMetrics(file->data.monitorable, metrics)); } else { /* this may happen, if the adaptor has not registered any GATMetrics */ GAT_CREATE_STATUS(GAT_NO_INTERFACE); } return GAT_RETURN_STATUS(); } return GAT_INVALID_HANDLE; } /* GATAdvertiseable API */ /** GATFileCPI_SerialiseCallback * * The function GATFileCPI_SerialiseCallback is used as a callback function * for the serialisation of a GATFile 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. */ static GATResult GATFileCPI_SerialiseCallback(GATObject object, GATObject stream, GATBool clear_dirty) { GATFile file = GATObject_ToGATFile(object); if (NULL != file) { GAT_USES_STATUS(file->data.context, "GATFileCPI_SerialiseCallback"); GAT_CREATE_STATUS(GATFileCPI_Serialise(file->cpi, &file->data, stream, clear_dirty)); if (GAT_SUCCEEDED(GAT_CURRENT_STATUS()) && GATTrue == clear_dirty) { file->data.isdirty = GATFalse; } return GAT_RETURN_STATUS(); } return GAT_INVALID_HANDLE; } /** int GATFile_Serialise(GATFile file, GATObject stream, GATBool clear_dirty) * @brief Serialise a GATFile object * * The function GATFile_Serialise serialises the given GATFIle object into the * given stream. * * @param file The GATFile 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 GATFile_Serialise(GATFile file, GATObject stream, GATBool clear_dirty) { if (NULL != file) { GAT_USES_STATUS(file->data.context, "GATFile_Serialise"); /* FIXME: serialise the location directly, when GATLocation is fully implemented */ char *name = GATLocation_ToString(GATFile_GetLocation(file)); if (NULL != name) { GAT_CREATE_STATUS(GATXds_SerialiseObject(GATFile_ToGATObject(file), stream, clear_dirty, GATFileCPI_SerialiseCallback, "uint32 string", GATFILE_VERSION1, name)); free(name); } else { GAT_CREATE_STATUS(GAT_MEMORYFAILURE); } return GAT_RETURN_STATUS(); } return GAT_INVALID_HANDLE; } /** GATFileCPI_VersionCallback * * The function GATFileCPI_VersionCallback is used as a callback function * during the de-serialisation of a GATFile. 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 GATFileCPI_VersionCallback(GATuint32 version) { GATBool retval = GATFalse; if ((version & ~GATFILE_MINOR_MASK) <= GATFILE_LASTVERSION) { retval = GATTrue; } return retval; } /** GATFileCPI_DeSerialiseCallback * * The function GATFileCPI_DeSerialiseCallback is used as a callback function * during the de-serialisation of a GATFile. It should be provided for the * instantiation of the new GATFile 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 * GATFile_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 GATFileCPI_DeSerialiseCallback(GATContext context, GATObject stream, GATObject *object, GATuint32 version, va_list args) { GAT_USES_STATUS(context, "GATFileCPI_DeSerialiseCallback"); /* the version was eaten already */ /* FIXME: serialise/de-serialise the location directly, when GATLocation is fully implemented */ /*GATLocation *location = va_arg(args, GATLocation *);*/ char const **name = va_arg(args, char const **); GATFile file = NULL; /* construct the new object */ GAT_CREATE_STATUS(GATFile_DeSerialise_Create(context, stream, *name, &file)); GAT_UNUSED_PARAMETER(version); if (GAT_SUCCEEDED(GAT_CURRENT_STATUS())) { if (NULL != object) { *object = GATFile_ToGATObject(file); } else { GATFile_Destroy(&file); GAT_CREATE_STATUS(GAT_INVALID_PARAMETER); } } return GAT_RETURN_STATUS(); } /** GATFile GATFile_DeSerialise(GATContext context, GATObject stream, GATBool clear_dirty) * @brief De-serialise a GATFile object * * The function GATFile_DeSerialise de-serialises a streamed GATFile 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 GATFile object. */ GATFile GATFile_DeSerialise(GATContext context, GATObject stream, GATResult *result) { GAT_USES_STATUS(context, "GATFile_DeSerialise"); GATObject object = NULL; /* the new object will be created here */ GATFile file = NULL; /* we must provide all instance data items to be de-serialised for this GATFile object accordingly to the provided format string */ GATuint32 version = 0; /* FIXME: de-serialise the location directly, when GATLocation is fully implemented */ /* GATLocation location = NULL; */ char *name = NULL; /* read the data */ GAT_CREATE_STATUS(GATXds_DeSerialiseObject(context, stream, GATFileCPI_DeSerialiseCallback, GATFileCPI_VersionCallback, &object, "uint32 string", &version, &name)); /* GATLocation_Destroy(&location);*/ free(name); file = GATObject_ToGATFile(object); if (NULL == file) { GAT_CREATE_STATUS(GAT_BAD_OBJECT_CONVERSION); } if (GAT_FAILED(GAT_CURRENT_STATUS())) { GATObject_Destroy(&object); file = NULL; } if (NULL != result) { *result = GAT_CURRENT_STATUS(); } GAT_STORE_STATUS(); return file; } /** GATFile_GetIsDirty * * The function GATFile_GetIsDirty retrieves the status of the dirty flag of * this GATFile object. * * @param file The GATFile object to inspect for its dirty status. * @param isdirty The pointer to a variable, which receives the dirty status. * * @return An error code. */ GATResult GATFile_GetIsDirty(GATFile_const file, GATBool *isdirty) { if (NULL != file) { GAT_STATUS_APIENTRY(file->data.context, "GATFile_GetIsDirty"); if (NULL != isdirty) { *isdirty = file->data.isdirty; } else { GAT_CREATE_STATUS(GAT_INVALID_PARAMETER); } return GAT_RETURN_STATUS(); } return GAT_INVALID_HANDLE; } /* Local functions */ /** GATFile_DeSerialise_Create * * The function GATFile_DeSerialise_Create creates a new GATFile object and * tries to 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 GATFile object. * @param stream The object from which the adaptor should read the streamed * instance data. * @param name This is the URI of the file to reconstruct. * @param new_object The pointer to the variable, which should receive the * newly constructed GATFile object. * * @return An error code. */ static GATResult GATFile_DeSerialise_Create(GATContext context, GATObject stream, char const *name, GATFile *new_object) { GAT_USES_STATUS(context, "GATFile_DeSerialise_Create"); GATFile new_file = (GATFile) malloc(sizeof(struct GATFile_S)); if(NULL != new_file) { memset(new_file, 0, sizeof(struct GATFile_S)); new_file->GATObject__vtable = &GATFile__vtable; new_file->GATSerialisable__vtable = &GATFile_ISerialisable__vtable; new_file->GATMonitorable__vtable = &GATFile_IMonitorable__vtable; new_file->data.context = context; new_file->data.isdirty = GATFalse; new_file->data.source = GATFile_ToGATObject_const(new_file); /* 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_file->data.location = GATLocation_Create(name); new_file->cpilist = GATRegistry_FindGATFileCPI(registry, preferences); if (NULL == new_file->cpilist) { GAT_CREATE_STATUS(GAT_NO_REGISTERED_CPI); } else if (NULL != new_file->data.location) { /* find out the current stream position */ GATuint32 offset = 0; GATBool found_cpi = GATFalse; GATFileCPIList current = NULL; GAT_CREATE_STATUS(GATStreamable_Seek(stream, GATOrigin_Current, 0, &offset)); if (GAT_SUCCEEDED(GAT_CURRENT_STATUS())) { /* create new instance data of the CPI provider */ for(current = new_file->cpilist; NULL != current; current = current->next) { /* try, whether this cpi can handle the input */ GAT_CREATE_STATUS(GATFileCPI_DeSerialise(current->cpi, stream, &new_file->data)); if (GAT_SUCCEEDED(GAT_CURRENT_STATUS())) { new_file->cpi = current->cpi; found_cpi = GATTrue; break; } /* reset stream pointer to the beginning of the CPI instance data */ GAT_CREATE_STATUS(GATStreamable_Seek(stream, GATOrigin_Set, offset, 0)); } } /* no available CPI object can handle this */ if (GATFalse == found_cpi) { GAT_CREATE_STATUS(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; GATResult retval = GATFileCPI_GetMetrics(new_file->cpi, &new_file->data, &metrics); if (GAT_SUCCEEDED(retval)) { new_file->data.monitorable = GATMonitorable_Impl_Create(metrics); if (NULL == new_file->data.monitorable) { GAT_CREATE_STATUS(GAT_MEMORYFAILURE); } GATList_GATMetric_Destroy(&metrics); } else if (GAT_NOTIMPL != retval) /* not impl: no monitoring supported here */ { GAT_CREATE_STATUS(retval); } else { retval = GAT_SUCCESS; } if (GAT_SUCCEEDED(retval)) { GAT_CREATE_STATUS(GATRegistry_AddGATFileToCPIList(new_file->data.context, new_file->cpi, new_file)); } } } } } else { GAT_CREATE_STATUS(GAT_MEMORYFAILURE); } if (GAT_SUCCEEDED(GAT_CURRENT_STATUS())) { if (NULL != new_object) { *new_object = new_file; } else { GATFile_Destroy(&new_file); GAT_CREATE_STATUS(GAT_INVALID_PARAMETER); } } else { GATFile_Destroy(&new_file); } return GAT_RETURN_STATUS(); } /* GATFile_GetCPIInstanceData * * The function GATFile_GetCPIInstanceData returns the CPI instance data, * associated with the given GATFile object. * * @param file 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 GATFile_GetCPIInstanceData(GATFile file, void **data) { if (NULL != file) { GAT_USES_STATUS(file->data.context, "GATFile_GetCPIInstanceData"); if (NULL != data) { *data = (void *)&file->data; } else { GAT_CREATE_STATUS(GAT_INVALID_PARAMETER); } return GAT_RETURN_STATUS(); } return GAT_INVALID_HANDLE; }