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.h Go to the documentation of this file. /** @file GATEndpoint.h * Header file for the GATEndpoint class. * * An GATEndpoint represents an end of a byte stream. * * @date $Date: 2004/03/24 19:30:58 $ * * @version $Header: /export/cvs-gridlab/wp-1/Codes/GATEngine/C-reference/src/GATEndpoint.h,v 1.9 2004/03/24 19:30:58 hartmutkaiser Exp $ * * Copyright (C) Kelly Davis * This file 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) */ #ifndef _GATENDPOINT_H_ #define _GATENDPOINT_H_ 1 #include "GATType.h" #include "GATObject.h" #ifdef __cplusplus extern "C" { #endif /* Declare the converters to/from GATObject */ GATOBJECT_DECLARE_CONVERTERS(GATEndpoint); /* GATObject API */ /** GATEndpoint_Destroy * The GATEndpoint destructor. * This is the destructor for GATEndpoint objects. * * @param this An old GATEndpoint */ void GATEndpoint_Destroy(GATEndpoint *endpoint); /** 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); /** 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_endpoint); /** 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); /** int GATEndpoint_GetInterface(GATEndpoint_const endpoint, GATInterface iftype, void const **ifp) * @brief Get an interface supported by a GATEndpoint * * 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); /* GATEndpoint API */ /** * 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); /** * 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); /** * 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); /** * 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 Call back data */ GATResult GATEndpoint_AddGATPipeListener( GATEndpoint_const endpoint, GATPipeListener peepListener, void *listenerData); /* GATMonitorable API */ /** 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); /** 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); /** 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); /** 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); /* GATAdvertiseable API */ #define GATENDPOINT_VERSION1 0x0100 #define GATENDPOINT_LASTVERSION GATENDPOINT_VERSION1 #define GATENDPOINT_MINOR_MASK 0x00ff /** 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); /** GATEndpoint GATEndpoint_DeSerialise(GATContext context, GATObject stream, GATBool 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); /** 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); #ifdef __cplusplus } #endif #endif /* _GATENDPOINT_H_ */