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

RNReplicaNet::XPSession Class Reference

#include <XPSession.h>

List of all members.

Public Types

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

Public Member Functions

 XPSession ()
virtual ~XPSession ()
virtual void Create (const std::string name)=0
virtual void Create (const std::string name, const std::string protocols)=0
virtual std::string ExportURL (const bool shortAddress=true)=0
virtual void Join (const std::string url)=0
virtual void Find (void)=0
virtual void Find (const std::string protocols)=0
virtual std::string EnumerateFound (void)=0
virtual int GetGameChannel (void)=0
virtual void SetGameChannel (const int channel=TransportAnyGameChannel)=0
virtual int GetSessionID (void)=0
virtual bool IsStable (void)=0
virtual Error GetStatus (void)=0
virtual Error GetSessionErrorReason (void)=0
virtual void DataSendToSession (const int sessionid, const char *data, const int length, const bool reliable=true, const bool certain=false)=0
virtual void DataSendToSessionUnreliable (const int sessionid, const char *data, const int length)=0
virtual void DataSendToSessionReliable (const int sessionid, const char *data, const int length)=0
virtual void DataSendToSessionCertain (const int sessionid, const char *data, const int length)=0
virtual bool DataReceive (int *const fromsessionid, char *const data, int *const length, unsigned char *const type=0)=0
virtual bool IsMaster (void)=0
virtual int GetJoiner (void)=0
virtual int GetLeaver (void)=0
virtual float GetTime (void)=0
virtual float GetLocalTime (void)=0
virtual float GetNetworkSendRate (void)=0
virtual float GetNetworkReceiveRate (void)=0
virtual int GetNetworkPacketsLost (void)=0
virtual void Poll (void)=0
virtual void SetPollLayerBelow (bool enable=true)=0
virtual bool GetPollLayerBelow (void)=0
virtual void SetManualPoll (void)=0
virtual void SetAutomaticPoll (void)=0
virtual void SetManualPollXPURL (void)=0
virtual void SetAutomaticPollXPURL (void)=0
virtual void SetCanSpider (const bool canSpider=true)=0
virtual bool GetCanSpider (void)=0
virtual void SetCanBecomeMaster (const bool canBeMaster=true)=0
virtual bool GetCanBecomeMaster (void)=0
virtual float GetLatencyToMasterSession (void)=0
virtual void SetLatencyRecalculationDelay (const float seconds=1.0f)=0
virtual void SetEncryption (const bool enable=false)=0
virtual bool GetEncryption (void)=0
virtual void Disconnect (const int sessionID=kXPSessionUnknownID)=0
virtual bool GetPreConnectStatus (void)=0
virtual void SetPreConnect (const bool enable=false)=0
virtual bool GetPreConnect (void)=0
virtual void PreConnectHasFinished (void)=0
virtual void SetAutomaticPacketCompression (const bool enable=false)=0
virtual bool GetAutomaticPacketCompression (void)=0
virtual void GetCompressionStatistics (int *const before=0, int *const after=0, const bool reset=false)=0
virtual void GetMergedStatistics (int *const sent=0, int *const received=0, const bool reset=false)=0
virtual int GetMasterSessionID (void)=0
virtual std::string GetURLFromSessionID (const int sessionID)=0
virtual void SetClientOnly (const bool isClient=false)=0
virtual bool GetClientOnly (void)=0
virtual bool GetBandwidthFromSessionID (const int sessionID, Transport::Bandwidth *const bandwidth, int *const output, int *const input)=0
virtual void SetAllowConnections (const bool allow=true)=0
virtual bool GetAllowConnections (void)=0
virtual void SetNodeBuffers (const bool enable=false)=0
virtual bool GetNodeBuffers (void)=0

Static Public Member Functions

static XPSessionAllocate (void)


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 RNReplicaNet::XPSession::Error
 

Standard XPSession errors

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


Constructor & Destructor Documentation

RNReplicaNet::XPSession::XPSession  )  [inline]
 

The ctor for an XPSession

virtual RNReplicaNet::XPSession::~XPSession  )  [inline, virtual]
 

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


Member Function Documentation

static XPSession* RNReplicaNet::XPSession::Allocate void   )  [static]
 

Allocates a new session to be used

Returns:
the new session that is allocated

virtual void RNReplicaNet::XPSession::Create const std::string  name,
const std::string  protocols
[pure virtual]
 

Creates a new session using the supplied protocols

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

virtual void RNReplicaNet::XPSession::Create const std::string  name  )  [pure virtual]
 

Creates a new session using the default protocols

