#include <XPSession.h>

Inheritance diagram for XPSession:

[legend]

Collaboration diagram for XPSession:

[legend]

Public Types
enum	Error { kXPSession_EOK = 0, kXPSession_EERROR = -1, kXPSession_ETRANSPORT_CLOSED = -2, kXPSession_ETRANSPORT_ERROR = -3 }

typedef int	GetSessionIDCallback (void *context)

Public Types inherited from MutexClass
enum	{ kNoOwnerThread = -1 }

Public Member Functions
	XPSession ()

virtual	~XPSession ()

void	Create (const std::string name)

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

std::string	ExportURL (const bool shortAddress=true)

void	Join (const std::string url)

void	Find (void)

void	Find (const std::string protocols)

std::string	EnumerateFound (void)

int	GetGameChannel (void)

void	SetGameChannel (const int channel=TransportAnyGameChannel)

int	GetSessionID (void)

bool	IsStable (void)

Error	GetStatus (void)

Error	GetSessionErrorReason (void)

void	DataSendToSession (const int sessionid, const char *data, const int length, const bool reliable=true, const bool certain=false, const bool ordered=false, const unsigned int band=0)

void	DataSendToSessionUnreliable (const int sessionid, const char *data, const int length)

void	DataSendToSessionOrdered (const int sessionid, const char *data, const int length, const unsigned int band=0)

void	DataSendToSessionReliable (const int sessionid, const char *data, const int length, const unsigned int band=0)

void	DataSendToSessionCertain (const int sessionid, const char *data, const int length)

bool	DataReceivePeek (int const fromsessionid, int const length, unsigned char *const type=0)

bool	DataReceive (int const fromsessionid, char const data, int const length, unsigned char const type=0)

bool	IsMaster (void)

int	GetJoiner (void)

int	GetLeaver (void)

SysTimeType	GetTime (void)

SysTimeType	GetLocalTime (void)

float	GetNetworkSendRate (void)

float	GetNetworkReceiveRate (void)

int	GetNetworkPacketsLost (void)

int	GetNetworkPacketsRejected (void)

void	Poll (void)

void	SetPollLayerBelow (bool enable=true)

bool	GetPollLayerBelow (void)

void	SetManualPoll (void)

void	SetAutomaticPoll (void)

void	SetManualPollXPURL (void)

void	SetAutomaticPollXPURL (void)

void	SetCanSpider (const bool canSpider=true)

bool	GetCanSpider (void)

void	SetCanBecomeMaster (const bool canBeMaster=true)

bool	GetCanBecomeMaster (void)

float	GetLatencyToMasterSession (void)

float	GetLatencyToSessionID (const int sessionID)

void	SetLatencyRecalculationDelay (const float seconds=1.0f)

void	SetEncryption (const bool enable=false)

bool	GetEncryption (void)

void	Disconnect (const int sessionID=kXPSessionUnknownID)

bool	GetPreConnectStatus (void)

void	SetPreConnect (const bool enable=false)

bool	GetPreConnect (void)

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

void	SetAllowConnections (const bool allow=true)

bool	GetAllowConnections (void)

void	SetNodeBuffers (const bool enable=false)

bool	GetNodeBuffers (void)

void	RegisterSessionIDCallback (GetSessionIDCallback callback=0, void context=0)

void	SetProxyMode (const bool enable=false)

bool	GetProxyMode (void)

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

int	GetLargePacketCompressionLevel (void) const

void	SetTransparentPacketCompression (const int level=0)

int	GetTransparentPacketCompression (void)

Public Member Functions inherited from XPURL
	XPURL ()

virtual	~XPURL ()

void	BeginEnumerateTransports (void)

Transport *	EnumerateTransports (void)

std::string	ParseURLs (const std::string urls)

void	Poll (void)

void	SetManualPoll (void)

void	SetAutomaticPoll (void)

Public Member Functions inherited from MessageHelper
	MessageHelper ()

virtual	~MessageHelper ()

void	SetBuffer (void *const buffer)

void *	GetBuffer (void) const

void *	GetCurrentPosition (void) const

virtual void	AddVariable (const void *variable, const int size)

virtual void	AddData (const void *data, const int size)

void	GetVariable (void *const variable, const int size)

void	GetData (void *const data, const int size)

void	SkipData (const int size)

