Introduction Manual Class Reference Header Reference

ZCom_Node Class Reference

List of all members.

Detailed Description

ZCom_Node represents one networkable object.

Each ZCom_Node represents one object in the network. There are several types of them:

Once nodes are linked up with their counterparts, they can send events back and forth as much as have their data synchronized and interpolated.

ZCom_Nodes appear in three roles (eZCom_NodeRole):


Event replication and file transfers

void acceptFile (ZCom_ConnID _src_id, ZCom_FileTransID _ftrans_id, const char *_path, bool _accept)
 Accept or deny an incoming file.
bool checkEventWaiting () const
 Check for new events.
const ZCom_FileTransInfogetFileInfo (ZCom_ConnID _conn_id, ZCom_FileTransID _ftrans_id) const
 Get data for a file transfer.
ZCom_BitStreamgetNextEvent (eZCom_Event *_type, eZCom_NodeRole *_remote_role, ZCom_ConnID *_connid, zU32 *_estimated_time_sent=NULL)
 Get the next event.
bool sendEvent (eZCom_SendMode _mode, zU8 _rules, ZCom_BitStream *_data)
 Send an event to the peers selected with _rules: Replication Rules.
bool sendEventDirect (eZCom_SendMode _mode, ZCom_BitStream *_data, ZCom_ConnID _destconn)
 Send an event to a connected node on a specific connection only (needed for initializing and syncing, see eZCom_Event).
bool sendEventToGroup (eZCom_SendMode _mode, ZCom_BitStream *_data, ZCom_GroupID _destgroup)
 Send an event to connected nodes on a group of connections.
ZCom_FileTransID sendFile (const char *_path, const char *_pathtosend, ZCom_ConnID _destconn, ZCom_BitStream *_data, zFloat _aggressivenes)
 Send a file to a specific connection.
void setEventInterceptor (ZCom_NodeEventInterceptor *_interceptor)
 Set event interceptor for this node.
void setEventNotification (bool _oninit, bool _onremove)
 Toggle connect/remove notification.

Data replication setup

Setup the data replication rules. They have to be exactly the same for all nodes of the same class on all systems.



void addInterpolationFloat (zFloat *_ptr, zU8 _mantissa_bits, zU8 _flags, zU8 _rules, zFloat _treshold, zFloat *_dst=NULL, zS16 _mindelay=-1, zS16 _maxdelay=-1, zFloat _ipolfac=0.4f)
 Add a float to the data replication and ask Zoidcom to interpolate it.
void addInterpolationInt (zS32 *_ptr, zU8 _bits, bool _sign, zU8 _flags, zU8 _rules, zS32 _treshold, zS32 *_dst=NULL, zS16 _mindelay=-1, zS16 _maxdelay=-1, zFloat _ipolfac=0.4f)
 Add an int to the data replication and ask Zoidcom to interpolate it.
void addReplicationBool (bool *_ptr, zU8 _flags, zU8 _rules, zS16 _mindelay=-1, zS16 _maxdelay=-1)
 Add a bool to the data replication.
void addReplicationFloat (zFloat *_ptr, zU8 _mantissa_bits, zU8 _flags, zU8 _rules, zS16 _mindelay=-1, zS16 _maxdelay=-1)
 Add a float to the data replication.
void addReplicationInt (zS32 *_ptr, zU8 _bits, bool _sign, zU8 _flags, zU8 _rules, zS16 _mindelay=-1, zS16 _maxdelay=-1)
 Add an int to the data replication.
void addReplicationString (char *_str, zU16 _maxlen, zU8 _flags, zU8 _rules, zS16 _mindelay=-1, zS16 _maxdelay=-1)
 Add a string to the data replication.
void addReplicationStringW (wchar_t *_str, zU16 _maxlen, zU8 _flags, zU8 _rules, zS16 _mindelay=-1, zS16 _maxdelay=-1)
 Add a string to the data replication.
void addReplicator (ZCom_Replicator *_rep, bool _autodelete)
 Add replicator object.
bool beginReplicationSetup (zU16 _replicators_max)
 Enclose all data replication setup functions with this and endReplicationSetup().
bool endReplicationSetup (void)
 End replication setup.
void setInterceptID (ZCom_InterceptID _id)
 Set intercept ID for all forthcoming replication registrations which have ZCOM_REPFLAG_INTERCEPT set.
void setReplicationInterceptor (ZCom_NodeReplicationInterceptor *_interceptor)
 Set replication interceptor for this node.

Node parameters

void applyForZoidLevel (zU8 _level)
 Add node to Zoidlevel. (Allowed on: Authority).
void dependsOn (ZCom_Node *_othernode, eZCom_DependencyOpt _opt=eZCom_AddDependency)
 Force replication order of nodes by making this dependent on _othernode. _othernode is replicated first. (Allowed on: Authority).
zU32 getRelevantConnectionCount () const
 Find out how many connections are relevant for this node. (Allowed on: Authority, Owner, Proxy).
