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

RNReplicaNet::Transport Class Reference

#include <Transport.h>

List of all members.

Public Types

enum  Error { kTransport_EOK = 0, kTransport_EERROR = -1, kTransport_ECANTLISTENONCHANNEL = -2, kTransport_EWAITING = -3 }
enum  Bandwidth { kBandwidth_Off = 0, kBandwidth_Connection = 1 }

Public Member Functions

 Transport ()
virtual ~Transport ()
virtual int GetPacketsSent (const bool reset=false)
virtual int GetPacketsSentMerged (const bool reset=false)
virtual int GetPacketsSentSize (const bool reset=false)
virtual int GetPacketsReceived (const bool reset=false)
virtual int GetPacketsReceivedMerged (const bool reset=false)
virtual int GetPacketsReceivedSize (const bool reset=false)
virtual int GetPacketsLost (const bool reset=false)
virtual void SetBandwidthLimit (const Bandwidth enable=kBandwidth_Off)
virtual Bandwidth GetBandwidthLimit ()
virtual void SetMaximumOutputBandwidth (const int bytesPerSecond=0)
virtual int GetMaximumOutputBandwidth (void)
virtual void SetMaximumInputBandwidth (const int bytesPerSecond=0)
virtual int GetMaximumInputBandwidth (void)
virtual std::string GetPeerURL (void)
virtual bool GetTransportClosed (void)
virtual void SetEnableLANDiscovery (const bool enable=true)
virtual bool GetEnableLANDiscovery (void)
virtual std::string CanAccept (void)=0
virtual std::string CanRoute (void)=0
virtual std::string ExportURL (void)=0
virtual TransportAllocate (void)=0
virtual Error Listen (const int channel=TransportAnyGameChannel)=0
virtual Error Connect (const std::string address)=0
virtual TransportAccept (void)=0
virtual Error Send (const char *data, const int len)=0
virtual Error SendReliable (const char *data, const int len)=0
virtual Error SendCertain (const char *data, const int len)=0
virtual int Recv (char *const data, const int maxlen)=0
virtual int GetMaxPacketSize (void)=0
virtual std::string HandleDiscovery (void)=0
virtual void HandleDiscoveryReply (const std::string reply)=0
virtual void BeginDiscovery (void)=0
virtual std::string GetNextDiscovery (void)=0
virtual Error GetStatus (void)=0


Detailed Description

A virtual base class that defines a transport layer. Each new Transport is a potential connection to the outside world or a method by which a machine can connect to another machine. Each transport can use any means necessary to accomplish this connection. Each new implementation of a transport class must support the operation of the base class pure virtual members. Naturally a transport need not support the virtual members as default values are returned for these.
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::Transport::Error
 

Standard Transport errors

Enumeration values:
kTransport_EOK  No error
kTransport_EERROR  A fatal error happened, like the connection broke and cannot be recovered
kTransport_ECANTLISTENONCHANNEL  Non-fatal, the transport couldn't listen on the channel. The usual response by the user is to then try to listen on AnyGameChannel
kTransport_EWAITING  Non-fatal, the transport is in the process of waiting to connect or for a connection or to listen


Constructor & Destructor Documentation

RNReplicaNet::Transport::Transport  ) 
 

The ctor performs some basic initialisation

virtual RNReplicaNet::Transport::~Transport  )  [virtual]
 

The dtor makes sure everything is tidy


Member Function Documentation

virtual Transport* RNReplicaNet::Transport::Accept void   )  [pure virtual]
 

Accepts the first pending connection from another Transport

Returns:
returns NULL if there are no pending Transport connections or a new Transport pointer that can be used to communicate with

virtual Transport* RNReplicaNet::Transport::Allocate void   )  [pure virtual]
 

Used to allocate a transport of the relevant class type

Returns:
a Transport pointer

virtual void RNReplicaNet::Transport::BeginDiscovery void   )  [pure virtual]
 

This starts the discovery cycle to try to find other transports

virtual std::string RNReplicaNet::Transport::CanAccept void   )  [pure virtual]
 

Enables a Transport to state which type of protocol it can receive. Each protocol type is separated by a comma.

Returns:
the comma separated list of protocols supported by the Transport

virtual std::string RNReplicaNet::Transport::CanRoute void   )  [pure virtual]
 

Enables a Transport to state which type of protocol it can route. Each protocol type is separated by a comma.

Returns:
the comma separated list of protocols routed by the Transport

virtual Error RNReplicaNet::Transport::Connect const std::string  address  )  [pure virtual]
 

Tries to connect to a specified address

Parameters:
address the address to connect to
Returns:
A Transport::Error is returned indicating success or failure for the operation

virtual std::string RNReplicaNet::Transport::ExportURL void   )  [pure virtual]
 

Exports a URL that is used by this transport and can be used by other Transports to locate this transport.

Returns:
the URL to locate this transport

virtual Bandwidth RNReplicaNet::Transport::GetBandwidthLimit  )  [virtual]
 

Reads the configuration value set by SetBandwidthLimit()

Returns:
the configured value

virtual bool RNReplicaNet::Transport::GetEnableLANDiscovery void   )  [virtual]
 

Reads the configuration value set by SetEnableLANDiscovery().

Returns:
the configured value.

virtual int RNReplicaNet::Transport::GetMaximumInputBandwidth void   )  [virtual]
 

Reads the configuration value set by GetMaximumInputBandwidth().

Returns:
the configured value.

virtual int RNReplicaNet::Transport::GetMaximumOutputBandwidth void   )  [virtual]
 

Reads the configuration value set by SetMaximumOutputBandwidth()

Returns:
the configured value

virtual int RNReplicaNet::Transport::GetMaxPacketSize void   )  [pure virtual]
 

Gets the maximum packet size that can be transmitted over this Transport. The base spec requires a Transport to cope with packets of at least the number of bytes defined by TransportMinimumPacketSize

Returns:
the maximum packet size that can be transmitted

virtual std::string RNReplicaNet::Transport::GetNextDiscovery void   )  [pure virtual]
 

This is the function that can be used to discover other similar transports that can be connected to.

Returns:
Returns a URL, which is the URL passed in by HandleDiscoveryReply()

virtual int RNReplicaNet::Transport::GetPacketsLost const bool  reset = false  )  [virtual]
 

Gets the total number of packets that were lost and had to be resent.

Parameters:
reset The default parameter for this function is false. If true then the value is returned as normal but the internal total is reset to zero
Returns:
Returns the total value, since the last reset to zero

virtual int RNReplicaNet::Transport::GetPacketsReceived const bool  reset = false  )  [virtual]
 

Gets the total number of packets that were received.

Parameters:
reset The default parameter for this function is false. If true then the value is returned as normal but the internal total is reset to zero
Returns:
Returns the total value, since the last reset to zero

virtual int RNReplicaNet::Transport::GetPacketsReceivedMerged const bool  reset = false  )  [virtual]
 

Gets the total number of merged packets that were received.

Parameters:
reset The default parameter for this function is false. If true then the value is returned as normal but the internal total is reset to zero
Returns:
Returns the total value, since the last reset to zero

virtual int RNReplicaNet::Transport::GetPacketsReceivedSize const bool  reset = false  )  [virtual]
 

Gets the total size of packets that were received.

Parameters:
reset The default parameter for this function is false. If true then the value is returned as normal but the internal total is reset to zero
Returns:
Returns the total value, since the last reset to zero

virtual int RNReplicaNet::Transport::GetPacketsSent const bool  reset = false  )  [virtual]
 

Gets the total number of packets that were sent.

Parameters:
reset The default parameter for this function is false. If true then the value is returned as normal but the internal total is reset to zero
Returns:
Returns the total value, since the last reset to zero

virtual int RNReplicaNet::Transport::GetPacketsSentMerged const bool  reset = false  )  [virtual]
 

Gets the total number of merged packets that were sent.

Parameters:
reset The default parameter for this function is false. If true then the value is returned as normal but the internal total is reset to zero
Returns:
Returns the total value, since the last reset to zero

virtual int RNReplicaNet::Transport::GetPacketsSentSize const bool  reset = false  )  [virtual]
 

Gets the total size of packets that were sent.

Parameters:
reset The default parameter for this function is false. If true then the value is returned as normal but the internal total is reset to zero
Returns:
Returns the total value, since the last reset to zero

virtual std::string RNReplicaNet::Transport::GetPeerURL void   )  [virtual]
 

If connected this gets the URL of the other transport. It is possible this function will return a null string when connected if the transport provider does not support this functionality.

