RNReplicaNet::ReplicaNet

ReplicaNet Class Reference

#include <ReplicaNet.h>

Collaboration diagram for 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, kMigrateObjectsToNewMaster }

Public Member Functions

 ReplicaNet ()
virtual ~ReplicaNet ()
virtual void PreRegisterReplicas (void)
int GetSessionID (void)
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)
void SessionFind (const std::string protocols)
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)
ReplicaObject * GetObserver (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)
float GetLatencyToSessionID (const int sessionID)
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)
ReplicaObject * ObjectListIterate (void)
ReplicaObject * ObjectListFind (const int sessionID, const int uniqueID)
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, const unsigned int band=0)
bool DataReceive (int *const fromsessionid, void *const data, int *const length, PacketType *const type=0)
bool DataReceivePeek (int *const fromsessionid, 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 ReplicaObject * CallBackAllocate (const int classID, const int sessionID, const int uniqueID)
virtual ReplicaObject * CallBackDelete (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 void CallbackPlaybackAdvanceToFinished (void)
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)
virtual void CallbackMasterSessionIDChanged (const int previousSessionID)

Static Public Member Functions

static ReplicaNet * GetCurrentReplicaNet (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 Error

Standard ReplicaNet errors

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

Constructor & Destructor Documentation

ReplicaNet (  ) 

The ctor performs some basic initialisation

virtual ~ReplicaNet (  )  [virtual]

The dtor makes sure everything is tidy

Member Function Documentation

virtual void 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.

static ReplicaNet* GetCurrentReplicaNet ( void   )  [static]

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

Returns:
returns the current ReplcaNet class in use

static void SetCurrentReplicaNet ( ReplicaNet *const   replicanet  )  [static]

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

Parameters:
replicanet the ReplicaNet class pointer

int GetSessionID ( void   ) 

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

int GetGameChannel ( void   ) 

Gets the current channel number

Returns:
the channel number

void 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 SessionCreate ( const std::string  name  ) 

Creates a new session using the default available protocols.
When this ReplicaNet instance is disconnected from a session this ReplicaNet instance should be deleted and a new instance allocated before attempting to create or join a session.

Parameters:
name The name to give to the ReplicaNet session. The maximum length of this string is 128 characters.

void SessionCreate ( const std::string  name,
const std::string  protocols 
)

Creates a new session using the supplied protocols.
When this ReplicaNet instance is disconnected from a session this ReplicaNet instance should be deleted and a new instance allocated before attempting to create or join a session.

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

std::string SessionExportURL ( void   ) 

Exports a URL that can be used to connect to this session in future. See XPSession::ExportURL().

Returns:
the full URL for the ReplicaNet session

void SessionJoin ( const std::string  url  ) 

Tries to connect this session to the supplied URL
When this ReplicaNet instance is disconnected from a session this ReplicaNet instance should be deleted and a new instance allocated before attempting to create or join a session.

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

void SessionFind ( void   ) 

Tries to find sessions using the default protocols

void SessionFind ( const std::string  protocols  ) 

Tries to find sessions using the listed protocols

Parameters:
protocols The list of protocols to use separated by commas. e.g. "UDP@,STREAMTCPIP@"

std::string SessionEnumerateFound ( void   ) 

Enumerates any found sessions

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

void 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 UnLockObjects ( void   ) 

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

float GetNetworkSendRate ( void   ) 

Gets the current network send transfer rate in bytes per second

Returns:
bytes per second

float GetNetworkReceiveRate ( void   ) 

Gets the current network receive transfer rate in bytes per second

Returns:
bytes per second

int GetNetworkPacketsLost ( void   ) 

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

Returns:
the number of packets lost.

virtual float 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

virtual float 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

void SetObserver ( ReplicaObject *const   object = 0  ) 

Sets a ReplicaObject as the observer for this ReplicaNet session. Any ReplicaObject master or replica can be used as an observer. The ReplicaObject being observed should use the Reliable update type to ensure it is propagated correctly or be created and observed before the network session is created or joined. The object must have been published, registered on the network session, (using ReplicaObject::Publish()) before being observed, an assert will be generated in debug builds.

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

ReplicaObject* 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.

void 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 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.

bool 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()

void 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.

bool GetPollLayerBelowForXPSession ( void   ) 

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

Returns:
the state of XPSession::GetPollLayerBelow()

void 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 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 SetManualPollXPSession ( void   ) 

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

void SetAutomaticPollXPSession ( void   ) 

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

void SetManualPollXPURL ( void   ) 

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

void SetAutomaticPollXPURL ( void   ) 

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

void 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

void 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 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

bool GetCanSpider ( void   ) 

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

float 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. This is half round trip ping time.

Returns:
the latency to the master session

float GetLatencyToSessionID ( const int  sessionID  ) 

This allows the latency to the sessionID to be read. This is the time taken for a packet to reach the sessionID. This is half round trip ping time.

Returns:
the latency to the sessionID.

void 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.

bool IsStable ( void   ) 

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

Returns:
returns true if the session is stable

bool IsMaster ( void   ) 

Returns true if this ReplicaNet session is the master session

Returns:
true if this session is the master

void 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.

bool GetCanBecomeMaster ( void   ) 

Allows the state to be read

Returns:
the status of the becoming a master state

Error GetStatus ( void   ) 

Gets the session status.

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

Error 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.

void 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.
kMigrateObjectsToNewMaster Causes objects that belong to other sessions to migrate to the new master if the new master uses SetCanAcceptObjects(true).
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.

OnError GetOnSessionErrorMigrateObjects ( void   ) 

Allows the status of SetOnSessionErrorMigrateObjects() to be read

Returns:
the status of SetOnSessionErrorMigrateObjects()

void 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.

bool GetCanAcceptObjects ( void   ) 

Allows the status of SetCanAcceptObjects() to be read

Returns:
the status of SetCanAcceptObjects()

void 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

bool GetEncryption ( void   ) 

Gets the status of the encryption flag for this session

Returns:
true if encryption is enabled

void 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.

bool GetLoadBalancing ( void   ) 

Gets the status of the load balancing flag

Returns:
true if load balancing is enabled

void 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.

float 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

float 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

void ObjectListBeginIterate ( void   ) 

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

void ObjectListFinishIterate ( void   ) 

Unlocks the iterated list of objects.

ReplicaObject* 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.

ReplicaObject* ObjectListFind ( const int  sessionID,
const int  uniqueID 
)

Find a ReplicaObject using its sessionID and uniqueID.

Returns:
the pointer to the object known to this ReplicaNet session if it is found or returns null if it was not found.

virtual void 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 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 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.

virtual void 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.

void 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 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.

void 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. See also SetDataRetention().
The intended for this mechanism is as follows:
1) SetPreConnect(true) and attempts to join a session. All calls to GetSessionID() will return kReplicaNetUnknownUniqueID until after this session finishes the pre-connect and the master session transmits the correct sessionID.
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.

bool GetPreConnect ( void   ) 

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

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

void 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.

void 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.

bool GetDataRetention ( void   )  const

Allows the raw data retention policy to be read.

Returns:
The data retention policy.

void DataSend ( const int  sessionid,
const void *  data,
const int  length,
const PacketType  type = kPacket_Reliable,
const unsigned int  band = 0 
)

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().
Data packets larger than 512 bytes can be sent and received correctly however these large packets may cause a performance hit as the large chunk of data is sent. A sessionID will not receive any data sent to itself either by using its own sessionID or from a broadcast.

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.
type The type of data packet to send
band The band to use for the underlying Transport when sending with the Reliable method.

bool 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.
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

bool DataReceivePeek ( int *const   fromsessionid,
int *const   length,
PacketType *const   type = 0 
)<