#include <ReplicaNet.h>

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, kPacket_Ordered = 3 }

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)

int	GetNetworkPacketsRejected (void)

virtual SysTimeType	GetTime (void)

virtual SysTimeType	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 SysTimeType 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)

void	SetSessionIDCallback (const bool enable=false)

virtual int	CallbackGetSessionID (void)

virtual int	CallbackGetObjectUniqueID (ReplicaObject *object)

void	SetMaximumDataSize (const int bytes=64 *1024)

int	GetMaximumDataSize (void) const

void	SetPacketCompressionLevel (const int level=10)

void	SetLargePacketCompressionLevel (const int level=5)

int	GetPacketCompressionLevel (void)

int	GetLargePacketCompressionLevel (void)

void	SetTransparentPacketCompression (const int level=0)

int	GetTransparentPacketCompression (void)

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", "Unreliable ordered" and "Certain" are references to the four 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.
"Unreliable ordered" does not guarantee delivery of data but does guarantee the order of the data when it is received.
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

bool 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 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* 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. The ROL utility functions usually perform this task for you. If the returned ReplicaObject instance was constructed before the ReplicaNet instance it will not be linked to the ReplicaNet instance, so ReplicaObject::GetNewSessionIDAndUniqueID() must be called after ReplicaNet is created and before or during this callback.

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* 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 int CallbackGetObjectUniqueID ( ReplicaObject * object )

virtual

Gets the next object unique ID to use from this ReplicaNet class. This can be overridden to allow unique IDs to be calculated by the user. The user must guarantee that the calculated unqiueID is unique for the local instance of ReplicaNet. The full 32 bits can be used. If virtual methods from the ReplicaObject pointer need to be called then use ReplicaObject::SetDelayIDFetch(true) to avoid the situation where this callback can be triggered during ReplicaObject construction.

Returns: the next unique ID to use

virtual int CallbackGetSessionID ( void )

virtual

See SetSessionIDCallback(). This function is called from the thread context of XPSession. The user must guarantee that the calculated sessionID is greater than 0 and less than 32768 and is unique for the entire network session.

Returns: The session ID.

virtual void CallbackMasterSessionIDChanged ( const int previousSessionID )

virtual

This callback is called when a ReplicaNet session changes masterID.

virtual void CallbackPlaybackAdvanceToFinished ( void )

virtual

This callback is called when ReplicaNet finishes advancing to the time set by PlaybackAdvanceTo().

virtual bool 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 if playback is required.

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 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 if recording is required.

Parameters

data	The data to store.
length	The size in bytes of the data to store.

