TCPClient
TCPClient
#include <icy/turn/client/tcpclient.h>class TCPClientDefined 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
| Name | Kind | Owner |
|---|---|---|
TCPClient | function | Declared here |
~TCPClient | function | Declared here |
start | function | Declared here |
stop | function | Declared here |
sendConnectRequest | function | Declared here |
sendData | function | Declared here |
handleResponse | function | Declared here |
handleConnectResponse | function | Declared here |
handleConnectErrorResponse | function | Declared here |
handleConnectionBindResponse | function | Declared here |
handleConnectionBindErrorResponse | function | Declared here |
handleConnectionAttemptIndication | function | Declared here |
createAndBindConnection | function | Declared here |
onRelayConnectionConnect | function | Declared here |
onRelayDataReceived | function | Declared here |
onRelayConnectionError | function | Declared here |
onRelayConnectionClosed | function | Declared here |
freeConnection | function | Declared here |
transportProtocol | function | Declared here |
connections | function | Declared here |
className | function | Declared here |
_observer | variable | Declared here |
_connections | variable | Declared here |
Client | function | Inherited from Client |
~Client | function | Inherited from Client |
start | function | Inherited from Client |
stop | function | Inherited from Client |
sendAllocate | function | Inherited from Client |
addPermission | function | Inherited from Client |
addPermission | function | Inherited from Client |
sendCreatePermission | function | Inherited from Client |
sendChannelBind | function | Inherited from Client |
sendRefresh | function | Inherited from Client |
sendData | function | Inherited from Client |
handleResponse | function | Inherited from Client |
handleAllocateResponse | function | Inherited from Client |
handleAllocateErrorResponse | function | Inherited from Client |
handleCreatePermissionResponse | function | Inherited from Client |
handleCreatePermissionErrorResponse | function | Inherited from Client |
handleRefreshResponse | function | Inherited from Client |
handleDataIndication | function | Inherited from Client |
transportProtocol | function | Inherited from Client |
createTransaction | function | Inherited from Client |
authenticateRequest | function | Inherited from Client |
sendAuthenticatedTransaction | function | Inherited from Client |
removeTransaction | function | Inherited from Client |
mappedAddress | function | Inherited from Client |
relayedAddress | function | Inherited from Client |
closed | function | Inherited from Client |
observer | function | Inherited from Client |
options | function | Inherited from Client |
addPermission | function | Inherited from Client |
addPermission | function | Inherited from Client |
hasPermission | function | Inherited from Client |
hasPermission | function | Inherited from Client |
removePermission | function | Inherited from Client |
removePermission | function | Inherited from Client |
_observer | variable | Inherited from Client |
_options | variable | Inherited from Client |
_socket | variable | Inherited from Client |
_timer | variable | Inherited from Client |
_error | variable | Inherited from Client |
_mappedAddress | variable | Inherited from Client |
_relayedAddress | variable | Inherited from Client |
_realm | variable | Inherited from Client |
_nonce | variable | Inherited from Client |
_pendingIndications | variable | Inherited from Client |
_transactions | variable | Inherited from Client |
setError | function | Inherited from Client |
onSocketConnect | function | Inherited from Client |
onSocketRecv | function | Inherited from Client |
onSocketClose | function | Inherited from Client |
onTransactionProgress | function | Inherited from Client |
onStateChange | function | Inherited from Client |
onTimer | function | Inherited from Client |
StateChange | variable | Inherited from Stateful |
Stateful | function | Inherited from Stateful |
~Stateful | function | Inherited from Stateful |
stateEquals | function | Inherited from Stateful |
stateBetween | function | Inherited from Stateful |
state | function | Inherited from Stateful |
state | function | Inherited from Stateful |
_state | variable | Inherited from Stateful |
beforeStateChange | function | Inherited from Stateful |
onStateChange | function | Inherited from Stateful |
setState | function | Inherited from Stateful |
setState | function | Inherited from Stateful |
operator<< | friend | Inherited from IAllocation |
IAllocation | function | Inherited from IAllocation |
~IAllocation | function | Inherited from IAllocation |
IAllocation | function | Inherited from IAllocation |
operator= | function | Inherited from IAllocation |
IAllocation | function | Inherited from IAllocation |
operator= | function | Inherited from IAllocation |
updateUsage | function | Inherited from IAllocation |
setLifetime | function | Inherited from IAllocation |
setBandwidthLimit | function | Inherited from IAllocation |
expired | function | Inherited from IAllocation |
deleted | function | Inherited from IAllocation |
bandwidthLimit | function | Inherited from IAllocation |
bandwidthUsed | function | Inherited from IAllocation |
bandwidthRemaining | function | Inherited from IAllocation |
timeRemaining | function | Inherited from IAllocation |
tuple | function | Inherited from IAllocation |
username | function | Inherited from IAllocation |
lifetime | function | Inherited from IAllocation |
permissions | function | Inherited from IAllocation |
relayedAddress | function | Inherited from IAllocation |
addPermission | function | Inherited from IAllocation |
addPermission | function | Inherited from IAllocation |
addPermissions | function | Inherited from IAllocation |
removePermission | function | Inherited from IAllocation |
removePermission | function | Inherited from IAllocation |
removeAllPermissions | function | Inherited from IAllocation |
removeExpiredPermissions | function | Inherited from IAllocation |
hasPermission | function | Inherited from IAllocation |
hasPermission | function | Inherited from IAllocation |
print | function | Inherited from IAllocation |
_tuple | variable | Inherited from IAllocation |
_username | variable | Inherited from IAllocation |
_permissions | variable | Inherited from IAllocation |
_lifetime | variable | Inherited from IAllocation |
_bandwidthLimit | variable | Inherited from IAllocation |
_bandwidthUsed | variable | Inherited from IAllocation |
_createdAt | variable | Inherited from IAllocation |
_updatedAt | variable | Inherited from IAllocation |
_deleted | variable | Inherited from IAllocation |
Inherited from Client
| Kind | Name | Description |
|---|---|---|
function | Client | |
function | ~Client virtual | |
function | start virtual | Connects the socket to the TURN server and starts the allocation sequence. Permissions must be added via addPermission() before calling this. |
function | stop virtual | Stops the timer, cancels pending transactions, and closes the socket. |
function | sendAllocate virtual | Sends 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. |
function | addPermission virtual | Adds multiple peer IP addresses to the permission list. |
function | addPermission virtual override | Adds 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. |
function | sendCreatePermission virtual | Sends 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. |
function | sendChannelBind virtual | Channel 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. |
function | sendRefresh virtual | Sends a Refresh request to extend the allocation lifetime. Called automatically by the timer when roughly one-third of the lifetime remains. |
function | sendData virtual | Sends 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. |
function | handleResponse virtual | Dispatches an incoming STUN/TURN response to the appropriate handler. |
function | handleAllocateResponse virtual | Processes a successful Allocate response; extracts mapped/relayed addresses and advances the state to Authorizing, then sends CreatePermission. |
function | handleAllocateErrorResponse virtual | Handles an Allocate error response; manages the 401 challenge/re-send flow and sets the client to Failed for unrecoverable errors. |
function | handleCreatePermissionResponse virtual | Handles a successful CreatePermission response; flushes queued Send Indications and advances state to Success. |
function | handleCreatePermissionErrorResponse virtual | Handles a failed CreatePermission response; clears all permissions and sets the client to Failed. |
function | handleRefreshResponse virtual | Handles a Refresh response; updates the stored lifetime. |
function | handleDataIndication virtual | Handles an incoming Data Indication; extracts peer address and data and forwards to ClientObserver::onRelayDataReceived(). |
function | transportProtocol virtual | |
function | createTransaction virtual | Creates a new STUN transaction, registers the progress callback, and adds it to the active transaction list. |
function | authenticateRequest virtual | Adds STUN long-term credential attributes (Username, Realm, Nonce, MessageIntegrity) to request if the realm has been received from the server. |
function | sendAuthenticatedTransaction virtual | Calls authenticateRequest() then sends the transaction. |
function | removeTransaction virtual | Removes a transaction from the active list. The IntrusivePtr keeps the object alive until the caller's copy is released. |
function | mappedAddress const | |
function | relayedAddress virtual const override | |
function | closed const | |
function | observer | |
function | options const | |
function | addPermission virtual | Adds a permission for ip, or refreshes the existing one. |
function | addPermission virtual | Adds a permission for address, or refreshes the existing one. The port is ignored; TURN permissions are IP-only. |
function | hasPermission virtual | Checks whether a permission exists for peerIP. Local addresses (192.168.x.x and 127.x.x.x) are always permitted. |
function | hasPermission virtual | Checks whether a permission exists for peerAddress. The port is ignored; TURN permissions are IP-only. |
function | removePermission virtual | Removes the permission for ip if present. |
function | removePermission virtual | Removes 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 | _pendingIndications | A list of queued Send indication packets awaiting server permissions. |
variable | _transactions | A list containing currently active transactions. |
function | setError virtual | Sets the error field and transitions the client to the Failed state. |
function | onSocketConnect virtual | Socket connect callback; starts the timer and sends the first Allocate request. |
function | onSocketRecv virtual | Socket receive callback; parses STUN messages from the buffer and dispatches them. |
function | onSocketClose virtual | Socket close callback; shuts down the client and records the socket error. |
function | onTransactionProgress virtual | STUN transaction state-change callback; handles Success and Failed outcomes. |
function | onStateChange override | Forwards state-change events to the observer. |
function | onTimer virtual | Periodic timer callback; re-allocates on expiry or refreshes when lifetime is below one-third remaining. Also calls ClientObserver::onTimer(). |
Inherited from Stateful
| Kind | Name | Description |
|---|---|---|
variable | StateChange | Signals when the state changes. |
function | Stateful inline | |
function | ~Stateful virtual inline | |
function | stateEquals virtual const inline | Returns true if the current state ID equals the given ID. |
function | stateBetween virtual const inline | Returns true if the current state ID is in the inclusive range [lid, rid]. |
function | state virtual inline | Returns a mutable reference to the current state. |
function | state virtual const inline | Returns a copy of the current state. |
variable | _state | |
function | beforeStateChange virtual inline | Override to handle pre state change logic. Return false to prevent state change. |
function | onStateChange virtual inline | Override to handle post state change logic. |
function | setState virtual inline | Sets the state and sends the state signal if the state change was successful. |
function | setState virtual inline | Sets the state and sends the state signal if the state change was successful. |
Inherited from IAllocation
| Kind | Name | Description |
|---|---|---|
friend | operator<< inline | |
function | IAllocation | |
function | ~IAllocation virtual | |
function | IAllocation | Deleted constructor. |
function | operator= | Deleted assignment operator. |
function | IAllocation | Deleted constructor. |
function | operator= | Deleted assignment operator. |
function | updateUsage virtual | Updates the last-activity timestamp and accumulates bandwidth usage. Call this whenever data is relayed through the allocation. |
function | setLifetime virtual | Sets the allocation lifetime in seconds and resets the activity timestamp, effectively extending the expiry from the current moment. |
function | setBandwidthLimit virtual | Sets the maximum number of bytes this allocation may relay in its lifetime. Pass 0 to disable bandwidth limiting. |
function | expired virtual const | |
function | deleted virtual const | Returns true if the allocation's deleted flag is set and or if the allocation has expired. |
function | bandwidthLimit virtual const | |
function | bandwidthUsed virtual const | |
function | bandwidthRemaining virtual const | |
function | timeRemaining virtual const | |
function | tuple virtual | |
function | username virtual const | |
function | lifetime virtual const | |
function | permissions virtual const | |
function | relayedAddress virtual const | |
function | addPermission virtual | Adds a permission for ip, or refreshes the existing one. |
function | addPermission virtual | Adds a permission for address, or refreshes the existing one. The port is ignored; TURN permissions are IP-only. |
function | addPermissions virtual | Adds (or refreshes) permissions for multiple IPs. |
function | removePermission virtual | Removes the permission for ip if present. |
function | removePermission virtual | Removes the permission for address if present. The port is ignored; TURN permissions are IP-only. |
function | removeAllPermissions virtual | Removes all permissions from the list. |
function | removeExpiredPermissions virtual | Removes any permissions whose 5-minute lifetime has elapsed. |
function | hasPermission virtual | Checks whether a permission exists for peerIP. Local addresses (192.168.x.x and 127.x.x.x) are always permitted. |
function | hasPermission virtual | Checks whether a permission exists for peerAddress. The port is ignored; TURN permissions are IP-only. |
function | print virtual const inline | |
variable | _tuple | |
variable | _username | |
variable | _permissions | |
variable | _lifetime | |
variable | _bandwidthLimit | |
variable | _bandwidthUsed | |
variable | _createdAt | |
variable | _updatedAt | |
variable | _deleted |
Public Methods
| Return | Name | Description |
|---|---|---|
TCPClient | ||
void | start virtual override | Connects the socket to the TURN server and starts the allocation sequence. Permissions must be added via addPermission() before calling this. |
void | stop virtual override | Stops the control connection, cancels all relay connections, and calls the base class stop(). |
void | sendConnectRequest virtual | 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). |
void | sendData virtual override | Sends raw data to peerAddress over the established relay connection. The peer must have an active permission and a bound relay connection. |
bool | handleResponse virtual override | Extends the base handler with Connect, ConnectionBind, and ConnectionAttempt responses. |
void | handleConnectResponse virtual | Processes a successful Connect response; extracts the connection ID and calls createAndBindConnection(). |
void | handleConnectErrorResponse virtual | Processes a Connect error response; notifies the observer that binding failed. |
void | handleConnectionBindResponse virtual | Processes a successful ConnectionBind response; arms the relay socket for data transfer and notifies the observer. |
void | handleConnectionBindErrorResponse virtual | Processes a ConnectionBind error response; frees the failed connection. |
void | handleConnectionAttemptIndication virtual | Processes a ConnectionAttempt indication from the server; optionally accepts the incoming peer connection by calling createAndBindConnection(). |
bool | createAndBindConnection virtual | Opens a new TCP relay socket to the TURN server and sends a ConnectionBind request carrying connectionID. |
bool | onRelayConnectionConnect virtual | Relay socket connect callback; sends the ConnectionBind request. |
bool | onRelayDataReceived virtual | Relay socket receive callback; forwards data to the observer. |
bool | onRelayConnectionError virtual | Relay socket error callback; notifies the observer of the error. |
bool | onRelayConnectionClosed virtual | Relay socket close callback; notifies the observer and frees the connection. |
void | freeConnection | Removes the relay connection for peerAddress, unregisters its callbacks, and deletes the associated RelayConnectionBinding. |
int | transportProtocol 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
observerObserver for TCP-specific relay events.optionsClient configuration; defaults to loopback server, 5-min lifetime.
start
virtual override
virtual void start() overrideDefined 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() overrideDefined 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
peerAddressTarget peer address.
sendData
virtual override
virtual void sendData(const char * data, size_t size, const net::Address & peerAddress) overrideDefined 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
dataPayload bytes.sizeNumber of bytes to send.peerAddressDestination peer (must have an entry in connections()).
Reimplements
handleResponse
virtual override
virtual bool handleResponse(const stun::Message & response) overrideDefined in src/turn/include/icy/turn/client/tcpclient.h:118
Extends the base handler with Connect, ConnectionBind, and ConnectionAttempt responses.
Parameters
responseIncoming 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
responseConnect 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
responseConnect 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
responseConnectionBind 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
responseConnectionBind 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
responseConnectionAttempt 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
connectionIDTURN CONNECTION-ID from the server.peerAddressPeer 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
socketThe 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
socketThe receiving relay socket.bufferReceived data.peerAddressSource 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
socketThe affected relay socket.errorError 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
socketThe 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
peerAddressPeer whose connection to release.
transportProtocol
virtual override
virtual int transportProtocol() overrideDefined 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() constDefined in src/turn/include/icy/turn/client/tcpclient.h:180
Protected Attributes
| Return | Name | Description |
|---|---|---|
TCPClientObserver & | _observer | |
ConnectionManager | _connections |
_observer
TCPClientObserver & _observerDefined in src/turn/include/icy/turn/client/tcpclient.h:183
_connections
ConnectionManager _connections