Home
TURN module (rfc5766)

TCPClient

TCP transport TURN client with relay connection management per RFC 6062.

TCPClient

#include <icy/turn/client/tcpclient.h>
class TCPClient

Defined in src/turn/include/icy/turn/client/tcpclient.h:87

Inherits: Client

TCP transport TURN client with relay connection management per RFC 6062. Uses a single TCP control connection for STUN signalling and opens additional TCP relay connections for each peer via the Connect / ConnectionBind flow.

List of all members

NameKindOwner
TCPClientfunctionDeclared here
~TCPClientfunctionDeclared here
startfunctionDeclared here
stopfunctionDeclared here
sendConnectRequestfunctionDeclared here
sendDatafunctionDeclared here
handleResponsefunctionDeclared here
handleConnectResponsefunctionDeclared here
handleConnectErrorResponsefunctionDeclared here
handleConnectionBindResponsefunctionDeclared here
handleConnectionBindErrorResponsefunctionDeclared here
handleConnectionAttemptIndicationfunctionDeclared here
createAndBindConnectionfunctionDeclared here
onRelayConnectionConnectfunctionDeclared here
onRelayDataReceivedfunctionDeclared here
onRelayConnectionErrorfunctionDeclared here
onRelayConnectionClosedfunctionDeclared here
freeConnectionfunctionDeclared here
transportProtocolfunctionDeclared here
connectionsfunctionDeclared here
classNamefunctionDeclared here
_observervariableDeclared here
_connectionsvariableDeclared here
ClientfunctionInherited from Client
~ClientfunctionInherited from Client
startfunctionInherited from Client
stopfunctionInherited from Client
sendAllocatefunctionInherited from Client
addPermissionfunctionInherited from Client
addPermissionfunctionInherited from Client
sendCreatePermissionfunctionInherited from Client
sendChannelBindfunctionInherited from Client
sendRefreshfunctionInherited from Client
sendDatafunctionInherited from Client
handleResponsefunctionInherited from Client
handleAllocateResponsefunctionInherited from Client
handleAllocateErrorResponsefunctionInherited from Client
handleCreatePermissionResponsefunctionInherited from Client
handleCreatePermissionErrorResponsefunctionInherited from Client
handleRefreshResponsefunctionInherited from Client
handleDataIndicationfunctionInherited from Client
transportProtocolfunctionInherited from Client
createTransactionfunctionInherited from Client
authenticateRequestfunctionInherited from Client
sendAuthenticatedTransactionfunctionInherited from Client
removeTransactionfunctionInherited from Client
mappedAddressfunctionInherited from Client
relayedAddressfunctionInherited from Client
closedfunctionInherited from Client
observerfunctionInherited from Client
optionsfunctionInherited from Client
addPermissionfunctionInherited from Client
addPermissionfunctionInherited from Client
hasPermissionfunctionInherited from Client
hasPermissionfunctionInherited from Client
removePermissionfunctionInherited from Client
removePermissionfunctionInherited from Client
_observervariableInherited from Client
_optionsvariableInherited from Client
_socketvariableInherited from Client
_timervariableInherited from Client
_errorvariableInherited from Client
_mappedAddressvariableInherited from Client
_relayedAddressvariableInherited from Client
_realmvariableInherited from Client
_noncevariableInherited from Client
_pendingIndicationsvariableInherited from Client
_transactionsvariableInherited from Client
setErrorfunctionInherited from Client
onSocketConnectfunctionInherited from Client
onSocketRecvfunctionInherited from Client
onSocketClosefunctionInherited from Client
onTransactionProgressfunctionInherited from Client
onStateChangefunctionInherited from Client
onTimerfunctionInherited from Client
StateChangevariableInherited from Stateful
StatefulfunctionInherited from Stateful
~StatefulfunctionInherited from Stateful
stateEqualsfunctionInherited from Stateful
stateBetweenfunctionInherited from Stateful
statefunctionInherited from Stateful
statefunctionInherited from Stateful
_statevariableInherited from Stateful
beforeStateChangefunctionInherited from Stateful
onStateChangefunctionInherited from Stateful
setStatefunctionInherited from Stateful
setStatefunctionInherited from Stateful
operator<<friendInherited from IAllocation
IAllocationfunctionInherited from IAllocation
~IAllocationfunctionInherited from IAllocation
IAllocationfunctionInherited from IAllocation
operator=functionInherited from IAllocation
IAllocationfunctionInherited from IAllocation
operator=functionInherited from IAllocation
updateUsagefunctionInherited from IAllocation
setLifetimefunctionInherited from IAllocation
setBandwidthLimitfunctionInherited from IAllocation
expiredfunctionInherited from IAllocation
deletedfunctionInherited from IAllocation
bandwidthLimitfunctionInherited from IAllocation
bandwidthUsedfunctionInherited from IAllocation
bandwidthRemainingfunctionInherited from IAllocation
timeRemainingfunctionInherited from IAllocation
tuplefunctionInherited from IAllocation
usernamefunctionInherited from IAllocation
lifetimefunctionInherited from IAllocation
permissionsfunctionInherited from IAllocation
relayedAddressfunctionInherited from IAllocation
addPermissionfunctionInherited from IAllocation
addPermissionfunctionInherited from IAllocation
addPermissionsfunctionInherited from IAllocation
removePermissionfunctionInherited from IAllocation
removePermissionfunctionInherited from IAllocation
removeAllPermissionsfunctionInherited from IAllocation
removeExpiredPermissionsfunctionInherited from IAllocation
hasPermissionfunctionInherited from IAllocation
hasPermissionfunctionInherited from IAllocation
printfunctionInherited from IAllocation
_tuplevariableInherited from IAllocation
_usernamevariableInherited from IAllocation
_permissionsvariableInherited from IAllocation
_lifetimevariableInherited from IAllocation
_bandwidthLimitvariableInherited from IAllocation
_bandwidthUsedvariableInherited from IAllocation
_createdAtvariableInherited from IAllocation
_updatedAtvariableInherited from IAllocation
_deletedvariableInherited from IAllocation

