Main Page Modules Namespaces C++ Classes Compound List File List Index
TNL: TNL::NetConnection Class Reference

# TNL::NetConnection Class Reference

`#include <tnlNetConnection.h>`

Inheritance diagram for TNL::NetConnection:

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

## 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.
F32 | cwnd
F32 | ssthresh
U32 | mLastSeqRecvdAck
U32 | mLastAckTime
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 | TerminationReason { ReasonTimedOut, ReasonFailedConnectHandshake, ReasonRemoteHostRejectedConnection, ReasonRemoteDisconnectPacket,
ReasonDuplicateConnectionAttempt,
ReasonSelfDisconnect,
ReasonError
}
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,
StateCount
}
| Connection state flags for a NetConnection instance. More...

## Public Member Functions

| NetConnection ()
| ~NetConnection ()
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.
ConnectionParameters & | getConnectionParameters ()
bool | isInitiator ()
| returns true if this object initiated the connection with the remote host
void | setRemoteConnectionObject (NetConnection *connection)
NetConnection * | getRemoteConnectionObject ()
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 Member Functions

static char * | getErrorBuffer ()
| returns the current error buffer
static void | setLastError (const char *fmt,...)
| Sets an error string and notifies the currently processing connection that it should terminate.

## Data Fields

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 Member Functions

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

static char | mErrorBuffer [256]
| String buffer that errors are written into.

## Private Types

enum | HeaderConstants { MaxPacketWindowSizeShift = 5, MaxPacketWindowSize = (1 << MaxPacketWindowSizeShift), PacketWindowMask = MaxPacketWindowSize - 1, MaxAckMaskSize = 1 << (MaxPacketWindowSizeShift - 5),
MaxAckByteCount = MaxAckMaskSize << 2,
SequenceNumberBitSize = 11,
SequenceNumberWindowSize = (1 << SequenceNumberBitSize),
SequenceNumberMask = -SequenceNumberWindowSize,
AckSequenceNumberBitSize = 10,
AckSequenceNumberWindowSize = (1 << AckSequenceNumberBitSize),
AckSequenceNumberMask = -AckSequenceNumberWindowSize,
PacketHeaderBitSize = 3 + AckSequenceNumberBitSize + SequenceNumberBitSize,
PacketHeaderByteSize = (PacketHeaderBitSize + 7) >> 3,
PacketHeaderPadBits = (PacketHeaderByteSize << 3) - PacketHeaderBitSize,
MessageSignatureBytes = 5
}
| Constants controlling the data representation of each packet header. More...
enum | NetPacketType { DataPacket, PingPacket, AckPacket, InvalidPacketType
}
| Two-bit identifier for each connected packet. More...
enum | DefaultPingConstants { AdaptiveInitialPingTimeout = 60000, AdaptivePingRetryCount = 4, DefaultPingTimeout = 5000, DefaultPingRetryCount = 10,
AdaptiveUnackedSentPingTimeout = 3000
}
| Constants controlling the behavior of pings and timeouts. More...
enum | RateDefaults { DefaultFixedBandwidth = 2500, DefaultFixedSendPeriod = 96, MaxFixedBandwidth = 65535, MaxFixedSendPeriod = 2047
}
typedef Object | Parent

## Private Member Functions

bool | hasUnackedSentPackets ()
| Returns true if this connection has sent packets that have not yet been acked by the remote host.
void | computeNegotiatedRate ()
| Called internally when the local or remote rate changes.

## Private Attributes