int	GetSize (void) const

void	SetSize (const int size)

void	AddInteger (const int value)

void	AddFloat (const float value)

int	GetInteger (void)

float	GetFloat (void)

std::string	DumpAsHex (const bool csv=true) const

void	SetGuardSize (const int size=-1)

void	SanityCheckGuardSize (const int newSize=0)

int	GetLastSizeAdded (void) const

template<typename T >
void	operator<< (const T &rhs)

template<typename T >
void	operator>> (T &rhs)

void	operator<< (const char *rhs)

void	operator<< (const std::string &rhs)

void	operator>> (std::string &rhs)

void	operator<< (const bool &rhs)

void	operator>> (bool &rhs)

Public Member Functions inherited from ThreadClass
	ThreadClass ()

virtual	~ThreadClass ()

void	Sleep (int milliseconds)

Public Member Functions inherited from MutexClass
	MutexClass ()

virtual	~MutexClass ()

void	Lock (void)

void	UnLock (void)

Static Public Member Functions
static XPSession *	Allocate (void)

Static Public Member Functions inherited from XPURL
static void	RegisterTransport (Transport &transport)

static void	RegisterDefaultTransports (void)

static Transport *	FindTransport (const std::string url)

static bool	FreeTransport (Transport *transport)

static void	InitialiseNetwork (const bool hardware=false)

static void	ShutdownNetwork (const bool hardware=false)

static DebugHandler *	RegisterDebugHandler (DebugHandler *debugHandler=0)

static DebugHandler *	GetDebugHandler (void)

Static Public Member Functions inherited from MessageHelper
static void	AddVariable (void buffer, const void variable, const int size)
	Adds data to a buffer with endian checking.

static void	GetVariable (const void buffer, void const variable, const int size)
	Adds data from a buffer with endian checking.

static int	GetInt (const void *buffer, const int offset)

static short	GetShort (const void *buffer, const int offset)

static void	SetInt (void *buffer, const int offset, const int value)

static void	SetShort (void *buffer, const int offset, const short value)

static std::string	DumpAsHex (const void *data, const int size, const bool csv=true)

Friends
struct	Route

Additional Inherited Members
Protected Member Functions inherited from ThreadClass
void	DoQuitNow (const int returnCode)

virtual void	ThreadExiting (const int returnCode)

void	CheckQuit (void)

Static Protected Member Functions inherited from ThreadClass
static size_t	GetNumAllocated (void)

Protected Attributes inherited from MessageHelper
int	mLastSizeAdded

Detailed Description

A network session class. This handles session nodes joining and leaving a session.
This is a general purpose class for interfacing with the known transports and maintaining a stable interface between various connected nodes. This class enables packets of data to be sent to a specific session node ID or to all session nodes as a broadcast. A session node is usually an individual computer or instance of this class. In addition to this the class also offers a standard time interface that gives a synchronised shared between all connected nodes. Sessions also have the option to make spider connections to other sessions directly. If enabled this means that sessions will attempt to use the shortest and quickest route for messages rather than relaying all messages through the master session. What this means in the real world is that a session that uses SetCanSpider(true) is advertising its self as being able to accept connections from other peers in the network topology. When a new session joins a spidering session will be told the new session has joined and advertise the peer connection service. If there is a fault with one of the session then the remaining sessions, if they have peer connections, will still be able to send messages around the gap in the network topology. Another session is then chosen to be the new overall session master. An XPSession is used as the main basis for a ReplicaNet session.
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.

Member Enumeration Documentation

enum Error

Standard XPSession errors

Enumerator
kXPSession_EOK	No error
kXPSession_EERROR	A fatal error happened, like the connection broke and cannot be recovered

Constructor & Destructor Documentation

XPSession ( )

The ctor for an XPSession

virtual ~XPSession ( )

virtual

The dtor for an XPSession This cleans up everything for this class

Member Function Documentation

static XPSession* Allocate ( void )

static

Allocates a new session to be used

Returns: the new session that is allocated

void Create ( const std::string name )

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

Parameters

name	The name to give to this session. The maximum length of this string is 128 characters.

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

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

Parameters

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

bool DataReceive	(	int *const	fromsessionid,
		char *const	data,
		int *const	length,
		unsigned char *const	type = `0`
	)

