GAT Documentation

00001 /** @file GATRequestNotifier.c
00002  *  Source file for the GATRequestNotifier class.
00003  *
00004  *  TODO: Fill in the description of the new GAT object here
00005  *
00006  *  @date Fri Jan 30 2004
00007  *
00008  *  @version $Header: /export/cvs-gridlab/wp-1/Codes/GATEngine/C-reference/src/GATRequestNotifier.c,v 1.6 2004/04/02 12:31: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 static const char *rcsid = "$Header";
00020  
00021 /* System Header objects */
00022 #include <stdlib.h>
00023 #include <string.h>
00024 
00025 /* GAT Header objects */
00026 #include "GAT.h"
00027 #include "GATInternal.h"
00028 #include "GATRequestNotifier.h"
00029 
00030 /* define the vtable types */
00031 GATOBJECT_DEFINE_VTABLE(GATRequestNotifier);
00032 
00033 /* define the converters to/from GATObject */
00034 GATOBJECT_DEFINE_CONVERTERS(GATRequestNotifier)
00035 
00036 /* Macros */
00037 
00038 /* Structures, unions and enums */
00039 struct GATRequestNotifier_S {
00040   /* supported interfaces */
00041   GATRequestNotifier_vtable *GATObject__vtable;
00042 
00043   /* listener to call back during GATRequestNotifier_Respond */
00044   GATRequestNotifierListener listener;
00045   
00046   /* data to be supplied to the GATRequestNotifierListener */
00047   void *adaptor_data;
00048   GATRequestCPI_Instance const *instance_data;
00049   void *context_data;
00050 };
00051 
00052 /* Static function prototypes */
00053 
00054 /* file scope variables */
00055 GATRequestNotifier_vtable GATRequestNotifier__vtable = {
00056   GATRequestNotifier_GetType,
00057   GATRequestNotifier_Destroy,
00058   GATRequestNotifier_Equals,
00059   GATRequestNotifier_Clone,
00060   GATRequestNotifier_GetInterface,
00061   0   /* this is needed for CPI based types only */
00062 };
00063 
00064 /* External functions */
00065 
00066 /** GATRequestNotifier_Create
00067  *  @brief Create a new GATRequestNotifier object
00068  *
00069  *  The function @c GATRequestNotifier_Create creates a new 
00070  *  GATRequestNotifier object
00071  *
00072  *  @param context The GAT context to use while the initialisation of the 
00073  *        new object.
00074  *  @param preferences The preferences to use while selecting the adaptor for 
00075  *        the corresponding CPI.
00076  *
00077  *  @return Returns a handle to the newly created GATRequestNotifier object.
00078  *        Returns 0 (zero) if an error occurs.
00079  */
00080 GATRequestNotifier 
00081 GATRequestNotifier_Create(void *adaptor_data, 
00082   GATRequestCPI_Instance const *instance_data,
00083   GATRequestNotifierListener listener, void *context_data)
00084 {
00085   GATResult err_code = GAT_MEMORYFAILURE;
00086   GATRequestNotifier retval = (GATRequestNotifier) malloc(
00087     sizeof(struct GATRequestNotifier_S));
00088       
00089   if (NULL != retval)
00090   {
00091     memset(retval, 0, sizeof(struct GATRequestNotifier_S));
00092     retval->GATObject__vtable = &GATRequestNotifier__vtable;
00093 
00094     retval->listener = listener;
00095     retval->adaptor_data = adaptor_data;
00096     retval->instance_data = instance_data;
00097     retval->context_data = context_data;
00098     
00099     err_code = GAT_SUCCESS;
00100   }
00101   
00102   /* error handling */
00103   if (GAT_FAILED(err_code))
00104   {
00105     /* FIXME: GATStatus(err_code) */
00106     GATRequestNotifier_Destroy(&retval);
00107   }
00108   return retval;
00109 }
00110 
00111 /** void GATRequestNotifier_Destroy(GATRequestNotifier *resource)
00112  *
00113  *  The function GATRequestNotifier_Destroy is the destructor used to
00114  *  free all the memory allocated by an GATRequestNotifier instance.
00115  *
00116  *  @param description The pointer to the GATRequestNotifier to destroy
00117  */
00118 void
00119 GATRequestNotifier_Destroy(GATRequestNotifier *object)
00120 {
00121   if (NULL != object && NULL != *object)
00122   {
00123     free(*object);
00124     *object = NULL;
00125   }
00126 }
00127 
00128 /** GATRequestNotifier_Equals
00129  *  @brief Compare two GATRequestNotifier objects
00130  *
00131  *  The function @c GATRequestNotifier_Equals compares two objects of the
00132  *  @c GATRequestNotifier type.
00133  *
00134  *  @param lhs The first list to compare
00135  *  @param rhs The second list to compare
00136  *  @param isequal The pointer to the GATBool variable, which should receive 
00137  *        the result if the comparision
00138  *
00139  *  @return An error code.
00140  */
00141 GATResult 
00142 GATRequestNotifier_Equals(GATRequestNotifier_const lhs,
00143   GATRequestNotifier_const rhs, GATBool *isequal)
00144 {
00145   GATResult retval = GAT_INVALID_HANDLE;
00146 
00147   if (NULL != lhs && NULL != rhs)
00148   {
00149     retval = GAT_INVALID_PARAMETER;
00150     if (NULL != isequal)
00151     {
00152       *isequal = GATFalse;    /* request notifiers are never equal */
00153       retval = GAT_SUCCESS;
00154     }
00155   }
00156   return retval;
00157 }
00158 
00159 /** GATRequestNotifier_Clone
00160  *  @brief Clone the given GATRequestNotifier
00161  *
00162  *  The function @c GATRequestNotifier_Clone generates a (deep) copy of 
00163  *  the given GATRequestNotifier. 
00164  *
00165  *  @param description The object to clone
00166  *  @param new_object The pointer, through which the result is to be 
00167  *        returned.
00168  *
00169  *  @return An error type.
00170  */
00171 GATResult 
00172 GATRequestNotifier_Clone(GATRequestNotifier_const handle, 
00173   GATRequestNotifier *new_handle)
00174 {
00175   GATResult retval = GAT_INVALID_HANDLE;
00176   if (NULL != handle)
00177   {
00178     if (NULL == new_handle)
00179     {
00180       retval = GAT_INVALID_PARAMETER;
00181     }
00182     else
00183     {
00184       struct GATRequestNotifier_S const *object = handle;
00185       GATRequestNotifier new_object = 
00186         (GATRequestNotifier) malloc(sizeof(struct GATRequestNotifier_S));
00187       
00188       *new_handle = NULL;
00189       if (NULL == new_object)
00190       {
00191         retval = GAT_MEMORYFAILURE;
00192       }
00193       else
00194       {
00195         memset(new_object, 0, sizeof(struct GATRequestNotifier_S));
00196         new_object->GATObject__vtable = &GATRequestNotifier__vtable;
00197 
00198         new_object->listener = handle->listener;
00199         new_object->adaptor_data = handle->adaptor_data;
00200         new_object->instance_data = handle->instance_data;
00201         new_object->context_data = handle->context_data;
00202       }
00203     }
00204   }
00205   return retval;
00206 }
00207 
00208 /** GATType GATRequestNotifier_GetType(GATRequestNotifier_const resource)
00209  *  @brief Return the type of the GATRequestNotifier
00210  *
00211  *  The function @c GATRequestNotifier_GetType always returns 
00212  *  @c #GATType_GATRequestNotifier. 
00213  *
00214  *  @param object The object to inspect
00215  *
00216  *  @return Returns always @c #GATType_GATRequestNotifier. 
00217  */
00218 GATType
00219 GATRequestNotifier_GetType(GATRequestNotifier_const object)
00220 {
00221   GAT_UNUSED_PARAMETER(object);
00222   return GATType_GATRequestNotifier;
00223 }
00224 
00225 /** GATResult GATRequestNotifier_GetInterface(GATRequestNotifier_const file, GATInterface iftype, void const **ifp)
00226  *  @brief Get an interface supported by a GATObject
00227  *
00228  *  The function GATRequestNotifier_GetInterface allows to get a pointer to an 
00229  *  additional interface supported by this GATRequestNotifier.
00230  *
00231  *  @param object The object to be asked for the new interface.
00232  *  @param iftype The interface the object is to be asked for.
00233  *  @param ifp The pointer, through which the result is to be returned.
00234  *
00235  *  @return An error type.
00236  */
00237 GATResult 
00238 GATRequestNotifier_GetInterface(GATRequestNotifier_const object, GATInterface iftype, 
00239   void const **ifp)
00240 {
00241   GATResult retval = GAT_INVALID_PARAMETER;
00242 
00243   if (NULL != ifp)
00244   {
00245     *ifp = NULL;
00246     {
00247       retval = GAT_NO_INTERFACE;
00248     }
00249   }
00250   return retval;
00251 }
00252 
00253 /** GATRequestNotifier_Respond
00254  *  
00255  *  The function GATRequestNotifier_Respond finalises a GATRequest, passing any 
00256  *  response information back to the invoker.
00257  *
00258  *  @param notifier The request notifier associated with the request object to 
00259  *        finalize.
00260  *  @param table Return Data containing any response data.
00261  *
00262  *  @return An error code.
00263  */
00264 GATResult
00265 GATRequestNotifier_Respond(GATRequestNotifier_const notifier, GATTable table)
00266 {
00267   GATResult retval = GAT_INVALID_HANDLE;
00268   if (NULL != notifier)
00269   {
00270     retval = notifier->listener(notifier->adaptor_data, 
00271       notifier->instance_data, table, notifier->context_data);
00272   }
00273   return retval;
00274 }  
00275 
00276 /* Local functions */
00277 
00278 
00279