U32 | mLastPacketRecvTime
| Time of the receipt of the last data packet.
U32 | mLastSeqRecvdAtSend [MaxPacketWindowSize]
| The sequence number of the last packet received from the remote host when we sent the packet with sequence X & PacketWindowMask.
U32 | mLastSeqRecvd
| The sequence number of the most recently received packet from the remote host.
U32 | mHighestAckedSeq
| The highest sequence number the remote side has acknowledged.
U32 | mLastSendSeq
| The sequence number of the last packet sent.
U32 | mAckMask [MaxAckMaskSize]
| long string of bits, each acking a packet sent by the remote host.
U32 | mLastRecvAckAck
| The highest sequence this side knows the other side has received an ACK or NACK for.
U32 | mInitialSendSeq
| The first mLastSendSeq for this side of the connection.
U32 | mInitialRecvSeq
| The first mLastSeqRecvd (the first mLastSendSeq for the remote host).
U32 | mHighestAckedSendTime
| The send time of the highest packet sequence acked by the remote host.
U32 | mPingTimeout
| Milliseconds to wait before sending a ping packet.
U32 | mPingRetryCount
| Number of unacknowledged pings to send before timing out.
BitSet32 | mTypeFlags
| Flags describing the type of connection this is, OR'd from NetConnectionTypeFlags.
U32 | mLastUpdateTime
| The last time a packet was sent from this instance.
F32 | mRoundTripTime
| Running average round trip time.
U32 | mSendDelayCredit
| Metric to help compensate for irregularities on fixed rate packet sends.
U32 | mSimulatedLatency
| Amount of additional time this connection delays its packet sends to simulate latency in the connection.
F32 | mSimulatedPacketLoss
| Function to simulate packet loss on a network.
NetRate | mLocalRate
| Current communications rate negotiated for this connection.
NetRate | mRemoteRate
| Maximum allowable communications rate for this connection.
bool | mLocalRateChanged
| Set to true when the local connection's rate has changed.
U32 | mCurrentPacketSendSize
| Current size of each packet sent to the remote host.
U32 | mCurrentPacketSendPeriod
| Millisecond delay between sent packets.
Address | mNetAddress
| The network address of the host this instance is connected to.
U32 | mPingSendCount
| Number of unacknowledged ping packets sent to the remote host.
U32 | mLastPingSendTime
| Last time a ping packet was sent from this connection.
ConnectionStringTable * | mStringTable
| Helper for managing translation between global NetStringTable ids to local ids for this connection.

## Friends

class | NetInterface
class | ConnectionStringTable

## Data Structures

struct | NetRate
| Rate management structure used specify the rate at which packets are sent and the maximum size of each packet. More...
struct | PacketNotify
| Structure used to track what was sent in an individual packet for processing upon notification of delivery success or failure. More...

## Member Typedef Documentation

typedef Object TNL::NetConnection::Parent`[private]`

Reimplemented in TNL::EventConnection, TNL::GhostConnection, TNLTest::TestConnection, Zap::ControlObjectConnection, Zap::GameConnection, and Zap::MasterServerConnection.

## Member Enumeration Documentation

enum TNL::NetConnection::HeaderConstants`[private]`

Constants controlling the data representation of each packet header.

Enumerator:

  MaxPacketWindowSizeShift | Packet window size is 2^MaxPacketWindowSizeShift.
  MaxPacketWindowSize | Maximum number of packets in the packet window.
  PacketWindowMask | Mask for accessing the packet window.
  MaxAckMaskSize | Each ack word can ack 32 packets.
  MaxAckByteCount | The maximum number of ack bytes sent in each packet.
  SequenceNumberBitSize | Bit size of the send and sequence number.
  SequenceNumberWindowSize | Size of the send sequence number window.
  SequenceNumberMask | Mask used to reconstruct the full send sequence number of the packet from the partial sequence number sent.
  AckSequenceNumberBitSize | Bit size of the ack receive sequence number.
  AckSequenceNumberWindowSize | Size of the ack receive sequence number window.
  AckSequenceNumberMask | Mask used to reconstruct the full ack receive sequence number of the packet from the partial sequence number sent.
  PacketHeaderBitSize | Size, in bits, of the packet header sequence number section.
  PacketHeaderByteSize | Size, in bytes, of the packet header sequence number information.
  PacketHeaderPadBits | Padding bits to get header bytes to align on a byte boundary, for encryption purposes.
  MessageSignatureBytes | Special data bytes written into the end of the packet to guarantee data consistency.

enum TNL::NetConnection::NetPacketType`[private]`

Two-bit identifier for each connected packet.

Enumerator:

  DataPacket | Standard data packet. Each data packet sent increments the current packet sequence number (mLastSendSeq).
  PingPacket | Ping packet, sent if this instance hasn't heard from the remote host for a while. Sending a ping packet does not increment the packet sequence number.
  AckPacket | Packet sent in response to a ping packet. Sending an ack packet does not increment the sequence number.
  InvalidPacketType |

enum TNL::NetConnection::DefaultPingConstants`[private]`

Constants controlling the behavior of pings and timeouts.

Enumerator:

  AdaptiveInitialPingTimeout |
  AdaptivePingRetryCount |
  DefaultPingTimeout | Default milliseconds to wait before sending a ping packet.
  DefaultPingRetryCount | Default number of unacknowledged pings to send before timing out.
  AdaptiveUnackedSentPingTimeout |

enum TNL::NetConnection::TerminationReason

Enumerator:

  ReasonTimedOut |
  ReasonFailedConnectHandshake |
  ReasonRemoteHostRejectedConnection |
  ReasonRemoteDisconnectPacket |
  ReasonDuplicateConnectionAttempt |
  ReasonSelfDisconnect |
  ReasonError |

enum TNL::NetConnection::NetConnectionTypeFlags

Flags specifying the type of the connection instance.

Enumerator:

  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.

enum TNL::NetConnection::RateDefaults`[private]`

Enumerator:

  DefaultFixedBandwidth | The default send/receive bandwidth - 2.5 Kb per second.
  DefaultFixedSendPeriod | The default delay between each packet send - approx 10 packets per second.
  MaxFixedBandwidth | The maximum bandwidth for a connection using the fixed rate transmission method.
  MaxFixedSendPeriod | The maximum period between packets in the fixed rate send transmission method.

enum TNL::NetConnection::NetConnectionState

Connection state flags for a NetConnection instance.

Enumerator:

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

## Constructor & Destructor Documentation

TNL::NetConnection::NetConnection | ( |  | ) |

TNL::NetConnection::~NetConnection | ( |  | ) |

## Member Function Documentation

bool TNL::NetConnection::hasUnackedSentPackets | ( |  | ) | `[inline, private]`

Returns true if this connection has sent packets that have not yet been acked by the remote host.

virtual void TNL::NetConnection::onConnectTerminated | ( | TerminationReason | reason,
|  | const char * | rejectionString |
| ) |  |  | `[protected, virtual]`

Called when a pending connection is terminated.

Reimplemented in TNLTest::TestConnection, and Zap::GameConnection.

virtual void TNL::NetConnection::onConnectionTerminated | ( | TerminationReason | ,
|  | const char * | errorDisconnectString |
| ) |  |  | `[protected, virtual]`

Called when this established connection is terminated for any reason.

Reimplemented in TNLTest::TestConnection, and Zap::GameConnection.

virtual void TNL::NetConnection::onConnectionEstablished | ( |  | ) | `[protected, virtual]`

Called when the connection is successfully established with the remote host.

Reimplemented in TNLTest::TestConnection, Zap::GameConnection, and Zap::MasterServerConnection.

virtual bool TNL::NetConnection::validateCertficate | ( | Certificate * | theCertificate,
|  | bool | isInitiator |
| ) |  |  | `[inline, protected, virtual]`

validates that the given certificate is a valid certificate for this connection.

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.

virtual void TNL::NetConnection::writeConnectRequest | ( | BitStream * | stream | ) | `[protected, virtual]`

Fills the connect request packet with additional custom data (from a subclass).

Reimplemented in TNL::EventConnection, Zap::GameConnection, and Zap::MasterServerConnection.

virtual 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, and Zap::GameConnection.

virtual void TNL::NetConnection::writeConnectAccept | ( | BitStream * | stream | ) | `[protected, virtual]`

Writes any data needed to start the connection on the accept packet.

Reimplemented in TNL::EventConnection.

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

Reads out the extra data read by writeConnectAccept and returns true if it is processed properly.

Reimplemented in TNL::EventConnection.

virtual void TNL::NetConnection::readPacket | ( | BitStream * | bstream | ) | `[protected, virtual]`

Called to read a subclass's packet data from the packet.

Reimplemented in TNL::EventConnection, TNL::GhostConnection, and Zap::ControlObjectConnection.

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

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

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

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

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, TNL::GhostConnection, and Zap::ControlObjectConnection.

U32 TNL::NetConnection::getNextSendSequence | ( |  | ) | `[inline]`

Returns the next send sequence that will be sent by this side.

U32 TNL::NetConnection::getLastSendSequence | ( |  | ) | `[inline]`

Returns the sequence of the last packet sent by this connection, or the current packet's send sequence if called from within writePacket().

void TNL::NetConnection::readRawPacket | ( | BitStream * | bstream | ) | `[protected]`

Reads a raw packet from a BitStream, as dispatched from NetInterface.

void TNL::NetConnection::writeRawPacket | ( | BitStream * | bstream,
|  | NetPacketType | packetType |
| ) |  |  | `[protected]`

Writes a full packet of the specified type into the BitStream.

void TNL::NetConnection::writePacketHeader | ( | BitStream * | bstream,
|  | NetPacketType | packetType |
| ) |  |  | `[protected]`

Writes the notify protocol's packet header into the BitStream.

bool TNL::NetConnection::readPacketHeader | ( | BitStream * | bstream | ) | `[protected]`

Reads a notify protocol packet header from the BitStream and returns true if it was a data packet that needs more processing.

void TNL::NetConnection::writePacketRateInfo | ( | BitStream * | bstream,
|  | PacketNotify * | note |
| ) |  |  | `[protected]`

Writes any packet send rate change information into the packet.

void TNL::NetConnection::readPacketRateInfo | ( | BitStream * | bstream | ) | `[protected]`

Reads any packet send rate information requests from the packet.

void TNL::NetConnection::sendPingPacket | ( |  | ) | `[protected]`

Sends a ping packet to the remote host, to determine if it is still alive and what its packet window status is.

void TNL::NetConnection::sendAckPacket | ( |  | ) | `[protected]`

Sends an ack packet to the remote host, in response to receiving a ping packet.

void TNL::NetConnection::handleNotify | ( | U32 | sequence,
|  | bool | recvd |
| ) |  |  | `[protected]`

Dispatches a notify when a packet is ACK'd or NACK'd.

void TNL::NetConnection::keepAlive | ( |  | ) | `[protected]`

Called when a packet is received to stop any timeout action in progress.

void TNL::NetConnection::clearAllPacketNotifies | ( |  | ) | `[protected]`

Clears out the pending notify list.

void TNL::NetConnection::setInitialRecvSequence | ( | U32 | sequence | ) |

Sets the initial sequence number of packets read from the remote host.

U32 TNL::NetConnection::getInitialRecvSequence | ( |  | ) | `[inline]`

Returns the initial sequence number of packets sent from the remote host.

U32 TNL::NetConnection::getInitialSendSequence | ( |  | ) | `[inline]`

Returns the initial sequence number of packets sent to the remote host.

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

bool TNL::NetConnection::connectLocal | ( | NetInterface * | connectionInterface,
|  | NetInterface * | localServerInterface |
| ) |  |  |

Connects to a server interface within the same process.

void TNL::NetConnection::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 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.

bool TNL::NetConnection::windowFull | ( |  | ) |

Returns true if the packet send window is full and no more data packets can be sent.

void TNL::NetConnection::computeNegotiatedRate | ( |  | ) | `[private]`

Called internally when the local or remote rate changes.

PacketNotify* TNL::NetConnection::getCurrentWritePacketNotify | ( |  | ) | `[inline, protected]`

Returns the notify structure for the current packet write, or last written packet.

ConnectionParameters& TNL::NetConnection::getConnectionParameters | ( |  | ) | `[inline]`

bool TNL::NetConnection::isInitiator | ( |  | ) | `[inline]`

returns true if this object initiated the connection with the remote host

void TNL::NetConnection::setRemoteConnectionObject | ( | NetConnection * | connection | ) | `[inline]`

NetConnection* TNL::NetConnection::getRemoteConnectionObject | ( |  | ) | `[inline]`

static char* TNL::NetConnection::getErrorBuffer | ( |  | ) | `[inline, static]`

returns the current error buffer

static void TNL::NetConnection::setLastError | ( | const char * | fmt,
|  |  | ... |
| ) |  |  | `[static]`

Sets an error string and notifies the currently processing connection that it should terminate.

void TNL::NetConnection::setInterface | ( | NetInterface * | myInterface | ) |

Sets the NetInterface this NetConnection will communicate through.

NetInterface* TNL::NetConnection::getInterface | ( |  | ) |

