GAT Documentation

00001 /** @file GATLogicalFileCPI.h
00002  * Header file for the GATLogicalFileCPI class.
00003  *
00004  * A GATLogicalFileCPI encapsulates all the methods that a GATLogicalFile 
00005  *  capability provider provides.
00006  *
00007  * @date Thu Oct 16 2003
00008  *
00009  * @version $Header: /export/cvs-gridlab/wp-1/Codes/GATEngine/C-reference/src/GATLogicalFileCPI.h,v 1.17 2004/03/24 19:30:58 hartmutkaiser Exp $
00010  *
00011  *  Copyright (C) Hartmut Kaiser
00012  *  This file is part of the GAT Engine.
00013  *  Contributed by Hartmut Kaiser <hartmutkaiser [at] t-online [dot] 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 #if !defined(_GATLOGICALFILECPI_H_)
00021 #define _GATLOGICALFILECPI_H_
00022 
00023 typedef struct GATLogicalFileCPI_S *GATLogicalFileCPI;
00024 typedef struct GATLogicalFileCPI_S const *GATLogicalFileCPI_const;
00025 
00026 #include "GATContext.h"
00027 #include "GATPreferences.h"
00028 #include "GATLogicalFile.h"
00029 #include "GATMonitorable.h"
00030 
00031 /* Versioning constants for the GATFileCPI_Data struct */
00032 #define GATLOGICALFILECPI_VERSION1 1 
00033 
00034 /* the newest version we know of */
00035 #define GATLOGICALFILECPI_VERSION  GATLOGICALFILECPI_VERSION1
00036 
00037 /**
00038  *  The @c #GATLogicalFileCPI_Instance structure holds all data items supplied 
00039  *  by the client during the construction of the GATLogicalFile object. 
00040  *  Additionally it contains the dirty status needes for the GATAdvertisable
00041  *  and GATSerializable interfaces.
00042  */
00043 typedef struct 
00044 {
00045   GATContext context;     /* the GAT context to use for all GATLogicalFile operations */
00046   GATLocation location;   /* the location of this object */
00047   GATBool isdirty;        /* dirty status for the whole object */
00048   GATLogicalFileMode mode;          /* create mode for this logical file */
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 } GATLogicalFileCPI_Instance;
00053 
00054 /* prototypes for the adapter callback functions */
00055 typedef void (*GATLogicalFileCPI_Adaptor_Destroy)(void *);
00056 
00057 typedef GATResult (*GATLogicaFileCPI_Adaptor_ServiceActions)(void *, 
00058   GATLogicalFileCPI_Instance *, GATTimePeriod_const);
00059 
00060 /* instance specific functions */
00061 typedef void (*GATLogicalFileCPI_Adaptor_DestroyInstance)(void *, 
00062   GATLogicalFileCPI_Instance *);
00063 
00064 typedef GATResult (*GATLogicalFileCPI_Adaptor_CreateInstance)(void *, 
00065   GATLogicalFileCPI_Instance *);
00066 
00067 typedef GATResult (*GATLogicalFileCPI_Adaptor_CloneInstance)(void *, 
00068   GATLogicalFileCPI_Instance const *, GATLogicalFileCPI_Instance *);
00069 
00070 typedef GATResult (*GATLogicalFileCPI_Adaptor_EqualsInstance)(void *, 
00071   GATLogicalFileCPI_Instance const *, GATLogicalFileCPI_Instance const *, 
00072   GATBool *);
00073 
00074 /* Serialisation API */
00075 typedef GATResult (*GATLogicalFileCPI_Adaptor_Serialise)(void *, 
00076   GATLogicalFileCPI_Instance const *, GATObject, GATBool);
00077 
00078 typedef GATResult (*GATLogicalFileCPI_Adaptor_DeSerialise)(void *, GATObject,
00079   GATLogicalFileCPI_Instance *);
00080 
00081 /* CPI specific API */
00082 typedef GATResult (*GATLogicalFileCPI_Adaptor_Add)(void *, 
00083   GATLogicalFileCPI_Instance *, GATFile_const);
00084 
00085 typedef GATResult (*GATLogicalFileCPI_Adaptor_RemoveFile)(void *, 
00086   GATLogicalFileCPI_Instance *, GATFile_const);
00087 
00088 typedef GATResult (*GATLogicalFileCPI_Adaptor_Replicate)(void *, 
00089   GATLogicalFileCPI_Instance const *, GATLocation_const);
00090 
00091 typedef GATResult (*GATLogicalFileCPI_Adaptor_GetFiles)(void *, 
00092   GATLogicalFileCPI_Instance const *, GATList_GATFile *);
00093 
00094 typedef GATResult (*GATLogicalFileCPI_Adaptor_Remove)(void *, 
00095   GATLogicalFileCPI_Instance const *);
00096 
00097 
00098 /* callback function prototypes for the GATMonitorable interface support */
00099 typedef GATResult (* GATLogicalFileCPI_Adaptor_GetMetrics)(void *, 
00100   GATLogicalFileCPI_Instance const *, GATList_GATMetric *);
00101 
00102 typedef GATResult (* GATLogicalFileCPI_Adaptor_GetMetricEvent)(void *, 
00103   GATLogicalFileCPI_Instance const *, GATMetric, GATMetricEvent *); 
00104   
00105 typedef struct
00106 {
00107   /* CPI data (type local data) */
00108   void *data;
00109   GATLogicalFileCPI_Adaptor_Destroy destroy;
00110   GATLogicaFileCPI_Adaptor_ServiceActions service_actions;
00111   
00112   /* CPI instance data */
00113   GATLogicalFileCPI_Adaptor_CreateInstance create_instance;
00114   GATLogicalFileCPI_Adaptor_DestroyInstance destroy_instance;
00115   GATLogicalFileCPI_Adaptor_CloneInstance clone_instance;
00116   GATLogicalFileCPI_Adaptor_EqualsInstance equals_instance;
00117 
00118   /* CPI serialisation */
00119   GATLogicalFileCPI_Adaptor_Serialise serialise;
00120   GATLogicalFileCPI_Adaptor_DeSerialise deserialise;
00121   
00122   /* CPI functionality */
00123   GATLogicalFileCPI_Adaptor_Add add;
00124   GATLogicalFileCPI_Adaptor_RemoveFile removefile;
00125   GATLogicalFileCPI_Adaptor_Replicate replicate;
00126   GATLogicalFileCPI_Adaptor_GetFiles getfiles;
00127   GATLogicalFileCPI_Adaptor_Remove remove;
00128 
00129   /* CPI monitoring support */
00130   GATLogicalFileCPI_Adaptor_GetMetrics get_metrics;
00131   GATLogicalFileCPI_Adaptor_GetMetricEvent get_metric_event;
00132 } GATLogicalFileCPI_Data;
00133 
00134 #ifdef __cplusplus
00135 extern "C" {
00136 #endif
00137 
00138 /* Adaptor API */
00139 GATLogicalFileCPI 
00140   GATLogicalFileCPI_Create(unsigned long version, GATLogicalFileCPI_Data *data);
00141 
00142 /* API internal to the GAT engine */
00143 void 
00144   GATLogicalFileCPI_Destroy(GATLogicalFileCPI *cpi);
00145 
00146 /* CPI instance specific functions */
00147 GATResult 
00148   GATLogicalFileCPI_CreateInstance(GATLogicalFileCPI cpi, 
00149     GATLogicalFileCPI_Instance *data);
00150   
00151 void 
00152   GATLogicalFileCPI_DestroyInstance(GATLogicalFileCPI cpi, 
00153     GATLogicalFileCPI_Instance *data);
00154 
00155 GATResult 
00156   GATLogicalFileCPI_CloneInstance(GATLogicalFileCPI cpi, 
00157     GATLogicalFileCPI_Instance const *data, 
00158     GATLogicalFileCPI_Instance *new_data);
00159 
00160 GATResult 
00161   GATLogicalFileCPI_EqualsInstance(GATLogicalFileCPI cpi, 
00162     GATLogicalFileCPI_Instance const *lhs, 
00163     GATLogicalFileCPI_Instance const *rhs, GATBool *isequal);
00164 
00165 /* Serialisation API */
00166 GATResult GATLogicalFileCPI_Serialise(GATLogicalFileCPI cpi, 
00167   GATLogicalFileCPI_Instance const *instance_data, GATObject stream,
00168   GATBool clear_dirty);
00169   
00170 GATResult GATLogicalFileCPI_DeSerialise(GATLogicalFileCPI cpi, 
00171   GATObject stream, GATLogicalFileCPI_Instance *instance_data);
00172   
00173 /* CPI specific API */
00174 
00175 /* Add a new physical file to the given logical file */
00176 GATResult 
00177   GATLogicalFileCPI_AddFile(GATLogicalFileCPI cpi, 
00178     GATLogicalFileCPI_Instance *data, GATFile_const target);
00179 
00180 /* Remove a physical file from the given logical file */
00181 GATResult 
00182   GATLogicalFileCPI_RemoveFile(GATLogicalFileCPI cpi, 
00183     GATLogicalFileCPI_Instance *data, GATFile_const target);
00184   
00185 /* Replicate to a given file */
00186 GATResult
00187   GATLogicalFileCPI_Replicate(GATLogicalFileCPI_const cpi, 
00188     GATLogicalFileCPI_Instance const *data, GATLocation_const target);
00189     
00190 /* Get a list of GATFiles, associated with this logical file store */
00191 GATResult
00192   GATLogicalFileCPI_GetFiles(GATLogicalFileCPI_const cpi, 
00193     GATLogicalFileCPI_Instance const *data, GATList_GATFile *files);
00194     
00195 /* Remove this logical file store */
00196 GATResult
00197   GATLogicalFileCPI_Remove(GATLogicalFileCPI_const cpi, 
00198     GATLogicalFileCPI_Instance const *data);
00199     
00200 
00201 /* GATMonitorable */
00202 GATResult GATLogicalFileCPI_GetMetrics(GATLogicalFileCPI cpi, 
00203   GATLogicalFileCPI_Instance const *data, GATList_GATMetric *metrics);
00204   
00205 GATResult GATLogicalFileCPI_GetMetricEvent(GATLogicalFileCPI cpi, 
00206   GATLogicalFileCPI_Instance const *data, GATMetric metric, 
00207     GATMetricEvent *event);
00208 
00209 #ifdef __cplusplus
00210 }
00211 #endif
00212 
00213 #endif /* !defined(_GATLOGICALFILECPI_H_) */