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

GATStatus.h Go to the documentation of this file. /** @file GATStatus.h * Header file for the GATStatus class. * * The GATStatus class provides a set of routines to maintain a flexible and * uniform way to store, retrieve and manage errors and related information, * which occured during a call to the GAT API. * * An instance of this class represents an error or an information message * from a GAT operation or from an underlying adaptor. instances of this class * are used to provide an audit trail which the application user can use to * trace the sequence of events which happened in any particular GAT operation; * this may then be used by the application, adaptor or service developers or * providers to debug problems. * Since the GAT Engine and adaptors may do several independent operations each * of which may have associated errors or status messages, a GATStatus instance * forms a node in a tree of GATStatus instances, rather than the more normal * parent-child process of a try-catch type error mechanism. * * @date Tue Sep 30 2003 * * @version $Header: /export/cvs-gridlab/wp-1/Codes/GATEngine/C-reference/src/GATStatus.h,v 1.19 2004/04/28 10:50:10 hartmutkaiser Exp $ * * Copyright (C) Hartmut Kaiser * This file is part of the GAT Engine. * Contributed by Hartmut Kaiser <hartmutkaiser [at] t-online [dot] 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) */ #if !defined(_GATSTATUS_H_) #define _GATSTATUS_H_ 1 #include "GATType.h" #include "GATList.h" /* typedefs */ #ifdef __cplusplus extern "C" { #endif /* Declare the GATList_GATStatus list. */ GATLIST_DECLARE_QUALIFIED(extern, GATStatus, GATList_GATStatus); /* Declare the converters to/from GATObject */ GATOBJECT_DECLARE_CONVERTERS(GATStatus); /* Helper API for GATStatus based error diagnostics and error propagation */ /** GATCreateStatus * * The function GATCreateStatus is a helper function used for creating and * assigning a GATStatus object to the function local GATStatus. It is used * for newly diagnosed errors. * * @param name The function name of the function, where the error/diagnostic * occured. * @param status The function local status object to which the newly created * error/diagnostic should be added. * @param code The GATResult code of the error/diagnostic to be added. * @param context The GATContext to which the GATStatus to be propagated is * associated with. * * @return The provided GATResult code from the code parameter. */ GATResult GATCreateStatus(char const *name, GATStatus *status, GATResult result_code, GATContext context, char const *filename, GATuint32 lineno); /** GATPropagateStatus * * The function GATPropagateStatus is used for taking the current status from * the given context and append it to the function local GATStatus. It is used * for error/diagnostics propagation purposes. * * @param name The function name of the function, where the error/diagnostic * occured. * @param status The function local status object to which the newly created * error/diagnostic should be added. * @param code The GATResult code of the error/diagnostic to be added. * @param context The GATContext to which the GATStatus to be propagated is * associated with. * * @return The provided GATResult code from the code parameter. * * @comment This function is depreciated and was completely replaced by the * GATCreateStatus function. */ GATResult GATPropagateStatus(char const *name, GATStatus *status, GATResult code, GATContext context); /* GATObject API */ /** void GATStatus_Destroy(GATStatus *status) * @brief Delete an existing GATStatus object * * The function GATStatus_Destroy destroys this GATStatus object and all of * the contained data (such as the GATStatus list of children and the list * of attached message strings). * * @param status The GATStatus object to be destroyed. If this parameter is 0 * (zero) the function does nothing, but returns @c #GAT_SUCCESS. */ void GATStatus_Destroy(GATStatus *status); /** int GATStatus_Equals(GATStatus_const lhs, GATStatus_const rhs, GATBool *isequal) * @brief Compare two GATStatus objects * * The function GATStatus_Equals compares the two given GATStatus objects and * returns the outcome of this comparison. * * @param lhs The first list to compare * @param rhs The second list to compare * @param isequal The pointer to the GATBool variable, which should receive * the result if the comparison * * @return An error code. */ GATResult GATStatus_Equals(GATStatus_const lhs, GATStatus_const rhs, GATBool *isequal); /** GATType GATStatus_GetType(GATStatus_const status) * @brief Return the type of the GATStatus * * The function @c GATStatus_GetType always returns GATType_GATStatus. * * @param object The object to inspect * * @return Returns always @c #GATType_GATStatus. */ GATType GATStatus_GetType(GATStatus_const status); /** int GATStatus_Clone(GATStatus_const status, GATStatus *new_status) * @brief Clones a GATStatus object. * * The function GATStatus_Clone makes a exact copy of the given @c #GATStatus * object. * * @param status The object to clone * @param new_Status The pointer, through which the result is to be * returned. * * @return An error type. */ GATResult GATStatus_Clone(GATStatus_const status, GATStatus *new_status); /** int GATStatus_GetInterface(GATStatus_const file, GATInterface iftype, void const **ifp) * @brief Get an interface supported by a GATFile * * The function GATStatus_GetInterface allows to get a pointer to an * additional interface supported by this GATFile. * * @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 GATStatus_GetInterface(GATStatus_const object, GATInterface iftype, void const **ifp); /** GATStatus_Trace * * The function GATStatus_Trace prints out to stderr the content of the given * GATStatus object. * * @param status The object for which to print the error information. */ void GATStatus_Trace(GATStatus_const status); /* GATAdvertiseable API */ #define GATSTATUS_VERSION1 0x0100 #define GATSTATUS_LASTVERSION GATSTATUS_VERSION1 #define GATSTATUS_MINOR_MASK 0x00ff /** GATResult GATStatus_Serialise(GATStatus file, GATObject stream, GATBool clear_dirty) * @brief Serialise a GATStatus object * * The function GATStatus_Serialise serialises the given GATStatus object into the * given stream. * * @param object The GATStatus 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 GATStatus_Serialise(GATStatus object, GATObject stream, GATBool clear_dirty); /** GATStatus GATStatus_DeSerialise(GATContext context, GATObject stream, GATBool clear_dirty) * @brief De-serialise a GATStatus object * * The function GATStatus_DeSerialise de-serialises a streamed GATStatus 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 GATStatus object. */ GATStatus GATStatus_DeSerialise(GATContext context, GATObject stream, GATResult *result); /** GATStatus_GetIsDirty * * The function GATStatus_GetIsDirty retrieves the status of the dirty flag of * this GATStatus object. * * @param object The GATStatus object to inspect for its dirty status. * @param isdirty The pointer to a variable, which receives the dirty status. * * @return An error code. */ GATResult GATStatus_GetIsDirty(GATStatus_const object, GATBool *isdirty); /* GATStatus API */ /** GATStatus GATStatus_Create(char const *message) * @brief Create a new GATStatus object * * The function @c GATStatus_Create creates a new GATStatus object and * associates with it the given message. The status code stored internally is * initialized to @c #GAT_SUCCESS. * * @param message The message to associate initially with the newly created * GATStatus. * * @return Returns a handle to the newly created GATStatus object. * returns 0 (zero) if an error occurs. */ GATStatus GATStatus_Create(char const *message, char const *filename, GATuint32 lineno); /** GATStatus GATStatus_Create_Code(GATResult code) * @brief Create a new GATStatus object * * The function @c GATStatus_Create_Code creates a new GATStatus object and * associates with it the given status code. * * @param code The status code to associate initially with the newly created * GATStatus. * * @return Returns a handle to the newly created GATStatus object. * returns 0 (zero) if an error occurs. */ GATStatus GATStatus_Create_Code(GATResult code, char const *filename, GATuint32 lineno); /** int GATStatus_SetStatusCode(GATStatus status, int code) * @brief Set the status code to be associated with the GATStatus object * * The function GATStatus_SetStatusCode associates a new status code with * the GATStatus object under inspection. * * @param status The GATStatus object, which associated status code * should be set. * @param code The new status code to be associated with the GATStatus * object. * * @return Returns @c #GAT_SUCCESS if the given status parameter is a * valid GATStatus object. If the given parameter was * not a valid GATStatus object, then @c #GAT_INVALID_HANDLE * is returned. */ GATResult GATStatus_SetStatusCode(GATStatus status, int code); /** int GATStatus_GetStatusCode(GATStatus status) * @brief Get the status code associated with the GATStatus object * * The function GATStatus_GetStatusCode returns the status code, which * was associated with the GATSTatus object with a call of the * @c #GATStatus_SetStatusCode function. * * @param status The GATStatus object, which associated status code * should be returned. * * @return The status code associated with the GATStatus object. If the * GATStatus under inspection was not a valid GATStatus (but not * equal zero), then @c #GAT_INVALID_HANDLE is returned. */ GATResult GATStatus_GetStatusCode(GATStatus_const status); /** int GATStatus_AddChild(GATStatus status, GATStatus child) * @brief Adds a child to the list of children * * The function GATStatus_AddChild adds a GATStatus to the list of * children of this status object. Please note, that there is no test * to avoid cyclic hierarchies, so you will have to ensure, that a GATStatus * object is @b not inserted into a GATStatus hierarchy twice. * * @param status The GATStatus object, which should get the child added. * @param child The GATStatus object to be added as the child. * * @returns The function returns @c #GAT_SUCCESS, if the child was * successfully added to the list of children. If the status * parameter wasn't a valid GATStatus object, then the value * @c #GAT_INVALID_HANDLE is returned. */ GATResult GATStatus_AddChild(GATStatus status, GATStatus child); /** GATList_GATStatus_const GATStatus_GetChildren(GATStatus status) * @brief Get the list of associated children * * The function GATStatus_GetChildren returns the list of children * associated with the given GATStatus. * * @param status The GATStatus object, for which the list of children is to * be returned. * * @return The function returns the handle of a GATList_GATStatus object, * which holds the GATStatus objects associated as children. If the * status parameter does not represent a valid GATStatus object or if * there aren't any associated children, then 0 (zero) is returned. */ GATList_GATStatus_const GATStatus_GetChildren(GATStatus_const status); /** int GATStatus_AddMessage(GATStatus status, char const *message) * @brief Add a message to the GATStatus object * * The function GATStatus_AddMessage adds a message to the list of * messages associated with this GATStatus object. * * @param status The GATStatus object the message has to be * associated with. * @param message The character string to be associated with the * GATStatus object. Note, that actually a copy of this string * is stored inside the GATStatus object. * * @return If the message was added successfully to the list of associated * messages of this GATSTatus, the function will return @c #GAT_SUCCESS. * If the status parameter does not represent a valid GATStatus object * the function returns @c #GAT_INVALID_HANDLE. */ GATResult GATStatus_AddMessage(GATStatus status, char const *message); /** GATList_String_const GATStatus_GetMessages(GATStatus status) * @brief get the list of associated messages * * The function GATStatus_GetMessages returns the list of associated messages. * * @param status The GATStatus object, for which the list of messages is to * be returned. * * @return The function returns the handle of a GATList_String object, * which holds the messages associated with this object. If the * status parameter does not represent a valid GATStatus object, * then 0 (zero) is returned. */ GATList_String_const GATStatus_GetMessages(GATStatus_const status); /** GATStatus GATStatus_GetParent(GATStatus status) * @brief Get the parent status of this GATStatus object * * The function GATStatus_GetParent returns the GATStatus object, which is the * direct parent of this status object. This is meaningful especially because, * different GATStatus objects may be organized in a hierarchical way. * * @param status The GATStatus object, for which the direct parent is to be * returned * * @return The function returns the GATStatus, which is stored as the direct * parent of this status object. If the status parameter does not * represent a valid GATStatus object, then 0 (zero) is returned. */ GATStatus_const GATStatus_GetParent(GATStatus_const status); #ifdef __cplusplus } /* extern "C" */ #endif #endif /* defined(_GATSTATUS_H_) */