Replication Interceptors

• Introduction
• Replicator Usage
• Replication Interceptors
• Custom Replicators

Introduction

Allowing Zoidcom to automatically and transparently update your object's data over a network connection is, without doubt, a convenient feature. However, sometimes an application just needs to know what is sent to whom and when, and, also important, what is received by whom and when. This is where replication interceptors come in handy. With them, it is possible to get notified about updates to a certain object or even updates to a single replicator. They tell you when some data of your object is going to be replaced with a new value, and what that value is. They tell you, how much bandwidth has been used to update that object and on top of that, you can totally prevent an update from happening entirely. They do not remind you of birthdays however.

Now this is what they can do, but what are they good for? A few things come to mind:

• debugging objects
• error detection
• cheat detection and prevention
• monitoring bandwidth usage of single objects
• updating other data depending on the replicated values

Usage

Interceptors are interfaces the user has to implement. Derive a class from ZCom_NodeReplicationInterceptor and copy the callback block from the commented section in zoidcom_node_interceptors.h into your derived class. Then implement the callbacks you are interested in - for an overview of what can be intercepted have a look at the documentation of the interceptor interface.

class MyInterceptor : public ZCom_NodeReplicationInterceptor
{
    void outPreReplicateNode(ZCom_Node *_node, ZCom_ConnID _to, 
                             eZCom_NodeRole _remote_role) {}
    void outPreDereplicateNode(ZCom_Node *_node, ZCom_ConnID _to, 
                               eZCom_NodeRole _remote_role) {}
    bool outPreUpdate(ZCom_Node *_node, ZCom_ConnID _to, 
                      eZCom_NodeRole _remote_role) { return true; }
    bool outPreUpdateItem(ZCom_Node *_node, ZCom_ConnID _to, 
                          eZCom_NodeRole _remote_role, 
                          ZCom_Replicator *_replicator) { return true; }
    void outPostUpdate(ZCom_Node *_node, ZCom_ConnID _to, 
                       eZCom_NodeRole _remote_role, zU32 _rep_bits, 
                       zU32 _event_bits, zU32 _meta_bits) {}
    bool inPreUpdate(ZCom_Node *_node, ZCom_ConnID _from, 
                     eZCom_NodeRole _remote_role) { return true; }
    bool inPreUpdateItem(ZCom_Node *_node, ZCom_ConnID _from, 
                         eZCom_NodeRole _remote_role, ZCom_Replicator *_replicator, 
                         zU32 _estimated_time_sent) { return true; }
    void inPostUpdate(ZCom_Node *_node, ZCom_ConnID _from, eZCom_NodeRole _remote_role, 
                      zU32 _rep_bits, zU32 _event_bits, zU32 _meta_bits) {}
};

I won't describe the semantics of all the callbacks here now, you can easily read that up here: ZCom_NodeReplicationInterceptor. Just let me explain the common parameters:

• The _node parameter holds a pointer to the node which generated the callback in the first place. That way, you can register one interceptor object with several different nodes.
• The second parameter always contains a connection ID. For all out* callbacks, this tells you to which connected client the update will get sent, and for the in* callbacks, where the update came from.
• Some of the callbacks expect you to return true or false. This allows you to prevent data from being sent (in the out* callbacks) or from getting applied (in the in* callbacks). When 'false' is returned, the update will be dropped.

The two *PreUpdateItem() callbacks give you detailed information about single replicators sending or receiving updates. They do not get called by default, however. To activate them, you have to give an additional flag to the replicator during registration. This flag is ZCOM_REPFLAG_INTERCEPT and should be ORed (|) together with any other flag you might find useful for that replicator. The most important piece of information is the pointer to the source/target replicator. Issueing a _replicator->getPeekData() call will peek into the update and return the data to the interceptor.

After deriving your class and creating an object from it, you can register the interceptor object with any node you wish through ZCom_Node::setReplicationInterceptor. From then on, the in* callbacks get called from within ZCom_processInput(), while the out* callbacks will get called from ZCom_processOutput() respectively.

---