zS32 getRelevantConnections (ZCom_ConnID *_conns, zU32 _max, zU32 *_count) const
 Find out which connections are relevant for this node. (Allowed on: Authority, Owner, Proxy).
zU8 getZoidLevel (zU32 _index) const
 Get one of the nodes Zoidlevels.
zU32 getZoidLevelCount () const
 Get amount of Zoidlevels this node is registered in.
void removeFromZoidLevel (zU8 _level)
 Remove node from Zoidlevel. (Allowed on: Authority).
void setAnnounceData (ZCom_BitStream *_data)
void setConnectionSpecificRelevance (ZCom_ConnID _conn, zFloat _rel)
 Set current relevance of this node to a specific connection. (Allowed on: Authority).
void setDefaultRelevance (zFloat _default_relevance)
 Set default relevance of this node to all connections. (Allowed on: Authority).
void setMustSync (bool _enabled, zU16 _order)
 Force this node to successfully sync during Zoidlevel transition. (Allowed on: Authority).
void setOwner (ZCom_ConnID _id, bool _enabled)
 Give owner-status to proxy nodes on clients. (Allowed on: Authority).
void setPrivate (bool _enabled)
 Make node private. (Allowed on: Authority).
void setSyncResult (ZCom_ConnID _conn, bool _success, ZCom_BitStream *_errormsg)
 Report sync result to Zoidcom. (Allowed on: Authority).
void setSyncResultAutoSuccess (bool _enabled)
 Tell node to automatically report all sync requests as successful. (Allowed on: Authority).
void setUpdatePriority (zU16 _prio)
 Set relative object priority. (Allowed on: Authority, Owner, Proxy).

Node registration

Register your node with the system, the needed ZCom_ClassID is the result of a call to ZCom_Control::ZCom_registerClass().

Attention:
Don't use the ZCom_ClassIDs in your network communication yourself, client and server may use completely different IDs for the same class. They are translated by Zoidcom automatically but obviously Zoidcom is unable to do that if the IDs are embedded in your custom data.


void disconnectAll ()
 Unlink nodes from all peers.
bool registerNodeByTag (ZCom_ClassID _classid, zU32 _tag, eZCom_NodeRole _role, ZCom_Control *_control)
 Register a tagnode, initially or on request.
bool registerNodeDynamic (ZCom_ClassID _classid, ZCom_Control *_control)
 Register an authoritative dynamic node.
bool registerNodeUnique (ZCom_ClassID _classid, eZCom_NodeRole _role, ZCom_Control *_control)
 Register a unique node.
bool registerRequestedNode (ZCom_ClassID _classid, ZCom_Control *_control)
 Register a requested dynamic node.
bool unregisterNode ()
 Unregister the node from ZCom_Control.

Misc.

ZCom_ClassID getClassID () const
 Get node's class ID.
ZCom_ControlgetControl () const
 Get the ZCom_Control this node is registered with.
zU32 getCurrentUpdateRate () const
 Get packet rate of source connection.
zS32 getEstimatedTimeUntilPossibleUpdate () const
 Get estimated time in msecs until next possible update arrives.
ZCom_NodeID getNetworkID () const
 Retrieve the node's network ID.
eZCom_NodeRole getRole () const
 Get role of this node.
zS32 getUpdateDelta () const
 Get time in msecs since last received update packet.
bool isPrivate () const
 Find out if node is in private mode.

User data

void * getUserData () const
 Retrieve global user data pointer.
void * getUserData (ZCom_ConnID _conn) const
 Retrieve user data.
void setUserData (void *_data)
 Set global user data pointer.
bool setUserData (ZCom_ConnID _conn, void *_data)
 Set user data pointer per relevant connection.


Member Function Documentation

bool ZCom_Node::registerNodeUnique ZCom_ClassID  _classid,
eZCom_NodeRole  _role,
ZCom_Control _control
 

Register a unique node.

Parameters:
_classid This node's class.
_role The role the node should have here.
_control The ZCom_Control you want the node to register with.
Returns:
'true' if everything went fine.

bool ZCom_Node::registerNodeByTag ZCom_ClassID  _classid,
zU32  _tag,
eZCom_NodeRole  _role,
ZCom_Control _control
 

Register a tagnode, initially or on request.

Parameters:
_classid This node's class.
_tag The tag you designated for this node.
_role The role the node should have here.
_control The ZCom_Control you want the node to register with.
Returns:
'true' if everything went fine.
If, for some reason, the server registers a tagnode and cannot find it on the client, the callback ZCom_Control::ZCom_cbNodeRequest_Tag() will be called on client. From within this callback, the corresponding tagnode has to be created and registered with registerNodeByTag().

bool ZCom_Node::registerNodeDynamic ZCom_ClassID  _classid,
ZCom_Control _control
 

Register an authoritative dynamic node.

Parameters:
_classid This node's class.
_control The ZCom_Control you want the node to register with.
Returns:
'true' if everything went fine.
The node's role will be eZCom_RoleProxy if the node is created inside ZCom_Control::ZCom_cbNodeRequest_Dynamic(), eZCom_RoleAuthority otherwise.