Returns:
the URL of the peer transport.

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

Gets the status of this transport

Returns:
the status

virtual bool RNReplicaNet::Transport::GetTransportClosed void   )  [virtual]
 

If this returns false the transport was closed due to an error such as a timeout. If this returns true then the transport was gracefully closed without an error. The default is to return false.

virtual std::string RNReplicaNet::Transport::HandleDiscovery void   )  [pure virtual]
 

If a discovery is pending this will return the URL of the source machine that made a discovery request

Returns:
returns the URL of the machine attempting a discovery or a "" string

virtual void RNReplicaNet::Transport::HandleDiscoveryReply const std::string  reply  )  [pure virtual]
 

This function handles the reply URL that is passed back to the previous calling machine of HandleDiscovery()

Parameters:
reply the reply string to send

virtual Error RNReplicaNet::Transport::Listen const int  channel = TransportAnyGameChannel  )  [pure virtual]
 

Sets this Transport to listen on a certain channel. The default channel is defined as AnyGameChannel

Parameters:
channel the channel to listen on, for example DefaultGameChannel. This parameter need not be passed in, in which case AnyGameChannel is used.
Returns:
A Transport::Error is returned indicating success or failure for the operation

virtual int RNReplicaNet::Transport::Recv char *const   data,
const int  maxlen
[pure virtual]
 

Tries to receive data pending at this Transport. Data packets received by this method cannot be merged together.

Parameters:
data the data buffer to use
maxlen the maximum length of this data buffer
Returns:
the length of the data received or zero for no data pending

virtual Error RNReplicaNet::Transport::Send const char *  data,
const int  len
[pure virtual]
 

Tries to send data to the currently connected Transport via the "unreliable" method without using any form of packet loss correction.
This method of sending packets is very cheap since there is no packet loss correction.

Parameters:
data the data to send
len the length of the data to send
Returns:
A Transport::Error is returned indicating success or failure for the operation

virtual Error RNReplicaNet::Transport::SendCertain const char *  data,
const int  len
[pure virtual]
 

Tries to send data to the currently connected Transport via the "certain" method that guarantees delivery of packets but does not gaurantee the packet receive order is maintained.
This method is less expensive than the "reliable" method because send and receive order is not kept.

Parameters:
data the data to send
len the length of the data to send
Returns:
A Transport::Error is returned indicating success or failure for the operation

virtual Error RNReplicaNet::Transport::SendReliable const char *  data,
const int  len
[pure virtual]
 

Tries to send data to the currently connected Transport via the "reliable" method that guarantees packets are received in the same order they are sent.
This method of sending packets is the most expensive in terms of CPU time and memory buffers

Parameters:
data the data to send
len the length of the data to send
Returns:
A Transport::Error is returned indicating success or failure for the operation

virtual void RNReplicaNet::Transport::SetBandwidthLimit const Bandwidth  enable = kBandwidth_Off  )  [virtual]
 

Sets the bandwidth limit algorithm to be used for this Transport type.

Parameters:
enable The default parameter is kBandwidth_Off which disables any bandwidth limit for this Transport type. kBandwidth_Connection will turn on bandwidth calculation for each instance and connection using this Transport. For example, if there are five instances of this Transport type and kBandwidth_Connection is used with the maximum outgoing bandwidth to be 1000 bytes per second then the maximum combined bandwidth will capped to five times 1000 bytes per second, which is 5000 bytes per second.

virtual void RNReplicaNet::Transport::SetEnableLANDiscovery const bool  enable = true  )  [virtual]
 

Enables or disables LAN discovery of this transport type.

Parameters:
enable Set this to be true to enable LAN discovery. False will disable LAN discovery. The default is true.

virtual void RNReplicaNet::Transport::SetMaximumInputBandwidth const int  bytesPerSecond = 0  )  [virtual]
 

Sets the maximum input bandwidth for emulation.

Parameters:
bytesPerSecond the bandwidth in bytes per second. The default value is 0 meaning there is no limit.

virtual void RNReplicaNet::Transport::SetMaximumOutputBandwidth const int  bytesPerSecond = 0  )  [virtual]
 

Sets the maximum output bandwidth for emulation.

Parameters:
bytesPerSecond the bandwidth in bytes per second. The default value is 0 meaning there is no limit.


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