Introduction Manual Class Reference Header Reference

Event Interception

Event Interception

Zoidcom provides an event interception interface, allowing you to tranparently monitor node events. The interface is an abstract class filled with pure virtual methods, one method for each type of event. The application has to derive from this class, implement the virtual methods and register an object of the derived class with the node it needs to monitor. This is very similar to how connection handling in ZCom_Control works. Through this interface the application can get notified about incoming node events before the node will receive them. It is also possible to prevent the node from receiving specific events.

Use cases:

Interface

The interface class is ZCom_NodeEventInterceptor. As with ZCom_Control, the first step is to derive from it and copy the empty callback block from zoidcom_node_interceptors.h into the derived class.

class EventCounter : ZCom_NodeEventInterceptor
{
  bool recUserEvent(ZCom_Node *_node, ZCom_ConnID _from, 
                    eZCom_NodeRole _remoterole, ZCom_BitStream &_data, 
                    zU32 _estimated_time_sent) {return true;}
                              
  bool recInit(ZCom_Node *_node, ZCom_ConnID _from,
               eZCom_NodeRole _remoterole) {return true;}
                    
  bool recSyncRequest(ZCom_Node *_node, ZCom_ConnID _from, 
                      eZCom_NodeRole _remoterole) {return true;}
                                  
  bool recRemoved(ZCom_Node *_node, ZCom_ConnID _from,
                  eZCom_NodeRole _remoterole) {return true;}
                            
  bool recFileIncoming(ZCom_Node *_node, ZCom_ConnID _from,
                       eZCom_NodeRole _remoterole, ZCom_FileTransID _fid, 
                       ZCom_BitStream &_request) {return true;}
                                 
  bool recFileData(ZCom_Node *_node, ZCom_ConnID _from,
                   eZCom_NodeRole _remoterole, ZCom_FileTransID _fid) 
                   {return true;}
                         
  bool recFileAborted(ZCom_Node *_node, ZCom_ConnID _from,
                      eZCom_NodeRole _remoterole, ZCom_FileTransID _fid) {return true;}
                               
  bool recFileComplete(ZCom_Node *_node, ZCom_ConnID _from,
                       eZCom_NodeRole _remoterole, ZCom_FileTransID _fid) {return true;}
};

Et voila, the interceptor is ready, and doesn't do anything. Note that all methods now return true. This means, that all events are let through. Returning false would drop the event in question and the nodes would never receive it.

Each of these methods corresponds to one type in the enum eZCom_Event.

If we wanted to count all eZCom_EventUser events, we would replace the default recUserEvent() with this implementation:

class EventCounter : ZCom_NodeEventInterceptor
{
public:
  // event counter
  int counter;
  
  // constructor initializing the counter
  EventCounter() { counter = 0; }
  
  bool recUserEvent(ZCom_Node *_node, ZCom_ConnID _from, 
                    eZCom_NodeRole _remoterole, ZCom_BitStream &_data, 
                    zU32 _estimated_time_sent) 
 {
   counter++;
   return true;
 }
 
 // other callback methods omitted here
};

Note:
As in ZCom_Control, it is necessary to actually implement all the callbacks with at least the provided default implementation.

Registration

In order to enable the interceptor, we need to register it with the target node:

EventCounter *evecounter = new EventCounter();
node->setEventInterceptor(evecounter);

To unregister it at a later time, do

node->setEventInterceptor(NULL);

Attention:
Don't delete the evecounter object as long as it is registered with a node.
It is perfectly possible to register the same interceptor with several nodes at the same time. All callback methods in the interceptor will deliver a pointer to the event's target node, so it is possible to distinguish them.

Usage As Poll Replacement

As mentioned above, event interceptors can be used to replace the need for event polling. If this is desired, all callback methods should be changed to return 'false'. When this is done, the interceptor will receive all events, but the event polling queue won't receive anything at all. It is then safe to remove the checkEventWaiting() / getNextEvent() code from the nodes. If callbacks do not return 'false', and the events are not polled, they will accumulate in the node until it is deleted.
This file is part of the documentation for Zoidcom. Documentation copyright © 2004-2008 by Jörg Rüppel. Generated on Sat Aug 16 15:26:51 2008 for Zoidcom by doxygen 1.4.6-NO