bool ZCom_Node::registerRequestedNode ZCom_ClassID  _classid,
ZCom_Control _control
 

Register a requested dynamic node.

Parameters:
_classid This node's class.
_control The ZCom_Control you want the node to register with.
Returns:
'true' if everything went fine.
The callback ZCom_Control::ZCom_cbNodeRequest_Dynamic() has been called and now a dynamic node is expected to be created on the client. Once the new node is created and setup, it has to be registered with this call from within the callback.

The node's role will be eZCom_RoleProxy if the node is created inside ZCom_Control::ZCom_cbNodeRequest_Dynamic(), eZCom_RoleAuthority otherwise.

Deprecated:
Use registerNodeDynamic() instead.

bool ZCom_Node::unregisterNode  ) 
 

Unregister the node from ZCom_Control.

Returns:
'true' if no errors occurred.
This will free all links of this node into the zoidcom library, you can delete it, copy it, or put it into an object pool for later use.

All node options, setups, replicators etc are lost. Actually, you can just as well delete the node and create a new one. Using unregisterNode() will just spare you one memory allocation.

Calls disconnectAll().

void ZCom_Node::disconnectAll  ) 
 

Unlink nodes from all peers.

Use this if the node is going to be deleted soon, the earlier this is called, the earlier peers will get notified about the removal and can react accordingly. You can also just delete this instead, if you don't need it any longer.

void ZCom_Node::setUpdatePriority zU16  _prio  ) 
 

Set relative object priority. (Allowed on: Authority, Owner, Proxy).

Parameters:
_prio The new priority.
Setting object priorities influences how often Zoidcom will send updates for this object to peers and how soon events will be sent.

void ZCom_Node::setDefaultRelevance zFloat  _default_relevance  ) 
 

Set default relevance of this node to all connections. (Allowed on: Authority).

Parameters:
_default_relevance The relevance factor from 0.0 (don't replicate) - 1.0 (full relevance)
The default relevance can be overriden with setConnectionSpecificRelevance.

Attention:
This should be called before registering the node, otherwise it will only apply to new connections.

void ZCom_Node::setConnectionSpecificRelevance ZCom_ConnID  _conn,
zFloat  _rel
 

Set current relevance of this node to a specific connection. (Allowed on: Authority).

Parameters:
_conn The connection the new relevance is meant for.
_rel The relevance factor from 0.0 - 1.0.
Set current relevance for this connection ( 0.0 - 1.0 ), which is multiplied with the update-priority. This will influence the frequency, with which the node is updated for the specified connection.

See also: getRelevantConnectionCount(), getRelevantConnections()

zU32 ZCom_Node::getRelevantConnectionCount  )  const
 

Find out how many connections are relevant for this node. (Allowed on: Authority, Owner, Proxy).

Returns:
Amount of connections currently linked to this node.

zS32 ZCom_Node::getRelevantConnections ZCom_ConnID _conns,
zU32  _max,
zU32 _count
const
 

Find out which connections are relevant for this node. (Allowed on: Authority, Owner, Proxy).

Parameters:
_conns A ptr to an array of ZCom_ConnIDs.
_max Size of that array.
_count Ptr to an int which will contain the number of valid IDs in the array afterwards.
This gives you an array with IDs of all connections which are interested in updates of this node.

Returns:
  • 1 if everything went ok
  • 0 if there was an error ( like the array being NULL )
  • -1 the array was too small to hold all connections
See also: getRelevantConnectionCount(), setConnectionSpecificRelevance()

void ZCom_Node::dependsOn ZCom_Node _othernode,
eZCom_DependencyOpt  _opt = eZCom_AddDependency
 

Force replication order of nodes by making this dependent on _othernode. _othernode is replicated first. (Allowed on: Authority).

Parameters:
_othernode The node that shall be replicated before this node.
_opt Whether to add or remove the dependency.
This method should be called on authority nodes only.

This will force _othernode to be replicated before this node whenever both nodes need to be replicated to a connection. It will show no effect if one of the nodes can't be replicated (because it is private or the relevance is 0) or if one of the nodes is replicated while the other is not.

Don't make cyclic dependencies. Don't add the same dependency multiple times. (The debug version of Zoidcom will check for latter case).

void ZCom_Node::applyForZoidLevel zU8  _level  ) 
 

Add node to Zoidlevel. (Allowed on: Authority).

Parameters:
_level The level.
This method should be called on authority nodes only.

You can manually switch connections to different Zoidlevels, only nodes which have applied for a specific level will be synced while the connection is in this level. All nodes are in ZoidLevel 1 by default.

void ZCom_Node::removeFromZoidLevel zU8  _level  ) 
 

Remove node from Zoidlevel. (Allowed on: Authority).

Parameters:
_level The level.
This method should be called on authority nodes only.

See also: applyForZoidlevel().

zU32 ZCom_Node::getZoidLevelCount  )  const
 

