TURN Client

Overview

TsgcTURNClient is the client that implements the TURN protocol and allows you 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.

At a glance

Features

• Native Delphi implementation with full ANSI/Unicode support.

Technical specification

Main properties

The principal published / public properties used to configure and drive the component. Consult the online help for the full list.

Main methods

The principal public methods exposed by the component.

Public events

The component exposes the following published events; consult the online help for full event-handler signatures.

Quick Start

Drop the component on a form, configure the properties below and activate it. The snippet that follows shows the typical TsgcTURNClient — Basic usage configuration sourced from the online help.

Delphi (VCL / FireMonkey)

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;

C++ Builder

TsgcTURNClient oTURN = new TsgcTURNClient(this);
    oTURN->Host = "turn.sgcwebsockets.com";
    oTURN->Port = 3478;
    oTURN->Allocate();

    private void OnTURNAllocate(TObject *Sender, const TsgcSocketConnection *aSocket, 
     const TsgcSTUN_Message *aMessage, const TsgcTURN_ResponseAllocation *aAllocation)
    {
    DoLog("Relayed IP: " + aAllocation->RelayedIP + ". Relayed Port: " + IntToStr(aAllocation->RelayedPort));
    }

    private void OnSTUNResponseError(TObject *Sender, const TsgcSTUN_Message *aMessage,
    const TsgcSTUN_ResponseError *aError)
    {
    DoLog("Error: " + IntToStr(aError->Code) + " " + aError->Reason);
    }

.NET (C#)

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);
    }

Common scenarios

The following scenarios are lifted verbatim from the online help. Each shows the configuration and method calls needed to drive the component through a specific real-world flow.

1 · TURN Client | Send Indication

TURN Protocol supports 2 mechanisms for sending and receiving data from peers, one of them is Send and Data mechanisms.

oTURN.SendIndication('80.147.23.157', 5000, 'random data');

procedure OnTURNDataIndication(Sender: TObject; const aSocket: TsgcSocketConnection; 
 const aMessage: TsgcSTUN_Message; const aDataIndication: TsgcTURN_ResponseDataIndication);
begin
DoLog('#Data Indication: [' + aDataIndication.PeerIP + ':' + IntToStr(aDataIndication.PeerPort) + '] ' + 
   sgcGetStringFromBytes(aDataIndication.Data));
end;

oTURN->SendIndication("80.147.23.157", 5000, "random data");

void OnTURNDataIndication(TObject *Sender, const TsgcSocketConnection *aSocket, 
 const TsgcSTUN_Message *aMessage, const TsgcTURN_ResponseDataIndication *aDataIndication)
{
DoLog("#Data Indication: [" + aDataIndication->PeerIP + ":" + IntToStr(aDataIndication->PeerPort) + "] " + 
   sgcGetStringFromBytes(aDataIndication->Data));
}

oTURN.SendIndication("80.147.23.157", 5000, "random data");


void OnTURNDataIndication(Component Sender, TsgcSocketConnection aSocket, 
 TsgcSTUN_Message aMessage, TsgcTURN_ResponseDataIndication aDataIndication)
{
DoLog("#Data Indication: [" + aDataIndication.PeerIP + ":" + IntToStr(aDataIndication.PeerPort) + "] " + 
    aDataIndication.Data.ToString());
}

2 · TURN Client | Allocate IP Address

TURN Protocol allows you to use a Relayed IP Address to exchange data between peers that are behind NATs.

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;

TsgcTURNClient oTURN = new TsgcTURNClient(this);
oTURN->Host = "turn.sgcwebsockets.com";
oTURN->Port = 3478;
oTURN->Allocate();


private void OnTURNAllocate(TObject *Sender, const TsgcSocketConnection *aSocket,
const TsgcSTUN_Message *aMessage, const TsgcTURN_ResponseAllocation *aAllocation)
{
DoLog("Relayed IP: " + aAllocation->RelayedIP + ". Relayed Port: " + 
   IntToStr(aAllocation->RelayedPort));
}


