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.h Go to the documentation of this file. /** @file GATFile.h * Header 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.h,v 1.28 2004/03/24 19:30:58 hartmutkaiser Exp $ * * Copyright (C) Tom Goodale * This file is part of the GAT Engine. * Contributed by Tom Goodale <goodale@aei.mpg.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 _GATFILE_H_ #define _GATFILE_H_ 1 #include "GATType.h" #include "GATContext.h" #include "GATPreferences.h" #include "GATLocation.h" #include "GATMetricEvent.h" #include "GATMetric.h" #include "GATMonitorable.h" #ifdef __cplusplus extern "C" { #endif /* Declare the converters to/from GATObject */ GATOBJECT_DECLARE_CONVERTERS(GATFile); /* GATObject API */ /** GATFile_Destroy * The GATFile destructor. * This is the destructor for GATFile objects. * * @param this An old GATFile */ void GATFile_Destroy(GATFile *file); /** 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); /** 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 file, GATFile *new_file); /** 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); /** int GATFile_GetInterface(GATFile_const file, GATInterface iftype, void const **ifp) * @brief Get an interface supported by a GATFile * * 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); /* GATFile API */ /** 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); /** 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_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); /** 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); /** 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); /** 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); /** 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); /** 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); /** 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); /** GATFile_GetLocation * This method returns the Location of this File * * @return The Location of this File */ GATLocation_const GATFile_GetLocation(GATFile_const file); /* GATMonitorable API */ /** 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); /** 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); /** 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); /** 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); /* GATAdvertiseable API */ #define GATFILE_VERSION1 0x0100 #define GATFILE_LASTVERSION GATFILE_VERSION1 #define GATFILE_MINOR_MASK 0x00ff /** 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); /** 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); /** 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); #ifdef __cplusplus } #endif #endif /* _GATFILE_H_ */