Inherited from Client

KindNameDescription
functionClient
function~Client virtual
functionstart virtualConnects the socket to the TURN server and starts the allocation sequence. Permissions must be added via addPermission() before calling this.
functionstop virtualStops the timer, cancels pending transactions, and closes the socket.
functionsendAllocate virtualSends an Allocate request to the server with the configured transport and lifetime. On first call the server will typically respond with a 401 challenge; the client re-sends with credentials automatically.
functionaddPermission virtualAdds multiple peer IP addresses to the permission list.
functionaddPermission virtual overrideAdds a single peer IP to the permission list, or refreshes it if already present. Permissions should be added before start(); they may also be added later, in which case a new CreatePermission request is required.
functionsendCreatePermission virtualSends a CreatePermission request for all IPs currently in the permission list. Called automatically after allocation succeeds and periodically by the timer to refresh expiring permissions.
functionsendChannelBind virtualChannel bindings (RFC 5766 Section 11) are intentionally not implemented. They are a bandwidth optimization that replaces STUN-framed Send/Data indications with a compact 4-byte ChannelData header. This only benefits high-throughput media relay scenarios; in practice, media flows directly via ICE/DTLS rather than through this TURN client's data path, so the optimization is not worth the complexity (channel number allocation, 10-minute binding refresh timers, ChannelData wire framing). Data relay uses sendData() with Send Indications instead.
functionsendRefresh virtualSends a Refresh request to extend the allocation lifetime. Called automatically by the timer when roughly one-third of the lifetime remains.
functionsendData virtualSends a Send Indication to relay data to peerAddress through the TURN server. If permissions are still being negotiated the indication is queued and flushed once CreatePermission succeeds.
functionhandleResponse virtualDispatches an incoming STUN/TURN response to the appropriate handler.
functionhandleAllocateResponse virtualProcesses a successful Allocate response; extracts mapped/relayed addresses and advances the state to Authorizing, then sends CreatePermission.
functionhandleAllocateErrorResponse virtualHandles an Allocate error response; manages the 401 challenge/re-send flow and sets the client to Failed for unrecoverable errors.
functionhandleCreatePermissionResponse virtualHandles a successful CreatePermission response; flushes queued Send Indications and advances state to Success.
functionhandleCreatePermissionErrorResponse virtualHandles a failed CreatePermission response; clears all permissions and sets the client to Failed.
functionhandleRefreshResponse virtualHandles a Refresh response; updates the stored lifetime.
functionhandleDataIndication virtualHandles an incoming Data Indication; extracts peer address and data and forwards to ClientObserver::onRelayDataReceived().
functiontransportProtocol virtual
functioncreateTransaction virtualCreates a new STUN transaction, registers the progress callback, and adds it to the active transaction list.
functionauthenticateRequest virtualAdds STUN long-term credential attributes (Username, Realm, Nonce, MessageIntegrity) to request if the realm has been received from the server.
functionsendAuthenticatedTransaction virtualCalls authenticateRequest() then sends the transaction.
functionremoveTransaction virtualRemoves a transaction from the active list. The IntrusivePtr keeps the object alive until the caller's copy is released.
functionmappedAddress const
functionrelayedAddress virtual const override
functionclosed const
functionobserver
functionoptions const
functionaddPermission virtualAdds a permission for ip, or refreshes the existing one.
functionaddPermission virtualAdds a permission for address, or refreshes the existing one. The port is ignored; TURN permissions are IP-only.
functionhasPermission virtualChecks whether a permission exists for peerIP. Local addresses (192.168.x.x and 127.x.x.x) are always permitted.
functionhasPermission virtualChecks whether a permission exists for peerAddress. The port is ignored; TURN permissions are IP-only.
functionremovePermission virtualRemoves the permission for ip if present.
functionremovePermission virtualRemoves the permission for address if present. The port is ignored; TURN permissions are IP-only.
variable_observer
variable_options
variable_socket
variable_timer
variable_error
variable_mappedAddress
variable_relayedAddress
variable_realm
variable_nonce
variable_pendingIndicationsA list of queued Send indication packets awaiting server permissions.
variable_transactionsA list containing currently active transactions.
functionsetError virtualSets the error field and transitions the client to the Failed state.
functiononSocketConnect virtualSocket connect callback; starts the timer and sends the first Allocate request.
functiononSocketRecv virtualSocket receive callback; parses STUN messages from the buffer and dispatches them.
functiononSocketClose virtualSocket close callback; shuts down the client and records the socket error.
functiononTransactionProgress virtualSTUN transaction state-change callback; handles Success and Failed outcomes.
functiononStateChange overrideForwards state-change events to the observer.
functiononTimer virtualPeriodic timer callback; re-allocates on expiry or refreshes when lifetime is below one-third remaining. Also calls ClientObserver::onTimer().

Inherited from Stateful

KindNameDescription
variableStateChangeSignals when the state changes.
functionStateful inline
function~Stateful virtual inline
functionstateEquals virtual const inlineReturns true if the current state ID equals the given ID.
functionstateBetween virtual const inlineReturns true if the current state ID is in the inclusive range [lid, rid].
functionstate virtual inlineReturns a mutable reference to the current state.
functionstate virtual const inlineReturns a copy of the current state.
variable_state
functionbeforeStateChange virtual inlineOverride to handle pre state change logic. Return false to prevent state change.
functiononStateChange virtual inlineOverride to handle post state change logic.
functionsetState virtual inlineSets the state and sends the state signal if the state change was successful.
functionsetState virtual inlineSets the state and sends the state signal if the state change was successful.

Inherited from IAllocation

KindNameDescription
friendoperator<< inline
functionIAllocation
function~IAllocation virtual
functionIAllocationDeleted constructor.
functionoperator=Deleted assignment operator.
functionIAllocationDeleted constructor.
functionoperator=Deleted assignment operator.
functionupdateUsage virtualUpdates the last-activity timestamp and accumulates bandwidth usage. Call this whenever data is relayed through the allocation.
functionsetLifetime virtualSets the allocation lifetime in seconds and resets the activity timestamp, effectively extending the expiry from the current moment.
functionsetBandwidthLimit virtualSets the maximum number of bytes this allocation may relay in its lifetime. Pass 0 to disable bandwidth limiting.
functionexpired virtual const
functiondeleted virtual constReturns true if the allocation's deleted flag is set and or if the allocation has expired.
functionbandwidthLimit virtual const
functionbandwidthUsed virtual const
functionbandwidthRemaining virtual const
functiontimeRemaining virtual const
functiontuple virtual
functionusername virtual const
functionlifetime virtual const
functionpermissions virtual const
functionrelayedAddress virtual const
functionaddPermission virtualAdds a permission for ip, or refreshes the existing one.
functionaddPermission virtualAdds a permission for address, or refreshes the existing one. The port is ignored; TURN permissions are IP-only.
functionaddPermissions virtualAdds (or refreshes) permissions for multiple IPs.
functionremovePermission virtualRemoves the permission for ip if present.
functionremovePermission virtualRemoves the permission for address if present. The port is ignored; TURN permissions are IP-only.
functionremoveAllPermissions virtualRemoves all permissions from the list.
functionremoveExpiredPermissions virtualRemoves any permissions whose 5-minute lifetime has elapsed.
functionhasPermission virtualChecks whether a permission exists for peerIP. Local addresses (192.168.x.x and 127.x.x.x) are always permitted.
functionhasPermission virtualChecks whether a permission exists for peerAddress. The port is ignored; TURN permissions are IP-only.
functionprint virtual const inline
variable_tuple
variable_username
variable_permissions
variable_lifetime
variable_bandwidthLimit
variable_bandwidthUsed
variable_createdAt
variable_updatedAt
variable_deleted

Public Methods

ReturnNameDescription
TCPClient
voidstart virtual overrideConnects the socket to the TURN server and starts the allocation sequence. Permissions must be added via addPermission() before calling this.
voidstop virtual overrideStops the control connection, cancels all relay connections, and calls the base class stop().
voidsendConnectRequest virtualSends a Connect request to the server asking it to open a TCP connection to peerAddress on the client's behalf (RFC 6062 section 4.3).
voidsendData virtual overrideSends raw data to peerAddress over the established relay connection. The peer must have an active permission and a bound relay connection.
boolhandleResponse virtual overrideExtends the base handler with Connect, ConnectionBind, and ConnectionAttempt responses.
voidhandleConnectResponse virtualProcesses a successful Connect response; extracts the connection ID and calls createAndBindConnection().
voidhandleConnectErrorResponse virtualProcesses a Connect error response; notifies the observer that binding failed.
voidhandleConnectionBindResponse virtualProcesses a successful ConnectionBind response; arms the relay socket for data transfer and notifies the observer.
voidhandleConnectionBindErrorResponse virtualProcesses a ConnectionBind error response; frees the failed connection.
voidhandleConnectionAttemptIndication virtualProcesses a ConnectionAttempt indication from the server; optionally accepts the incoming peer connection by calling createAndBindConnection().
boolcreateAndBindConnection virtualOpens a new TCP relay socket to the TURN server and sends a ConnectionBind request carrying connectionID.
boolonRelayConnectionConnect virtualRelay socket connect callback; sends the ConnectionBind request.
boolonRelayDataReceived virtualRelay socket receive callback; forwards data to the observer.
boolonRelayConnectionError virtualRelay socket error callback; notifies the observer of the error.
boolonRelayConnectionClosed virtualRelay socket close callback; notifies the observer and frees the connection.
voidfreeConnectionRemoves the relay connection for peerAddress, unregisters its callbacks, and deletes the associated RelayConnectionBinding.
inttransportProtocol virtual override
ConnectionManager &connections
const char *className virtual const inline

TCPClient

TCPClient(TCPClientObserver & observer, const Client::Options & options = Client::Options())

Defined in src/turn/include/icy/turn/client/tcpclient.h:92

Parameters

  • observer Observer for TCP-specific relay events.

  • options Client configuration; defaults to loopback server, 5-min lifetime.


start

virtual override

virtual void start() override

Defined in src/turn/include/icy/turn/client/tcpclient.h:96

Connects the socket to the TURN server and starts the allocation sequence. Permissions must be added via addPermission() before calling this.

Reimplements

stop

virtual override

virtual void stop() override

Defined in src/turn/include/icy/turn/client/tcpclient.h:100

Stops the control connection, cancels all relay connections, and calls the base class stop().

Reimplements

sendConnectRequest

virtual

virtual void sendConnectRequest(const net::Address & peerAddress)

Defined in src/turn/include/icy/turn/client/tcpclient.h:105

Sends a Connect request to the server asking it to open a TCP connection to peerAddress on the client's behalf (RFC 6062 section 4.3).

Parameters

  • peerAddress Target peer address.

sendData

virtual override

virtual void sendData(const char * data, size_t size, const net::Address & peerAddress) override

Defined in src/turn/include/icy/turn/client/tcpclient.h:112

Sends raw data to peerAddress over the established relay connection. The peer must have an active permission and a bound relay connection.

Parameters

  • data Payload bytes.

  • size Number of bytes to send.

  • peerAddress Destination peer (must have an entry in connections()).

Reimplements

handleResponse

virtual override

virtual bool handleResponse(const stun::Message & response) override

Defined in src/turn/include/icy/turn/client/tcpclient.h:118

Extends the base handler with Connect, ConnectionBind, and ConnectionAttempt responses.

Parameters

  • response Incoming STUN response.

Returns

true if the message was handled.

Reimplements

handleConnectResponse

virtual

virtual void handleConnectResponse(const stun::Message & response)

Defined in src/turn/include/icy/turn/client/tcpclient.h:123

Processes a successful Connect response; extracts the connection ID and calls createAndBindConnection().

Parameters

  • response Connect success response.

handleConnectErrorResponse

virtual

virtual void handleConnectErrorResponse(const stun::Message & response)

Defined in src/turn/include/icy/turn/client/tcpclient.h:127

Processes a Connect error response; notifies the observer that binding failed.

Parameters

  • response Connect error response.

handleConnectionBindResponse

virtual

virtual void handleConnectionBindResponse(const stun::Message & response)

Defined in src/turn/include/icy/turn/client/tcpclient.h:132

Processes a successful ConnectionBind response; arms the relay socket for data transfer and notifies the observer.

Parameters

  • response ConnectionBind success response.

handleConnectionBindErrorResponse

virtual

virtual void handleConnectionBindErrorResponse(const stun::Message & response)

Defined in src/turn/include/icy/turn/client/tcpclient.h:136

Processes a ConnectionBind error response; frees the failed connection.

Parameters

  • response ConnectionBind error response.

handleConnectionAttemptIndication

virtual

virtual void handleConnectionAttemptIndication(const stun::Message & response)

Defined in src/turn/include/icy/turn/client/tcpclient.h:141

Processes a ConnectionAttempt indication from the server; optionally accepts the incoming peer connection by calling createAndBindConnection().

Parameters

  • response ConnectionAttempt indication message.

createAndBindConnection

virtual

virtual bool createAndBindConnection(uint32_t connectionID, const net::Address & peerAddress)

Defined in src/turn/include/icy/turn/client/tcpclient.h:148

Opens a new TCP relay socket to the TURN server and sends a ConnectionBind request carrying connectionID.

Parameters

  • connectionID TURN CONNECTION-ID from the server.

  • peerAddress Peer associated with this connection.

Returns

true on success.


onRelayConnectionConnect

virtual

virtual bool onRelayConnectionConnect(net::Socket & socket)

Defined in src/turn/include/icy/turn/client/tcpclient.h:152

Relay socket connect callback; sends the ConnectionBind request.

Parameters

  • socket The relay socket that just connected.

onRelayDataReceived

virtual

virtual bool onRelayDataReceived(net::Socket & socket, const MutableBuffer & buffer, const net::Address & peerAddress)

Defined in src/turn/include/icy/turn/client/tcpclient.h:158

Relay socket receive callback; forwards data to the observer.

Parameters

  • socket The receiving relay socket.

  • buffer Received data.

  • peerAddress Source address (populated by the socket layer).


onRelayConnectionError

virtual

virtual bool onRelayConnectionError(net::Socket & socket, const Error & error)

Defined in src/turn/include/icy/turn/client/tcpclient.h:163

Relay socket error callback; notifies the observer of the error.

Parameters

  • socket The affected relay socket.

  • error Error descriptor.


onRelayConnectionClosed

virtual

virtual bool onRelayConnectionClosed(net::Socket & socket)

Defined in src/turn/include/icy/turn/client/tcpclient.h:167

Relay socket close callback; notifies the observer and frees the connection.

Parameters

  • socket The closed relay socket.

freeConnection

void freeConnection(const net::Address & peerAddress)

Defined in src/turn/include/icy/turn/client/tcpclient.h:172

Removes the relay connection for peerAddress, unregisters its callbacks, and deletes the associated RelayConnectionBinding.

Parameters

  • peerAddress Peer whose connection to release.

transportProtocol

virtual override

virtual int transportProtocol() override

Defined in src/turn/include/icy/turn/client/tcpclient.h:175

Returns

kProtocolTCP (6).

Reimplements

connections

ConnectionManager & connections()

Defined in src/turn/include/icy/turn/client/tcpclient.h:178

Returns

Reference to the map of active relay connections keyed by peer address.


className

virtual const inline

virtual inline const char * className() const

Defined in src/turn/include/icy/turn/client/tcpclient.h:180

Protected Attributes

ReturnNameDescription
TCPClientObserver &_observer
ConnectionManager_connections

_observer

TCPClientObserver & _observer

Defined in src/turn/include/icy/turn/client/tcpclient.h:183


_connections

ConnectionManager _connections

Defined in src/turn/include/icy/turn/client/tcpclient.h:184