Main Page | Class Hierarchy | Class List | Directories | File List | Class Members

RNReplicaNet::ReplicaNet Class Reference

#include <ReplicaNet.h>

Collaboration diagram for RNReplicaNet::ReplicaNet:

Collaboration graph
[legend]
List of all members.

Public Types

enum  Error {
  kReplicaNet_EOK = 0, kReplicaNet_EERROR = -1, kReplicaNet_ETRANSPORT_CLOSED = -2, kReplicaNet_ETRANSPORT_ERROR = -3,
  kReplicaNet_EEND_RECORDING = -4
}
enum  PacketType { kPacket_Unreliable = 0, kPacket_Reliable = 1, kPacket_Certain = 2 }
enum  OnError { kMigrateObjects = 0, kDeleteObjects, kLeaveObjects }

Public Member Functions

 ReplicaNet ()
virtual ~ReplicaNet ()
virtual void PreRegisterReplicas (void)
int GetSessionID (void)
void AddObject (ReplicaObject *const object)
void RemoveObject (ReplicaObject *const object)
int GetGameChannel (void)
void SetGameChannel (const int channel=TransportAnyGameChannel)
void SessionCreate (const std::string name)
void SessionCreate (const std::string name, const std::string protocols)
std::string SessionExportURL (void)
void SessionJoin (const std::string url)
void SessionFind (void)
std::string SessionEnumerateFound (void)
void LockObjects (void)
void UnLockObjects (void)
float GetNetworkSendRate (void)
float GetNetworkReceiveRate (void)
int GetNetworkPacketsLost (void)
virtual float GetTime (void)
virtual float GetLocalTime (void)
void SetObserver (ReplicaObject *const object=0)
ReplicaObjectGetObserver (void)
void Poll (void)
void SetPollLayerBelow (bool enable=true)
bool GetPollLayerBelow (void)
void SetPollLayerBelowForXPSession (bool enable=true)
bool GetPollLayerBelowForXPSession (void)
void SetManualPoll (void)
void SetAutomaticPoll (void)
void SetManualPollXPSession (void)
void SetAutomaticPollXPSession (void)
void SetManualPollXPURL (void)
void SetAutomaticPollXPURL (void)
void GiveOwnership (ReplicaObject *const object, const int sessionID)
void RequestOwnership (ReplicaObject *const object)
void SetCanSpider (const bool canSpider=true)
bool GetCanSpider (void)
float GetLatencyToMasterSession (void)
void SetLatencyRecalculationDelay (const float seconds=1.0f)
bool IsStable (void)
bool IsMaster (void)
void SetCanBecomeMaster (const bool canBeMaster=true)
bool GetCanBecomeMaster (void)
Error GetStatus (void)
Error GetSessionErrorReason (void)
void SetOnSessionError (const OnError whatToDo=kMigrateObjects)
OnError GetOnSessionErrorMigrateObjects (void)
void SetCanAcceptObjects (bool accept=true)
bool GetCanAcceptObjects (void)
void SetEncryption (const bool enable=false)
bool GetEncryption (void)
void SetLoadBalancing (const bool enable=false)
bool GetLoadBalancing (void)
void SetMaximumLoad (float load=0.0f)
float GetMaximumLoad (int sessionID=kReplicaNetUnknownUniqueID)
float GetTotalLoad (int sessionID=kReplicaNetUnknownUniqueID)
void ObjectListBeginIterate (void)
void ObjectListFinishIterate (void)
ReplicaObjectObjectListIterate (void)
virtual void JoinerSessionIDPre (const int sessionID)
virtual void JoinerSessionIDPost (const int sessionID)
virtual void LeaverSessionIDPre (const int sessionID)
virtual void LeaverSessionIDPost (const int sessionID)
void Disconnect (const int sessionID=kReplicaNetUnknownUniqueID)
bool GetPreConnectStatus (void)
void SetPreConnect (const bool enable=false)
bool GetPreConnect (void)
void PreConnectHasFinished (void)
void SetDataRetention (const bool enable=false)
bool GetDataRetention (void) const
void DataSend (const int sessionid, const void *data, const int length, const PacketType type=kPacket_Reliable)
bool DataReceive (int *const fromsessionid, void *const data, int *const length, PacketType *const type=0)
void SetDataBlockUpdatePolicy (const bool automatic=true)
bool GetDataBlockUpdatePolicy (void) const
void ProcessDataBlockUpdate (void)
void SetAutomaticPacketCompression (const bool enable=false)
bool GetAutomaticPacketCompression (void)
void GetCompressionStatistics (int *const before=0, int *const after=0, const bool reset=false)
void GetMergedStatistics (int *const sent=0, int *const received=0, const bool reset=false)
int GetMasterSessionID (void)
std::string GetURLFromSessionID (const int sessionID)
void SetClientOnly (const bool isClient=false)
bool GetClientOnly (void)
bool GetBandwidthFromSessionID (const int sessionID, Transport::Bandwidth *const bandwidth, int *const output, int *const input)
virtual ReplicaObjectCallBackAllocate (const int classID, const int sessionID, const int uniqueID)
virtual ReplicaObjectCallBackDelete (ReplicaObject *object)
bool BeginSessionRecord (void)
void StopSessionRecord (void)
virtual bool CallbackSessionRecord (const void *data, const int length)
bool GetSessionRecord (void) const
bool BeginSessionPlayback (void)
void StopSessionPlayback (void)
void SetPlaybackSpeed (const float speed=1.0f)
bool PlaybackAdvanceTo (const float time)
virtual bool CallbackSessionPlayback (void *data, const int length)
bool GetSessionPlayback (void) const
void SetPlaybackAllowMasterReplicaObjects (const bool allow=false)
bool GetPlaybackAllowMasterReplicaObjects (void)
void SetAllowConnections (const bool allow=true)
bool GetAllowConnections (void)
void SetNodeBuffers (const bool enable=false)
bool GetNodeBuffers (void)

