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

GATEndpoint.c Go to the documentation of this file. /** @file GATEndpoint.c * Main .c for the GATEndpoint class. * * An GATEndpoint represents an end of a byte stream. * * @date $Date: 2004/05/10 15:17:32 $ * * @version $Header: /export/cvs-gridlab/wp-1/Codes/GATEngine/C-reference/src/GATEndpoint.c,v 1.22 2004/05/10 15:17:32 hartmutkaiser Exp $ * * Copyright (C) Kelly Davis * This is part of the GAT Engine. * Contributed by Kelly Davis <kdavis@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) */ static const char *rcsid = "$Header: /export/cvs-gridlab/wp-1/Codes/GATEngine/C-reference/src/GATEndpoint.c,v 1.22 2004/05/10 15:17:32 hartmutkaiser Exp $"; /* System Header Files */ #include <stdio.h> #include <stdlib.h> #include <string.h> #include <assert.h> #include <errno.h> /* POSIX.1 Files */ #include <sys/utsname.h> /* GAT Header Files */ #include "GAT.h" #include "GATRegistry.h" #include "GATInternal.h" #include "GATXdsWrapper.h" #include "GATEndpointCPI.h" #include "GATMetricEvent.h" /* define the vtable types */ GATOBJECT_DEFINE_VTABLE(GATEndpoint); GATSERIALISABLE_DEFINE_VTABLE(GATEndpoint); GATMONITORABLE_DEFINE_VTABLE(GATEndpoint); /* Declare the converters to/from GATObject */ GATOBJECT_DEFINE_CONVERTERS(GATEndpoint); /* Macros */ /* Structures, unions and enums */ struct GATEndpoint_S { /* supported interfaces */ GATEndpoint_vtable *GATObject__vtable; GATEndpoint_ISerialisable_vtable *GATSerialisable__vtable; GATEndpoint_IMonitorable_vtable *GATMonitorable__vtable; /* instance data */ GATEndpointCPI_Instance data; /* instance data of the corresponding CPI object */ GATEndpointCPI cpi; /* CPI object to use for all subsequent operations */ GATEndpointCPIList cpilist; /* CPI list of appropriate CPI objects */ }; /* Static function prototypes */ static GATResult GATEndpoint_GetCPIInstanceData(GATEndpoint endpoint, void **data); static int GATEndpoint_DeSerialise_Create(GATContext context, GATObject stream, char const *name, GATEndpoint *new_endpoint); static GATResult GATEndpoint_GetNodename(struct utsname systemInfo, char **nodename ); static GATResult GATEndpoint_CloneString(char **destination, const char *source); /* Endpoint scope variables */ static GATEndpoint_vtable GATEndpoint__vtable = { GATEndpoint_GetType, GATEndpoint_Destroy, GATEndpoint_Equals, GATEndpoint_Clone, GATEndpoint_GetInterface, GATEndpoint_GetCPIInstanceData }; static GATEndpoint_ISerialisable_vtable GATEndpoint_ISerialisable__vtable = { GATEndpoint_Serialise, GATEndpoint_DeSerialise, GATEndpoint_GetIsDirty }; static GATEndpoint_IMonitorable_vtable GATEndpoint_IMonitorable__vtable = { GATEndpoint_AddMetricListener, GATEndpoint_RegisterPolling, GATEndpoint_RemoveRegisteredMetric, GATEndpoint_GetMetrics }; /* External functions */ /** GATEndpoint_Register_GATSerialisable * The GATEndpoint_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 GATEndpoint_Register_GATSerialisable(void) { return GATObject_Register_GATSerialisable(GATType_GATEndpoint, &GATEndpoint_ISerialisable__vtable); } /** * Constructs a unconnected instance of this class. * * @param context Used to broker resources. * @param preferences User preferences for this instance. */ GATEndpoint GATEndpoint_Create(GATContext context, GATPreferences_const preferences) { GAT_STATUS_APIENTRY(context, "GATEndpoint_Create"); GATEndpoint new_endpoint = (GATEndpoint) malloc(sizeof(struct GATEndpoint_S)); if(NULL != new_endpoint) { memset(new_endpoint, 0, sizeof(struct GATEndpoint_S)); new_endpoint->GATObject__vtable = &GATEndpoint__vtable; new_endpoint->GATSerialisable__vtable = &GATEndpoint_ISerialisable__vtable; new_endpoint->GATMonitorable__vtable = &GATEndpoint_IMonitorable__vtable; new_endpoint->data.context = context; new_endpoint->data.isdirty = GATFalse; new_endpoint->data.source = GATEndpoint_ToGATObject_const(new_endpoint); /* find a CPI object, which can handle the endpoint */ { struct utsname systemInfo; if (0 != uname(&systemInfo)) { GAT_CREATE_STATUS(GAT_FAIL); } else { GATRegistry_const registry = GATContext_internal_GetRegistry(context); GAT_CREATE_STATUS(GATEndpoint_GetNodename(systemInfo, &new_endpoint->data.nodename)); /* use default preferences, if appropriate */ if (NULL == preferences) { preferences = GATContext_GetPreferences(context); } new_endpoint->cpilist = GATRegistry_FindGATEndpointCPI(registry, preferences); if (NULL == new_endpoint->cpilist) { GAT_CREATE_STATUS(GAT_NO_REGISTERED_CPI); } else if(GAT_SUCCEEDED(GAT_CURRENT_STATUS())) { /* create a new instance of the CPI provider */ GATBool found_cpi = GATFalse; GATEndpointCPIList current = NULL; for(current = new_endpoint->cpilist; NULL != current; current = current->next) { GAT_CREATE_STATUS(GATEndpointCPI_CreateInstance(current->cpi, &new_endpoint->data)); if (GAT_SUCCEEDED(GAT_CURRENT_STATUS())) { new_endpoint->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 = GATEndpointCPI_GetMetrics(new_endpoint->cpi, &new_endpoint->data, &metrics); if (GAT_SUCCEEDED(retval)) { new_endpoint->data.monitorable = GATMonitorable_Impl_Create(metrics); if (NULL == new_endpoint->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_AddGATEndpointToCPIList(context, new_endpoint->cpi, new_endpoint)); } } } } } else { GAT_CREATE_STATUS(GAT_MEMORYFAILURE); } /* error handling */ if (GAT_FAILED(GAT_CURRENT_STATUS())) { GATEndpoint_Destroy(&new_endpoint); } GAT_STORE_STATUS(); return new_endpoint; } /** GATEndpoint_Destroy * The GATEndpoint destructor. * This is the destructor for GATEndpoint objects. * * @param endpoint An old GATEndpoint */ void GATEndpoint_Destroy(GATEndpoint *endpoint) { if(NULL != endpoint && NULL != *endpoint) { GATMonitorable_Impl_Destroy(&(*endpoint)->data.monitorable); if (NULL != (*endpoint)->cpi) { GATRegistry_RemoveGATEndpointFromCPIList((*endpoint)->data.context, (*endpoint)->cpi, *endpoint); GATEndpointCPI_DestroyInstance((*endpoint)->cpi, &(*endpoint)->data); } GATEndpointCPIList_Destroy((*endpoint)->cpilist); free((*endpoint)->data.nodename); free(*endpoint); *endpoint = NULL; } } /** int GATEndpoint_GetType(GATEndpoint_const endpoint) * @brief Return the type of the GATEndpoint * * The function @c GATEndpoint_GetType always returns GATType_GATEndpoint. * * @param object The object to inspect * * @return returns always @c #GATType_GATEndpoint. */ GATType GATEndpoint_GetType(GATEndpoint_const endpoint) { GAT_UNUSED_PARAMETER(endpoint); return GATType_GATEndpoint; } /** int GATEndpoint_Clone(GATEndpoint_const endpoint, GATEndpoint *new_endpoint) * @brief Clone the given GATEndpoint * * The function @c GATEndpoint_Clone generates a (deep) copy of the given * GATEndpoint. * * @param endpoint The object to clone * @param new_endpoint The pointer, through which the result is to be * returned. * * @return An error type. */ GATResult GATEndpoint_Clone(GATEndpoint_const endpoint, GATEndpoint *new_object) { if (NULL != endpoint) { GAT_STATUS_APIENTRY(endpoint->data.context, "GATEndpoint_Clone"); if (NULL != new_object) { struct GATEndpoint_S const *passedEndpoint = endpoint; GATEndpoint new_endpoint = (GATEndpoint) malloc(sizeof(struct GATEndpoint_S)); *new_object = NULL; if (NULL == new_endpoint) { GAT_CREATE_STATUS(GAT_MEMORYFAILURE); } else { memset(new_endpoint, 0, sizeof(struct GATEndpoint_S)); new_endpoint->GATObject__vtable = &GATEndpoint__vtable; new_endpoint->GATSerialisable__vtable = &GATEndpoint_ISerialisable__vtable; new_endpoint->GATMonitorable__vtable = &GATEndpoint_IMonitorable__vtable; new_endpoint->data.context = passedEndpoint->data.context; new_endpoint->data.isdirty = GATFalse; new_endpoint->data.source = GATEndpoint_ToGATObject_const(new_endpoint); new_endpoint->cpilist = GATRegistry_CloneGATEndpointCPIList( passedEndpoint->cpilist); GAT_CREATE_STATUS(GATEndpoint_CloneString(&(new_endpoint->data.nodename), passedEndpoint->data.nodename )); if (NULL == new_endpoint->cpilist) { GAT_CREATE_STATUS(GAT_MEMORYFAILURE); } else { /* re-find the cpi to use */ GATEndpointCPIList current = passedEndpoint->cpilist; GATEndpointCPIList new_current = new_endpoint->cpilist; for (/**/; NULL != current; current = current->next, new_current = new_current->next) { if (current->cpi == passedEndpoint->cpi) { new_endpoint->cpi = new_current->cpi; break; } } assert(NULL != new_endpoint->cpi); /* clone the instance data */ GAT_CREATE_STATUS(GATEndpointCPI_CloneInstance(passedEndpoint->cpi, &passedEndpoint->data, &new_endpoint->data)); /* clone the monitoring data */ if (NULL != passedEndpoint->data.monitorable) { GAT_CREATE_STATUS(GATMonitorable_Impl_Clone( passedEndpoint->data.monitorable, &new_endpoint->data.monitorable)); } /* register this object with the engine */ GAT_CREATE_STATUS(GATRegistry_AddGATEndpointToCPIList( new_endpoint->data.context, new_endpoint->cpi, new_endpoint)); } } /* destroy the newly allocated object, if some error occured */ if (GAT_FAILED(GAT_CURRENT_STATUS())) { GATEndpoint_Destroy(&new_endpoint); } else { /* return the new object */ *new_object = new_endpoint; } } else { GAT_CREATE_STATUS(GAT_INVALID_PARAMETER); } return GAT_RETURN_STATUS(); } return GAT_INVALID_HANDLE; } /** int GATEndpoint_Equals(GATEndpoint_const lhs, GATEndpoint_const rhs, GATBool *isequal) * @brief Compares two GATEndpoint objects * * The function @c GATEndpoint_Equals compares two endpoint objects of type * @c #GATEndpoint. * * @param lhs The first endpoint object to compare * @param rhs The second endpoint object to compare * @param isequal The pointer to the GATBool variable, which should receive * the result if the comparision * * @return An error code. */ GATResult GATEndpoint_Equals(GATEndpoint_const lhs, GATEndpoint_const rhs, GATBool *isequal) { if (NULL != lhs && NULL != rhs) { GAT_STATUS_APIENTRY(lhs->data.context, "GATEndpoint_Equals"); if (NULL != isequal) { *isequal = GATFalse; if (0 == strcmp(lhs->data.nodename, rhs->data.nodename)) { GAT_CREATE_STATUS(GATEndpointCPI_EqualsInstance(lhs->cpi, &lhs->data, &rhs->data, isequal)); } } return GAT_RETURN_STATUS(); } return GAT_INVALID_HANDLE; } /** int GATEndpoint_GetInterface(GATEndpoint_const endpoint, GATInterface iftype, void const **ifp) * @brief Get an interface supported by a GATObject * * The function GATEndpoint_GetInterface allows to get a pointer to an * additional interface supported by this GATEndpoint. * * @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 GATEndpoint_GetInterface(GATEndpoint_const endpoint, GATInterface iftype, void const **ifp) { if (NULL != endpoint) { GAT_STATUS_APIENTRY(endpoint->data.context, "GATEndpoint_GetInterface"); if (NULL != ifp) { *ifp = NULL; if (GATInterface_ISerialisable == iftype || GATInterface_IAdvertisable == iftype) { *ifp = (void const *) &endpoint->GATSerialisable__vtable; } else if (GATInterface_IMonitorable == iftype && NULL != endpoint->data.monitorable) { *ifp = (void const *) &endpoint->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; } /** * When a GATEndpoint is obtained from an Advert Directory, it can be * used to create a GATPipe connected to the advertising application, * by calling connect on the GATEndpoint instance. This method takes * no parameters. The GATEndpoint can be destroyed at any time * without affecting the obtained GATPipe. * * @param endpoint The GATEndpoint on which to act * @param peep A GATPipe connected to the endpoint */ GATResult GATEndpoint_Connect(GATEndpoint_const endpoint, GATPipe *peep) { if (NULL != endpoint) { GAT_STATUS_APIENTRY(endpoint->data.context, "GATEndpoint_Connect"); GAT_CREATE_STATUS(GATEndpointCPI_Connect(endpoint->cpi, &endpoint->data, peep)); return GAT_RETURN_STATUS(); } return GAT_INVALID_HANDLE; } /** * The creator of an GATEndpoint can use the GATEndpoint to create * GATPipes, which represent incoming connections. This is done by * calling Listen on the GATEndpoint instance. The GATEndpoint can * be destroyed at any time without affecting the obtained GATPipe. * * @param endpoint The GATEndpoint on which to act * @param peep A GATPipe connected to the endpoint */ GATResult GATEndpoint_Listen(GATEndpoint_const endpoint, GATPipe *peep) { if (NULL != endpoint) { GAT_STATUS_APIENTRY(endpoint->data.context, "GATEndpoint_Listen"); GAT_CREATE_STATUS(GATEndpointCPI_Listen(endpoint->cpi, &endpoint->data, peep)); return GAT_RETURN_STATUS(); } return GAT_INVALID_HANDLE; } /** * The creator of an GATEndpoint can use the GATEndpoint to create * GATPipes, which represent incoming connections. This is done by * calling Listen on the GATEndpoint instance. This call is * asynchroneous, and returns immediately. The GATPipe creation is * performed on the passed GATPipeListener \object. The * GATEndpoint can be destroyed at any time without affecting the * obtained GATPipe. * * @param endpoint The GATEndpoint on which to act * @param peepListener GATPipeListener object which handles incoming connections * @param listenerData Callback data */ GATResult GATEndpoint_AddGATPipeListener(GATEndpoint_const endpoint, GATPipeListener peepListener, void *listenerData) { if (NULL != endpoint) { GAT_STATUS_APIENTRY(endpoint->data.context, "GATEndpoint_AddGATPipeListener"); GAT_CREATE_STATUS(GATEndpointCPI_AddGATPipeListener(endpoint->cpi, &endpoint->data, peepListener, listenerData)); return GAT_RETURN_STATUS(); } return GAT_INVALID_HANDLE; } /* GATMonitorable */ /** GATEndpoint_AddMetricListener * * The function GATEndpoint_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 endpoint The GATEndpoint 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 GATEndpoint_AddMetricListener(GATEndpoint endpoint, GATMetricListener listener, void *listener_data, GATMetric metric, GATuint32 *cookie) { if (NULL != endpoint) { GAT_STATUS_APIENTRY(endpoint->data.context, "GATEndpoint_AddMetricListener"); if (NULL != endpoint->data.monitorable) { GAT_CREATE_STATUS(GATMonitorable_Impl_AddMetricListener(endpoint->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; } /** GATEndpoint_RegisterPolling * * The function GATEndpoint_RegisterPolling registers a continuous * metric with the given GATEndpoint instance. * * @param endpoint The GATEndpoint 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 GATEndpoint. * * @return An error code. */ GATResult GATEndpoint_RegisterPolling(GATEndpoint endpoint, GATMetric metric, GATMetricEvent *event, GATuint32 *cookie) { if (NULL != endpoint) { GAT_STATUS_APIENTRY(endpoint->data.context, "GATEndpoint_RegisterPolling"); if (NULL != endpoint->data.monitorable) { GAT_CREATE_STATUS(GATMonitorable_Impl_RegisterPolling( endpoint->data.monitorable, metric, 0, cookie)); /* ask the CPI provider to return the corresponding metric event */ GAT_CREATE_STATUS(GATEndpointCPI_GetMetricEvent(endpoint->cpi, &endpoint->data, metric, event)); if (GAT_FAILED(GAT_CURRENT_STATUS()) && NULL != cookie && 0 != *cookie) { GATMonitorable_Impl_RemoveRegisteredMetric(endpoint->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; } /** GATEndpoint_RemoveRegisteredMetric * * The function GATEndpoint_RemoveRegisteredMetric removes a GATMetricListener, * which was previously registered with GATEndpoint_AddMetricListener. * * @param endpoint The GATEndpoint 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 GATEndpoint_RemoveRegisteredMetric(GATEndpoint endpoint, GATMetric metric, GATuint32 cookie) { if (NULL != endpoint) { GAT_STATUS_APIENTRY(endpoint->data.context, "GATEndpoint_RemoveRegisteredMetric"); if (NULL != endpoint->data.monitorable) { GAT_CREATE_STATUS(GATMonitorable_Impl_RemoveRegisteredMetric( endpoint->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; } /** GATEndpoint_GetMetrics * * The function GATEndpoint_GetMetrics returns a list of metrics supported by this * GATEndpoint. * * @param endpoint The GATEndpoint 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 GATEndpoint_GetMetrics(GATEndpoint_const endpoint, GATList_GATMetric *metrics) { if (NULL != endpoint) { GAT_STATUS_APIENTRY(endpoint->data.context, "GATEndpoint_GetMetrics"); if (NULL != endpoint->data.monitorable) { GAT_CREATE_STATUS(GATMonitorable_Impl_GetMetrics( endpoint->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 */ /** GATEndpointCPI_SerialiseCallback * * The function GATEndpointCPI_SerialiseCallback is used as a callback function * for the serialisation of a GATEndpoint 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 GATEndpointCPI_SerialiseCallback(GATObject object, GATObject stream, GATBool clear_dirty) { GATEndpoint endpoint = GATObject_ToGATEndpoint(object); if (NULL != endpoint) { GAT_USES_STATUS(endpoint->data.context, "GATEndpointCPI_SerialiseCallback"); GAT_CREATE_STATUS(GATEndpointCPI_Serialise(endpoint->cpi, &endpoint->data, stream, clear_dirty)); if (GAT_SUCCEEDED(GAT_CURRENT_STATUS()) && GATTrue == clear_dirty) { endpoint->data.isdirty = GATFalse; } return GAT_RETURN_STATUS(); } return GAT_INVALID_HANDLE; } /** int GATEndpoint_Serialise(GATEndpoint endpoint, GATObject stream, GATBool clear_dirty) * @brief Serialise a GATEndpoint object * * The function GATEndpoint_Serialise serialises the given GATFIle object into the * given stream. * * @param endpoint The GATEndpoint 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 GATEndpoint_Serialise(GATEndpoint endpoint, GATObject stream, GATBool clear_dirty) { if (NULL != endpoint) { GAT_USES_STATUS(endpoint->data.context, "GATEndpoint_Serialise"); GAT_CREATE_STATUS(GATXds_SerialiseObject(GATEndpoint_ToGATObject(endpoint), stream, clear_dirty, GATEndpointCPI_SerialiseCallback, "uint32 string", GATENDPOINT_VERSION1, endpoint->data.nodename)); return GAT_RETURN_STATUS(); } return GAT_INVALID_HANDLE; } /** GATEndpointCPI_VersionCallback * * The function GATEndpointCPI_VersionCallback is used as a callback function * during the de-serialisation of a GATEndpoint. 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 GATEndpointCPI_VersionCallback(GATuint32 version) { GATBool retval = GATFalse; if ((version & ~GATENDPOINT_MINOR_MASK) <= GATENDPOINT_LASTVERSION) { retval = GATTrue; } return retval; } /** GATEndpointCPI_DeSerialiseCallback * * The function GATEndpointCPI_DeSerialiseCallback is used as a callback function * during the de-serialisation of a GATEndpoint. It should be provided for the * instantiation of the new GATEndpoint 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 * GATEndpoint_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 GATEndpointCPI_DeSerialiseCallback(GATContext context, GATObject stream, GATObject *object, GATuint32 version, va_list args) { GAT_USES_STATUS(context, "GATEndpointCPI_DeSerialiseCallback"); /* the version was eaten already */ char const **nodename = va_arg(args, char const **); GATEndpoint endpoint = NULL; struct utsname sysinfo; GAT_CREATE_STATUS_IF(uname(&sysinfo) != 0, POSIX_TO_GAT(errno)); GAT_CREATE_STATUS(GATEndpoint_DeSerialise_Create(context, stream, *nodename, &endpoint)); /* Silly stuff */ GAT_UNUSED_PARAMETER(version); /* construct the new object */ if (GAT_SUCCEEDED(GAT_CURRENT_STATUS())) { if (NULL != object) { *object = GATEndpoint_ToGATObject(endpoint); } else { GATEndpoint_Destroy(&endpoint); GAT_CREATE_STATUS(GAT_INVALID_PARAMETER); } } return GAT_RETURN_STATUS(); } /** GATEndpoint GATEndpoint_DeSerialise(GATContext context, GATObject stream, GATResult clear_dirty) * @brief De-serialise a GATEndpoint object * * The function GATEndpoint_DeSerialise de-serialises a streamed GATEndpoint 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 GATEndpoint object. */ GATEndpoint GATEndpoint_DeSerialise(GATContext context, GATObject stream, GATResult *result) { GAT_USES_STATUS(context, "GATEndpoint_DeSerialise"); GATObject object = NULL; /* the new object will be created here */ GATEndpoint endpoint = NULL; /* we must provide all instance data items to be de-serialised for this GATEndpoint object accordingly to the provided format string */ GATuint32 version = 0; char *nodename = NULL; /* read the data */ GAT_CREATE_STATUS(GATXds_DeSerialiseObject(context, stream, GATEndpointCPI_DeSerialiseCallback, GATEndpointCPI_VersionCallback, &object, "uint32 string", &version, &nodename)); free(nodename); endpoint = GATObject_ToGATEndpoint(object); if (NULL == endpoint) { GAT_CREATE_STATUS(GAT_BAD_OBJECT_CONVERSION); } if (GAT_FAILED(GAT_CURRENT_STATUS())) { GATObject_Destroy(&object); endpoint = NULL; } if (NULL != result) { *result = GAT_CURRENT_STATUS(); } GAT_STORE_STATUS(); return endpoint; } /** GATEndpoint_GetIsDirty * * The function GATEndpoint_GetIsDirty retrieves the status of the dirty flag of * this GATEndpoint object. * * @param endpoint The GATEndpoint object to inspect for its dirty status. * @param isdirty The pointer to a variable, which receives the dirty status. * * @return An error code. */ GATResult GATEndpoint_GetIsDirty(GATEndpoint_const endpoint, GATBool *isdirty) { if (NULL != endpoint) { GAT_STATUS_APIENTRY(endpoint->data.context, "GATEndpoint_GetIsDirty"); if (NULL != isdirty) { *isdirty = endpoint->data.isdirty; } else { GAT_CREATE_STATUS(GAT_INVALID_PARAMETER); } return GAT_RETURN_STATUS(); } return GAT_INVALID_HANDLE; } /* Local functions */ /** GATEndpoint_DeSerialise_Create * * The function GATEndpoint_DeSerialise_Create creates a new GATEndpoint object and * tries to find a CPI provider to associate with this endpoint 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 GATEndpoint object. * @param stream The object from which the adaptor should read the streamed * instance data. * @param new_object The pointer to the variable, which should receive the * newly constructed GATEndpoint object. * * @return An error code. */ static GATResult GATEndpoint_DeSerialise_Create(GATContext context, GATObject stream, char const *name, GATEndpoint *new_object) { GAT_USES_STATUS(context, "GATEndpoint_DeSerialise_Create"); GATEndpoint new_endpoint = (GATEndpoint) malloc(sizeof(struct GATEndpoint_S)); if(NULL != new_endpoint) { memset(new_endpoint, 0, sizeof(struct GATEndpoint_S)); new_endpoint->GATObject__vtable = &GATEndpoint__vtable; new_endpoint->GATSerialisable__vtable = &GATEndpoint_ISerialisable__vtable; new_endpoint->GATMonitorable__vtable = &GATEndpoint_IMonitorable__vtable; new_endpoint->data.context = context; new_endpoint->data.isdirty = GATFalse; new_endpoint->data.source = GATEndpoint_ToGATObject_const(new_endpoint); /* 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); } GAT_CREATE_STATUS(GATEndpoint_CloneString(&new_endpoint->data.nodename, name)); new_endpoint->cpilist = GATRegistry_FindGATEndpointCPI(registry, preferences); if (NULL == new_endpoint->cpilist) { GAT_CREATE_STATUS(GAT_NO_REGISTERED_CPI); } else if (GAT_SUCCEEDED(GAT_CURRENT_STATUS())) { /* find out the current stream position */ GATuint32 offset = 0; GATBool found_cpi = GATFalse; GATEndpointCPIList 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_endpoint->cpilist; NULL != current; current = current->next) { /* try, whether this cpi can handle the input */ GAT_CREATE_STATUS(GATEndpointCPI_DeSerialise(current->cpi, stream, &new_endpoint->data)); if (GAT_SUCCEEDED(GAT_CURRENT_STATUS())) { new_endpoint->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 = GATEndpointCPI_GetMetrics(new_endpoint->cpi, &new_endpoint->data, &metrics); if (GAT_SUCCEEDED(retval)) { new_endpoint->data.monitorable = GATMonitorable_Impl_Create(metrics); if (NULL == new_endpoint->data.monitorable) { GAT_CREATE_STATUS(GAT_MEMORYFAILURE); } GATList_GATMetric_Destroy(&metrics); } else if (GAT_NOTIMPL != retval) { GAT_CREATE_STATUS(retval); } { retval = GAT_SUCCESS; /* no monitoring supported here */ } if (GAT_SUCCEEDED(retval)) { GAT_CREATE_STATUS(GATRegistry_AddGATEndpointToCPIList( new_endpoint->data.context, new_endpoint->cpi, new_endpoint)); } } } } } else { GAT_CREATE_STATUS(GAT_MEMORYFAILURE); } if (GAT_SUCCEEDED(GAT_CURRENT_STATUS())) { if (NULL != new_object) { *new_object = new_endpoint; } else { GATEndpoint_Destroy(&new_endpoint); GAT_CREATE_STATUS(GAT_INVALID_PARAMETER); } } else { GATEndpoint_Destroy(&new_endpoint); } return GAT_RETURN_STATUS(); } /** GATEndpoint_GetNodename * * This function takes a <code>struct utsname</code> struct and returns a copy * of the <code>nodename</code> element in the passed structure. * * @param systemInfo The <code>struct utsname</code> to quell info from * @param nodename A copy of the nodename contained in the passed structure * @return A GAT error code */ static GATResult GATEndpoint_GetNodename(struct utsname systemInfo, char **nodename) { GATResult retval = GAT_INVALID_PARAMETER; if (NULL != nodename) { retval = GATEndpoint_CloneString(nodename, systemInfo.nodename); } return retval; } /** GATEndpoint_CloneString * Creates a clone of a string * * @param destination The destination string * @param source The source string * @return The error code */ static GATResult GATEndpoint_CloneString(char **destination, const char *source) { GATResult retval = GAT_INVALID_PARAMETER;; if (NULL != destination && NULL != source) { int sourceLength = strlen(source) + 1; char *tempDestination = (char *) malloc(sourceLength); if (NULL != tempDestination) { strcpy( tempDestination, source ); *destination = tempDestination; retval = GAT_SUCCESS; } else { retval = GAT_MEMORYFAILURE; } } return retval; } /* GATEndpoint_GetCPIInstanceData * * The function GATEndpoint_GetCPIInstanceData returns the CPI instance data, * associated with the given GATFile object. * * @param endpoint 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 GATEndpoint_GetCPIInstanceData(GATEndpoint endpoint, void **data) { if (NULL != endpoint) { GAT_USES_STATUS(endpoint->data.context, "GATEndpoint_GetCPIInstanceData"); if (NULL != data) { *data = (void *)&endpoint->data; } else { GAT_CREATE_STATUS(GAT_INVALID_PARAMETER); } return GAT_RETURN_STATUS(); } return GAT_INVALID_HANDLE; }