WebSocket Client (Delphi)

Overview

Client WebSocket component — connects to any RFC 6455 WebSocket server and sends/receives text and binary messages.

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 TsgcWebSocketClient | Client Exceptions configuration sourced from the online help.

Delphi (VCL / FireMonkey)

procedure OnError(Connection: TsgcWSConnection; const Error: string);
begin
WriteLn('#error: ' + Error);
end;

C++ Builder

void OnError(TsgcWSConnection *Connection, const string Error)
{
WriteLn("#error: " + Error);
}

.NET (C#)

private void OnError(TsgcWSConnection Connection, string aError)
{
Console.WriteLine("#error: " + aError);
}

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 · TsgcWebSocketClient | Client Proxies

TsgcWebSocket client supports connections through proxies. To configure a proxy connection, just fill in the Proxy properties of the TsgcWebSocket client.

Client := TsgcWebSocketClient.Create(nil);
Client.Proxy.Enabled := true;
Client.Proxy.Username := 'user';
Client.Proxy.Password := 'secret';
Client.Proxy.Host := '80.55.44.12';
Client.Proxy.Port := 8080;
Client.Active := True;

Client = new TsgcWebSocketClient();
Client->Proxy->Enabled = true;
Client->Proxy->Username = "user";
Client->Proxy->Password = "secret";
Client->Proxy->Host = "80.55.44.12";
Client->Proxy->Port = 8080;
Client->Active = true;

Client = new TsgcWebSocketClient();
Client.Proxy.Enabled = true;
Client.Proxy.Username = "user";
Client.Proxy.Password = "secret";
Client.Proxy.Host = "80.55.44.12";
Client.Proxy.Port = 8080;
Client.Active = true;

2 · TsgcWebSocketClient | Client Register Protocol

By default, TsgcWebSocketClient does not use any SubProtocol. WebSocket sub-protocols are built on top of the WebSocket protocol and define a custom message protocol. Examples of WebSocket sub-protocols include MQTT, STOMP, etc.

Client := TsgcWebSocketClient.Create(nil);
Client.Host := 'server host';
Client.Port := server.port;
Client.RegisterProtocol('myprotocol');
Client.Active := True;

Client = new TsgcWebSocketClient();
Client->Host = "server host";
Client->Port = server.port;
Client->RegisterProtocol("myprotocol");
Client->Active = true;

Client = new TsgcWebSocketClient();
Client.Host = "server host";
Client.Port = server.port;
Client.RegisterProtocol("myprotocol");
Client.Active = true;

3 · TsgcWebSocketClient | Client Send a Text and Binary Message

WebSocket protocol only allows two types of messages: Text or Binary. However, you cannot send binary data along with text in the same message.

sgcWSStreamWrite('00001', oStream);
TsgcWebSocketClient1.WriteData(oStream);

sgcWSStreamWrite("00001", oStream);
TsgcWebSocketClient1->WriteData(oStream);

sgcWSBytesWrite("00001", oBytes);
TsgcWebSocketClient1.WriteData(oBytes);

4 · TsgcWebSocketClient | Receive Binary Messages

When the client receives a Binary Message, the OnBinary event is fired. Read the Data parameter to retrieve the binary message received.

procedure OnBinary(Connection: TsgcWSConnection; const Data: TMemoryStream);
var
oBitmap: TBitmap;
begin
oBitmap := TBitmap.Create;
Try
oBitmap.LoadFromStream(Data);
Image1.Picture.Assign(oBitmap);
Log(
'#image uncompressed size: ' + IntToStr(Data.Size) +
'. Total received: ' + IntToStr(Connection.RecBytes));
Finally
FreeAndNil(oBitmap);
End;
end;

void OnBinary(TsgcWSConnection *Connection, const TMemoryStream *Data)
{
oBitmap = new TBitmap();
oBitmap->LoadFromStream(Data);
Image1->Picture->Assign(oBitmap);
Log(
"#image uncompressed size: " + IntToStr(Data->Size) +
". Total received: " + IntToStr(Connection->RecBytes));
delete oBitmap;
}

private void OnBinary(TsgcWSConnection Connection, byte[] Bytes)
{
MemoryStream stream = new MemoryStream(Bytes);
pictureBox1.Image = new Bitmap(stream);
}

5 · TsgcWebSocketClient | Receive Text Messages

When the client receives a Text Message, the OnMessage event is fired. Read the Text parameter to retrieve the string of the message received.

procedure OnMessage(Connection: TsgcWSConnection; const Text: string);
begin
ShowMessage('Message Received from Server: ' + Text);
end;

void OnMessage(TsgcWSConnection *Connection, const string Text)
{
ShowMessage("Message Received from Server: " + Text);
}

void OnMessage(TsgcWSConnection Connection, string Text)
{
MessageBox.Show("Message Received from Server: " + Text);
}

6 · TsgcWebSocketClient | SChannel Get Connection Info

Once the client has connected to the secure server, you can request information about which TLS version is being used (TLS 1.2, TLS 1.3, etc.), the cipher used, strength, and more.

uses
 </code><span>sgcIdSSL, sgcSSL_SChannel_Indy, sgcSSL_SChannel;
</span>
<code class="delphi">var
SSL: TsgcIdSSLIOHandlerSocketSChannel;
oClient := TsgcWebSocketClient.Create(nil);
oClient.URL := 'wss://www.esegece.com:2053';
oClient.TLSOptions.Version := tls1_2;
oClient.TLSOptions.IOHandler := iohSChannel;
oClient.OnSSLAfterCreateHandler := OnSSLAfterCreateHandlerEvent;
oClient.OnConnect := OnConnectEvent;
oClient.Active := True;
procedure OnSSLAfterCreateHandlerEvent(Sender: TObject; aType: TwsSSLHandler; 
 aSSLHandler: TIdSSLIOHandlerSocketBase);
begin
if aSSLHandler.ClassType = TsgcIdSSLIOHandlerSocketSChannel then
SSL := TsgcIdSSLIOHandlerSocketSChannel(aSSLHandler);
end;
procedure OnConnectEvent(Connection: TsgcWSConnection);
var
oInfo: TsgcSChannelConnectionInfo;
begin
if Assigned(SSL) then
begin
oInfo := SSL.GetInfo;
if (oInfo.Protocol != tls1_2) then
raise Exception.Create('Client cannot connect using TLS 1.2');
end;
end;

oClient = new TsgcWebSocketClient();
oClient->URL = "wss://www.esegece.com:2053";
oClient->TLSOptions->Version = tls1_2;
oClient->TLSOptions->IOHandler = iohSChannel;
oClient->OnSSLAfterCreateHandler = OnSSLAfterCreateHandlerEvent;
oClient->OnConnect = OnConnectEvent;
oClient->Active = true;
void OnSSLAfterCreateHandlerEvent(TObject *Sender, TwsSSLHandler aType, 
 TIdSSLIOHandlerSocketBase *aSSLHandler)
{
if (aSSLHandler->ClassType() == __classid(TsgcIdSSLIOHandlerSocketSChannel))
{
SSL = dynamic_cast<TsgcIdSSLIOHandlerSocketSChannel*>(aSSLHandler);
}
}
void OnConnectEvent(TsgcWSConnection *Connection)
{
if (SSL != NULL)
{
TsgcSChannelConnectionInfo oInfo = SSL->GetInfo();
if (oInfo->Protocol != tls1_2)
{
throw Exception("Client cannot connect using TLS 1.2");
}
}
}

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.