Get amount of Zoidlevels this node is registered in.

Returns:
Amount of Zoidlevels.
Only relevant on authority nodes.

zU8 ZCom_Node::getZoidLevel zU32  _index  )  const
 

Get one of the nodes Zoidlevels.

Parameters:
_index Must be in range 0 <= _index < getZoidLevelCount()
Returns:
One of the node's levels. 0 = invalid.
Use this in conjunction with getZoidLevelCount to enumerate the node's levels.

void ZCom_Node::setMustSync bool  _enabled,
zU16  _order
 

Force this node to successfully sync during Zoidlevel transition. (Allowed on: Authority).

Parameters:
_enabled 'true' if node must sync, 'false' otherwise.
_order sync order relative to other mustsync nodes.
When a connection starts the transition to a Zoidlevel, the first thing it does is replicate and connect all nodes in the new Zoidlevel, which have the mustsync flag set. They are processed in an order which is the result of sorting all mustsync nodes by the _order param. If >1 nodes have the same order, their sync process gets started simultaneously.

If any of the mustsync nodes reports failure, the whole Zoidlevel transition fails for the connection in question.

This is only relevant for nodes in existence _before_ the connection changes to the node's Zoidlevel. Nodes created when a connection is already in the respective Zoidlevel will be handled like normal, mustsync=false nodes.

All other nodes ( which don't have MustSync=true ) are synced after all MustSync-nodes have synced.

UseCase:

Client joins server. There is a ResourceControl class with it's affiliated node. This node has MustSync=true with a unique _order=1, so it will be synced before anything else. The node will communicate with it's newly connected peer about the files present on the client's system. The client is missing a file.

  • Case 1(File download enabled on server): The ResourceControl will transmit the missing file, and give the OK to Zoidcom. The node has synced successfully and the following nodes will now attempt to sync.

  • Case 2(File download disabled on server): The ResourceControl will tell Zoidcom that the Node failed to sync, the Zoidlevel transition is canceled, an error message is sent to the client. The client falls back to it's previous zoidlevel.

See also: setSyncResult(), setSyncResultAutoSuccess()

void ZCom_Node::setSyncResult ZCom_ConnID  _conn,
bool  _success,
ZCom_BitStream _errormsg
 

Report sync result to Zoidcom. (Allowed on: Authority).

Parameters:
_conn The connection which is waiting for a result.
_success 'true' to report success, 'false' to report failure.
_errormsg Pass additional failure information in this bitstream. The bitstream will be taken over by Zoidcom, so there is no need to delete it manually.
This must be called when mustsync is true, when either the node synced successfully on the connection or not. If the sync failed for the connection, you can provide a ZCom_BitStream which will be sent to the client, and given to the callback ZCom_Control::ZCom_cbZoidResult().

Attention:
If you have a mustsync node, and forget to call this method for this node, the Zoidmode transition will last forever!
See also: setMustSync(), setSyncResultAutoSuccess()

void ZCom_Node::setSyncResultAutoSuccess bool  _enabled  ) 
 

Tell node to automatically report all sync requests as successful. (Allowed on: Authority).

Parameters:
_enabled True to enable this behavior.
Enable this to automatically set the sync result to true as soon as the request to sync is generated, the node won't receive the request anymore. This only applies to mustsync nodes.

This method should be called on authority nodes only.

See also: setSyncResult(), setMustSync()

void ZCom_Node::setOwner ZCom_ConnID  _id,
bool  _enabled
 

Give owner-status to proxy nodes on clients. (Allowed on: Authority).

Parameters:
_id The connection on which this node's proxy shall receive owner status (eZCom_RoleOwner)
_enabled 'true' to set owner status, 'false' to remove it.
This permits the client on the other side of the connection a higher authority over the node. Normally, all nodes created on a client are eZCom_RoleProxy. It can advance to an eZCom_RoleOwner if the server permits that (with this method). This advancement won't do anything special on it's own, instead, the application is responsible to take some action here. You can define data to be replicated only to eZCom_RoleOwner nodes. Also, when sending events you can specify if only the owner or all proxies should receive the event. Furthermore, the application can filter events based on the role of their sender.

Example scenario: A spaceship. The server of course has the authority over it, and there are 10 proxies (which replicate what the server object is doing). Now you declare one proxy to become the owner of that ship (in fact, one object may have several owners, and one client can own several objects, it totally depends on the application what it means to be an owner). This owner (which is a client) now can send events to the server node which are not dropped because it accepts these specific events from an owner. In our scenario, these events are control commands to steer the ship and fire. In turn, the server would replicate some additional data (as set by the application), like the current ammo left for each weapon and other special infos no other players need to or should know about.

You can also use the owner status to delegate AI calculations to clients, for example.

void ZCom_Node::setPrivate bool  _enabled  ) 
 

Make node private. (Allowed on: Authority).

Parameters:
_enabled 'true' to make private, 'false' to make public. (default=false)
If a node is private, it will only get replicated to those connections, for which the node's role is eZCom_RoleOwner. See also: setOwner()

