TsgcTURNClient is the client that implements the TURN protocol and allows to send allocation requests to TURN servers. The client inherits from STUN Client, so all methods supported by STUN client are already supported by TURN Client.
Usually TURN servers runs on UDP port 3478 and don't require authentication, so in order to send a TURN request, fill the server properties to allow the client know where connect and Handle the events where the component will receive the response from server.
Configure the server
Call the method Allocate, to send a request to allocate an IP Address and a Port to the TURN server.
Handle the events
If the server returns a successful response, the event OnTURNAllocateSuccess will be called and you can access to the Allocation information reading the aAllocation object.
TsgcTURNClient oTURN = new TsgcTURNClient();
oTURN.Host = "turn.sgcwebsockets.com";
oTURN.Port = 3478;
oTURN.Allocate();
private void OnTURNAllocate(Component Sender, const TsgcSocketConnection aSocket,
const TsgcSTUN_Message aMessage, const TsgcTURN_ResponseAllocation aAllocation)
{
DoLog("Relayed IP: " + aAllocation.RelayedIP + ". Relayed Port: " + aAllocation.RelayedPort.ToString());
}
private void OnSTUNResponseError(Component Sender, const TsgcSTUN_Message aMessage,
const TsgcSTUN_ResponseError aError)
{
DoLog("Error: " + aError.Code.ToString() + " " + aError.Reason);
}
There are basically 2 ways to send data between peers:
1. Send Indications, which encapsulates the data in a STUN packet. Use the method SendIndication to send an indication to other peer.
2. Use Channel Data, it's a more efficient way to send data between peers because the packet size is smaller than indications. Use SendChannelData method to send a channel data to other peer.
When a TURN server receives a packet in a Relayed IP Address from an IP Address with an active permission, if there is channel data bound to the peer IP Address, the TURN client will receive the data in the event OnTURNChannelData. But if there is no channel, the TURN client will receive the data in the event OnTURNData.
Allocate
This method sends a request to the server to allocate an IP Address and a Port which will be used to relay date between the peers.
If the server can allocate successfully an IP Address and a Port, the event OnTURNAllocate event will be called. If not, the OnSTUNRequestError event will be called.
The client saves in the Allocation property of the client, the data returned by server about the allocated IP Address.
Refresh
If there is an active allocation, the client can refresh it sending a Refresh request.
This method has a parameter called Lifetime, if the value is zero, the allocation will expire immediately. If the value is greater of zero, it means the number of seconds to expiry.
If the result is successful, the event OnTURNRefresh will be called.
CreatePermission
This method creates a new permission fo the IP Address set as an argument of the CreatePermission method. If the permission already exists for this IP, it will be refreshed by the server.
If the result is successful, the event OnCreatePermission will be called.
SendIndication
This method sends a data to the peer identified as PeerIP and PeerPort. This method requires there is an active permission for this IP in the TURN server.
ChannelBind
This method sends a request to the server to create a new channel to communicate with the peer identified as PeerIP and PeerPort.
if the result is successful, the event OnChannelBind will be called. You can access to the channel-id assigned, reading the parameter aChannelBind of the event.
SendChannelData
This method sends data to a peer using a ChannelId. This method requires the channel exists and is active.
Host: it's the IP Address or DNS name of TURN server where the client will send a binding request.
Port: it's the listening port of TURN server, by default 3478.
IPVersion: it's the Family Address, by default IPv4.
Transport: it's the transport used to connect to TURN server, by default UDP.
STUNOptions: here are defined the specific STUN options of client component
Fingerprint: if enabled, the message includes a fingerprint that aids to identify STUN messages from packets of other protocols when the two are multiplexed on the same transport address.
Software: if enabled, sends an attribute with the name of the software being used by the client.
Authentication: some STUN servers requires that requests are authenticated.
Credentials: there are 2 types of Authentication: LongTermCredentials and ShortTermCredentials. By default the requests are not authenticated
Username: the string that identifies the user.
Password: the secret string.
TURNOptions: here are defined the specific TURN options of client component
Allocation: here are defined the Allocation properties
Lifetime: default lifetime in seconds, by default 600 seconds.
Authentication: usually TURN servers are user protected.
Credentials: by default Long-Term credentials is enabled
Username: the string that identifies the user.
Password: the secret string.
AutoRefresh: when a new allocation is created, requires to be refreshed in order to be used by the peers. Here you can define which methods are automatically refreshed by the TURN Client Component.
Allocations
Channels
Permissions
Fingerprint: if enabled, the message includes a fingerprint that aids to identify STUN messages from packets of other protocols when the two are multiplexed on the same transport address.
Software: if enabled, sends an attribute with the name of the software being used by the client.
RetransmissionOptions: when messages are sent using UDP as transport, UDP doesn't includes a mechanism to know if a message has arrived or not to other peer. This property allows to configure a mechanism to re-send UDP messages if not arrived after a small time.
Enabled: if enabled, the message will be re-send until receives a confirmation or the maximum number of retries has been reached.
RTO: retransmission time in milliseconds, by default 500ms. For example, assuming an RTO of 500 ms, requests would be sent at times 0 ms, 500 ms, 1500 ms, 3500 ms, 7500 ms, 15500 ms, and 31500 ms.
MaxRetries: Max number of retries, by default 7.
LogFile: if enabled save stun messages to a specified log file, useful for debugging. The access to log file is not thread safe if it's accessed from several threads.
Enabled: if enabled every time a message is received and sent by client it will be saved on a file.
FileName: full path to the filename.
NotifyEvents: defines which mode to notify WebSocket events.
neAsynchronous: this is the default mode, notify threaded events on asynchronous mode, adds events to a queue that are synchronized with the main thread asynchronously.
neSynchronous: if this mode is selected, notify threaded events on synchronous mode, needs to synchronize with the main thread to notify these events.
neNoSync: there is no synchronization with the main thread, if you need to access to controls that are not thread-safe, you need to implement your own synchronization methods.
The TURN client inherits from STUN Client the events: OnSTUNResponseSuccess, OnSTUNResponseError, OnSTUNException and OnSTUNBeforeSend.
Additionally, includes the following events to handle all TURN messages.
OnTURNAllocate
This event is called after a successful IP Address allocation in the TURN server.
OnTURNCreatePermission
This event is called after creating a new permission in the TURN server.
OnTURNRefresh
This event is called after receiving a successful refresh response from the TURN Server.
OnTURNDataIndication
The event is called when the client receives a DATA Indication from other peer.
OnTURNChannelBind
This event is called when the server creates a new channel. Returns the new channel-id created.
OnTURNChannelData
The event is called when the client receives new Data from a Channel previously created.