#include <Transport.h>
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 Transport * | Allocate (void)=0 |
| virtual Error | Listen (const int channel=TransportAnyGameChannel)=0 |
| virtual Error | Listen (const std::string &address)=0 |
| virtual Error | Connect (const std::string address)=0 |
| virtual Transport * | Accept (void)=0 |
| virtual Error | Send (const char *data, const int len)=0 |
| virtual Error | SendOrdered (const char *data, const int len, const unsigned int band=0)=0 |
| virtual Error | SendReliable (const char *data, const int len, const unsigned int band=0)=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 |
| int | GetInstance (void) |
| virtual void | SetTransparentPacketCompression (const int level=0) |
| virtual int | GetTransparentPacketCompression (void) |
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 Error |
Standard Transport errors
Constructor & Destructor Documentation
| Transport | ( | ) |
The ctor performs some basic initialisation
|
virtual |
The dtor makes sure everything is tidy
Member Function Documentation
|
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
Implemented in TransportNATUDP.
|
pure virtual |
Used to allocate a transport of the relevant class type
- Returns
- a Transport pointer
Implemented in TransportNATUDP.
|
pure virtual |
This starts the discovery cycle to try to find other transports
Implemented in TransportNATUDP.
|
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
Implemented in TransportNATUDP.
|
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
Implemented in TransportNATUDP.
|
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
Implemented in TransportNATUDP.
|
pure virtual |
Exports a URL that is used by this transport and can be used by other Transports to locate this transport. The format of the URL follows this convention: <TransportType><data>/
- Returns
- the URL to locate this transport
Implemented in TransportNATUDP.
|
virtual |
Reads the configuration value set by SetBandwidthLimit()
- Returns
- the configured value
Reimplemented in TransportNATUDP.
|
virtual |
Reads the configuration value set by SetEnableLANDiscovery().
- Returns
- the configured value.
Reimplemented in TransportNATUDP.
| int GetInstance | ( | void | ) |
Gets the current instance of this Transport compared to all Transports allocated in this session.
|
virtual |
Reads the configuration value set by GetMaximumInputBandwidth().
- Returns
- the configured value.
Reimplemented in TransportNATUDP.
|
virtual |
Reads the configuration value set by SetMaximumOutputBandwidth()
- Returns
- the configured value
Reimplemented in TransportNATUDP.
|
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
Implemented in TransportNATUDP.
|
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()
Implemented in TransportNATUDP.
|
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
Reimplemented in TransportNATUDP.
|
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
Reimplemented in TransportNATUDP.
|
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
Reimplemented in TransportNATUDP.
|
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
Reimplemented in TransportNATUDP.
|
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
Reimplemented in TransportNATUDP.
|
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
Reimplemented in TransportNATUDP.
|
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
Reimplemented in TransportNATUDP.
|
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.
Reimplemented in TransportNATUDP.
|
pure virtual |
|
inlinevirtual |
Allows the setting for SetTransparentPacketCompression() to be read. Transports that do not support this functioanlity will always return 0 regardless of any calls to SetTransparentPacketCompression().
- Returns
- The setting for SetTransparentPacketCompression()
|
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.
Reimplemented in TransportNATUDP.
|
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
Implemented in TransportNATUDP.
|
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
Implemented in TransportNATUDP.
|
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
Implemented in TransportNATUDP.
|
pure virtual |
Sets this Transport to listen on a certain address. The default blank address is defined by the implemented Transport.
- Parameters
-
address The address to listen on prefixed by the transport's CanAccept() string.
- Returns
- A Transport::Error is returned indicating success or failure for the operation
Implemented in TransportNATUDP.
|
pure virtual |
Tries to receive data pending at this Transport. Data packets received by this method are not 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. If maxlen is too small the size of the next packet is still returned but the packet data is not returned. The next function call should use an increased maxlen size for the packet.
Implemented in TransportNATUDP.
|
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. Before attempting to send any data using this transport instance wait for GetStatus() to return kTransport_EOK.
- 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
Implemented in TransportNATUDP.
|
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 preserved. Before attempting to send any data using this transport instance wait for GetStatus() to return kTransport_EOK.
- 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
Implemented in TransportNATUDP.
|
pure virtual |
Tries to send data to the currently connected Transport via the "unreliable ordered" method without using any form of packet loss correction.
This method of sending packets is very cheap since there is no packet loss correction. Packets will be received at the destination in order. Before attempting to send any data using this transport instance wait for GetStatus() to return kTransport_EOK.
- Parameters
-
data the data to send len the length of the data to send band This optional parameter allows the user to send ordered packets and ensure they are in original order grouped by band. This parameter is optional for a Transport to support and if supported the Transport may only support a limited number of bands.
- Returns
- A Transport::Error is returned indicating success or failure for the operation
Implemented in TransportNATUDP.
|
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 Before attempting to send any data using this transport instance wait for GetStatus() to return kTransport_EOK.
- Parameters
-
data the data to send len the length of the data to send band This optional parameter allows the user to send reliable packets and ensure they are in original order grouped by band. This parameter is optional for a Transport to support and if supported the Transport may only support a limited number of bands.
- Returns
- A Transport::Error is returned indicating success or failure for the operation
Implemented in TransportNATUDP.
|
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.
Reimplemented in TransportNATUDP.
|
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.
Reimplemented in TransportNATUDP.
|
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.
Reimplemented in TransportNATUDP.
|
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.
Reimplemented in TransportNATUDP.
|
inlinevirtual |
Allows transparent packet compression to be enabled or disabled. Setting this on a Transport listener will enable accepted Transports to inherit this value. This will only have an effect before a Connect() or Accept() call.
- Parameters
-
enable The default is 0 which disables compression. A number between 1 and 10 will enable the extra packet compression where 1 is the fastest compression and 10 is the slowest and best compression. See XPCompression for details. Compression level 5 is a good trade-off between speed and compression.