void ZCom_Node::setAnnounceData ZCom_BitStream _data  ) 
 

Set data that will be attached to each announcement of this node to a client.

The data needs to be set only on server side. It will be used only if the node's classname (registered with ZCom_Control::ZCom_registerClass()) has been registered with the ZCOM_CLASSFLAG_ANNOUNCEDATA flag. When the flag is set, such data MUST be available. The client needs to be able to read exactly the amount of data which has been set here, as no size information will be transmitted.

The bitstream goes into ownership of Zoidcom, it may not be deleted or used otherwise after giving it to the node.

More information about this topic can be found in the documentation to the flag.

bool ZCom_Node::beginReplicationSetup zU16  _replicators_max  ) 
 

Enclose all data replication setup functions with this and endReplicationSetup().

Parameters:
_replicators_max If set to >0, Zoidcom will preallocate memory for the replicators. If you leave it at 0 or you register more replicators than hinted here, reallocations have to be performed and maybe more memory than necessary will end up being used.

void ZCom_Node::setInterceptID ZCom_InterceptID  _id  ) 
 

Set intercept ID for all forthcoming replication registrations which have ZCOM_REPFLAG_INTERCEPT set.

Parameters:
_id The Id which will get assigned.
The intercept ID is passed to the info structure available in the replication interceptor callback, enabling the application to distinguish between several data items.

void ZCom_Node::addReplicationInt zS32 _ptr,
zU8  _bits,
bool  _sign,
zU8  _flags,
zU8  _rules,
zS16  _mindelay = -1,
zS16  _maxdelay = -1
 

Add an int to the data replication.

Parameters:
_ptr Pointer to the data source.
_bits The amount of relevant bits. Zoidcom will replicate no more than the relevant bits across the net link.
_sign Store the sign bit as extra information, you don't need this if _bits is set to 32 on a 32 bit value (the sign is included already in that case).
_flags Combination of Replication Flags, ORed together.
_rules Combination of Replication Rules, ORed together.
_mindelay Measured in msecs and defines how much time has to pass between two consecutive updates of this data.
_maxdelay Measured in msecs and defines how much time may pass between two consecutive updates of this data.
Attention:
Make sure that only pointers to zS32 or larger data types are passed here, since Zoidcom writes sizeof(zS32) bytes on incoming updates!
The update frequency bounds as defined by _mindelay and _maxdelay are not guaranteed. The resolution highly depends on factors like the client's connection, node priority and node relevance.

void ZCom_Node::addReplicationBool bool *  _ptr,
zU8  _flags,
zU8  _rules,
zS16  _mindelay = -1,
zS16  _maxdelay = -1
 

Add a bool to the data replication.

Parameters:
_ptr Pointer to the data source.
_flags Combination of Replication Flags, ORed together.
_rules Combination of Replication Rules, ORed together.
_mindelay Measured in msecs and defines how much time has to pass between two consecutive updates of this data.
_maxdelay Measured in msecs and defines how much time may pass between two consecutive updates of this data.
The update frequency bounds as defined by _mindelay and _maxdelay are not guaranteed. The resolution highly depends on factors like the client's connection, node priority and node relevance.

void ZCom_Node::addReplicationFloat zFloat _ptr,
zU8  _mantissa_bits,
zU8  _flags,
zU8  _rules,
zS16  _mindelay = -1,
zS16  _maxdelay = -1
 

Add a float to the data replication.

Parameters:
_ptr Pointer to the data source.
_mantissa_bits The amount of mantissa bits Zoidcom will replicate.
_flags Combination of Replication Flags, ORed together.
_rules Combination of Replication Rules, ORed together.
_mindelay Measured in msecs and defines how much time has to pass between two consecutive updates of this data.
_maxdelay Measured in msecs and defines how much time may pass between two consecutive updates of this data.
The update frequency bounds as defined by _mindelay and _maxdelay are not guaranteed. The resolution highly depends on factors like the client's connection, node priority and node relevance.

_mantissa_bits states how big your mantissa should be. Default for floats in C++ is 23. Additional 9 bits will be replicated for exponent and sign bit. The smaller the mantissa and the bigger the value of the float, the lower the precision will be.

Example: original value(mantissa size) => replicated value

  • 10.723(10) => 10.719
  • 20.7236(10) => 20.719
  • 20.7236(8) => 20.688
  • 20.7236(6) => 20.5
  • 20.7236(4) => 20.0
  • 100.723(10) => 100.688
  • 1000.723(10) => 1000.500
  • 10000.723(10)=> 10000
  • 10000.723(6) => 9984

In some cases, it may be better to make your own conversion. Take your float, create an approximation value for it and store it in an int, and register the int instead. Every time the float changes, the approx. value in the int has to be recomputed, or at least every time before you tell Zoidcom to process the updates. On the other side, you register that int, too. And every time after Zoidcom has processed the incoming updates, convert it back.