Receives data and responds with what session sent this data.

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 will be kXPSessionPacketType_Unreliable, kXPSessionPacketType_Certain, kXPSessionPacketType_Reliable or kXPSessionPacketType_Ordered. This parameter can be null in which case the type is not filled in. The default value for this pointer is null.

Returns: returns true if data was received. If false the entry parameters to this function are unchanged.

bool DataReceivePeek	(	int *const	fromsessionid,
		int *const	length,
		unsigned char *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 will be kXPSessionPacketType_Unreliable, kXPSessionPacketType_Certain, kXPSessionPacketType_Reliable or kXPSessionPacketType_Ordered. This parameter can be null in which case the type is not filled in. The default value for this pointer is null.

Returns: returns true if data was received. If false the entry parameters to this function are unchanged.

void DataSendToSession	(	const int	sessionid,
		const char *	data,
		const int	length,
		const bool	reliable = `true`,
		const bool	certain = `false`,
		const bool	ordered = `false`,
		const unsigned int	band = `0`
	)

Sends data from this session to any other session via its ID or to all sessions by using XPSessionBroadcastID. If the node is in a pre-connect state and wants to send data to the master session then use kXPSessionUnknownID as the session ID to send to.
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. Transport::GetMaxPacketSize() is used with the current connection instance to calculate if a packet needs to be sent as chunks. A sessionID will not receive any data sent to itself either by using its own sessionID or from a broadcast.
The other functions DataSendToSessionXXX use this function

Parameters

sessionid	the session id to send to or XPSessionBroadcastID.
data	the pointer to the data to send
length	the length of the data to send.
reliable	a flag to make this packet reliable, the default is true
certain	a flag to make this packet certain, the default is false
ordered	a flag to make this packet ordered, the default is false
band	The band to use for the underlying Transport when sending with the Reliable method.

void DataSendToSessionCertain	(	const int	sessionid,
		const char *	data,
		const int	length
	)

Sends data using the 'Certain' packet type from this session to any other session via it's ID or to all sessions by using XPSessionBroadcastID

Parameters

sessionid	the session id to send to or XPSessionBroadcastID
data	the pointer to the data to send
length	the length of the data to send.

void DataSendToSessionOrdered	(	const int	sessionid,
		const char *	data,
		const int	length,
		const unsigned int	band = `0`
	)

Sends data using the 'Unreliable ordered' packet type from this session to any other session via it's ID or to all sessions by using XPSessionBroadcastID

Parameters

sessionid	the session id to send to or XPSessionBroadcastID
data	the pointer to the data to send.
length	the length of the data to send.
band	The band to use for the underlying Transport when sending with the Reliable method.

void DataSendToSessionReliable	(	const int	sessionid,
		const char *	data,
		const int	length,
		const unsigned int	band = `0`
	)

Sends data using the 'Reliable' packet type from this session to any other session via it's ID or to all sessions by using XPSessionBroadcastID

Parameters

sessionid	the session id to send to or XPSessionBroadcastID
data	the pointer to the data to send.
length	the length of the data to send.
band	The band to use for the underlying Transport when sending with the Reliable method.

void DataSendToSessionUnreliable	(	const int	sessionid,
		const char *	data,
		const int	length
	)

Sends data using the 'Unreliable' packet type from this session to any other session via it's ID or to all sessions by using XPSessionBroadcastID

Parameters

sessionid	the session id to send to or XPSessionBroadcastID
data	the pointer to the data to send.
length	the length of the data to send.

void Disconnect ( const int sessionID = kXPSessionUnknownID )

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 to other nodes if it is enabled.

Parameters

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

std::string EnumerateFound ( void )

Enumerates any found sessions

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

std::string ExportURL ( const bool shortAddress = true )

Exports a URL that can be used to connect to this session in future. The format of the URL is as follows:
"SESSION://" the URL header.
Any number of exported Transport URLs separated with a '/'. Transport URLs are in the format "Transport type""address"
The standard XPSession brace block which contains: {SESSIONNAME=<session name>="">}
Any number of user defined brace blocks.
An example is as follows: SESSION://UDP@127.0.0.1:4000/{SESSIONNAME=Game}

Parameters

shortAddress If this is true then only the short address for this session is exported. The short address only contains the address of the master listen transports, the long address also contains the listen addresses for the spider connections if they are available. By default the short address is exported.

Returns: the URL for this session

void Find ( void )

Tries to find sessions using the default protocols

void Find ( 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@"

bool GetAllowConnections ( void )

Returns the value configured by SetAllowConnections() the value.

bool GetAutomaticPacketCompression ( void )

Gets the value configured by SetAutomaticPacketCompression()

Returns: Returns true if 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.
Note: This function can take some time to execute when there are hundreds of connected users.

Parameters

sessionID	The session ID of the required node.
bandwidth	A pointer to accept the Transport::Bandwidth value, this can be null.
output	A pointer to accept the output bandwidth value, this can be null.
input	A pointer to accept the input bandwidth value, this can be null.

Returns: Success returns true, failure returns false.

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.

bool GetEncryption ( void )

Gets the status of the encryption flag for this session

int GetGameChannel ( void )

Gets the current channel number for this session

Returns: the channel number

int GetJoiner ( void )

Gets the session id that recently joined the network session

Returns: the session id or kXPSessionUnknownID to indicate no more session ids changed

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.

int GetLeaver ( void )

Gets the session id that left the network session

Returns: the session id or kXPSessionUnknownID to indicate no more session ids changed

SysTimeType GetLocalTime ( void )

Gets the current local time. This time is local to the session and is not synchronised to the session master clock.

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

Returns: the master session unique ID

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.
Note: This function can take some time to execute when there are hundreds of connected users.

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 that are lost and lost and resent

Returns: number of packets

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.

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

Gets 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 XPSession encounters a session error.

Returns: The error can be:
kXPSession_EOK for when there is no session error.
kXPSession_EERROR for undefined errors.
kXPSession_ETRANSPORT_CLOSED for when the session is disconnected or closed.
kXPSession_ETRANSPORT_ERROR when the session is abnormally terminated due to a transport timeout.

int GetSessionID ( void )

Gets the session unique ID

Returns: the session unique ID

Error GetStatus ( void )

Gets the session status. A session error happens when the master session disconnects and a new master cannot be found.

Returns: the session status will be either kXPSession_EOK or kXPSession_EERROR.

SysTimeType GetTime ( void )

Gets the current system time of this ReplicaNet session synchronised with the time on the session master.

Returns: the float time 1.0 units == 1 second

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.

Returns: The URL in the same format supplied by Transport::GetPeerURL()

bool IsMaster ( void )

Tests to see if this session is a master session

Returns: returns true is the session is a master session, false if not

bool IsStable ( void )

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

Returns: returns true if the session is stable

void Join ( const std::string url )

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

Parameters

url	the url of the session to connect to

void Poll ( void )

This polls XPSession. Normally an application will yield enough time during threads for XPSession 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 XPSession::Poll() to yield some time to XPSession to perform housekeeping.
Single threaded considerations:
When using the single threaded libraries this method should be called regularly. Unless ReplicaNet::Poll() is called in which case this Poll() method is already called.

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 RegisterSessionIDCallback	(	GetSessionIDCallback *	callback = `0`,
		void *	context = `0`
	)

Registers a callback for the user to create their own sessionIDs. The handle can be used by the user to store context specific data and is passed to the registered callback function. The user must guarantee that the calculated sessionID is greater than 0 and less than 32768 and is unique for the entire network session.

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

void SetAutomaticPollXPURL ( void )

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

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
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 to be true also automatically sets SetCanBecomeMaster() and SetCanSpider() to be false.

Parameters

isClient The default value is false.

void SetEncryption ( const bool enable = false )

Enables or disables encryption for this session

Parameters

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

void SetGameChannel ( const int channel = TransportAnyGameChannel )

Sets the current channel number for this session. 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 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.
The application must call Poll() on a regular basis. A good place is just before or after the frame update is done.

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 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 SetPacketCompressionLevel ( const int level = 10 )

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

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

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.
The intended for this mechanism is as follows:
1) SetPreConnect(true) and attempts to join a session. All calls to GetSessionID() will return kXPSessionUnknownID 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 kXPSessionUnknownID. 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 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. See Transport::SetTransparentPacketCompression() for more details. Note: If this compression method is enabled then use SetAutomaticPacketCompression(false) and SetEncryption(false) for best performance.

Public Types

Public Member Functions

Static Public Member Functions

Friends

Additional Inherited Members

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation