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

GATContext.h Go to the documentation of this file. /** @file GATContext.h * Header file for the GATContext class. * * The GATContext is the primary GAT object, and is used to maintain * state. There may be multiple contexts. Creation of the first GATContext * initialises the GATEngine, and destruction of the last one shuts down the * GATEngine. * * @date Tue Sep 2 2003 * * @version $Header: /export/cvs-gridlab/wp-1/Codes/GATEngine/C-reference/src/GATContext.h,v 1.23 2004/04/19 12:52:15 hartmutkaiser Exp $ * * Copyright (C) Tom Goodale * This file is part of the GAT Engine. * Contributed by Tom Goodale <goodale@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 _GATCONTEXT_H_ #define _GATCONTEXT_H_ 1 #include "GATType.h" #include "GATInternal.h" #include "GATSecurityContext.h" #ifdef __cplusplus extern "C" { #endif /* Declare the converters to/from GATObject */ GATOBJECT_DECLARE_CONVERTERS(GATContext); /** GATContext_Create * The GATContext constructor. * This is the constuctor for the GATContext. If there is a GATSelf it uses * that for initialisation, otherwise it creates it. * * @return A new GATContext */ GATContext GATContext_Create(void); /** GATContext_Destroy * The GATContext destructor. * This is the destructor for the GATContext. * * @param context An old GATContext */ void GATContext_Destroy(GATContext *ctx); /** * This fucntion returns the type, a #GATType of the passed #GATContext_const. * This function will always return #GATType_GATContext. * * @param this The #GATContext_const to query * @return The #GATType of the passed @c context */ GATType GATContext_GetType(GATContext_const ctx); /** GATContext_AddPreferences * The given GATPreferences are used as default preferences if for GATObjects * created with this GATContext. * * @param context The GATContext to modify * @param preferences Default GATPreferences for GATObjects created with this * GATContext. * @return An error code */ GATResult GATContext_AddPreferences(GATContext context, GATPreferences_const preferences); /** GATContext_RemovePreferences * Remove the GATPreferences used as default preferences if for * GATObjects created with this GATContext. * * @param context The context to modify * @return An error code */ GATResult GATContext_RemovePreferences(GATContext context); /** GATContext_GetPreferences * Return the GATPreferences that are used as default preferences if for * GATObjects created with this GATContext. * * @param context The GATContext to query * @return The GATPreferences of the passed GATContext */ GATPreferences_const GATContext_GetPreferences(GATContext_const context); /** GATContext_Clone * Clone is used to clone a specified context, copying all * state and security information. The new GATContext is * completely independent from the original one, which may * be destroyed with no effect on the new one. * * @param this The GATContext to clone * @param thisClone The cloned GATContext * @return An error code */ GATResult GATContext_Clone(GATContext_const ctx, GATContext *thisClone); /** * Tests this GATContext for equality with * the passed GATContext instance * * If the passed GATContext points to the same location * in memory, then it is deemed equal to the passed * GATContext instance. * * @param this The first GATContext to compare * @param that The second GATContext to compare * @param isequal Result of comparrison * @return An error code */ GATResult GATContext_Equals(GATContext_const lhs, GATContext_const rhs, GATBool *isequal); /** GATContext_GetInterface * This function gets an interface supported by this GATContext * * The function GATContext_GetInterface allows to get a pointer to an * additional interface supported by this GATContext. * * @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 GATContext_GetInterface(GATContext_const object, GATInterface iftype, void const **ifp); /** GATContext_GetCurrentStatus * * The function GATContext_GetCurrentStatus returns the GATStatus object, * which is currently associated with the given GATContext. * * Note, that the ownership of the GATStatus is transfered to the caller of * this function. The caller has to destroy the returned GATStatus * explicitely. * * @param context The GATContext, which associated status is to be returned. * @param status The pointer to the variable, which receives the returned * status. * * @return An error code. */ GATResult GATContext_GetCurrentStatus(GATContext context, GATStatus_const *status); /** GATContext_SetCurrentStatus * * The function GATContext_SetCurrentStatus associates the given GATStatus * object with this instance of GATContext. * * Note, that the ownership of the GATStatus is transfered to the GATContext * object, so don't destroy the GATStatus directly after calling this * function. * * @param context The GATContext the new status is to be associated with. * @param status The GATStatus object to associate with this context * (the ownership is transferred to the context!). * * @return An error code. */ GATResult GATContext_SetCurrentStatus(GATContext context, GATStatus *status); /* GATContext_ServiceActions * * The ServiceActions call is used to allow the GAT Engine to service * asynchronous actions, such as GATRequests and GATMetricEvents. In a * single-threaded application it is likely that a timeout would be supplied, * in a multi-threaded application one thread may be used for the GAT by using * this call and no timeout. * * @param timeout This may be a 0 timeout to indicate no timeout at all, or * a specific time length. * * @return An error code. */ GATResult GATContext_ServiceActions(GATContext context, GATTimePeriod_const timeout); /** GATContext_AddSecurityContext * Adds the passed GATSecurityContext. * * @param context The #GATContext to modify * @param securityContext The #GATSecurityContext to add * @return An error code */ GATResult GATContext_AddSecurityContext(GATContext context, GATSecurityContext securityContext); /** GATContext_RemoveSecurityContext * Removes the passed GATSecurityContext. Upon completion a #GATSecurityContext equivalent * to the passed #GATSecurityContext is removed from the passed #GATContext, if such exists * in the passed #GATContext, or an error is returned. * * @param The context #GATContext to modify * @param The #GATSecurityContext to remove * @return An error code */ GATResult GATContext_RemoveSecurityContext(GATContext context, GATSecurityContext securityContext); /** GATContext_GetSecurityContexts * Gets a list of GATSecurityContexts associated with this GATContext. The returned * list must be freed by the caller. * * @param context The #GATContext to modify * @param A pointer to a GATList_GATSecurityContext receiving this * #GATSecurityContext instances or NULL in an error occurs. * * @return An error code. */ GATResult GATContext_GetSecurityContexts(GATContext_const context, GATList_GATSecurityContext *list); /** GATContext_GetSecurityContextsByType * Gets a List of GATSecurityContexts of the specified type associated with * this GATContext. * The returned list must be freed by the caller. * * @param context The #GATContext to query * @param type The type of the #GATSecurityContext to return * @param The pointer to a GATList_GATSecurityContext which receives the * #GATSecurityContext instances of the the specified type or (NULL or * empty list) on error. * * @return An error code. */ GATResult GATContext_GetSecurityContextsByType(GATContext_const context, GATSecurityContextType type, GATList_GATSecurityContext *list); #ifdef __cplusplus } #endif #endif /* _GATCONTEXT_H_ */