Returns: Success returns true, failure returns false.

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`
	)

This allows the parameters of the next pending received data to be read. The data is left waiting to be read by DataReceive.

Parameters

fromsessionid	The session id that sent this 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

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.

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

Returns the value configured by SetAllowConnections()

Returns: the value.

bool GetAutomaticPacketCompression ( void )

Gets the value configured by SetAutomaticPacketCompression()

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

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

Allows the status of SetCanAcceptObjects() to be read

Returns: the status of SetCanAcceptObjects()

bool GetCanBecomeMaster ( void )

Allows the state to be read

Returns: the status of the becoming a master state

bool GetCanSpider ( void )

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

bool GetClientOnly ( void )

Gets the client only configuration set by SetClientOnly().

Returns: The configuration set by SetClientOnly().

void 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* GetCurrentReplicaNet ( void )

static

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

Returns: returns the current ReplcaNet class in use

bool GetDataBlockUpdatePolicy ( void ) const

Returns the state set by SetDataBlockUpdatePolicy().

Returns: the state set by SetDataBlockUpdatePolicy().

bool GetDataRetention ( void ) const

Allows the raw data retention policy to be read.

Returns: The data retention policy.

bool GetEncryption ( void )

Gets the status of the encryption flag for this session

Returns: true if encryption is enabled

int GetGameChannel ( void )

Gets the current channel number

Returns: the channel number

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.

bool GetLoadBalancing ( void )

Gets the status of the load balancing flag

Returns: true if load balancing is enabled

virtual SysTimeType 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 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 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 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 GetNetworkPacketsLost ( void )

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

Returns: the number of packets lost.

int GetNetworkPacketsRejected ( void )

Gets the number of packets that have been rejected due to failing the checksum, decryption of decompression checks.

Returns: number of packets

float GetNetworkReceiveRate ( void )

Gets the current network receive transfer rate in bytes per second

Returns: bytes per second

float GetNetworkSendRate ( void )

Gets the current network send transfer rate in bytes per second

Returns: bytes per second

bool GetNodeBuffers ( void )

Returns the value configured by SetNodeBuffers()

Returns: The value.

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.

OnError GetOnSessionErrorMigrateObjects ( void )

Allows the status of SetOnSessionErrorMigrateObjects() to be read

Returns: the status of SetOnSessionErrorMigrateObjects()

bool GetPlaybackAllowMasterReplicaObjects ( void )

Returns the value configured by SetPlaybackAllowMasterReplicaObjects().

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

bool GetPollLayerBelowForXPSession ( void )

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

Returns: the state of XPSession::GetPollLayerBelow()

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.

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.

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.

int GetSessionID ( void )

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

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

Gets the session status.

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

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

int GetTransparentPacketCompression ( void )

Allows the setting for SetTransparentPacketCompression() to be read.

Returns: The setting for SetTransparentPacketCompression()

std::string 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 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 IsMaster ( void )

Returns true if this ReplicaNet session is the master session

Returns: true if this session is the master

bool IsStable ( void )

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

Returns: returns true if the session is stable

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

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

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.

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.

bool PlaybackAdvanceTo ( const SysTimeType 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 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 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 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 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 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 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 SessionEnumerateFound ( void )

Enumerates any found sessions

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

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 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@"

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 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 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 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 behavior is to enable multi-threading automatic polls,
The default single-threading library behavior is to use manual polls,

void SetAutomaticPollXPSession ( void )

This allows the poll method to be set for the XPSession 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 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 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 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 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 SetCurrentReplicaNet ( ReplicaNet *const replicanet )

static

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

Parameters

replicanet the ReplicaNet class pointer

void 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 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 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 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 SetLargePacketCompressionLevel ( const int level = 5 )

Sets the compression level to use when compressing large session packets that are split into chunks.

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.

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.

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 SetManualPollXPSession ( 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 SetMaximumDataSize ( const int bytes = 64 *1024 )

Sets the maximum size of data that can be sent or received. If a session sends more data than the recipient is willing to receive then the recipient can decide to disconnect the source session connection.

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.

void 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 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. If a session has an object set as an observer but the observed object has not arrived yet the session will not receive any distance based propagated objects. Only when the observed object arrives will distance based objects be propagated. Using the Reliable or Certain object update type will guarantee delivery of the object update. 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.

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.

void SetPacketCompressionLevel ( const int level = 10 )

Sets the compression level to use when compressing normal session packets.

void 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 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 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 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 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 pre-connection mechanism is assumed to be disabled. The default is false.

void SetSessionIDCallback ( const bool enable = false )

Enables or disables the CallbackGetSessionID() callback for the user to create their own sessionIDs.

void SetTransparentPacketCompression ( const int level = 0 )

Instead of using discrete data compression for each data packet sent using XPSession, use the Transport packet compression instead. This can result in higher compression ratios. This must be called before SessionCreate() or SessionJoin(). See Transport::SetTransparentPacketCompression() for more details. Note: If this compression method is enabled then use SetAutomaticPacketCompression(false) and SetEncryption(false) for best performance.

void StopSessionPlayback ( void )

Stops playback of a recorded network session.

void StopSessionRecord ( void )

Stops recording the network session.

void UnLockObjects ( void )

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

Public Types

Public Member Functions

Static Public Member Functions

Friends

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation