---

TNL::NetConnection Class Reference

TNL network connection base class. More...

#include <tnlNetConnection.h>

Inheritance diagram for TNL::NetConnection:

List of all members.

Adaptive Protocol
Functions and state for the adaptive rate protocol. TNL's adaptive rate uses rate control algorithms similar to TCP/IP's. There are a few state variables here that aren't documented.
void	setIsAdaptive ()
	Enables the adaptive protocol.
void	setFixedRateParameters (U32 minPacketSendPeriod, U32 minPacketRecvPeriod, U32 maxSendBandwidth, U32 maxRecvBandwidth)
	sets the fixed rate send and receive data sizes, and sets the connection to not behave as an adaptive rate connection
bool	isAdaptive ()
	Query the adaptive status of the connection.
virtual bool	isDataToTransmit ()
	Returns true if this connection has data to transmit.
Public Types
enum	NetConnectionTypeFlags { ConnectionToServer = BIT(0), ConnectionToClient = BIT(1), ConnectionAdaptive = BIT(2), ConnectionRemoteAdaptive = BIT(3) }
	Flags specifying the type of the connection instance. More...
enum	NetConnectionState {   NotConnected = 0, AwaitingChallengeResponse, SendingPunchPackets, ComputingPuzzleSolution,   AwaitingConnectResponse, ConnectTimedOut, ConnectRejected, Connected,   Disconnected, TimedOut }
	Connection state flags for a NetConnection instance. More...
Public Methods
U32	getNextSendSequence ()
	Returns the next send sequence that will be sent by this side.
U32	getLastSendSequence ()
	Returns the sequence of the last packet sent by this connection, or the current packet's send sequence if called from within writePacket().
void	setInitialRecvSequence (U32 sequence)
	Sets the initial sequence number of packets read from the remote host.
U32	getInitialRecvSequence ()
	Returns the initial sequence number of packets sent from the remote host.
U32	getInitialSendSequence ()
	Returns the initial sequence number of packets sent to the remote host.
void	connect (NetInterface *connectionInterface, const Address &address, bool requestKeyExchange=false, bool requestCertificate=false)
	Connect to a server through a given network interface.
bool	connectLocal (NetInterface *connectionInterface, NetInterface *localServerInterface)
	Connects to a server interface within the same process.
void	connectArranged (NetInterface *connectionInterface, const Vector< Address > &possibleAddresses, Nonce &myNonce, Nonce &remoteNonce, ByteBufferPtr sharedSecret, bool isInitiator, bool requestsKeyExchange=false, bool requestsCertificate=false)
	Connects to a remote host that is also connecting to this connection (negotiated by a third party).
void	disconnect (const char *reason)
	Sends a disconnect packet to notify the remote host that this side is terminating the connection for the specified reason.
bool	windowFull ()
	Returns true if the packet send window is full and no more data packets can be sent.
bool	isInitiator ()
	returns true if this object initiated the connection with the remote host
void	setInterface (NetInterface *myInterface)
	Sets the NetInterface this NetConnection will communicate through.
NetInterface *	getInterface ()
	Returns the NetInterface this connection communicates through.
void	setSymmetricCipher (SymmetricCipher *theCipher)
	Sets the SymmetricCipher this NetConnection will use for encryption.
virtual NetClassGroup	getNetClassGroup () const
	Returns the class group of objects that can be transmitted over this NetConnection.
void	setPingTimeouts (U32 msPerPing, U32 pingRetryCount)
	Sets the ping/timeout characteristics for a fixed-rate connection. Total timeout is msPerPing * pingRetryCount.
void	setSimulatedNetParams (F32 packetLoss, U32 latency)
	Simulates a network situation with a percentage random packet loss and a connection one way latency as specified.
void	setIsConnectionToServer ()
	Specifies that this NetConnection instance is a connection to a "server.".
bool	isConnectionToServer ()
	Returns true if this is a connection to a "server.".
void	setIsConnectionToClient ()
	Specifies that this NetConnection instance is a connection to a "client.".
bool	isConnectionToClient ()
	Returns true if this is a connection to a "client.".
bool	isLocalConnection ()
	Returns true if the remote side of this connection is a NetConnection instance in on the same host.
bool	isNetworkConnection ()
	Returns true if the remote side if this connection is on a remote host.
F32	getRoundTripTime ()
	Returns the running average packet round trip time.
F32	getOneWayTime ()
	Returns have of the average of the round trip packet time.