void ZCom_Node::addReplicationString char *  _str,
zU16  _maxlen,
zU8  _flags,
zU8  _rules,
zS16  _mindelay = -1,
zS16  _maxdelay = -1
 

Add a string to the data replication.

Parameters:
_str Pointer to the data source.
_maxlen The maximum length the string will have. Zoidcom only replicates the actual length, but it is needed for other reasons.
_flags Combination of Replication Flags, ORed together.
_rules Combination of Replication Rules, ORed together.
_mindelay Measured in msecs and defines how much time has to pass between two consecutive updates of this data.
_maxdelay Measured in msecs and defines how much time may pass between two consecutive updates of this data.
The update frequency bounds as defined by _mindelay and _maxdelay are not guaranteed. The resolution highly depends on factors like the client's connection, node priority and node relevance.

void ZCom_Node::addReplicationStringW wchar_t *  _str,
zU16  _maxlen,
zU8  _flags,
zU8  _rules,
zS16  _mindelay = -1,
zS16  _maxdelay = -1
 

Add a string to the data replication.

Parameters:
_str Pointer to the data source.
_maxlen The maximum length the string will have. Zoidcom only replicates the actual length, but it is needed for other reasons.
_flags Combination of Replication Flags, ORed together.
_rules Combination of Replication Rules, ORed together.
_mindelay Measured in msecs and defines how much time has to pass between two consecutive updates of this data.
_maxdelay Measured in msecs and defines how much time may pass between two consecutive updates of this data.
The update frequency bounds as defined by _mindelay and _maxdelay are not guaranteed. The resolution highly depends on factors like the client's connection, node priority and node relevance.

void ZCom_Node::addInterpolationInt zS32 _ptr,
zU8  _bits,
bool  _sign,
zU8  _flags,
zU8  _rules,
zS32  _treshold,
zS32 _dst = NULL,
zS16  _mindelay = -1,
zS16  _maxdelay = -1,
zFloat  _ipolfac = 0.4f
 

Add an int to the data replication and ask Zoidcom to interpolate it.

Parameters:
_ptr Pointer to the data source.
_bits The amount of relevant bits. Zoidcom will replicate no more than the relevant bits across the netlink.
_sign Store the sign bit as extra information, you don't need this if _bits is set to 32 on a 32 bit value (the sign is included already in that case).
_flags Combination of Replication Flags, ORed together.
_rules Combination of Replication Rules, ORed together.
_treshold The error margin. If the difference between the received and the current value is bigger than _treshold, Zoidcom will just set current = received without interpolation.
_dst If set, Zoidcom will store incoming updates in _dst and interpolate against _dst. If not set, Zoidcom will use internal memory. Read the detailed description to find out more.
_mindelay Measured in msecs and defines how much time has to pass between two consecutive updates of this data.
_maxdelay Measured in msecs and defines how much time may pass between two consecutive updates of this data.
_ipolfac Interpolation factor, the higher it becomes, the higher the influence of the incoming data over the local data. Set to 0 to ignore incoming data, or 1 to just write incoming data to _ptr.
Attention:
Make sure that only pointers to ints or larger data types are passed here, since Zoidcom writes sizeof(int) bytes on incoming updates!
The update frequency bounds as defined by _mindelay and _maxdelay are not guaranteed. The resolution highly depends on factors like the client's connection, node priority and node relevance.

Setting the _dst parameter orders Zoidcom to store incoming updates in application provided memory. Now it is possible to provide custom interpolation by setting the _ipolfac to 0 and interpolate manually between _dst and _ptr. Or let Zoidcom handle interpolation with _ipolfac > 0, but the application can also write to _dst itself thus forcing Zoidcom to interpolate against clientside generated values. (E.g. You could process your physics locally as means of dead reckoning and store the current status is _dst. Zoidcom will then interpolate against the locally computed value, and also against incoming values from the server, which overwrite _dst).

See also: addReplicationInt()

void ZCom_Node::addInterpolationFloat zFloat _ptr,
zU8  _mantissa_bits,
zU8  _flags,
zU8  _rules,
zFloat  _treshold,
zFloat _dst = NULL,
zS16  _mindelay = -1,
zS16  _maxdelay = -1,
zFloat  _ipolfac = 0.4f
 

Add a float to the data replication and ask Zoidcom to interpolate it.

Parameters:
_ptr Pointer to the data source.
_mantissa_bits The amount of mantissa bits Zoidcom will replicate.
_flags Combination of Replication Flags, ORed together.
_rules Combination of Replication Rules, ORed together.
_treshold The error margin. If the difference between the received and the current value is bigger than _treshold, Zoidcom will just set current = received without interpolation.
_dst If set, Zoidcom will store incoming updates in _dst and interpolate against _dst. If not set, Zoidcom will use internal memory. Read the detailed description to find out more.
_mindelay Measured in msecs and defines how much time has to pass between two consecutive updates of this data.
_maxdelay Measured in msecs and defines how much time may pass between two consecutive updates of this data.
_ipolfac Interpolation factor, the higher it becomes, the higher the influence of the incoming data over the local data. Set to 0 to ignore incoming data, or 1 to just write incoming data to _ptr.
The update frequency bounds as defined by _mindelay and _maxdelay are not guaranteed. The resolution highly depends on factors like the client's connection, node priority and node relevance.

