GAT Documentation

00001 /** @file GATFileCPI.h
00002  * Header file for the GATFileCPI class.
00003  * 
00004  * A GATFileCPI encapsulates all the methods that a GATFile capability
00005  * provider provides.
00006  * 
00007  * @date Thu Sep 18 2003
00008  * 
00009  * @version $Header: /export/cvs-gridlab/wp-1/Codes/GATEngine/C-reference/src/GATFileCPI.h,v 1.29 2004/03/24 19:30:58 hartmutkaiser Exp $
00010  *
00011  *  Copyright (C) Tom Goodale
00012  *  This file is part of the GAT Engine.
00013  *  Contributed by Tom Goodale <goodale@aei.mpg.de>.
00014  *
00015  *  Use, modification and distribution is subject to the Gridlab Software
00016  *  License. (See accompanying file GLlicense.txt or copy at
00017  *  http://www.gridlab.org/GLlicense.txt)
00018  */
00019 
00020 #ifndef _GATFILECPI_H_
00021 #define _GATFILECPI_H_ 1
00022 
00023 typedef struct GATFileCPI_S *GATFileCPI;
00024 
00025 #include "GATContext.h"
00026 #include "GATPreferences.h"
00027 #include "GATLocation.h"
00028 #include "GATMetricEvent.h"
00029 #include "GATMetric.h"
00030 #include "GATTime.h"
00031 #include "GATFile.h"
00032 #include "GATMonitorable.h"
00033 
00034 /* Versioning constants for the GATFileCPI_Data struct */
00035 #define GATFILECPI_VERSION1 1 
00036 
00037 /* the newest version we know of */
00038 #define GATFILECPI_VERSION  GATFILECPI_VERSION1
00039 
00040 /**
00041  *  The @c #GATFileCPI_Instance structure holds all data items supplied by the 
00042  *  client during the construction of the GATFile object.
00043  */
00044 typedef struct 
00045 {
00046   GATContext context;   /* the GAT context to use for all GATFile operations */
00047   GATLocation location; /* the location of the file */
00048   GATBool isdirty;      /* dirty status for the whole object */
00049   GATMonitorable_Impl monitorable;  /* monitoring support */
00050   GATObject_const source;   /* the object this CPI is associated with */
00051   void *instance_data;  /* eventually supplied CPI provider instance data */
00052 } GATFileCPI_Instance;
00053 
00054 /* prototypes for the adapter callback functions */
00055 typedef void (*GATFileCPI_Adaptor_Destroy)(void *);
00056 
00057 typedef GATResult (*GATFileCPI_Adaptor_ServiceActions)(void *, 
00058   GATFileCPI_Instance *, GATTimePeriod_const);
00059 
00060 /* instance specific functions */
00061 typedef void (*GATFileCPI_Adaptor_DestroyInstance)(void *, 
00062   GATFileCPI_Instance *);
00063 
00064 typedef GATResult (*GATFileCPI_Adaptor_CreateInstance)(void *, 
00065   GATFileCPI_Instance *);
00066 
00067 typedef GATResult (*GATFileCPI_Adaptor_CloneInstance)(void *, 
00068   GATFileCPI_Instance const *, GATFileCPI_Instance *);
00069 
00070 typedef GATResult (*GATFileCPI_Adaptor_EqualsInstance)(void *, 
00071   GATFileCPI_Instance const *, GATFileCPI_Instance const *, GATBool *);
00072 
00073 
00074 /* Serialisation API */
00075 typedef GATResult (*GATFileCPI_Adaptor_Serialise)(void *, 
00076   GATFileCPI_Instance const *, GATObject, GATBool);
00077 
00078 typedef GATResult (*GATFileCPI_Adaptor_DeSerialise)(void *, GATObject,
00079   GATFileCPI_Instance *);
00080 
00081 
00082 /* CPI specific API */
00083 typedef GATResult (*GATFileCPI_Adaptor_Copy)(void *, GATFileCPI_Instance const *, 
00084   GATLocation_const, GATFileMode);
00085 
00086 typedef GATResult (*GATFileCPI_Adaptor_Move)(void *, GATFileCPI_Instance const *, 
00087   GATLocation_const, GATFileMode);
00088 
00089 typedef GATResult (*GATFileCPI_Adaptor_Delete)(void *, GATFileCPI_Instance const *);
00090 
00091 typedef GATResult (*GATFileCPI_Adaptor_IsReadable)(void *, 
00092   GATFileCPI_Instance const *);
00093 
00094 typedef GATResult (*GATFileCPI_Adaptor_IsWritable)(void *, 
00095   GATFileCPI_Instance const *);
00096 
00097 typedef GATResult (*GATFileCPI_Adaptor_GetLength)(void *, GATFileCPI_Instance const *, 
00098   unsigned long *);
00099 
00100 typedef GATResult (*GATFileCPI_Adaptor_LastWriteTime)(void *, 
00101   GATFileCPI_Instance const *, GATTime *);
00102 
00103 /* callback function prototypes for the GATMonitorable interface support */
00104 typedef GATResult (* GATFileCPI_Adaptor_GetMetrics)(void *, 
00105   GATFileCPI_Instance const *, GATList_GATMetric *);
00106 
00107 typedef GATResult (* GATFileCPI_Adaptor_GetMetricEvent)(void *, 
00108   GATFileCPI_Instance const *, GATMetric, GATMetricEvent *); 
00109   
00110 typedef struct
00111 {
00112   /* CPI data (type local data) */
00113   void *data;
00114   GATFileCPI_Adaptor_Destroy destroy;
00115   
00116   /* CPI instance data */
00117   GATFileCPI_Adaptor_ServiceActions service_actions;
00118   GATFileCPI_Adaptor_CreateInstance create_instance;
00119   GATFileCPI_Adaptor_DestroyInstance destroy_instance;
00120   GATFileCPI_Adaptor_CloneInstance clone_instance;
00121   GATFileCPI_Adaptor_EqualsInstance equals_instance;
00122   
00123   /* CPI serialisation */
00124   GATFileCPI_Adaptor_Serialise serialise;
00125   GATFileCPI_Adaptor_DeSerialise deserialise;
00126   
00127   /* CPI functionality */
00128   GATFileCPI_Adaptor_Copy copy;
00129   GATFileCPI_Adaptor_Move move;
00130   GATFileCPI_Adaptor_Delete remove;
00131   GATFileCPI_Adaptor_IsReadable isreadable;
00132   GATFileCPI_Adaptor_IsWritable iswritable;
00133   GATFileCPI_Adaptor_GetLength length;
00134   GATFileCPI_Adaptor_LastWriteTime lastwritetime;
00135   
00136   /* CPI monitoring support */
00137   GATFileCPI_Adaptor_GetMetrics get_metrics;
00138   GATFileCPI_Adaptor_GetMetricEvent get_metric_event;
00139 } GATFileCPI_Data;
00140 
00141 #ifdef __cplusplus
00142 extern "C" {
00143 #endif
00144 
00145 /* Adaptor API */
00146 GATFileCPI GATFileCPI_Create(unsigned long int version,
00147   GATFileCPI_Data *data);
00148 
00149 /* API internal to the GAT engine */
00150 void GATFileCPI_Destroy(GATFileCPI *cpi);
00151 
00152 /* CPI instance specific functions */
00153 GATResult GATFileCPI_CreateInstance(GATFileCPI cpi, 
00154   GATFileCPI_Instance *instance_data);
00155   
00156 void GATFileCPI_DestroyInstance(GATFileCPI cpi, 
00157   GATFileCPI_Instance *instance_data);
00158 
00159 GATResult GATFileCPI_CloneInstance(GATFileCPI cpi, 
00160   GATFileCPI_Instance const *instance_data, 
00161   GATFileCPI_Instance *new_instance_data);
00162 
00163 GATResult GATFileCPI_EqualsInstance(GATFileCPI cpi, GATFileCPI_Instance const *lhs, 
00164   GATFileCPI_Instance const *rhs, GATBool *isequal);
00165 
00166 /* Serialisation API */
00167 GATResult GATFileCPI_Serialise(GATFileCPI cpi, GATFileCPI_Instance const *data, 
00168   GATObject stream, GATBool clear_dirty);
00169   
00170 GATResult GATFileCPI_DeSerialise(GATFileCPI cpi, GATObject stream, 
00171   GATFileCPI_Instance *data);
00172   
00173 /* CPI specific API functions */
00174 GATResult GATFileCPI_Copy(GATFileCPI cpi, GATFileCPI_Instance const *data,
00175   GATLocation_const targetLocation, GATFileMode mode);
00176 
00177 GATResult GATFileCPI_Move(GATFileCPI cpi, GATFileCPI_Instance const *data,
00178   GATLocation_const targetLocation, GATFileMode mode);
00179 
00180 GATResult GATFileCPI_Delete(GATFileCPI cpi, GATFileCPI_Instance const *data);
00181 
00182 GATResult GATFileCPI_IsReadable(GATFileCPI cpi, GATFileCPI_Instance const *data);
00183 
00184 GATResult GATFileCPI_IsWritable(GATFileCPI cpi, GATFileCPI_Instance const *data);
00185 
00186 GATResult GATFileCPI_GetLength(GATFileCPI cpi, GATFileCPI_Instance const *data, 
00187   unsigned long *length);
00188 
00189 GATResult GATFileCPI_LastWriteTime(GATFileCPI cpi, GATFileCPI_Instance const *data, 
00190   GATTime *lw_time);
00191 
00192 /* GATMonitorable */
00193 GATResult GATFileCPI_GetMetrics(GATFileCPI cpi, GATFileCPI_Instance const *data, 
00194   GATList_GATMetric *metrics);
00195   
00196 GATResult GATFileCPI_GetMetricEvent(GATFileCPI cpi, GATFileCPI_Instance const *data, 
00197   GATMetric metric, GATMetricEvent *event);
00198 
00199 #ifdef __cplusplus
00200 }
00201 #endif
00202 
00203 #endif /* _GATFILECPI_H_ */