const Address &	getNetAddress ()
	Returns the remote address of the host we're connected or trying to connect to.
const char *	getNetAddressString () const
	Returns the remote address in string form.
void	setNetAddress (const Address &address)
	Sets the address of the remote host we want to connect to.
NetError	sendPacket (BitStream *stream)
	Sends a packet that was written into a BitStream to the remote host, or the mRemoteConnection on this host.
bool	checkTimeout (U32 time)
	Checks to see if the connection has timed out, possibly sending a ping packet to the remote host. Returns true if the connection timed out.
void	checkPacketSend (bool force, U32 currentTime)
	Checks to see if a packet should be sent at the currentTime to the remote host.
void	setConnectionState (NetConnectionState state)
	Sets the current connection state of this NetConnection.
NetConnectionState	getConnectionState ()
	Gets the current connection state of this NetConnection.
bool	isEstablished ()
	Returns true if the connection handshaking has completed successfully.
void	setTranslatesStrings ()
	Enables string tag translation on this connection.
Static Public Methods
char *	getErrorBuffer ()
	returns the current error buffer
void	setLastError (const char *fmt,...)
	Sets an error string and notifies the currently processing connection that it should terminate.
Public Attributes
U32	mConnectSendCount
	Number of challenge or connect requests sent to the remote host.
U32	mConnectLastSendTime
	The send time of the last challenge or connect request.
NetConnectionState	mConnectionState
	Current state of this NetConnection.
Protected Methods
virtual void	onConnectTerminated (TerminationReason reason, const char *rejectionString)
	Called when a pending connection is terminated.
virtual void	onConnectionTerminated (TerminationReason, const char *errorDisconnectString)
	Called when this established connection is terminated for any reason.
virtual void	onConnectionEstablished ()
	Called when the connection is successfully established with the remote host.
virtual bool	validateCertficate (Certificate *theCertificate, bool isInitiator)
	validates that the given certificate is a valid certificate for this connection.
virtual bool	validatePublicKey (AsymmetricKey *theKey, bool isInitiator)
	Validates that the given public key is valid for this connection.
virtual void	writeConnectRequest (BitStream *stream)
	Fills the connect request packet with additional custom data (from a subclass).
virtual bool	readConnectRequest (BitStream *stream, const char **errorString)
	Called after this connection instance is created on a non-initiating host (server).
virtual void	writeConnectAccept (BitStream *stream)
	Writes any data needed to start the connection on the accept packet.
virtual bool	readConnectAccept (BitStream *stream, const char **errorString)
	Reads out the extra data read by writeConnectAccept and returns true if it is processed properly.
virtual void	readPacket (BitStream *bstream)
	Called to read a subclass's packet data from the packet.
virtual void	prepareWritePacket ()
	Called to prepare the connection for packet writing.
virtual void	writePacket (BitStream *bstream, PacketNotify *note)
	Called to write a subclass's packet data into the packet.
virtual void	packetReceived (PacketNotify *note)
	Called when the packet associated with the specified notify is known to have been received by the remote host.
virtual void	packetDropped (PacketNotify *note)
	Called when the packet associated with the specified notify is known to have been not received by the remote host.
virtual PacketNotify *	allocNotify ()
	Allocates a data record to track data sent on an individual packet.
void	readRawPacket (BitStream *bstream)
	Reads a raw packet from a BitStream, as dispatched from NetInterface.
void	writeRawPacket (BitStream *bstream, NetPacketType packetType)
	Writes a full packet of the specified type into the BitStream.
void	writePacketHeader (BitStream *bstream, NetPacketType packetType)
	Writes the notify protocol's packet header into the BitStream.
bool	readPacketHeader (BitStream *bstream)
	Reads a notify protocol packet header from the BitStream and returns true if it was a data packet that needs more processing.
void	writePacketRateInfo (BitStream *bstream, PacketNotify *note)
	Writes any packet send rate change information into the packet.
void	readPacketRateInfo (BitStream *bstream)
	Reads any packet send rate information requests from the packet.
void	sendPingPacket ()
	Sends a ping packet to the remote host, to determine if it is still alive and what its packet window status is.
void	sendAckPacket ()
	Sends an ack packet to the remote host, in response to receiving a ping packet.
void	handleNotify (U32 sequence, bool recvd)
	Dispatches a notify when a packet is ACK'd or NACK'd.
void	keepAlive ()
	Called when a packet is received to stop any timeout action in progress.
void	clearAllPacketNotifies ()
	Clears out the pending notify list.
PacketNotify *	getCurrentWritePacketNotify ()
	Returns the notify structure for the current packet write, or last written packet.
Protected Attributes
PacketNotify *	mNotifyQueueHead
	Linked list of structures representing the data in sent packets.
PacketNotify *	mNotifyQueueTail
	Tail of the notify queue linked list. New packets are added to the end of the tail.
SafePtr< NetConnection >	mRemoteConnection
	Safe pointer to a short-circuit remote connection on the same host.
SafePtr< NetInterface >	mInterface
	The NetInterface of which this NetConnection is a member.
RefPtr< SymmetricCipher >	mSymmetricCipher
	The helper object that performs symmetric encryption on packets.
Static Protected Attributes
char	mErrorBuffer [256]
	String buffer that errors are written into.

---

Detailed Description

TNL network connection base class.

NetConnection is the base class for the connection classes in TNL. It implements a notification protocol on the unreliable packet transport of UDP (via the TNL::Net layer). NetConnection manages the flow of packets over the network, and calls its subclasses to read and write packet data, as well as handle packet delivery notification.

Because string data can easily soak up network bandwidth, for efficiency NetConnection implements an optional networked string table. Users can then notify the connection of strings it references often, such as player names, and transmit only a tag, instead of the whole string.

Definition at line 142 of file tnlNetConnection.h.

---

Member Enumeration Documentation

enum TNL::NetConnection::NetConnectionState

Connection state flags for a NetConnection instance. Enumeration values: NotConnected  Initial state of a NetConnection instance - not connected. AwaitingChallengeResponse  We've sent a challenge request, awaiting the response. SendingPunchPackets  The state of a pending arranged connection when both sides haven't heard from the other yet. ComputingPuzzleSolution  We've received a challenge response, and are in the process of computing a solution to its puzzle. AwaitingConnectResponse  We've received a challenge response and sent a connect request. ConnectTimedOut  The connection timed out during the connection process. ConnectRejected  The connection was rejected. Connected  We've accepted a connect request, or we've received a connect response accept. Disconnected  The connection has been disconnected. TimedOut  The connection timed out. Definition at line 511 of file tnlNetConnection.h.

enum TNL::NetConnection::NetConnectionTypeFlags

Flags specifying the type of the connection instance. Enumeration values: ConnectionToServer  A connection to a "server", used for directing NetEvents. ConnectionToClient  A connection to a "client". ConnectionAdaptive  Indicates that this connection uses the adaptive protocol. ConnectionRemoteAdaptive  Indicates that the remote side of this connection requested the adaptive protocol. Definition at line 366 of file tnlNetConnection.h.

---

Member Function Documentation

virtual PacketNotify* TNL::NetConnection::allocNotify (    )  [inline, protected, virtual]

Allocates a data record to track data sent on an individual packet. If you need to track additional notification information, you'll have to override this so you allocate a subclass of PacketNotify with extra fields. Reimplemented in TNL::EventConnection, and TNL::GhostConnection. Definition at line 282 of file tnlNetConnection.h. Referenced by writeRawPacket().

void TNL::NetConnection::checkPacketSend (  bool    force, U32    currentTime )

Checks to see if a packet should be sent at the currentTime to the remote host. If force is true and there is space in the window, it will always send a packet. Definition at line 642 of file netConnection.cpp. References TNL::F32, isAdaptive(), isDataToTransmit(), prepareWritePacket(), sendAckPacket(), sendPacket(), TNL::U32, windowFull(), and writeRawPacket().

void TNL::NetConnection::connect (  NetInterface *    connectionInterface, const Address &    address, bool    requestKeyExchange = false, bool    requestCertificate = false )

Connect to a server through a given network interface. The connection request can require that the connection use encryption, or that the remote host's certificate be validated by a known Certificate Authority Definition at line 790 of file netConnection.cpp. References mInterface, TNL::ConnectionParameters::mIsInitiator, TNL::ConnectionParameters::mRequestCertificate, TNL::ConnectionParameters::mRequestKeyExchange, setInterface(), and setNetAddress().

void TNL::NetConnection::disconnect (  const char *    reason )

Sends a disconnect packet to notify the remote host that this side is terminating the connection for the specified reason. This will remove the connection from its NetInterface, and may have the side effect that the connection is deleted, if there are no other objects with RefPtrs to the connection. Definition at line 817 of file netConnection.cpp. References mInterface.

virtual bool TNL::NetConnection::isDataToTransmit (    )  [inline, virtual]

Returns true if this connection has data to transmit. The adaptive rate protocol needs to be able to tell if there is data ready to be sent, so that it can avoid sending unnecessary packets. Each subclass of NetConnection may need to send different data - events, ghost updates, or other things. Therefore, this hook is provided so that child classes can overload it and let the adaptive protocol function properly. Note: Make sure this calls to its parents - the accepted idiom is: return Parent::isDataToTransmit() || localConditions(); Reimplemented in TNL::EventConnection, and TNL::GhostConnection. Definition at line 578 of file tnlNetConnection.h. Referenced by checkPacketSend().

void TNL::NetConnection::packetDropped (  PacketNotify *    note )  [protected, virtual]

Called when the packet associated with the specified notify is known to have been not received by the remote host. Packets are guaranteed to be notified in the order in which they were sent. Reimplemented in TNL::EventConnection, and TNL::GhostConnection. Definition at line 760 of file netConnection.cpp. References TNL::ConnectionStringTable::packetDropped(), and TNL::NetConnection::PacketNotify::stringList. Referenced by handleNotify().

void TNL::NetConnection::packetReceived (  PacketNotify *    note )  [protected, virtual]

Called when the packet associated with the specified notify is known to have been received by the remote host. Packets are guaranteed to be notified in the order in which they were sent. Reimplemented in TNL::EventConnection, and TNL::GhostConnection. Definition at line 754 of file netConnection.cpp. References TNL::ConnectionStringTable::packetReceived(), and TNL::NetConnection::PacketNotify::stringList. Referenced by handleNotify().

void TNL::NetConnection::prepareWritePacket (    )  [protected, virtual]

Called to prepare the connection for packet writing. Any setup work to determine if there isDataToTransmit() should happen in this function. prepareWritePacket should _always_ call the Parent:: function. Reimplemented in TNL::GhostConnection. Definition at line 746 of file netConnection.cpp. Referenced by checkPacketSend().

bool TNL::NetConnection::readConnectRequest (  BitStream *    stream, const char **    errorString )  [protected, virtual]

Called after this connection instance is created on a non-initiating host (server). Reads data sent by the writeConnectRequest method and returns true if the connection is accepted or false if it's not. The errorString pointer should be filled if the connection is rejected. Reimplemented in TNL::EventConnection. Definition at line 844 of file netConnection.cpp. References getNetClassGroup(), TNL::BitStream::read(), and TNL::U32. Referenced by connectLocal(), and TNL::NetInterface::handleArrangedConnectRequest().

void TNL::NetConnection::setIsAdaptive (    )

Enables the adaptive protocol. By default NetConnection operates with a fixed rate protocol - that is, it sends a packet every few milliseconds, based on some configuration parameters. However, it is possible to use an adaptive rate protocol that attempts to maximize thoroughput over the connection. Calling this function enables this behavior. Definition at line 537 of file netConnection.cpp. References ConnectionAdaptive, and TNL::BitSet32::set().

virtual bool TNL::NetConnection::validatePublicKey (  AsymmetricKey *    theKey, bool    isInitiator )  [inline, protected, virtual]

Validates that the given public key is valid for this connection. If this host requires a valid certificate for the communication, this function should always return false. It will only be called if the remote side of the connection did not provide a certificate. Definition at line 242 of file tnlNetConnection.h. Referenced by TNL::NetInterface::handleConnectChallengeResponse(), and TNL::NetInterface::handlePunch().

void TNL::NetConnection::writePacket (  BitStream *    bstream, PacketNotify *    note )  [protected, virtual]

Called to write a subclass's packet data into the packet. Information about what the instance wrote into the packet can be attached to the notify object. Reimplemented in TNL::EventConnection, and TNL::GhostConnection. Definition at line 750 of file netConnection.cpp. Referenced by writeRawPacket().

---

Member Data Documentation

SafePtr<NetConnection> TNL::NetConnection::mRemoteConnection [protected]

Safe pointer to a short-circuit remote connection on the same host. This currently isn't enabled - see the end of netConnection.cpp for an example of how to use this. If it's set, the code will use short circuited networking. Definition at line 419 of file tnlNetConnection.h. Referenced by TNL::GhostConnection::readPacket(), and sendPacket().

---

The documentation for this class was generated from the following files:

• /home/rdbrown/doxygen/cse125g1/src/modules/tnl/tnlNetConnection.h
• /home/rdbrown/doxygen/cse125g1/src/modules/tnl/netConnection.cpp

---