GAT Documentation

00001 /** @file GATPipeCPI.h
00002  * Header for the GATPipeCPI class.
00003  * 
00004  * A GATPipeCPI encapsulates all the methods that a GATPipe capability
00005  * provider provides.
00006  * 
00007  * @date $Date: 2004/03/24 19:30:58 $
00008  * 
00009  * @version $Header: /export/cvs-gridlab/wp-1/Codes/GATEngine/C-reference/src/GATPipeCPI.h,v 1.6 2004/03/24 19:30:58 hartmutkaiser Exp $
00010  *
00011  *  Copyright (C) Kelly Davis
00012  *  This is part of the GAT Engine.
00013  *  Contributed by Kelly Davis <kdavis@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 _GATPIPECPI_H_
00021 #define _GATPIPECPI_H_ 1
00022 
00023 typedef struct GATPipeCPI_S *GATPipeCPI;
00024 
00025 #include "GATContext.h"
00026 #include "GATPreferences.h"
00027 #include "GATMetricEvent.h"
00028 #include "GATMetric.h"
00029 #include "GATTime.h"
00030 #include "GATPipe.h"
00031 #include "GATMonitorable.h"
00032 
00033 /* Versioning constants for the GATPipeCPI_Data struct */
00034 #define GATPIPECPI_VERSION1 1 
00035 
00036 /* the newest version we know of */
00037 #define GATPIPECPI_VERSION  GATPIPECPI_VERSION1
00038 
00039 /**
00040  *  The @c #GATPipeCPI_Instance structure holds all data items supplied by the 
00041  *  client during the construction of the GATPipe object.
00042  */
00043 typedef struct 
00044 {
00045   GATContext context;   /* the GAT context to use for all GATPipe operations */
00046   GATMonitorable_Impl monitorable;  /* monitoring support */
00047   GATObject_const source;   /* the object this CPI is associated with */
00048   void *instance_data;  /* eventually supplied CPI provider instance data */
00049 } GATPipeCPI_Instance;
00050 
00051 /* prototypes for the adapter callback functions */
00052 typedef void (*GATPipeCPI_Adaptor_Destroy)(void *);
00053 
00054 typedef GATResult (*GATPipeCPI_Adaptor_ServiceActions)(void *, 
00055   GATPipeCPI_Instance *, GATTimePeriod_const);
00056 
00057 /* instance specific functions */
00058 typedef void (*GATPipeCPI_Adaptor_DestroyInstance)(void *, 
00059   GATPipeCPI_Instance *);
00060 
00061 typedef GATResult (*GATPipeCPI_Adaptor_CreateInstance)(void *, 
00062   GATPipeCPI_Instance *, void *);
00063 
00064 typedef GATResult (*GATPipeCPI_Adaptor_CloneInstance)(void *, 
00065   GATPipeCPI_Instance const *, GATPipeCPI_Instance *);
00066 
00067 typedef GATResult (*GATPipeCPI_Adaptor_EqualsInstance)(void *, 
00068   GATPipeCPI_Instance const *, GATPipeCPI_Instance const *, GATBool *);
00069 
00070 
00071 /* CPI specific API */
00072 typedef GATResult (*GATPipeCPI_Adaptor_Read)(void *, 
00073   GATPipeCPI_Instance const *, void *, GATuint32, GATuint32 *);
00074   
00075 typedef GATResult (*GATPipeCPI_Adaptor_Write)(void *, 
00076   GATPipeCPI_Instance const *, void const *, GATuint32, GATuint32 *);
00077   
00078 typedef GATResult (*GATPipeCPI_Adaptor_Seek)(void *, 
00079   GATPipeCPI_Instance const *, GATOrigin, GATint32, GATuint32 *);
00080 
00081 typedef GATResult (*GATPipeCPI_Adaptor_Close)(void *, 
00082   GATPipeCPI_Instance const *);
00083   
00084 
00085 /* callback function prototypes for the GATMonitorable interface support */
00086 typedef GATResult (* GATPipeCPI_Adaptor_GetMetrics)(void *, 
00087   GATPipeCPI_Instance const *, GATList_GATMetric *);
00088 
00089 typedef GATResult (* GATPipeCPI_Adaptor_GetMetricEvent)(void *, 
00090   GATPipeCPI_Instance const *, GATMetric, GATMetricEvent *); 
00091   
00092 typedef struct
00093 {
00094   /* CPI data (type local data) */
00095   void *data;
00096   GATPipeCPI_Adaptor_Destroy destroy;
00097   GATPipeCPI_Adaptor_ServiceActions service_actions;
00098   
00099   /* CPI instance data */
00100   GATPipeCPI_Adaptor_CreateInstance create_instance;
00101   GATPipeCPI_Adaptor_DestroyInstance destroy_instance;
00102   GATPipeCPI_Adaptor_CloneInstance clone_instance;
00103   GATPipeCPI_Adaptor_EqualsInstance equals_instance;
00104   
00105   /* CPI functionality */
00106   GATPipeCPI_Adaptor_Read read;
00107   GATPipeCPI_Adaptor_Write write;
00108   GATPipeCPI_Adaptor_Seek seek;
00109   GATPipeCPI_Adaptor_Close close;
00110   
00111   /* CPI monitoring support */
00112   GATPipeCPI_Adaptor_GetMetrics get_metrics;
00113   GATPipeCPI_Adaptor_GetMetricEvent get_metric_event;
00114 } GATPipeCPI_Data;
00115 
00116 #ifdef __cplusplus
00117 extern "C" {
00118 #endif
00119 
00120 /* Adaptor API */
00121 GATPipeCPI GATPipeCPI_Create(unsigned long int version,
00122   GATPipeCPI_Data *data);
00123 
00124 /* API internal to the GAT engine */
00125 void GATPipeCPI_Destroy(GATPipeCPI *cpi);
00126 
00127 /* CPI instance specific functions */
00128 GATResult GATPipeCPI_CreateInstance(GATPipeCPI cpi, 
00129   GATPipeCPI_Instance *instance_data, void *information);
00130   
00131 void GATPipeCPI_DestroyInstance(GATPipeCPI cpi, 
00132   GATPipeCPI_Instance *instance_data);
00133 
00134 GATResult GATPipeCPI_CloneInstance(GATPipeCPI cpi, 
00135   GATPipeCPI_Instance const *instance_data, 
00136   GATPipeCPI_Instance *new_instance_data);
00137 
00138 GATResult GATPipeCPI_EqualsInstance(GATPipeCPI cpi, GATPipeCPI_Instance const *lhs, 
00139   GATPipeCPI_Instance const *rhs, GATBool *isequal);
00140 
00141 /* CPI specific API functions */
00142 GATResult GATPipeCPI_Read(GATPipeCPI cpi, GATPipeCPI_Instance const *data, void *buffer, GATuint32 size, GATuint32 *read_bytes);
00143   
00144 GATResult GATPipeCPI_Write(GATPipeCPI cpi, GATPipeCPI_Instance const *data, void const *buffer, GATuint32 size, GATuint32 *written_bytes);
00145   
00146 GATResult GATPipeCPI_Seek(GATPipeCPI cpi, GATPipeCPI_Instance const *data, GATOrigin origin, GATint32 offset, GATuint32 *new_position);
00147 
00148 GATResult GATPipeCPI_Close(GATPipeCPI cpi, GATPipeCPI_Instance const *data );
00149 
00150 /* GATMonitorable */
00151 GATResult GATPipeCPI_GetMetrics(GATPipeCPI cpi, GATPipeCPI_Instance const *data, 
00152   GATList_GATMetric *metrics);
00153   
00154 GATResult GATPipeCPI_GetMetricEvent(GATPipeCPI cpi, GATPipeCPI_Instance const *data, 
00155   GATMetric metric, GATMetricEvent *event);
00156 
00157 #ifdef __cplusplus
00158 }
00159 #endif
00160 
00161 #endif /* _GATPIPECPI_H_ */