Static Public Member Functions

static ReplicaNetGetCurrentReplicaNet (void)
static void SetCurrentReplicaNet (ReplicaNet *const replicanet)

Friends

class ReplicaObject
class ReplicaNetPrivate
class ReplicaNetDLLRegister

Detailed Description

The main class for ReplicaNet. This class handles everything to do with the management of all ReplicaObject types that are allocated to a network session.
ReplicaNet uses XPSession to manage a network session which includes session migration and client-server or peer-to-peer network topology.
Each instance of ReplicaNet can be configured depending on the intended use on a per-machine basis. As an example a Massively Multiplayer Online (MMO) server node could use:
SetLoadBalancing(true);		// This is optional and should only be used if you expect your server objects to be moved between other nodes that use this flag.
SetCanAcceptObjects(true);	// In the event of a server node failure this node can accept fault tolerant objects.
SetCanBecomeMaster(true);	// In the event of the master server node failure this node is capable of becoming the new master.
SetCanSpider(true);			// This node will advertise a connection that can be used to communicate directly to other nodes.
// Adding packet buffering using the TransportConfig class will reduce the number of packets sent over the wire.
TransportConfig::SetPacketBufferTime(1.0f / 50.0f);
TransportConfig::SetPacketBufferEnable(true);
// Using multi-threaded libraries does help performance for a server that is going to have a high load and automatically uses multiple CPU cores or Hyper-Threads if the hardware/OS support is available.
SetAutomaticPoll();			// Allow automatic polling of ReplicaNet.
SetAutomaticPollXPSession();// Allow automatic polling of XPSession.
SetAutomaticPollXPURL();	// Allow automatic polling of XPURL and Transports.
SetPollLayerBelow(false);	// Separates the ReplicaNet thread from the XPSession thread.
SetPollLayerBelowForXPSession(false);	// Separates the XPSession thread from the XPURL threads.
SetNodeBuffers(true);		// This uses extra memory for low-latency cross thread buffers to improve threading performance.
Spidering can also be set to be on for server nodes and this this helps to distribute network bandwidth.

For the clients:

SetLoadBalancing(false);
SetCanAcceptObjects(false);
SetCanBecomeMaster(false);
SetCanSpider(false);
SetClientOnly(true);		// This lowers bandwidth to this node and ensures only this node sends object updates to server nodes.
// Adding packet buffering using the TransportConfig class will reduce the number of packets sent over the wire.
TransportConfig::SetPacketBufferTime(1.0f / 50.0f);
TransportConfig::SetPacketBufferEnable(true);
Note that all the clients are not going to have peer connections to other clients. This is what you want for a MMO.

Or for a traditional peer-to-peer LAN/WAN type of game with host and object migration:

SetLoadBalancing(false);
SetCanAcceptObjects(true);
SetCanBecomeMaster(true);
SetCanSpider(true);
// Adding packet buffering using the TransportConfig class will reduce the number of packets sent over the wire.
TransportConfig::SetPacketBufferTime(1.0f / 50.0f);
TransportConfig::SetPacketBufferEnable(true);

These options are explained below in the documentation.

ReplicaNet can also send and receive raw data packets from the session for those applications that do not always want to use the data driven ReplicaObject methods of propagation.
The terms "Reliable", "Unreliable" and "Certain" are references to the three packet delivery types used by ReplicaNet, XPSession and XPURL Transport classes.
"Reliable" guarantees delivery of data in the same order it was sent.
"Certain" guarantees delivery of data but the order the data is received may not be preserved.
"Unreliable" does not guarantee delivery of data and the order of the data when it is received may not be preserved.
In general it is a good idea to not use too many "Reliable" updates because this method is quite expensive in terms of network and memory performance. If one packet gets lost it will delay the delivery of all other Reliable data until that packet is resent. The better choice would be to use "Certain" because this is less expensive in terms of memory and network performance. Also if one Certain packet is lost the delivery of other Certain packets is not delayed. Generally use Reliable for those events that absolutely must occur in the same order they were sent.
For most ReplicaObject updates use the Certain update type because generally it doesn't matter if an object is sometimes created in a different order to other objects. By default ReplicaObject uses the Reliable method to give the most reliable performance for easier first-pass testing of new networked software. This means network performance can be improved by using the ROL code:

object ObjectFoo
{
    networking
    {
    ... Some member variables ...
    }

    // Set Certain updates for this object.
    Certain();
}
The default for ReplicaObject class member variables (the DataBlock derived classes) is to use Unreliable packets. For example it generally doesn't matter if a position update packet is lost because another update will be transmitted at some point in the near future. Remember that each network shared ReplicaObject class member variable using a DataBlock can have a different packet update type.


Member Enumeration Documentation

enum RNReplicaNet::ReplicaNet::Error
 

Standard ReplicaNet errors

