gml_Callback.h

Go to the documentation of this file.
00001 /** @file gml_Callback.h
00002  * 
00003  *     Management of callback functions and lists of callback functions.
00004  * 
00005  *   Copyright (c) 2004 CLIPS-IMAG
00006  * 
00007  *   See the file "gml_LicenseTerms.txt" for information on usage and redistribution
00008  *   of this file, and for a DISCLAIMER OF ALL WARRANTIES.
00009  * 
00010  *   Created on August 12, 2004 (FB).
00011  */
00012 
00013 
00014 #ifndef __GML_CALLBACK__
00015 #define __GML_CALLBACK__
00016 
00017 #include "gml/base/gml_Errors.h"
00018 #include "gml/base/gml_List.h"
00019 
00020 
00021 /// gml_TCallback --
00022 ///
00023 ///  A general type for a "Callback" function pointer.
00024 ///
00025 ///  Addresses of function of this type are registered to some event, then called
00026 ///  asynchronously.
00027 
00028 typedef void (*gml_TCallback) (gml_TError err, gml_TPointer userData);
00029 
00030 
00031 
00032 /// gml_TCallbackDescr --
00033 ///
00034 ///  A structure that stores a callback and its userdata.
00035 
00036 struct gml_TCallbackDescr {
00037 
00038   gml_TCallback         fCallback;
00039   gml_TPointer          fUserData;
00040 
00041 };
00042 
00043 
00044 
00045 /// gml_TCallbackList --
00046 ///
00047 ///  A list of callback functions. Can invoke all functions in the list.
00048 
00049 class gml_TCallbackList {
00050 public:
00051 
00052   /// Init --
00053   ///
00054   ///   Initializes the list to an empty state.
00055 
00056   gml_TError          Init ();
00057 
00058   /// Dispose --
00059   ///
00060   ///   Releases all the resources of the callback list.
00061 
00062   void                Dispose ();
00063 
00064   /// RegisterCallback --
00065   ///
00066   ///   Registers the function <callback> so that it will be called when the
00067   ///   "Invoke" method is called on this object. <callback> will receive
00068   ///   <userData> as its second parameter (the first parameter being the error
00069   ///   code).
00070 
00071   gml_TError          RegisterCallback   (gml_TCallback     callback,
00072                                           gml_TPointer      userData);
00073 
00074   /// DeregisterCallback --
00075   ///
00076   ///   De-registers the function <callback> if it was registered with a
00077   ///   userData parameter equal tu <userData>. If no such <callback> <userData>
00078   ///   couple exist in the list, does nothing. If more than one such couple
00079   ///   exist in the list, only the first one is removed.
00080 
00081   void                DeregisterCallback (gml_TCallback     callback,
00082                                           gml_TPointer      userData);
00083 
00084   /// Invoke --
00085   ///
00086   ///   Calls all the registered callback, passing the the errorcode <err> and their
00087   ///   userData as parameters.
00088 
00089   void                Invoke (gml_TError err = gml_cNoError);
00090   
00091   /// Count --
00092   ///
00093   ///   Return the current list length.
00094   
00095   UInt32              Count () { return fNbCallbacks; }
00096 
00097 private:
00098   UInt32              fNbCallbacks;     ///< the current total number of callbacks registered
00099   gml_TList*          fList;            ///< The list of gml_TCallbackDescr
00100 };
00101 
00102 
00103 
00104 #endif