Setting the _dst parameter orders Zoidcom to store incoming updates in application provided memory. Now it is possible to provide custom interpolation by setting the _ipolfac to 0 and interpolate manually between _dst and _ptr. Or let Zoidcom handle interpolation with _ipolfac > 0, but the application can also write to _dst itself thus forcing Zoidcom to interpolate against clientside generated values. (E.g. You could process your physics locally as means of dead reckoning and store the current status is _dst. Zoidcom will then interpolate against the locally computed value, and also against incoming values from the server, which overwrite _dst).

See also: addReplicationFloat() for more details on float replication.

void ZCom_Node::addReplicator ZCom_Replicator _rep,
bool  _autodelete
 

Add replicator object.

Parameters:
_rep Fully setup and initialized replicator.
_autodelete If true, the replicator will be deleted when the node gets deleted.
With this method you can register your own replicator to the node. When the node gets deleted, the replicator will get deleted if _autodelete is set.

The replicator setups however, won't get deleted. (Replicator setups are the configuration object passed to the replicator's constructor.

If you want to save memory, you'd better use this method for all your replication needs. Only this method allows you to use one (static) ZCom_ReplicatorSetup for several replicator objects, while the other replication methods allocate one ZCom_ReplicatorSetup object for each replication item.

Read the manual for more in depth information on this.

bool ZCom_Node::endReplicationSetup void   ) 
 

End replication setup.

This finalizes the replication setup. Make sure that nodes of the same ZCom_ClassID have the same replication setup. Important for that are especially:

  • order of replication elements (addReplicationXXX...)
  • the amount of bits replicated
  • the _flags

void ZCom_Node::setReplicationInterceptor ZCom_NodeReplicationInterceptor _interceptor  ) 
 

Set replication interceptor for this node.

Parameters:
_interceptor Pointer to interceptor object.
Refer to ZCom_NodeReplicationInterceptor documentation for further information.

bool ZCom_Node::sendEvent eZCom_SendMode  _mode,
zU8  _rules,
ZCom_BitStream _data
 

Send an event to the peers selected with _rules: Replication Rules.

Parameters:
_mode eZCom_SendMode
_rules Replication Rules
_data ZCom_BitStream with your event data. It will be deleted eventually.
Returns:
'true' on success.

bool ZCom_Node::sendEventDirect eZCom_SendMode  _mode,
ZCom_BitStream _data,
ZCom_ConnID  _destconn
 

Send an event to a connected node on a specific connection only (needed for initializing and syncing, see eZCom_Event).

Parameters:
_mode eZCom_SendMode
_destconn Connection of the destination node.
_data ZCom_BitStream with your event data. It will be deleted eventually.
Returns:
'true' on success.

bool ZCom_Node::sendEventToGroup eZCom_SendMode  _mode,
ZCom_BitStream _data,
ZCom_GroupID  _destgroup
 

Send an event to connected nodes on a group of connections.

Parameters:
_mode eZCom_SendMode
_destgroup Valid group ID from ZCom_Control::ZCom_getGroupManager()
_data ZCom_BitStream with your event data. It will be deleted eventually.
Returns:
'true' on success.

void ZCom_Node::setEventNotification bool  _oninit,
bool  _onremove
 

Toggle connect/remove notification.

Parameters:
_oninit Generate event if a new proxy node connected.
_onremove Generate event if a proxy node is removed.

bool ZCom_Node::checkEventWaiting  )  const
 

Check for new events.

Returns:
'true' if an event is waiting.

ZCom_BitStream* ZCom_Node::getNextEvent eZCom_Event _type,
eZCom_NodeRole _remote_role,
ZCom_ConnID _connid,
zU32 _estimated_time_sent = NULL
 

Get the next event.

Parameters:
_type Pass a ptr to eZCom_Event here, the event's type will be stored there. May be NULL.
_remote_role Pass a ptr to eZCom_NodeRole here, the sender's role will be stored there. May be NULL.
_connid Pass a ptr to ZCom_ConnID here, the sender's connection ID will be stored here. May be NULL.
_estimated_time_sent Pass a ptr to zFloat here, the estimated sending time will be stored here. May be NULL.
Returns:
Bitstream containing the event data. Can be NULL.
The event will be deleted automatically afterwards along with the ZCom_BitStream. The contained data for special events is detailed here.

The _estimated_time_sent parameter gives an msec value trying to estimate the time the event has left the remote ZCom_Control. Execute "ZoidCom::getTime() - _sent_time" to find out the event's travel time in msecs.

ZCom_FileTransID ZCom_Node::sendFile const char *  _path,
const char *  _pathtosend,
ZCom_ConnID  _destconn,
ZCom_BitStream _data,
zFloat  _aggressivenes
 

