mcb.h

Go to the documentation of this file.

/**
 * \file mcb.h <mi32/mcb.h>
 * \brief Include file for Mcb (MicroImages Callback) toolkit
 *
 * \if NODOC
 * $Id: mcb.h_v 1.22 2003/09/15 13:49:56 fileserver!dwilliss Exp $
 *
 * $Log: mcb.h_v $
 * Revision 1.22  2003/09/15 13:49:56  fileserver!dwilliss
 * Doxygen
 *
 * Revision 1.21  2000/08/17 22:34:19  scowan
 * *** empty log message ***
 *
 * Revision 1.20  2000/07/21 14:46:07  mju
 * Put prototypes before McbLIST defns so can inline McbLIST dtor.
 *
 * Revision 1.19  2000/07/21 14:15:13  mju
 * Add McbLIST dtor which removes all callbacks.
 * Exclude internal stuff from Genitor docs.
 *
 * Revision 1.18  2000/06/15 18:30:35  sparsons
 * Genitor revision.
 *
 * Revision 1.17  2000/06/13 20:30:39  sparsons
 * Genitor documentation.
 *
 * Revision 1.16  1999/10/25 13:17:54  mju
 * Add ctors for McbAnyCallbackStruct.
 *
 * Revision 1.15  1999/10/22  15:47:47  mju
 * Add default ctor for McbLIST.
 *
 * Revision 1.8  1998/06/15  20:37:17  mju
 * Add McbAddCallbackExt() and MCB_Priority... definitions.
 *
 * Revision 1.6  1996/12/12  22:20:31  mju
 * Add fields needed to handle callback remove while calling.
 *
 * \endif
**/

#ifndef  INC_MI32_MCB_H
#define  INC_MI32_MCB_H

#ifndef  INC_MI32_STDDEFNS_H
   #include <mi32/stddefns.h>
#endif

#ifdef MIODLL
   #define LIBEXPORT MI_DLLEXPORT
#else
   #define LIBEXPORT MI_DLLIMPORT
#endif

#if defined(__cplusplus)

//! Macros for defining class methods to add Mcb callbacks
#define  MCB_ADD(_clsname)                inline void McbCallbackAdd (McbLIST *list, void (*f)(McbAnyCallbackStruct*,_clsname*), UINT32 flags) const { McbAddCallback(list,reinterpret_cast<McbCallbackFunc>(f),const_cast<_clsname*>(this),(flags)); }
#define  MCB_ADDEX(_clsname,_strname)     inline void McbCallbackAdd (McbLIST *list, void (*f)(_strname*,_clsname*), UINT32 flags) const { McbAddCallback(list,reinterpret_cast<McbCallbackFunc>(f),const_cast<_clsname*>(this),(flags)); }
#define  MCB_REMOVE(_clsname)             inline void McbCallbackRemove (McbLIST *list, void (*f)(McbAnyCallbackStruct*,_clsname*), UINT32 flags) const { McbRemoveCallback(list,reinterpret_cast<McbCallbackFunc>(f),const_cast<_clsname*>(this),(flags)); }
#define  MCB_REMOVEEX(_clsname,_strname)  inline void McbCallbackRemove (McbLIST *list, void (*f)(_strname*,_clsname*), UINT32 flags) const { McbRemoveCallback(list,reinterpret_cast<McbCallbackFunc>(f),const_cast<_clsname*>(this),(flags)); }

