GAT Documentation

00001 /** @file GATReservation.h
00002  *  Header file for the GATReservation class.
00003  *
00004  *  An instance of this class is a reservation for a GATResource.
00005  *
00006  *  @date Thu Oct 23 2003
00007  *
00008  *  @version $Header: /export/cvs-gridlab/wp-1/Codes/GATEngine/C-reference/src/GATReservation.h,v 1.9 2004/03/24 19:30:58 hartmutkaiser Exp $
00009  *
00010  *  Copyright (C) Hartmut Kaiser
00011  *  This file is part of the GAT Engine.
00012  *  Contributed by Hartmut Kaiser <hartmutkaiser [at] t-online [dot] de>.
00013  *
00014  *  Use, modification and distribution is subject to the Gridlab Software
00015  *  License. (See accompanying file GLlicense.txt or copy at
00016  *  http://www.gridlab.org/GLlicense.txt)
00017  */
00018  
00019 #if !defined(_GATRESERVATION_H_)
00020 #define  _GATRESERVATION_H_
00021 
00022 /* GAT Header Files */
00023 #include "GATObject.h"
00024 #include "GATType.h"
00025 #include "GATResource.h"
00026 #include "GATReservation.h"
00027 
00028 /* Structures, unions and enums */
00029 
00030 #ifdef __cplusplus
00031 extern "C" {
00032 #endif
00033 
00034 /* Declare the converters to/from GATObject */
00035 GATOBJECT_DECLARE_CONVERTERS(GATReservation);
00036 
00037  /** GATReservation_Create
00038  *  @brief Create a new GATReservation object.
00039  *
00040  *  The function @c GATReservation_Create creates a new GATReservation object.
00041  *
00042  *  @return Returns a handle to the newly created GATReservation object.
00043  *        Returns 0 (zero) if an error occurs.
00044  *
00045  *  @remark This is an internal function, do not use it directly.
00046  */
00047 GATReservation 
00048   GATReservation_Create(GATContext context, GATPreferences_const preferences,
00049   char const *unique_name);
00050 
00051 /** void GATReservation_Destroy(GATReservation *resource)
00052  *
00053  *  The function GATReservation_Destroy is the destructor used to
00054  *  free all the memory allocated by an GATReservation instance.
00055  *
00056  *  @param description The pointer to the GATReservation to destroy
00057  */
00058 void
00059   GATReservation_Destroy(GATReservation *object);
00060 
00061 /** int GATReservation_Equals(GATReservation_const lhs, GATReservation_const rhs, GATBool *isequal)
00062  *  @brief Compares two GATReservation objects
00063  *
00064  *  The function @c GATReservation_Equals compares two file objects of type 
00065  *  @c #GATReservation.
00066  *
00067  *  @param lhs The first file object to compare
00068  *  @param rhs The second file object to compare
00069  *  @param isequal The pointer to the GATBool variable, which should receive 
00070  *        the result if the comparison
00071  *
00072  *  @return An error code.
00073  */
00074 GATResult
00075   GATReservation_Equals(GATReservation_const lhs,
00076     GATReservation_const rhs, GATBool *isequal);
00077 
00078 /** int GATReservation_Clone(GATReservation_const filehandle, GATReservation *new_file)
00079  *  @brief Clone the given GATReservation
00080  *
00081  *  The function @c GATReservation_Clone generates a (deep) copy of the given
00082  *  GATReservation. 
00083  *
00084  *  @param filehandle The object to clone
00085  *  @param new_file The pointer, through which the result is to be 
00086  *        returned.
00087  *
00088  *  @return An error type.
00089  */
00090 GATResult
00091   GATReservation_Clone(GATReservation_const object, 
00092     GATReservation *new_object);
00093 
00094 /** int GATReservation_GetType(GATReservation_const file)
00095  *  @brief Return the type of the GATReservation
00096  *
00097  *  The function @c GATReservation_GetType always returns GATType_GATReservation. 
00098  *
00099  *  @param object The object to inspect
00100  *
00101  *  @return returns always @c #GATType_GATReservation.
00102  */
00103 GATType
00104   GATReservation_GetType(GATReservation_const object);
00105 
00106 /** int GATReservation_GetInterface(GATReservation_const table, GATInterface iftype, void const **ifp)
00107  *  @brief Get an interface supported by a GATList
00108  *
00109  *  The function GATReservation_GetInterface allows to get a pointer to an 
00110  *  additional interface supported by this GATList.
00111  *
00112  *  @param object The object to be asked for the new interface.
00113  *  @param iftype The interface the object is to be asked for.
00114  *  @param ifp The pointer, through which the result is to be returned.
00115  *
00116  *  @return An error type.
00117  */
00118 GATResult 
00119   GATReservation_GetInterface(GATReservation_const object, 
00120     GATInterface iftype, void const **ifp);
00121 
00122 /** int GATReservation_Cancel(GATReservation handle)
00123  *  @brief Cancel this reservation
00124  *
00125  *  The function @c GATReservation_Cancel cancels the reservation, which is 
00126  *  associated with the given GATReservation instance
00127  *
00128  *  @param object The reservation to cancel
00129  *
00130  *  @return An error code. 
00131  */
00132 GATResult
00133   GATReservation_Cancel(GATReservation reservation);
00134   
00135 /** int GATReservationCPI_GetResource(GATReservation handle, GATResource_const *resource)
00136  *  @brief Get the associated resource of this reservation.
00137  *
00138  *  The function @c GATReservation_Cancel returns the resource instance, which 
00139  *  is associated with the given GATReservation instance.
00140  *
00141  *  @param object The reservation for which to access the associated resource
00142  *  @param resource The pointer to the variable, where the resulting resource
00143  *        should be returned.
00144  *
00145  *  @return An error code. 
00146  */
00147 GATResult GATReservation_GetResource(GATReservation_const reservation,
00148   GATResource_const *resource);
00149   
00150 #ifdef __cplusplus
00151 } /* extern "C" */
00152 #endif
00153 
00154 #endif /* !defined(_GATRESERVATION_H_) */