Send a file to a specific connection.

Parameters:
_data is optional. use it to pass additional information about the file to the receiver.
_path is the full path to the local file which is to be sent.
_pathtosend is the path the peer will receive for that file, if NULL, _path will be used.
_destconn Destination connection.
_aggressivenes can be anything >0.0 - 1.0. If it is 1.0, it will always use up the complete rest of the stream for sending the file. That means, when this node is asked to fill the stream, no other node after this in the priority queue can fill in it's data. Otherwise it will fill in (_aggresivenes * bytes left in stream) bytes.
Returns:
A FileTransferID you can use to check the status of the transfer. Equals ZCom_InvalidID on error.
The destination will receive the request in the form of an eEvent_File_Incoming and can reply with acceptFile().

void ZCom_Node::acceptFile ZCom_ConnID  _src_id,
ZCom_FileTransID  _ftrans_id,
const char *  _path,
bool  _accept
 

Accept or deny an incoming file.

Parameters:
_src_id Source connection.
_ftrans_id Transfer ID as contained in the eEvent_File_Incoming event.
_path Store location. If NULL, the file will be saved in the location that came with the request.
_accept Set to 'true' to accept the transfer, 'false' otherwise.

const ZCom_FileTransInfo& ZCom_Node::getFileInfo ZCom_ConnID  _conn_id,
ZCom_FileTransID  _ftrans_id
const
 

Get data for a file transfer.

Parameters:
_conn_id Connection of the transfer.
_ftrans_id Id of that transfer.
Returns:
Reference to a filled ZCom_FileTransInfo structure. If transfer is invalid, the resulting struct will have ZCom_Invalid_ID in the id field. All other fields are invalid then.

void ZCom_Node::setEventInterceptor ZCom_NodeEventInterceptor _interceptor  ) 
 

Set event interceptor for this node.

Parameters:
_interceptor Pointer to interceptor object.
Refer to ZCom_NodeEventInterceptor documentation for further information.

bool ZCom_Node::setUserData ZCom_ConnID  _conn,
void *  _data
 

Set user data pointer per relevant connection.

Parameters:
_conn The connection the userdata is associated to.
_data Pointer to the data.
Returns:
true if the connection is relevant to the node and the data has been attached.
After the connection has been closed, the attached data cannot be retrieved anymore.

void* ZCom_Node::getUserData ZCom_ConnID  _conn  )  const
 

Retrieve user data.

Parameters:
_conn The connection ID the data was attached to.
Returns:
Pointer to the previously stored data.

void ZCom_Node::setUserData void *  _data  ) 
 

Set global user data pointer.

Parameters:
_data Pointer to the data.
In constrast to the other setUserData() method, this one stores the pointer without association to a connection.

void* ZCom_Node::getUserData  )  const
 

Retrieve global user data pointer.

Returns:
Previously stored data pointer.

zS32 ZCom_Node::getUpdateDelta  )  const
 

Get time in msecs since last received update packet.

Returns:
Time in msecs since last received update packet or -1 if no update occured, yet.

zU32 ZCom_Node::getCurrentUpdateRate  )  const
 

Get packet rate of source connection.

Returns:
The current packet send rate of the data source connection.
This returns the current packet rate from the data source connection. For eZCom_RoleProxy nodes, the send rate of the connection with the eZCom_RoleAuthority node is returned, and for authority nodes, the send rate of the connection with the eZCom_RoleOwner node is returned.

zS32 ZCom_Node::getEstimatedTimeUntilPossibleUpdate  )  const
 

Get estimated time in msecs until next possible update arrives.

Returns:
Estimated time in msecs or -1 if the information cannot be retrieved.
This tries to estimate the time until the next packet arrives from the data source connection. This packet won't necessarily contain an update for this node, but it could.

ZCom_Control* ZCom_Node::getControl  )  const
 

Get the ZCom_Control this node is registered with.

Returns:
A ZCom_Control pointer, or NULL if node is not registered.

eZCom_NodeRole ZCom_Node::getRole  )  const
 

Get role of this node.

Returns:
The node's current role.

bool ZCom_Node::isPrivate  )  const
 

Find out if node is in private mode.

Returns:
bool 'true' if node is private.
See also: setPrivate()

ZCom_ClassID ZCom_Node::getClassID  )  const
 

Get node's class ID.

Returns:
ZCom_ClassID. The class ID this node represents.

ZCom_NodeID ZCom_Node::getNetworkID  )  const
 

Retrieve the node's network ID.

Returns:
ZCom_NodeID
Once the node is registered to a ZCom_Control and linked up to other nodes it owns a network ID. This ID is equal to all ZCom_Nodes in all connected ZCom_Controls representing the same object. If the node's role is eZCom_RoleAuthority, the network ID is available as soon as the node is registered, if the role is proxy or owner, the ID will be available as soon as the node is linked up to a authority node, so after the node has received eEvent_Init or eEvent_SyncRequest.


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:50 2008 for Zoidcom by doxygen 1.4.6-NO