Enumeration values:
kReplicaNet_EOK  No error.
kReplicaNet_EERROR  A fatal error happened, like the connection broke and cannot be recovered.


Constructor & Destructor Documentation

RNReplicaNet::ReplicaNet::ReplicaNet  ) 
 

The ctor performs some basic initialisation

virtual RNReplicaNet::ReplicaNet::~ReplicaNet  )  [virtual]
 

The dtor makes sure everything is tidy


Member Function Documentation

void RNReplicaNet::ReplicaNet::AddObject ReplicaObject *const   object  ) 
 

Adds a ReplicaObject class to this ReplicaNet class. The object can be a master or replica. The object is added via this call when it is 1) Published or 2) Allocated as a replica.

Parameters:
object the object to add

bool RNReplicaNet::ReplicaNet::BeginSessionPlayback void   ) 
 

Starts playback of a recorded network session. This function must be called before any ReplicaObject derived classes are published and before any network session is joined or created using this ReplicaNet instance. All of the session events are then simulated from the recording so a SessionJoin() or SessionCreate() is not required. CallbackSessionPlayback() will then be called when ReplicaNet needs to read in data. The user must implement reading this data.

Returns:
Success returns true, failure returns false.

bool RNReplicaNet::ReplicaNet::BeginSessionRecord void   ) 
 

Starts recording the network session. When the ReplicaNet session is created or joined recording of the entire session will begin. This function may be called at any time, for example before the session is created, joined or during the period when the session is running. CallbackSessionRecord() will then be called when ReplicaNet needs to save data. The user must implement storing this data.

Returns:
Success returns true, failure returns false.

virtual ReplicaObject* RNReplicaNet::ReplicaNet::CallBackAllocate const int  classID,
const int  sessionID,
const int  uniqueID
[virtual]
 

This virtual callback method may be implemented to override any ROL registered ReplicaObject factory allocate function. If a ReplicaObject is returned then ReplicaObject::GetClassID() must be implemented in the derived class in such a way as to return the correct classID.

Parameters:
classID The classID of the object to create.
sessionID The sessionID of the object to create.
uniqueID The uniqueID of the object to create.
Returns:
The default implementation is to return null which allows ReplicaNet to use the ROL registered factory.

virtual ReplicaObject* RNReplicaNet::ReplicaNet::CallBackDelete ReplicaObject object  )  [virtual]
 

This virtual callback method may be implemented to override any ROL registered ReplicaObject factory delete function.

Parameters:
object The classID of the object to delete.
Returns:
The default implementation is to return the input object pointer, this allows ReplicaNet to use the ROL registered factory on the returned object pointer. For example it would also be possible to return a different object pointer to that passed into the callback. Returning null will signal to ReplicaNet that the object has been handled.

virtual bool RNReplicaNet::ReplicaNet::CallbackSessionPlayback void *  data,
const int  length
[virtual]
 

This callback is called when ReplicaNet wants to get data from a session recording. The user must implement this function.

Parameters:
data The destination data pointer for the data to be stored.
length The requested amount of data in bytes that ReplicaNet wants. If the user cannot supply the exact length of data then false should be returned.
Returns:
Success returns true, failure returns false.

virtual bool RNReplicaNet::ReplicaNet::CallbackSessionRecord const void *  data,
const int  length
[virtual]
 

This callback is called when ReplicaNet wants to save data from a recording session. The user must implement this function.

Parameters:
data The data to store.
length The size in bytes of the data to store.
Returns:
Success returns true, failure returns false.

bool RNReplicaNet::ReplicaNet::DataReceive int *const   fromsessionid,
void *const   data,
int *const   length,
PacketType *const   type = 0
 

Receives raw data and responds with what session sent this data. See also SetDataRetention().

Parameters:
fromsessionid The session id that sent this data.
data The buffer for the data.
length The length of the data received, which should not be greater than 512 bytes.
type A pointer that can receive the packet type. This parameter can be null in which case the type is not filled in. The default value for this pointer is null.
Returns:
True if data was received

void RNReplicaNet::ReplicaNet::DataSend const int  sessionid,
const void *  data,
const int  length,
const PacketType  type = kPacket_Reliable
 

Sends raw data from this session to any other session via it's ID or to all sessions by using kReplicaNetBroadcastID. If the node is in a pre-connect state and wants to send data to the master session then use kReplicaNetUnknownUniqueID as the session ID to send to. See also SetDataRetention().

Parameters:
sessionid the session id to send to or kReplicaNetBroadcastID
data the pointer to the data to send
length the length of the data to send, which should not be greater than 512 bytes.
type The type of data packet to send

void RNReplicaNet::ReplicaNet::Disconnect const int  sessionID = kReplicaNetUnknownUniqueID  ) 
 

This forces a disconnect from the supplied sessionID or if the sessionID is not supplied then all session nodes are disconnected. The disconnect is immediate and initiates the fault tolerant mechanism for XPSession and ReplicaNet on other connected session nodes. This means if the session was a master session node then the other session nodes will try to find a new master if this mechanism is enabled. In the case of a ReplicaNet session node having objects, these objects will attempt to use the fault recovery and migration if it is enabled.

Parameters:
sessionID The sessionID to disconnect from. The default is to disconnect from all sessionIDs.

bool RNReplicaNet::ReplicaNet::GetAllowConnections void   ) 
 

Returns the value configured by SetAllowConnections() the value.

