Delphi TURN Client Component (2/4)

Basic Usage 

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

• Host: the IP or DNS name of the server, example: turn.sgcwebsockets.com
• Port: the listening Server port, example: 3478

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.
• If the server returns an error, the event OnSTUNResponseError will be called and you can access the Error Code and Reason reading the aError object.

oTURN := TsgcTURNClient.Create(nil);
oTURN.Host := 'turn.sgcwebsockets.com';
oTURN.Port := 3478;
oTURN.Allocate;
 
procedure OnTURNAllocate(Sender: TObject; const aSocket: TsgcSocketConnection; const aMessage: TsgcSTUN_Message; const aAllocation: TsgcTURN_ResponseAllocation);
begin
  DoLog('Relayed IP: ' + aAllocation.RelayedIP + '. Relayed Port: ' + IntToStr(aAllocation.RelayedPort));
end;
 
procedure OnSTUNResponseError(Sender: TObject; const aMessage: TsgcSTUN_Message;
const aError: TsgcSTUN_ResponseError);
begin
  DoLog('Error: ' + IntToStr(aError.Code) + ' ' + aError.Reason);
end; 

TURN Relay Data 

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.

Methods 

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.