Returns the NetInterface this connection communicates through.

void TNL::NetConnection::setSymmetricCipher | ( | SymmetricCipher * | theCipher | ) |

Sets the SymmetricCipher this NetConnection will use for encryption.

virtual NetClassGroup TNL::NetConnection::getNetClassGroup | ( |  | ) | const`[inline, virtual]`

Returns the class group of objects that can be transmitted over this NetConnection.

void TNL::NetConnection::setPingTimeouts | ( | U32 | msPerPing,
|  | U32 | pingRetryCount |
| ) |  |  | `[inline]`

Sets the ping/timeout characteristics for a fixed-rate connection. Total timeout is msPerPing * pingRetryCount.

void TNL::NetConnection::setSimulatedNetParams | ( | F32 | packetLoss,
|  | U32 | latency |
| ) |  |  | `[inline]`

Simulates a network situation with a percentage random packet loss and a connection one way latency as specified.

void TNL::NetConnection::setIsConnectionToServer | ( |  | ) | `[inline]`

Specifies that this NetConnection instance is a connection to a "server.".

bool TNL::NetConnection::isConnectionToServer | ( |  | ) | `[inline]`

Returns true if this is a connection to a "server.".

void TNL::NetConnection::setIsConnectionToClient | ( |  | ) | `[inline]`

Specifies that this NetConnection instance is a connection to a "client.".

bool TNL::NetConnection::isConnectionToClient | ( |  | ) | `[inline]`

Returns true if this is a connection to a "client.".

bool TNL::NetConnection::isLocalConnection | ( |  | ) | `[inline]`

Returns true if the remote side of this connection is a NetConnection instance in on the same host.

bool TNL::NetConnection::isNetworkConnection | ( |  | ) | `[inline]`

Returns true if the remote side if this connection is on a remote host.

F32 TNL::NetConnection::getRoundTripTime | ( |  | ) | `[inline]`

Returns the running average packet round trip time.

F32 TNL::NetConnection::getOneWayTime | ( |  | ) | `[inline]`

Returns have of the average of the round trip packet time.

const Address& TNL::NetConnection::getNetAddress | ( |  | ) |

Returns the remote address of the host we're connected or trying to connect to.

const char* TNL::NetConnection::getNetAddressString | ( |  | ) | const`[inline]`

Returns the remote address in string form.

void TNL::NetConnection::setNetAddress | ( | const Address & | address | ) |

Sets the address of the remote host we want to connect to.

NetError TNL::NetConnection::sendPacket | ( | BitStream * | stream | ) |

Sends a packet that was written into a BitStream to the remote host, or the mRemoteConnection on this host.

bool TNL::NetConnection::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 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.

void TNL::NetConnection::setConnectionState | ( | NetConnectionState | state | ) | `[inline]`

Sets the current connection state of this NetConnection.

NetConnectionState TNL::NetConnection::getConnectionState | ( |  | ) | `[inline]`

Gets the current connection state of this NetConnection.

bool TNL::NetConnection::isEstablished | ( |  | ) | `[inline]`

Returns true if the connection handshaking has completed successfully.

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.

void TNL::NetConnection::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 TNL::NetConnection::isAdaptive | ( |  | ) | `[inline]`

Query the adaptive status of the connection.

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, TNL::GhostConnection, TNLTest::TestConnection, and Zap::ControlObjectConnection.

void TNL::NetConnection::setTranslatesStrings | ( |  | ) |

Enables string tag translation on this connection.

## Friends And Related Function Documentation

friend class NetInterface`[friend]`

friend class ConnectionStringTable`[friend]`

## Field Documentation

U32 TNL::NetConnection::mLastPacketRecvTime`[private]`

Time of the receipt of the last data packet.

U32 TNL::NetConnection::mLastSeqRecvdAtSend[MaxPacketWindowSize]`[private]`

The sequence number of the last packet received from the remote host when we sent the packet with sequence X & PacketWindowMask.

U32 TNL::NetConnection::mLastSeqRecvd`[private]`

The sequence number of the most recently received packet from the remote host.

U32 TNL::NetConnection::mHighestAckedSeq`[private]`

The highest sequence number the remote side has acknowledged.

U32 TNL::NetConnection::mLastSendSeq`[private]`

The sequence number of the last packet sent.

U32 TNL::NetConnection::mAckMask[MaxAckMaskSize]`[private]`

long string of bits, each acking a packet sent by the remote host.

The bit associated with mLastSeqRecvd is the low bit of the 0'th word of mAckMask.

U32 TNL::NetConnection::mLastRecvAckAck`[private]`

The highest sequence this side knows the other side has received an ACK or NACK for.

U32 TNL::NetConnection::mInitialSendSeq`[private]`

The first mLastSendSeq for this side of the connection.

U32 TNL::NetConnection::mInitialRecvSeq`[private]`

The first mLastSeqRecvd (the first mLastSendSeq for the remote host).

U32 TNL::NetConnection::mHighestAckedSendTime`[private]`

The send time of the highest packet sequence acked by the remote host.

Used in the computation of round trip time.

U32 TNL::NetConnection::mPingTimeout`[private]`

Milliseconds to wait before sending a ping packet.

U32 TNL::NetConnection::mPingRetryCount`[private]`

Number of unacknowledged pings to send before timing out.

BitSet32 TNL::NetConnection::mTypeFlags`[private]`

Flags describing the type of connection this is, OR'd from NetConnectionTypeFlags.

U32 TNL::NetConnection::mLastUpdateTime`[private]`

The last time a packet was sent from this instance.

F32 TNL::NetConnection::mRoundTripTime`[private]`

Running average round trip time.

U32 TNL::NetConnection::mSendDelayCredit`[private]`

Metric to help compensate for irregularities on fixed rate packet sends.

U32 TNL::NetConnection::mSimulatedLatency`[private]`

Amount of additional time this connection delays its packet sends to simulate latency in the connection.

F32 TNL::NetConnection::mSimulatedPacketLoss`[private]`

Function to simulate packet loss on a network.

NetRate TNL::NetConnection::mLocalRate`[private]`

Current communications rate negotiated for this connection.

NetRate TNL::NetConnection::mRemoteRate`[private]`

Maximum allowable communications rate for this connection.

bool TNL::NetConnection::mLocalRateChanged`[private]`

Set to true when the local connection's rate has changed.

U32 TNL::NetConnection::mCurrentPacketSendSize`[private]`

Current size of each packet sent to the remote host.

U32 TNL::NetConnection::mCurrentPacketSendPeriod`[private]`

Millisecond delay between sent packets.

Address TNL::NetConnection::mNetAddress`[private]`

The network address of the host this instance is connected to.

U32 TNL::NetConnection::mPingSendCount`[private]`

Number of unacknowledged ping packets sent to the remote host.

U32 TNL::NetConnection::mLastPingSendTime`[private]`

Last time a ping packet was sent from this connection.

PacketNotify* TNL::NetConnection::mNotifyQueueHead`[protected]`

Linked list of structures representing the data in sent packets.

PacketNotify* TNL::NetConnection::mNotifyQueueTail`[protected]`

Tail of the notify queue linked list. New packets are added to the end of the tail.

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.

ConnectionParameters TNL::NetConnection::mConnectionParameters`[protected]`

U32 TNL::NetConnection::mConnectSendCount

Number of challenge or connect requests sent to the remote host.

U32 TNL::NetConnection::mConnectLastSendTime

The send time of the last challenge or connect request.

char TNL::NetConnection::mErrorBuffer[256]`[static, protected]`

String buffer that errors are written into.

SafePtr<NetInterface> TNL::NetConnection::mInterface`[protected]`

The NetInterface of which this NetConnection is a member.

RefPtr<SymmetricCipher> TNL::NetConnection::mSymmetricCipher`[protected]`

The helper object that performs symmetric encryption on packets.

NetConnectionState TNL::NetConnection::mConnectionState

Current state of this NetConnection.

F32 TNL::NetConnection::cwnd`[private]`

F32 TNL::NetConnection::ssthresh`[private]`

U32 TNL::NetConnection::mLastSeqRecvdAck`[private]`

U32 TNL::NetConnection::mLastAckTime`[private]`

ConnectionStringTable* TNL::NetConnection::mStringTable`[private]`

Helper for managing translation between global NetStringTable ids to local ids for this connection.