private void OnSTUNResponseError(TObject *Sender, const TsgcSTUN_Message *aMessage,
const TsgcSTUN_ResponseError *aError)
{
DoLog("Error: " + IntToStr(aError->Code) + " " + aError->Reason);
}

TsgcTURNClient oTURN = new TsgcTURNClient();
oTURN.Host = "turn.sgcwebsockets.com";
oTURN.Port = 3478;
oTURN.Allocate();


private void OnTURNAllocate(Component Sender, TsgcSocketConnection aSocket, TsgcSTUN_Message aMessage, 
 const TsgcTURN_ResponseAllocation aAllocation)
{
DoLog("Relayed IP: " + aAllocation.RelayedIP + ". Relayed Port: " + 
    aAllocation.RelayedPort.ToString());
}

private void OnSTUNResponseError(Component Sender, TsgcSTUN_Message aMessage, 
 TsgcSTUN_ResponseError aError)
{
DoLog("Error: " + aError.Code.ToString() + " " + aError.Reason);
}

3 · TURN Client | Channels

Channels provide a way for the TURN Client and Server to send application data using ChannelData messages, which have less overhead than Send and Data Indications.

oTURN.ChannelBind('80.147.23.157', 5000);

procedure OnTURNChannelBind(Sender: TObject; const aSocket: TsgcSocketConnection; 
 const aMessage: TsgcSTUN_Message; const aChannelBind: TsgcTURN_ResponseChannelBind);
begin
DoLog('#Channel Bind: ' + IntToStr(aChannelBind.Channel));
end;

oTURN->ChannelBind("80.147.23.157", 5000);

void OnTURNChannelBind(TObject *Sender, const TsgcSocketConnection *aSocket, 
 const TsgcSTUN_Message *aMessage, const TsgcTURN_ResponseChannelBind *aChannelBind)
{
DoLog("#Channel Bind: " + IntToStr(aChannelBind->Channel));
}

oTURN.ChannelBind("80.147.23.157", 5000);


void OnTURNChannelBind(Component Sender, TsgcSocketConnection aSocket, 
 TsgcSTUN_Message aMessage, TsgcTURN_ResponseChannelBind aChannelBind)
{
DoLog("#Channel Bind: " + aChannelBind.Channel.ToString());
}

4 · TURN Client | Create Permissions

When a new Allocation is created in a TURN server, this allocation cannot process any incoming packet from other peers if has no permissions. So, in order to allow other peers to communicate using a Relayed IP Address, first the TURN Client must create permissions for the IP Addresses that are allowed to exchange Data.

oTURN.CreatePermission('80.147.23.157');

procedure OnTURNCreatePermission(Sender: TObject; const aSocket: TsgcSocketConnection; 
 const aMessage: TsgcSTUN_Message; const aCreatePermission: TsgcTURN_ResponseCreatePermission);
begin
DoLog('#Create Permission: ' + aCreatePermission.IPAddresses.Text);
end;

oTURN->CreatePermission("80.147.23.157");


void OnTURNCreatePermission(TObject *Sender, const TsgcSocketConnection *aSocket,
 const TsgcSTUN_Message *aMessage, const TsgcTURN_ResponseCreatePermission *aCreatePermission)
{
DoLog("#Create Permission: " + aCreatePermission->IPAddresses->Text);
}

oTURN.CreatePermission("80.147.23.157");


void OnTURNCreatePermission(Component Sender, TsgcSocketConnection aSocket,
  TsgcSTUN_Message aMessage, TsgcTURN_ResponseCreatePermission aCreatePermission)
{
DoLog("#Create Permission: " + aCreatePermission.IPAddresses);
}

Sources used to build this document

Every external claim links back to a primary source. The online-help references decode the canonical deep-link the company maintains for this component.