TTMSFNCWebSocketClient

The TTMSFNCWebSocketClient is a non-visual component enabling to perform websocket communication with a websocket server. It implements the RFC 6455 standard for websocket communication protocol.

Note

For WEB use the existing TWebSocketClient component.

Connect to a server

The basic steps to connect to a server are the following:

• Set the HostName property to the server host.
• Set the Port to the port of the websocket server.
• Set the PathName.Optional
  For example: in case of ws://localhost:5050/socketpath the PathName equals to socketpath.
• Set Active to True or call Connect.

Closing a connection

Calling Disconnect will send the closing frame to the server and wait for the reply. After receiving a closing frame in return, the socket client will close the underlying TCP connection.

Non-WEB only To abort/terminate the connection without sending the closing frame, pass a False boolean value as a parameter to the Disconnect call.

Send data/messages

Use Send(AMessage: string) or Send(ABytes: TBytes) to send a string or binary messages to the server.

procedure TForm1.messageBtnClick(Sender: TObject);
begin
  TMSFNCWebSocketClient1.Send('Hello server!');
end;

Send in multiple frames

By default all messages are sent in one single frame. If SplitMessage is set to True, the message will be split up into multiple frames based on size defined by FrameSize. Size of the frame includes frame headers too.

Receive data/messages

When a string message arrives from the server the OnMessageReceived event will be triggered. The AMessage parameter will contain the string message from the server.

When a binary message arrives from the server the OnBinaryDataReceived event will be triggered. The AData parameter will contain the binary message from the server.

Ping and pong

Whenever a ping message arrives from the server the OnPing event is triggered and an automatic pong message is sent back.

If the Options property contains the twsoManualPong value the poing message is NOT sent automatically. In this case the OnPing can be used to send manually or skip it entirely.

procedure TForm1.TMSFNCWebsocketClient1Ping(Sender: TObject;
  AConnection: TTMSFNCWebSocketConnection; const aData: TArray<System.Byte>);
begin
  AConnection.SendSimpleFrame(focPong);
end;

The OnPong event is triggered whenever a pong message is received from the server.

Detect disconnection

By specification a websocket connection is a TCP connection. A TCP client connection does not get notificed when connection is closed by the server. Whenever attempting to send a message it's recommended to wrap it in a try..except block to detect this:

procedure TForm1.messageBtnClick(Sender: TObject);
begin
  try
    TMSFNCWebSocketClient1.Send('Hello server!');
  except
    //Handle exception
  end;
end;

Secure connection

WEB clients

Connection thorugh browsers supported as:

• http -> ws, wss
• https -> wss

To force secure connection from an http source, set the UseSSL property to True.

Non-WEB clients

When connecting to a secure websocket server, the UseSSL property must be set to True.

For secure connection OpenSSL libraries are required.

Default OpenSSL (1.0.2 and below)

The IO handler is created automatically internally.

• Source files
• Precompiled

OpenSSL 3.x

You can make use of the OnCreateIOHandler event to create a custom IO handler instead of the default created one. Simply look for a library or unit that builds on top of Indy TLS support (for example, TaurusTLS) and implement the event similarly to:

uses
  ..., IdIOHandler, ...

implementation

procedure TForm1.TMSFNCWebsocketClient1CreateIOHandler(Sender: TObject;
  var AIOHandler: TIdIOHandler);
begin
  AIOHandler := TCustomIOHandler.Create;
  TCustomIOHandler(AIOHandler).CustomProperty := xxx;
end;

Keep in mind

When using a custom IO handler, you need to setup all necessary properties and events. These will not be hooked internally.

Properties

Property name	Description
Active: Boolean	Set True to connect and False to disconnect.
AutoCheckInterval: Integer	Used when AutoCheckMessages is enabled.
AutoCheckMessages: Boolean	Check for incoming messages automatically. The interval of this action is defined by AutoCheckInterval.
CheckTimeout: Integer	Timeout for message check.
ConnectTimeout: Integer	Timeout for connection.
FrameSize: Uint64	The size of each frame to be sent. Used when SplitMessage is set to True.
HostName: string	Name of the host. For example: ws://hostname:port/path
Options: TTMSFNCWebsocketOptions	A set connection related options. Values are: - twsoFrameByFrame: Do not assemble the frames - twsoSkipUpgradeCheck: Do not check handshake Upgrade header - twsoSkipVersionCheck: Do not check handshake version - twsoManualPong: Do not send pong automatucally - twsoManualClose: Do not send close reply automatically
Origin: string	Optional header field for non-browser clients.
PathName: string	Name of the path. For example: ws://hostname:port/path
Port: Integer	Port number. For example: ws://hostname:port/path
SplitMessage: Boolean	If set to True, messages are split into multiple frames based on FrameSize.
UseSSL: Boolean	Set to True if the server is protected via TLS.

Methods

Method name	Description
CheckIncoming: TTMSFNCWebSocketIncomingResult	Manually trigger message reading.
Connect	Connect to a server and perform handshake
Disconnect(SendClose: Boolean = True)	Disconnect from the server. If SendClose is False, the client will not send a closing frame. If True, it will send a closing frame and wait for reply from the server.
Ping(AMessage: string)	Sends a ping frame to the server with an optional message.
Send(ABytes: TBytes)	Sends a string message to the server.
Send(AMessage: string)	Sends a binary message to the server

Events

Event name	Description
OnBinaryDataReceived	Event triggered when binary data is received from the server.
OnConnect	Event triggered when connection to the server is successful.
OnDisconnect	Event triggered when client is disconnected from the server. Keep in mind this is event does not trigger if the connection is suddenly lost. To make sure you have connection to the server, use the Ping method to periodically check the connection.
OnHandshakeResponse	Event triggered when handshake is completed.
OnMessageReceived	Event triggered when string data is received from the server.
OnPing	Event triggered when a ping message is received from the server.
OnPong	Event triggered when a pong message is received from the server.
OnSendHandshake	Event triggered when handshake is sent.