bool RNReplicaNet::ReplicaNet::GetAutomaticPacketCompression void   ) 
 

Gets the value configured by SetAutomaticPacketCompression()

Returns:
Returns true is the automatic packet compression is enabled.

bool RNReplicaNet::ReplicaNet::GetBandwidthFromSessionID const int  sessionID,
Transport::Bandwidth *const   bandwidth,
int *const   output,
int *const   input
 

Attempts to read the configured bandwidth for a route to a specific session ID. If the session ID is not directly connected to this node then this function will return false and the contents of the output and input pointers will be left unchanged. If this node can supply bandwidth information about a session ID then this function will return true and the bandwidth, output, input pointers will contain the values as used by SetBandwidthLimit(), SetMaximumOutputBandwidth() and SetMaximumInputBandwidth(). Note that output and input bandwidth will appear to be exchanged because the output of one end of transport connection is really the input of the other end of the connection.

Parameters:
sessionID The session ID of the required node.
bandwidth A pointer to accept the Transport::Bandwidth value.
output A pointer to accept the output bandwidth value.
input A pointer to accept the input bandwidth value.
Returns:
Success returns true, failure returns false.

bool RNReplicaNet::ReplicaNet::GetCanAcceptObjects void   ) 
 

Allows the status of SetCanAcceptObjects() to be read

Returns:
the status of SetCanAcceptObjects()

bool RNReplicaNet::ReplicaNet::GetCanBecomeMaster void   ) 
 

Allows the state to be read

Returns:
the status of the becoming a master state

bool RNReplicaNet::ReplicaNet::GetCanSpider void   ) 
 

This allows the spidering state to be read /return the status of the spidering state

bool RNReplicaNet::ReplicaNet::GetClientOnly void   ) 
 

Gets the client only configuration set by SetClientOnly().

Returns:
The configuration set by SetClientOnly().

void RNReplicaNet::ReplicaNet::GetCompressionStatistics int *const   before = 0,
int *const   after = 0,
const bool  reset = false
 

Gets the compression statistics totals for packets sent from this session node.

Parameters:
before The total number of bytes before compression. This can be null.
after The total number of bytes after compression. This can be null.
reset If true, after returning the information to the caller both totals are reset back to zero. The default value is false.

static ReplicaNet* RNReplicaNet::ReplicaNet::GetCurrentReplicaNet void   )  [static]
 

Static function to return the current ReplicaNet class that is being used

Returns:
returns the current ReplcaNet class in use

bool RNReplicaNet::ReplicaNet::GetDataBlockUpdatePolicy void   )  const
 

Returns the state set by SetDataBlockUpdatePolicy().

Returns:
the state set by SetDataBlockUpdatePolicy().

bool RNReplicaNet::ReplicaNet::GetDataRetention void   )  const
 

Allows the raw data retention policy to be read.

Returns:
The data retention policy.

bool RNReplicaNet::ReplicaNet::GetEncryption void   ) 
 

Gets the status of the encryption flag for this session

Returns:
true if encryption is enabled

int RNReplicaNet::ReplicaNet::GetGameChannel void   ) 
 

Gets the current channel number

Returns:
the channel number

float RNReplicaNet::ReplicaNet::GetLatencyToMasterSession void   ) 
 

This allows the latency to the master session to be read. This is the time taken for a packet to reach the master session.

Returns:
the latency to the master session

bool RNReplicaNet::ReplicaNet::GetLoadBalancing void   ) 
 

Gets the status of the load balancing flag

Returns:
true if load balancing is enabled

virtual float RNReplicaNet::ReplicaNet::GetLocalTime void   )  [virtual]
 

Gets the current local time. This time is local to the session and is not synchronised to the session master clock. This function is virtual allowing the application to provide their own source for time. If providing a custom source of time and recording a session or playing a session recording then care must be taken to provide proper synchronisation of time.

Returns:
the float time 1.0 units == 1 second

int RNReplicaNet::ReplicaNet::GetMasterSessionID void   ) 
 

Gets the master session unique ID. If the session is not connected then the return value is kReplicaNetUnknownUniqueID.

Returns:
the master session unique ID

float RNReplicaNet::ReplicaNet::GetMaximumLoad int  sessionID = kReplicaNetUnknownUniqueID  ) 
 

Gets the maximum load set by SetMaximumLoad() or the maximum load for a supplied session ID if one is supplied

Parameters:
sessionID the session ID to return the load value for
Returns:
the load setting

void RNReplicaNet::ReplicaNet::GetMergedStatistics int *const   sent = 0,
int *const   received = 0,
const bool  reset = false
 

Gets the merged packet statistics totals for connections managed by this session node.

Parameters:
sent The total number of merged sent packets. This can be null.
received The total number of merged sent packets. This can be null.
reset If true, after returning the information to the caller both totals are reset back to zero. The default value is false.

int RNReplicaNet::ReplicaNet::GetNetworkPacketsLost void   ) 
 

Gets the number of packets lost so far by the network layer.

Returns:
the number of packets lost.

float RNReplicaNet::ReplicaNet::GetNetworkReceiveRate void   ) 
 

Gets the current network receive transfer rate in bytes per second

Returns:
bytes per second

float RNReplicaNet::ReplicaNet::GetNetworkSendRate void   ) 
 

Gets the current network send transfer rate in bytes per second

Returns:
bytes per second

bool RNReplicaNet::ReplicaNet::GetNodeBuffers void   ) 
 

Returns the value configured by SetNodeBuffers()

Returns:
The value.

ReplicaObject* RNReplicaNet::ReplicaNet::GetObserver void   ) 
 

Gets the current observer ReplicaObject.

Returns:
returns the point to the object that is the observer, or NULL if there is no observer.

OnError RNReplicaNet::ReplicaNet::GetOnSessionErrorMigrateObjects void   ) 
 

Allows the status of SetOnSessionErrorMigrateObjects() to be read

Returns:
the status of SetOnSessionErrorMigrateObjects()

bool RNReplicaNet::ReplicaNet::GetPlaybackAllowMasterReplicaObjects void   ) 
 

Returns the value configured by SetPlaybackAllowMasterReplicaObjects().

bool RNReplicaNet::ReplicaNet::GetPollLayerBelow void   ) 
 

Allows the state of SetPollLayerBelow() to be read. If the library is always single threading then this function will always return true.

Returns:
the state of SetPollLayerBelow()

bool RNReplicaNet::ReplicaNet::GetPollLayerBelowForXPSession void   ) 
 

This calls XPSession::GetPollLayerBelow(). Please see the documentation in XPSession for more information.

Returns:
the state of XPSession::GetPollLayerBelow()

bool RNReplicaNet::ReplicaNet::GetPreConnect void   ) 
 

Allows the status of the pre-connect mechanism for this session node.

Returns:
Returns true if the pre-connect mechanism is enabled.

bool RNReplicaNet::ReplicaNet::GetPreConnectStatus void   ) 
 

Allows the status of the pre-connect mechanism to be tested.

Returns:
When GetPreConnectStatus() returns true after this session node starts a join then this session node is in a pre-connect state.

Error RNReplicaNet::ReplicaNet::GetSessionErrorReason void   ) 
 

This can be used to read extended information when ReplicaNet encounters a session error.

Parameters:
error The error can be:
kReplicaNet_EOK for when there is no session error.
kReplicaNet_EERROR for undefined errors.
kReplicaNet_ETRANSPORT_CLOSED for when the session is disconnected or closed.
kReplicaNet_ETRANSPORT_ERROR when the session is abnormally terminated due to a transport timeout.

int RNReplicaNet::ReplicaNet::GetSessionID void   ) 
 

Gets the session ID from the session associated with the ReplicaNet class

bool RNReplicaNet::ReplicaNet::GetSessionPlayback void   )  const
 

Allows the playback status of the session to be read.

Returns:
If true this means BeginSessionPlayback() has been used and the session is currently playing back a recording.

bool RNReplicaNet::ReplicaNet::GetSessionRecord void   )  const
 

Allows the recording status of the session to be read.

Returns:
If true this means BeginSessionRecord() has been used and the session is currently recording.

Error RNReplicaNet::ReplicaNet::GetStatus void   ) 
 

Gets the session status.

Returns:
the session status will be either kReplicaNet_EOK or kReplicaNet_EERROR.

virtual float RNReplicaNet::ReplicaNet::GetTime void   )  [virtual]
 

Gets the current system time of this ReplicaNet session synchronised with the time on the session master. This function is virtual allowing the application to provide their own source for time. If providing a custom source of time and recording a session or playing a session recording then care must be taken to provide proper synchronisation of time.

Returns:
the float time 1.0 units == 1 second

float RNReplicaNet::ReplicaNet::GetTotalLoad int  sessionID = kReplicaNetUnknownUniqueID  ) 
 

Gets the total load for a session ID. If the session ID is set to be kReplicaNetUnknownUniqueID then the load for the current session is returned

Parameters:
sessionID the session ID to return the load value for
Returns:
the total load for a session ID

std::string RNReplicaNet::ReplicaNet::GetURLFromSessionID const int  sessionID  ) 
 

Attempts to resolve the URL of the session unique ID from the point of view of this session node. If the session unique ID is not known to the session then the result is a null string. If the session unique ID is not directly connected to this node, for example the spider connection was broken, then this function is not guaranteed to produce a URL and can return a null string.

void RNReplicaNet::ReplicaNet::GiveOwnership ReplicaObject *const   object,
const int  sessionID
 

This tries to change the ownership on a ReplicaObject to another session. This only works if the ReplicaObject is a Master object and approves migration.

Parameters:
object the pointer to the ReplicaObject
sessionID the target sessionID for this object to migrate to

bool RNReplicaNet::ReplicaNet::IsMaster void   ) 
 

Returns true if this ReplicaNet session is the master session

Returns:
true if this session is the master

bool RNReplicaNet::ReplicaNet::IsStable void   ) 
 

This allows the user to check if the session is really stable.

Returns:
returns true if the session is stable

virtual void RNReplicaNet::ReplicaNet::JoinerSessionIDPost const int  sessionID  )  [virtual]
 

This virtual callback method allows a derived ReplicaNet class to be notified when a session ID joins the network session.
Sessions should not be disconnected by the user during this callback because all ReplicaObjects will see the sessionID join and then very quickly leave. To be able to disconnect potentially joining sessions use the SetPreConnect() mechanism. This method is called by ReplicaNet after all of the internal routines are run when a session joins.

virtual void RNReplicaNet::ReplicaNet::JoinerSessionIDPre const int  sessionID  )  [virtual]
 

This virtual callback method allows a derived ReplicaNet class to be notified when a session ID joins the network session.
Sessions should not be disconnected by the user during this callback because all ReplicaObjects will see the sessionID join and then very quickly leave. To be able to disconnect potentially joining sessions use the SetPreConnect() mechanism. This method is called by ReplicaNet before all of the internal routines are run when a session joins.

virtual void RNReplicaNet::ReplicaNet::LeaverSessionIDPost const int  sessionID  )  [virtual]
 

This virtual callback method allows a derived ReplicaNet class to be notified when a session ID leaves the network session.
This method is called by ReplicaNet after any of the internal routines are run when a session leaves.

virtual void RNReplicaNet::ReplicaNet::LeaverSessionIDPre const int  sessionID  )  [virtual]
 

This virtual callback method allows a derived ReplicaNet class to be notified when a session ID leaves the network session.
This method is called by ReplicaNet before any of the internal routines are run when a session leaves.

void RNReplicaNet::ReplicaNet::LockObjects void   ) 
 

This function locks the object lists so that the user application can guarantee that objects won't be created or deleted while accessing the objects created by ReplicaNet

void RNReplicaNet::ReplicaNet::ObjectListBeginIterate void   ) 
 

Starts iterating through all the allocated objects, effectively locking the list until ObjectListFinishIterate() is called.

void RNReplicaNet::ReplicaNet::ObjectListFinishIterate void   ) 
 

Unlocks the iterated list of objects. The list is unlocked automatically if ObjectListIterate() returns null.

ReplicaObject* RNReplicaNet::ReplicaNet::ObjectListIterate void   ) 
 

Iterates through the object list.

Returns:
the pointer to the next object known to this ReplicaNet session or returns null if there are no more objects.

bool RNReplicaNet::ReplicaNet::PlaybackAdvanceTo const float  time  ) 
 

This advances the playback simulation to a specified network time.

Parameters:
time The network time to advance to.
Returns:
True is returned if the simulation time has been advanced. False is returned if time is already in the past.

void RNReplicaNet::ReplicaNet::Poll void   ) 
 

This polls ReplicaNet. Normally an application will yield enough time during threads for ReplicaNet to function. Sometimes an application that uses a lot of 3D graphics can lock out other threads for quite some time. In these cases you may call ReplicaNet::Poll() to yield some time to ReplicaNet to perform housekeeping. This method also calls the XPSession::Poll() and XPURL::Poll() methods.
Single threaded considerations:
When using the single threaded libraries this method should be called regularly.

void RNReplicaNet::ReplicaNet::PreConnectHasFinished void   ) 
 

If the pre-connect mechanism is enabled then this function must be called by the joining session node when packets have been exchanged to the satisfaction of the joining session node.

virtual void RNReplicaNet::ReplicaNet::PreRegisterReplicas void   )  [virtual]
 

This registers all of the objects used in the application to the ReplicaNet class. This is used by ReplicaNet when a new node is allocated.

void RNReplicaNet::ReplicaNet::ProcessDataBlockUpdate void   ) 
 

If SetDataBlockUpdatePolicy(false) is used this function must be called by the user. See SetDataBlockUpdatePolicy() for more informaiton. If automatic updates are being used calling this function has no effect.

void RNReplicaNet::ReplicaNet::RemoveObject ReplicaObject *const   object  ) 
 

Removes a ReplicaObject class from this ReplicaNet class. The object can be a master or replica. This routine does not free an object it only removes the ReplicaNet reference to the object. If the object is a master then this calls also notifies other ReplicaNet session nodes that this object should be deleted from the session.

Parameters:
object the object to remove

void RNReplicaNet::ReplicaNet::RequestOwnership ReplicaObject *const   object  ) 
 

This requests a change of the ownership on a ReplicaObject to be the calling session. This only works if the ReplicaObject is a Replica object and approves migration.

Parameters:
object the pointer to the ReplicaObject

void RNReplicaNet::ReplicaNet::SessionCreate const std::string  name,
const std::string  protocols
 

Creates a new session using the supplied protocols.

Parameters:
name The name to give to the ReplicaNet session
protocols The list of protocols to use separated by commas. e.g. "UDP@,STREAMTCPIP@"

void RNReplicaNet::ReplicaNet::SessionCreate const std::string  name  ) 
 

Creates a new session using the available protocols.

Parameters:
name The name to give to the ReplicaNet session

std::string RNReplicaNet::ReplicaNet::SessionEnumerateFound void   ) 
 

Enumerates any found sessions

Returns:
the URL of a session or a "" string

std::string RNReplicaNet::ReplicaNet::SessionExportURL void   ) 
 

Exports a URL that can be used to connect to this session in future

Returns:
the full URL for the ReplicaNet session

void RNReplicaNet::ReplicaNet::SessionFind void   ) 
 

Tries to find sessions

void RNReplicaNet::ReplicaNet::SessionJoin const std::string  url  ) 
 

Tries to connect this session to the supplied URL

Parameters:
url the url of the ReplicaNet session to connect to

void RNReplicaNet::ReplicaNet::SetAllowConnections const bool  allow = true  ) 
 

Enables or disables any further connection attempts to this session.

Parameters:
allow Set this to be true to allow connections to this session. False will stop any further connection attempts to this session and the connecting session will get kReplicaNet_ETRANSPORT_CLOSED from GetSessionErrorReason().

void RNReplicaNet::ReplicaNet::SetAutomaticPacketCompression const bool  enable = false  ) 
 

Enables or disables the automatic packet compression test. If enabled XPSession will test each packet sent to see if it can be compressed and if there is a space saving then the packet is compressed before sending.

Parameters:
enable Enable or disable automatic packet compression. The default is false to disable automatic packet compression.

void RNReplicaNet::ReplicaNet::SetAutomaticPoll void   ) 
 

Sets the automatic Poll() method In multi-threading libraries this restarts the automatic polling thread so that an application does not need the call Poll()
In single-threading libraries this method has no effect and does not start a thread.
The default multi-threading library behaviour is to enable multi-threading automatic polls,
The default single-threading library behaviour is to use manual polls,

void RNReplicaNet::ReplicaNet::SetAutomaticPollXPSession void   ) 
 

This allows the poll method to be set for the XPSession layer that is used by this session.

void RNReplicaNet::ReplicaNet::SetAutomaticPollXPURL void   ) 
 

This allows the poll method to be set for the XPURL layer that is used by this session.

void RNReplicaNet::ReplicaNet::SetCanAcceptObjects bool  accept = true  ) 
 

Allows the user to set if this ReplicaNet session can accept objects via migration

Parameters:
accept Set this to be true if this session can accept objects through migration
However if this session becomes a master and no other sessions can accept objects then this session uses the rule from SetOnSessionError() and flags a session error if objects are left when using kLeaveObjects. The default value is true
Once a session is created or joined this parameter cannot be changed.

void RNReplicaNet::ReplicaNet::SetCanBecomeMaster const bool  canBeMaster = true  ) 
 

This allows the session to set if it can become a master due to a fault being found from another session

Parameters:
canBeMaster Pass in true to enable this session to become a master if needed.
The default is true
Once a session is created or joined this parameter cannot be changed.
Currently a session can only become a master if it is enabled for spidering however.

void RNReplicaNet::ReplicaNet::SetCanSpider const bool  canSpider = true  ) 
 

This allows the user to enable or disable spidering of network connections

Parameters:
canSpider Pass in true to enable spidering or false to disable spidering The default is true

void RNReplicaNet::ReplicaNet::SetClientOnly const bool  isClient = false  ) 
 

Sets the client only flag for this session node. The default value is false which means this node will get joiner and leaver messages. If this is set to be true then this node will only get joiner/leaver messages for spider nodes or nodes that can become master nodes. This must not be changed after the session is used for joining a session. Setting this to option be true also automatically sets to be false SetCanBecomeMaster() and SetCanSpider()

Parameters:
isClient The default value is false.

static void RNReplicaNet::ReplicaNet::SetCurrentReplicaNet ReplicaNet *const   replicanet  )  [static]
 

Static function to set the current ReplicaNet class that is being used

Parameters:
replicanet the ReplicaNet class pointer

void RNReplicaNet::ReplicaNet::SetDataBlockUpdatePolicy const bool  automatic = true  ) 
 

This sets the update policy for all registered DataBlock classes for every ReplicaObject. By default ReplicaNet will automatically update the each DataBlock when the Poll() method is called or regularly when using threads. However by calling this method with false will disable the automatic updates and the user must then call ProcessDataBlockUpdate() to update each DataBlock. This is useful if the user wants to uncouple the DataBlock updates from the internal ReplicaNet operations.

Parameters:
automatic Enable or disable automatic DataBlock updates. The default is true, which enables automatic updates.

void RNReplicaNet::ReplicaNet::SetDataRetention const bool  enable = false  ) 
 

Allows the raw data retention policy to be configured. By default ReplicaNet will discard raw data packets from the DataSend() or DataReceive() mechanism.

Parameters:
enable Set this to be true to enable retention of raw data packets. The default value is false, which means ReplicaNet will discard any raw data packets.

void RNReplicaNet::ReplicaNet::SetEncryption const bool  enable = false  ) 
 

Enables or disables encryption for this session

Parameters:
enable set this to be true to enable encryption for data sent from this session. The default is false

void RNReplicaNet::ReplicaNet::SetGameChannel const int  channel = TransportAnyGameChannel  ) 
 

Sets the current channel number. If no channel number is passed then TransportAnyGameChannel is used.

Parameters:
channel The channel number to use.

void RNReplicaNet::ReplicaNet::SetLatencyRecalculationDelay const float  seconds = 1.0f  ) 
 

This allows the latency recalculation delay to be set. The default value is 1 second meaning there is a ping packet sent every second.

Parameters:
seconds The number of seconds before latency is recalculated.

void RNReplicaNet::ReplicaNet::SetLoadBalancing const bool  enable = false  ) 
 

Enables or disables load balancing for this ReplicaNet session.

Parameters:
enable set this to true to enable load balancing. The default is false Once a session is created or joined this parameter cannot be changed.

void RNReplicaNet::ReplicaNet::SetManualPoll void   ) 
 

Sets the manual Poll() method for this class only.
For multi-threaded libraries this turns off the automatic polling method.
This allows an application to time exactly when polls are done.
Doing this allows the extrapolation and prediction routines to calculate a more reliable set of data to send to other sessions.
The application must call Poll() on a regular basis. A good place is just before or after the frame update is done.

void RNReplicaNet::ReplicaNet::SetManualPollXPSession void   ) 
 

This allows the poll method to be set for the XPSession layer that is used by this session.

void RNReplicaNet::ReplicaNet::SetManualPollXPURL void   ) 
 

This allows the poll method to be set for the XPURL layer that is used by this session.

void RNReplicaNet::ReplicaNet::SetMaximumLoad float  load = 0.0f  ) 
 

SetMaximumLoad() sets the maximum load that the current session ID will try to have. This is specifically for when ReplicaNet::SetLoadBalancing(true) is used. Each object can have a 'load' value set by using ReplicaObject::SetLoadBalancing(true) and also setting the load value by using ReplicaObject::SetLoadScore(float). When the total load for the master objects for a session ID exceeds the SetMaximumLoad() value then the session tries to migrate objects to a session ID that has a smaller load. This allows a system to be scaled such that if the server cluster was becoming full then another machine in the cluster could be started and some objects would be migrated to the new machine. The definition and scale of load "units" is left to the user to define.

Parameters:
load the load in load "units" Once a session is created or joined this parameter cannot be changed.

void RNReplicaNet::ReplicaNet::SetNodeBuffers const bool  enable = false  ) 
 

Enables or disables buffering for this session node. With buffering enabled extra memory is used to improve multi-threaded performance when this node is used by another thread.

Parameters:
enable The default is false which disables extra buffering.

void RNReplicaNet::ReplicaNet::SetObserver ReplicaObject *const   object = 0  ) 
 

Sets a ReplicaObject as the observer for this ReplicaNet session.

Parameters:
object the object to use as an observer. Pass in NULL or omit the parameter to unset the observer.

void RNReplicaNet::ReplicaNet::SetOnSessionError const OnError  whatToDo = kMigrateObjects  ) 
 

If a session error happens then this enables the user to decide if all ReplicaObjects should be tested for migration to this session. A session error happens when the master session disconnects and a new master cannot be found.

Parameters:
enable Set this to be true if all objects should be tested for migration to this session on an error condition
The default is kMigrateObjects which takes all the objects from other sessions and converts them to be master objects if possible.
kDeleteObjects Causes objects that belong to other sessions to be deleted.
kLeaveObjects Causes objects that belong to other sessions to be unchanged and no migration checks are used.
Once a session is created or joined this parameter cannot be changed.

void RNReplicaNet::ReplicaNet::SetPlaybackAllowMasterReplicaObjects const bool  allow = false  ) 
 

When playing back a recorded session the defines the if a recorded master ReplicaObject derived classes is kept as a master or is marked as a replica. For some applications it may be useful to always playback classes as replicas so that the application code does not try to control what was a master class.

Parameters:
allow If this is true, what were recorded master classes will stay as masters. If this is false, what were master classes will be replicas when the recorded session is played back. The default is false.

void RNReplicaNet::ReplicaNet::SetPlaybackSpeed const float  speed = 1.0f  ) 
 

Sets the speed of the playback.

Parameters:
speed The speed for the playback. Smaller values produce slower playback and larger values produce faster playback. The default is 1.0.

void RNReplicaNet::ReplicaNet::SetPollLayerBelow bool  enable = true  ) 
 

This allows the user to determine if during a Poll() the layer below also gets called. For single threaded applications this function has no effect as the layer below always has the Poll() called. The default is true.
The layer below in this case is XPSession.

Parameters:
enable Enable or disable layer below polling.

void RNReplicaNet::ReplicaNet::SetPollLayerBelowForXPSession bool  enable = true  ) 
 

This calls XPSession::SetPollLayerBelow(). Please see the documentation in XPSession for more information. The default is true.

Parameters:
enable Enable or disable layer below polling.

void RNReplicaNet::ReplicaNet::SetPreConnect const bool  enable = false  ) 
 

Enables or disables the pre-connect mechanism for session nodes that are joining a session. When this mechanism is enabled the joining session node will be able to exchange packets with the master session node before the node properly joins the session. The function PreConnectHasFinished() can be called to signal that the node wishes to complete a connect to the session. This function should only be used before a session node is used to join the session. The function IsStable() will not return true until the pre-connect is finished.
The intended for this mechanism is as follows:
1) SetPreConnect(true) and attempts to join a session.
2) When GetPreConnectStatus() returns true after this session node starts a join then this session node is in a pre-connect state.
3) This node will send one or more user defined packets that signal that the session wants to exchange certain pre-connect data to the master session using DataSendToSession() and session ID kReplicaNetUnknownUniqueID. Using the reliable packet type is recommended but not mandatory.
4) The master session will receive user data packets and detecting that pre-connect data has been received will in reply send a user data message to the effect that it has received this information.
5) The joining node receives pre-connect data from the master session, verifies the data and either completes the pre-connect by calling PreConnectHasFinished() or uses Disconnect() to abort the connection.

Parameters:
enable Set this to be true to enable the pre-connect mechanism for this session node. If false then the session node will discard all pre-connect packets and the preconnection mechanism is assumed to be disabled. The default is false.

void RNReplicaNet::ReplicaNet::StopSessionPlayback void   ) 
 

Stops playback of a recorded network session.

void RNReplicaNet::ReplicaNet::StopSessionRecord void   ) 
 

Stops recording the network session.

void RNReplicaNet::ReplicaNet::UnLockObjects void   ) 
 

This unlocks the object lists from a previous LockObjects() call


The documentation for this class was generated from the following file:
Generated on Sun Oct 30 01:11:58 2005 for ReplicaNet by  doxygen 1.4.1