Skip to content

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.

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.

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.