Parameters:
name The name to give to this session

virtual bool RNReplicaNet::XPSession::DataReceive int *const   fromsessionid,
char *const   data,
int *const   length,
unsigned char *const   type = 0
[pure virtual]
 

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 with be kXPSessionPacketType_Unreliable, kXPSessionPacketType_Certain or kXPSessionPacketType_Reliable. 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

virtual void RNReplicaNet::XPSession::DataSendToSession const int  sessionid,
const char *  data,
const int  length,
const bool  reliable = true,
const bool  certain = false
[pure virtual]
 

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

virtual void RNReplicaNet::XPSession::DataSendToSessionCertain const int  sessionid,
const char *  data,
const int  length
[pure virtual]
 

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

virtual void RNReplicaNet::XPSession::DataSendToSessionReliable const int  sessionid,
const char *  data,
const int  length
[pure virtual]
 

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

virtual void RNReplicaNet::XPSession::DataSendToSessionUnreliable const int  sessionid,
const char *  data,
const int  length
[pure virtual]
 

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

virtual void RNReplicaNet::XPSession::Disconnect const int  sessionID = kXPSessionUnknownID  )  [pure virtual]
 

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.

virtual std::string RNReplicaNet::XPSession::EnumerateFound void   )  [pure virtual]
 

Enumerates any found sessions

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

virtual std::string RNReplicaNet::XPSession::ExportURL const bool  shortAddress = true  )  [pure virtual]
 

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

Parameters:
shortAddress If this is true then only the short address for this session is exported. By default the short address is exported
Returns:
the URL for this session

virtual void RNReplicaNet::XPSession::Find const std::string  protocols  )  [pure virtual]
 

Tries to find sessions using the listed protocols

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

virtual void RNReplicaNet::XPSession::Find void   )  [pure virtual]
 

Tries to find sessions using the default protocols

virtual bool RNReplicaNet::XPSession::GetAllowConnections void   )  [pure virtual]
 

Returns the value configured by SetAllowConnections() the value.

virtual bool RNReplicaNet::XPSession::GetAutomaticPacketCompression void   )  [pure virtual]
 

Gets the value configured by SetAutomaticPacketCompression()

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

virtual bool RNReplicaNet::XPSession::GetBandwidthFromSessionID const int  sessionID,
Transport::Bandwidth *const   bandwidth,
int *const   output,
int *const   input
[pure virtual]
 

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.

virtual bool RNReplicaNet::XPSession::GetCanBecomeMaster void   )  [pure virtual]
 

Allows the state to be read

Returns:
the status of the becoming a master state

virtual bool RNReplicaNet::XPSession::GetCanSpider void   )  [pure virtual]
 

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

virtual bool RNReplicaNet::XPSession::GetClientOnly void   )  [pure virtual]
 

Gets the client only configuration set by SetClientOnly().

Returns:
The configuration set by SetClientOnly().

virtual void RNReplicaNet::XPSession::GetCompressionStatistics int *const   before = 0,
int *const   after = 0,
const bool  reset = false
[pure virtual]
 

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.

virtual bool RNReplicaNet::XPSession::GetEncryption void   )  [pure virtual]
 

Gets the status of the encryption flag for this session

virtual int RNReplicaNet::XPSession::GetGameChannel void   )  [pure virtual]
 

Gets the current channel number for this session

Returns:
the channel number

virtual int RNReplicaNet::XPSession::GetJoiner void   )  [pure virtual]
 

Gets the session id that recently joined the network session

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

virtual float RNReplicaNet::XPSession::GetLatencyToMasterSession void   )  [pure virtual]
 

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

Returns:
the latency to the master session

virtual int RNReplicaNet::XPSession::GetLeaver void   )  [pure virtual]
 

Gets the session id that left the network session

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

virtual float RNReplicaNet::XPSession::GetLocalTime void   )  [pure virtual]
 

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

virtual int RNReplicaNet::XPSession::GetMasterSessionID void   )  [pure virtual]
 

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

Returns:
the master session unique ID

virtual void RNReplicaNet::XPSession::GetMergedStatistics int *const   sent = 0,
int *const   received = 0,
const bool  reset = false
[pure virtual]
 

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.

virtual int RNReplicaNet::XPSession::GetNetworkPacketsLost void   )  [pure virtual]
 

Gets the number of packets that are lost and lost and resent

Returns:
number of packets

virtual float RNReplicaNet::XPSession::GetNetworkReceiveRate void   )  [pure virtual]
 

Gets the current network receive transfer rate in bytes per second

Returns:
bytes per second

