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

GATTable.h Go to the documentation of this file. /** @file GATTable.h * Header file for the GATTable class. * * GatTable is a set of routines for implementing * hash tables within the GAT engine * * @date Sun Sep 21 2003 * * Copyright (C) Gavin Powell * This file is part of the GAT Engine. * Contributed by Gavin Powell <g.r.powell@cs.cf.ac.uk>. * * 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 _GATHASH_H_ #define _GATHASH_H_ 1 #include "GATType.h" #include "GATObject.h" /* typedefs */ #ifdef __cplusplus extern "C" { #endif /* Declare the converters to/from GATObject */ GATOBJECT_DECLARE_CONVERTERS(GATTable); /* GATTable with a string as a key */ /** GATTable_Create * Create the GATTable object. * this_ is the method used by any * application code to create the GATTable * object. * * @param void. * * @return The GATTable object */ GATTable GATTable_Create(void); /** int GATTable_GetType(GATTable_const file) * @brief Return the type of the GATTable * * The function @c GATTable_GetType always returns GATType_GATTable. * * @param object The object to inspect * * @return returns always @c #GATType_GATTable. */ GATType GATTable_GetType(GATTable_const table); /** GATTable_Destroy * The GATTable destructor. * This is the destructor for GATTable objects. * * @param this An old GATTable */ void GATTable_Destroy(GATTable *table); /** int GATTable_Equals(GATTable_const lhs, GATTable_const rhs, GATBool *isequal) * @brief Compares two GATTable objects * * The function @c GATTable_Equals compares two file objects of type * @c #GATTable. * * @param lhs The first file object to compare * @param rhs The second file object to compare * @param isequal The pointer to the GATBool variable, which should receive * the result if the comparison * * @return An error code. */ GATResult GATTable_Equals(GATTable_const lhs, GATTable_const rhs, GATBool *isequal); /** int GATTable_Clone(GATTable_const filehandle, GATTable *new_file) * @brief Clone the given GATTable * * The function @c GATTable_Clone generates a (deep) copy of the given * GATTable. * * @param filehandle The object to clone * @param new_file The pointer, through which the result is to be * returned. * * @return An error type. */ GATResult GATTable_Clone(GATTable_const table, GATTable *new_table); /** int GATTable_GetInterface(GATTable_const table, GATInterface iftype, void const **ifp) * @brief Get an interface supported by a GATList * * The function GATTable_GetInterface allows to get a pointer to an * additional interface supported by this GATList. * * @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 GATTable_GetInterface(GATTable_const table, GATInterface iftype, void const **ifp); /** GATTable_Remove * Remove a key,value pair from the hash table. * * @param this_ The hash table to remove from. * @param key The the key for the key,value pair to be removed * * @return GAT error code */ GATResult GATTable_Remove(GATTable table, const void *key); /** GATTable_Add_Int * Add a type int to the hash table. * * @param table The hash table to add the data to. * @param key The key value to associate the data to. * @param data The int data to be added * * @return GAT error code */ GATResult GATTable_Add_int(GATTable table, const void *key, GATint32 data); /** GATTable_Add_Short * Add a type short to the hash table. * * @param table The hash table to add the data to. * @param key The key value to associate the data to. * @param data The short data to be added * * @return GAT error code */ GATResult GATTable_Add_short(GATTable table, const void *key, GATint16 data); /** GATTable_Add_Double * Add a type double to the hash table. * * @param table The hash table to add the data to. * @param key The key value to associate the data to. * @param data The double data to be added * * @return GAT error code */ GATResult GATTable_Add_double(GATTable table, const void *key, GATdouble64 data); /** GATTable_Add_Float * Add a type float to the hash table. * * @param table The hash table to add the data to. * @param key The key value to associate the data to. * @param data The float data to be added * * @return GAT error code */ GATResult GATTable_Add_float(GATTable table, const void *key, GATfloat32 data); /** GATTable_Add_String * Add a type string to the hash table. * * @param table The hash table to add the data to. * @param key The key value to associate the data to. * @param data The string data to be added * * @return GAT error code */ GATResult GATTable_Add_String(GATTable table, const void *key, const char *data); /** GATTable_Add_GATObject * Add a type GATObject to the hash table. * * @param table The hash table to add the data to. * @param key The key value to associate the data to. * @param data The float data to be added * * @return GAT error code */ GATResult GATTable_Add_GATObject(GATTable table, const void *key, GATObject_const object); /** GATTable_Get_ElementType * Get the type associated with a key. * * @param table The hash table to get the type from. * @param key The key value associated with the data type. * * @return GATType */ GATType GATTable_Get_ElementType(GATTable_const table, const void *key); /** GATTable_GetKeys * Get a list of all the current keys in the hash table. The key list is * terminated by a NULL * * @param table The hash table to get the keys from. * * @return the list of keys */ void **GATTable_GetKeys(GATTable_const table); /** GATTable_ReleaseKeys * * The function GATTable_ReleaseKeys may be used to free all the keys * allocated by a call to the GATTable_GetKeys function. * * @param table The table, from which the keys where retrieved. * @param keys The pointer to the array of keys returned by a call to the * GATTable_GetKeys function. */ void GATTable_ReleaseKeys(GATTable_const table, void ***keys); /** GATTable_Get_Int * Get the int type data associated with a key. * * @param table The hash table get the data from. * @param key The key value to associate the data to. * @param data The recovered int data * * @return GAT error code */ GATResult GATTable_Get_int(GATTable_const table, const void *key, GATint32 *data); /** GATTable_Get_Short * Get the short type data associated with a key. * * @param table The hash table get the data from. * @param key The key value to associate the data to. * @param data The recovered short data * * @return GAT error code */ GATResult GATTable_Get_short(GATTable_const table, const void *key, GATint16 *data); /** GATTable_Get_Double * Get the double type data associated with a key. * * @param table The hash table get the data from. * @param key The key value to associate the data to. * @param data The recovered double data * * @return GAT error code */ GATResult GATTable_Get_double(GATTable_const table, const void *key, double *data); /** GATTable_Get_Float * Get the float type data associated with a key. * * @param table The hash table get the data from. * @param key The key value to associate the data to. * @param data The recovered float data * * @return GAT error code */ GATResult GATTable_Get_float(GATTable_const table, const void *key, float *data); /** GATTable_Get_String * Get the string type data associated with a key. * * @param table The hash table get the data from. * @param key The key value to associate the data to. * @param data The recovered string data. If table parameter is 0 (zero), the * function does not try to recover the data but simply returns the * required size of the buffer needed to recover the data. * @param length length of the string buffer arg data * * @return length of string found or error code */ GATResult GATTable_Get_String(GATTable_const table, const void *key, char *data, GATuint32 length); /** GATTable_Get_GATObject * Get the GATObject type data associated with a key. * * @param table The hash table get the data from. * @param key The key value to associate the data to. * @param data The recovered GATObject data * * @return GAT error code */ GATResult GATTable_Get_GATObject(GATTable_const table, const void *key, GATObject_const *object); /** GATTable_Size * @brief Return the number of elements stored inside a table * * The function @c GATTable_Size returns the number of elements, currently * stored inside the given table. * * @param table The table to be queried for its number of elements * * @return If successful, the function returns number of elements. If an error * occures, (size_t)(-1) is returned. */ GATuint32 GATTable_Size(GATTable_const table); /* GATAdvertiseable API */ #define GATTABLE_VERSION1 0x0100 #define GATTABLE_LASTVERSION GATTABLE_VERSION1 #define GATTABLE_MINOR_MASK 0x00ff /** int GATTable_Serialise(GATTable file, GATObject stream, GATBool clear_dirty) * @brief Serialise a GATTable object * * The function GATTable_Serialise serialises the given GATTable object into * the given stream. * * @param file The GATTable 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 GATTable_Serialise(GATTable file, GATObject stream, GATBool clear_dirty); /** GATTable GATTable_DeSerialise(GATContext context, GATObject stream, GATBool clear_dirty) * @brief De-serialise a GATTable object * * The function GATTable_DeSerialise de-serialises a streamed GATTable 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 GATTable object. */ GATTable GATTable_DeSerialise(GATContext context, GATObject stream, GATResult *result); /** GATTable_GetIsDirty * * The function GATTable_GetIsDirty retrieves the status of the dirty flag of * this GATTable object. * * @param file The GATTable object to inspect for its dirty status. * @param isdirty The pointer to a variable, which receives the dirty status. * * @return An error code. */ GATResult GATTable_GetIsDirty(GATTable_const file, GATBool *isdirty); #ifdef __cplusplus } #endif #endif /* _GATHASH_H_ */