extern "C" {
#endif

struct McbAnyCallbackStruct {
   UINT32 reason;
   //! CONSTRUCTION
   McbAnyCallbackStruct () {}          //! Default constructor, performs no initialization
   McbAnyCallbackStruct (              //! Construct with specified reason value
      UINT32 ireason
      ):
      reason(ireason)
      { }
   };

typedef void (*McbCallbackFunc)(McbAnyCallbackStruct*,void*);

struct McbLIST;



#define  MCB_PriorityHigh     -1
#define  MCB_PriorityNormal   0
#define  MCB_PriorityLow      1

//! Add callback to callback list with position determined by priority.
//!
//! If reasonmask is 0 all reasons will be selected.
LIBEXPORT int McbAddCallbackExt (
   McbLIST *cblist,                    //!< Callback list to add to
   McbCallbackFunc cbfunc,             //!< Callback function
   void *cbdata,                       //!< "Hook" data to pass to callback function
   UINT32 reasonmask,                  //!< Programmer-defined reasons for which callback will be called
   INT8 priority                       //!< (MCB_PriorityHigh, MCB_PriorityNormal, MCB_PriorityLow)
   );

//!   Add callback to callback list.
//!
//! This is equivalent to McbAddCallbackExt(cblist, cbfunc, cbdata, reasonmask, MCB_PriorityNormal).
LIBEXPORT int McbAddCallback (
   McbLIST *cblist,                    //!< Callback list to add to
   McbCallbackFunc cbfunc,             //!< Callback function
   void *cbdata,                       //!< "Hook" data to pass to callback function
   UINT32 reasonmask                   //!< Programmer-defined reasons for which callback will be called
   );

//! Call callbacks in list selected by reason.
//!
//! The specified reason will be bitwise-anded with the reasonmask which was specified in
//!   McbAddCallback() to determine if the callback function will actually be called.  You can
//!   use McbAnyCallbackStruct for the structure type if you are only interested in specifying
//!   a callback reason and no additional information.
LIBEXPORT void McbCallCallbacks (
   McbLIST *cblist,                    //!< Callback list
   McbAnyCallbackStruct *cbstruct,     //!< Pointer to callback structure, first entry must be ULONG reason
   UINT32 reason                       //!< Reason, will be ANDed with callback reasonmask
   );

//!   Check to see if callback list has a callback for a given reason.
//!
//! @return True if there is a callback in the callback list which matches the given reason.
LIBEXPORT int McbHasCallbacks (
   McbLIST *cblist,                    //!< Callback list
   UINT32 reason                       //!< Reason, will be ANDed with callback reasonmask
   );

//! Remove all callbacks from list.
LIBEXPORT void McbRemoveAllCallbacks (
   McbLIST *cblist                     //!< Callback list to remove all callbacks from
   );

//! Remove callback from list.
//!
//! If "cbfunc" or "cbdata" are NULL and/or the "reasonmask" is 0 they will not be used to "match"
//!   the callbacks.  For example, McbRemoveCallback(&cblist,NULL,data,0) will remove all callbacks
//!   that reference the specified "data".  This can be useful if that data is about to be freed.
//!   Selected callback "reasons" can be removed without removing the entire callback as well.
//! Callbacks can be removed from the list safely while being called.
LIBEXPORT void McbRemoveCallback (
   McbLIST *cblist,                    //!< Callback list to remove to 
   McbCallbackFunc cbfunc,             //!< Callback function
   void *cbdata,                       //!< "Hook" data specified in McbAddCallback()
   UINT32 reasonmask                   //!< Programmer-defined reasons specified in McbAddCallback()
   );

#if defined(__cplusplus)
}
#endif

#ifndef GENERATING_DOXYGEN_OUTPUT
//! This is internal, so don't documente in Genitor
struct McbREC {
   McbCallbackFunc cbfunc;
   void *cbdata;
   UINT32 ReasonMask;
   INT8 Priority;
   McbREC *next;
   };
#endif //!< GENERATING_DOXYGEN_OUTPUT

//! Callback list.
struct McbLIST {
   // MEMBERS
   #ifndef GENERATING_DOXYGEN_OUTPUT
   //! These members are really internal, so we don't need to document them
   McbREC *first;
   McbREC *last;
   UINT16 callcount;
   UINT16 didremove;
   #endif //!< GENERATING_DOXYGEN_OUTPUT

   // CONSTRUCTION / DESTRUCTION

   McbLIST (
      ):
      first(0),
      last(0),
      callcount(0),
      didremove(0)
      { }

   ~McbLIST (
      ) {
      McbRemoveAllCallbacks(this);
      }
   };

#undef LIBEXPORT

#endif //!<  INC_MI32_MCB_H 

---