The Announcement

• Introduction
• Classes And Class IDs
• Adding The Nodes
• Entering Zoidmode
• The Announcement
• Handling Node Events
• Deleting The Server Nodes
• Extended Object Information
• Replication Summary

The Announcement

An announcement occurs, when the server replicates an object to a client. These announcements are handled in different ways depending on the replicated node's replication mode.

• With unique replication, the client counterpart node and it's object are expected to be registered on the client already when the annoucement arrives. No additional action needs to be performed by the application.

• Announcements of dynamically replicated nodes need to be handled by the application as soon as they arrive. They generate the callback ZCom_cbNodeRequest_Dynamic() in ZCom_Control. The name says everything, the callback requests the creation of a node. It has to be implemented just like the other callbacks in the Client and Server sections(The Server, The Client). If a dynamic node is requested but the callback does not create that node, the connection will fail.

• Tagmode replicated nodes can generate a callback, too, but only if the requested node is not registered before the announcement arrives. The callback for these nodes is ZCom_cbNodeRequest_Tag().

Callback Prototype

We are going to extend the client class from earlier. As you know, many callbacks were left unimplemented there, and here one of these callbacks will get an implementation. Announcements of dynamic nodes can be handled properly as soon as we implemented it.

This is the prototype of the method:

class Client : public ZCom_Control {
  void 
    ZCom_cbNodeRequest_Dynamic( ZCom_ConnID _id, ZCom_ClassID _requested_class, ZCom_BitStream *_announcedata,
                                eZCom_NodeRole _role, ZCom_NodeID _net_id ) 
    {
    }

  // all other callback methods omitted here
};

The parameters to the callback give information about the connection id from which the announcement came (typically always the same id, since there seldomly are connections to several servers at once), the class id, the role which the new node will possess (either eZCom_RoleProxy or eZCom_RoleOwner), the new node's network id and a custom bitstream that can be attached when the node is registered on the server.

Example Callback Implementation

The most important information is the _requested_class parameter. This equals one of the class ids we got by calling ZCom_registerClass() before. We are expected to create one instance of the requested class, so building on top of the Rock and Tree code again, here goes a simple implementation:

void Client::ZCom_cbNodeRequest_Dynamic( 
                   ZCom_ConnID _id, ZCom_ClassID _requested_class, ZCom_BitStream *_announcedata,
                   eZCom_NodeRole _role, ZCom_NodeID _net_id ) 
{
  if (_requested_class == Tree::getClassID()) 
    // create tree and register it with the client, i.e. 'this'
    Tree* tree = new Tree(this);
  else
  if (_requested_class == Rock::getClassID()) 
    // create rock and register it with the client, i.e. 'this'
    Rock* rock = new Rock(this);
};

That handles the creation of requested Rocks and Trees. Whenever the server creates one of these and thinks the client should have it, this callback is called, asking the client to create the object and register it's node.

---