Featured

WebSockets Client Delphi and CBuilder

QuickStart 

1. Create a new Window Forms Application

2. Drop a TsgcWebSocketClient onto a Form and configure Host and Port Properties to connect to Server.

3. Drop a TButton in a Form, Double Click and type this code: 

TsgcWebSocketClient1.Active := True; 

4. Drop a Button onto the Form, Double Click and type this code: 

TsgcWebSocketClient1.WriteData('Hello Server From VCL Client'); 

SSL

TsgcWebSocketClient can connect to WebSocket servers using secure and none-secure connections. 

TLSOptions

In TLSOptions property there are the properties to customize a secure connection. The most important property is version, which specifies the version of TLS protocol. Usually setting TLS property to true and TLSOptions.Version to tls1_2 is enough for the wide majority of WebSocket Servers.

If you get an error trying to connect to a server about TLS protocol, most probably this server requires a TLS version newer than you set. Example: if you set TLSOptions.Version = tls1_0 and you get an error about TLS protocol, try to set to tls1_2 and most probably will work.

If TLSOptions.IOHandler is set to iohOpenSSL, you need to deploy OpenSSL libraries (which are the libraries that handle all TLS stuff), check the following article about OpenSSL.

If TLSOptions.IOHandler is set to iohSChannel, then there is no need to deploy any library.

Authentication 

TsgcWebSocket client supports 4 types of Authentications:

  • Basic: sends an HTTP Header during WebSocket HandShake with User and Password encoded as Basic Authorization.
  • Token: sends a Token as HTTP Header during WebSocket HandShake, just set in Authentication.Token.AuthToken the required token by server.
  • Session: first client request an HTTP session to server and if server returns a session this is passed in GET HTTP Header of WebSocket HandShake. (* own authorization method for sgcWebSockets library).
  • URL: client request authorization using GET HTTP Header of WebSocket HandShake. (* own authorization method for sgcWebSockets library).

Authorization Basic
Is a simple authorization method where user and password are encoded and passes as an HTTP Header. Just set User and Password and enable only Basic Authorization type to use this method.
oClient := TsgcWebSocketClient.Create(nil);
oClient.Authorization.Enabled := true;
oClient.Authorization.Basic.Enabled := true;
oClient.User := 'your user';
oClient.Password := 'your password';
oClient.Authorization.Token.Enabled := false;
oClient.Authorization.URL.Enabled := false;
oClient.Authorization.Session.Enabled := false;
oClient.Active := True; 

HeartBeat 

HeartBeat property allows to send a Ping every X seconds to maintain connection alive. Some servers, close TCP connections if there is no data exchanged between peers. HeartBeat solves this problem, sending a ping every a specific interval. Usually this is enough to maintain a connection active, but you can set a TimeOut interval if you want to close connection if a response from server is not received after X seconds.

Example: send a ping every 30 seconds

oClient := TsgcWebSocketClient.Create(nil);
oClient.HeartBeat.Interval := 30;
oClient.HeartBeat.Timeout := 0;
oClient.HeartBeat.Enabled := true;
oClient.Active := true; 

 WatchDog

If WatchDog is enabled, when client detects a disconnection, WatchDog try to reconnect again every X seconds until connection is active again.

Example: reconnect every 10 seconds after a disconnection with unlimited attempts. 

oClient := TsgcWebSocketClient.Create(nil);
oClient.WatchDog.Interval := 10;
oClient.WatchDog.Attempts := 0;
oClient.WatchDog.Enabled := true;
oClient.Active := true; 

Connect TCP Server

TsgcWebSocketClient can connect to WebSocket servers but can connect to plain TCP Servers too. 

URL Property

The most easy way to connect to a WebSocket server is use URL property and call Active = true.

Example: connect to 127.0.0.1 port 5555

oClient := TsgcWebSocketClient.Create(nil);
oClient.URL := 'tcp://127.0.0.1:5555';
oClient.Active := true; 

Send Message

Once client has connected to server, it can send Text Messages to server. To send a Text Message, just call WriteData() method and send your text message. 

Send a Text Message

Call To WriteData() method and send a Text message. This method is executed on the same thread that is called.

TsgcWebSocketClient1.WriteData('My First sgcWebSockets Message!.'); 

Receive Messages 

When client receives a Text Message, OnMessage event is fired, just read Text parameter to know the string of message received. 

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

By default, client uses neAsynchronous method to dispatch OnMessage event, this means that this event is executed on the context of Main Thread, so it's thread-safe to update any control of a form for example.

If your client receives lots of messages or you need to control the synchronization with other threads, set NotifyEvents property to neNoSync, this means that OnMessage event will be executed on the context of connection thread, so if you require to update any control of a form or access shared objects, you must implement your own synchronization methods. 

Online Documentation 

Download Trial

UpdateMode in DataSet Protocol
WebSockets Server Delphi and CBuilder

Related Posts