virtual float RNReplicaNet::XPSession::GetNetworkSendRate void   )  [pure virtual]
 

Gets the current network send transfer rate in bytes per second

Returns:
bytes per second

virtual bool RNReplicaNet::XPSession::GetNodeBuffers void   )  [pure virtual]
 

Returns the value configured by SetNodeBuffers()

Returns:
The value.

virtual bool RNReplicaNet::XPSession::GetPollLayerBelow void   )  [pure virtual]
 

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

virtual bool RNReplicaNet::XPSession::GetPreConnect void   )  [pure virtual]
 

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

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

virtual bool RNReplicaNet::XPSession::GetPreConnectStatus void   )  [pure virtual]
 

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.

virtual Error RNReplicaNet::XPSession::GetSessionErrorReason void   )  [pure virtual]
 

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.

virtual int RNReplicaNet::XPSession::GetSessionID void   )  [pure virtual]
 

Gets the session unique ID

Returns:
the session unique ID

virtual Error RNReplicaNet::XPSession::GetStatus void   )  [pure virtual]
 

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.

virtual float RNReplicaNet::XPSession::GetTime void   )  [pure virtual]
 

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

virtual std::string RNReplicaNet::XPSession::GetURLFromSessionID const int  sessionID  )  [pure virtual]
 

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

virtual bool RNReplicaNet::XPSession::IsMaster void   )  [pure virtual]
 

Tests to see if this session is a master session

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

virtual bool RNReplicaNet::XPSession::IsStable void   )  [pure virtual]
 

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

Returns:
returns true if the session is stable

virtual void RNReplicaNet::XPSession::Join const std::string  url  )  [pure virtual]
 

Tries to connect this session to the supplied URL

Parameters:
url the url of the session to connect to

virtual void RNReplicaNet::XPSession::Poll void   )  [pure virtual]
 

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.

virtual void RNReplicaNet::XPSession::PreConnectHasFinished void   )  [pure virtual]
 

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

virtual void RNReplicaNet::XPSession::SetAllowConnections const bool  allow = true  )  [pure virtual]
 

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

virtual void RNReplicaNet::XPSession::SetAutomaticPacketCompression const bool  enable = false  )  [pure virtual]
 

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.

virtual void RNReplicaNet::XPSession::SetAutomaticPoll void   )  [pure virtual]
 

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,

virtual void RNReplicaNet::XPSession::SetAutomaticPollXPURL void   )  [pure virtual]
 

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

virtual void RNReplicaNet::XPSession::SetCanBecomeMaster const bool  canBeMaster = true  )  [pure virtual]
 

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.

virtual void RNReplicaNet::XPSession::SetCanSpider const bool  canSpider = true  )  [pure virtual]
 

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

virtual void RNReplicaNet::XPSession::SetClientOnly const bool  isClient = false  )  [pure virtual]
 

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.

virtual void RNReplicaNet::XPSession::SetEncryption const bool  enable = false  )  [pure virtual]
 

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

virtual void RNReplicaNet::XPSession::SetGameChannel const int  channel = TransportAnyGameChannel  )  [pure virtual]
 

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.

virtual void RNReplicaNet::XPSession::SetLatencyRecalculationDelay const float  seconds = 1.0f  )  [pure virtual]
 

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.

virtual void RNReplicaNet::XPSession::SetManualPoll void   )  [pure virtual]
 

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.

virtual void RNReplicaNet::XPSession::SetManualPollXPURL void   )  [pure virtual]
 

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

virtual void RNReplicaNet::XPSession::SetNodeBuffers const bool  enable = false  )  [pure virtual]
 

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.

virtual void RNReplicaNet::XPSession::SetPollLayerBelow bool  enable = true  )  [pure virtual]
 

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.

virtual void RNReplicaNet::XPSession::SetPreConnect const bool  enable = false  )  [pure virtual]
 

Enables or disables the pre-connect mechanism for session nodes that are joining a session. When this mechanism is enabled the joining session node will be able to exchange packets with the master session node before the node properly joins the session. The function PreConnectHasFinished() can be called to signal that the node wishes to complete a connect to the session. This function should only be used before a session node is used to join the session. The function IsStable() will not return true until the pre-connect is finished.
The intended for this mechanism is as follows:
1) SetPreConnect(true) and attempts to join a session.
2) When GetPreConnectStatus() returns true after this session node starts a join then this session node is in a pre-connect state.
3) This node will send one or more user defined packets that signal that the session wants to exchange certain pre-connect data to the master session using DataSendToSession() and session ID 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.


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