Handling Node Events

In order to catch important events related to a node, it is necessary to check for such events on a regular basis. Among these events are notifications about the status of remote counterpart nodes. An authority node on the server will get informed when it has been successfully announced to a client while a proxy node on a client will get informed when it's authority node on the server has been deleted. In addition to that, custom application data can be sent and received through this event system.

Example Implementation

Here we add a new method to class GameObject. processNodeEvents() will fetch all currently waiting events from the object's node, and process the only event currently interesting to us: eZCom_EventRemoved. This event will be generated automatically on a client node when it's server node has been deleted, removed or disconnected.

class GameObject
{
protected:
  ZCom_Node*          m_node;
  // this is new
  bool                m_deleteme;
public:
  GameObject();
  virtual ~GameObject();
  
  // this is new
  void processNodeEvents();
};

void GameObject::processNodeEvents()
{
  // checkEventWaiting() returns true whenever there is a waiting event in the node
  while (m_node->checkEventWaiting()) 
  {
    eZCom_Event       type;            // event type
    eZCom_NodeRole    remote_role;     // role of remote sender
    ZCom_ConnID       conn_id;         // connection id of sender

    // get next waiting event
    ZCom_BitStream *data = m_node->getNextEvent(&type, &remote_role, &conn_id);

    // the server object has been deleted on the server, we should delete it here, too
    if (remote_role == eZCom_RoleAuthority && type == eZCom_EventRemoved)
      m_deleteme = true;
  }
}

checkEventWaiting() returns true whenever there is a waiting event in the node. The waiting event is then fetched with a call to getNextEvent(). This method returns the event data as bitstream pointer, and the event meta information (event id, role of event sender, connection id of event sender) through pointer-parameters. If getNextEvent(NULL, NULL, NULL) is called, the only thing you get is the event data itself. The contents of the data stream depends on the event type though, so it is always necessary to get at least the event type (i.e. the first parameter to getNextEvent() should not be NULL)).

Handling Deannouncements

The event handled in the above code is received on client nodes when the counterpart server node has been deleted. This actually is the deannouncement mentioned earlier. Of course, you shouldn't delete the object right away with a 'delete this;' statement. Instead, we add a flag 'm_deleteme' to the GameObject which indicates to a possible object handler that the object is garbage. Cleanup can then be done at a proper time.

Same Event Handler Code For Server and Client

Implementing one event handler for each side (client and server) or using the same code to handle events on both sides is up to you. If there are only minimal differences in server and client event handling code, these differences can be included in a one-size-fits-all handler.

ZCom_Node::getRole() allows you to find out on which side of the fence the code is executed. When it returns eZCom_RoleAuthority then the node is on the server, while eZCom_RoleProxy and eZCom_RoleOwner implicate that the current node is on the client. So if you want to avoid having two different event handlers for server and client just do something like this:

// pseudocode
void processNodeEvents()
{
  while (node->checkEventWaiting())
  {
    data, type = node->getNextEvent();
    if (type == something that appears on both client and server) 
    {
      // check if we are server
      if (node->getRole() == eZCom_RoleAuthority) 
      {
        // do server stuff with the event
      } else
      {
        // do client stuff with the event
      }
    }
  }
}

Event Handling Through Callbacks

If you do not like to constantly poll for events, there is also the possibility to handle some or all node events through callbacks similar to the event handling in ZCom_Control. Read about this here: Event Interception

1.4.6-NO