Skip to content


The TTMSFNCWebSocketServer is a non-visual component enabling communication to websocket clients. It implements the RFC 6455 standard for websocket communication protocol.

Start/stop the server

Starting/stopping the server is as simple as setting the Active property.

procedure TForm1.startBtnClick(Sender: TObject);
  TMSFNCWebSocketServer1.Active := True;

procedure TForm1.stopBtnClick(Sender: TObject);
  TMSFNCWebSocketServer1.Active := False;

Allowing connections

By default all connections are allowed as long as they initiate a valid handshake request. After the handshake request is validated, the OnAllow event is triggered. This event has an AAllow: Boolean parameter which can be used to allow or disallow a connection regardless of the handshake request. The AConnection parameter gives access to the HandshakeRequest property which lets the details of the request be inspected.

procedure TForm2.TMSFNCWebSocketServer1Allow(Sender: TObject;
  AConnection: TTMSFNCWebSocketServerConnection; var aAllow: Boolean);
  //Allow all connections
  AAllow := True

Send data

Use BroadcastMessage(AMessage: string) or BroadcastData(AData: TBytes) to broadcast a string or binary messages to all connected clients.

procedure TForm1.broadcastBtnClick(Sender: TObject);
  TMSFNCWebSocketServer1.BroadcastMessage('Hello client!');

Use SendMessageTo(AMessage, ASelector) or SendDataTo(AData, ASelector) to send string or binary messages to connected clients. The ASelector callback determines which clients should the message be sent to.

//Forward incoming message to all client, except the one the message came from
procedure TForm2.TMSFNCWebSocketServer1MessageReceived(Sender: TObject;
  AConnection: TTMSFNCWebSocketConnection; const aMessage: string);
  TMSFNCWebSocketServer1.SendMessageTo(AMessage, function(AClientConnection: TTMSFNCWebSocketServerConnection): Boolean
      Result := AClientConnection <> AConnection;

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 one of the clients the OnMessageReceived event will be triggered. The AMessage parameter will contain the string message from the client.

When a binary message arrives from one of the clients the OnBinaryDataReceived event will be triggered. The AData parameter will contain the binary message from the client.

Ping and pong

Whenever a ping message arrives from a client 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 TForm2.TMSFNCWebSocketServer1Ping(Sender: TObject;
  AConnection: TTMSFNCWebSocketConnection; const aData: TArray<System.Byte>);

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

Custom connection data

The TTMSFNCWebSocketServerConnection.UserData object property allows you to store any kind of custom data paired to your connection. It also has an OwnsUserData property which will free the object automatically if it's set to True. If it's set to False, the object needs to be released manually.

When to create/assign the UserData object is depending on the use-case. When the data that needs storing is arriving from the client itself as a form of message, then the OnMessageReceived event is the place to handle this. For example as a form of JSON message:

  TMyDataObject = class(TObject)
    FID: string;
    property ID: string read FID write FID;

procedure TForm1.TMSFNCWebSocketServer1MessageReceived(Sender: TObject;
  AConnection: TTMSFNCWebSocketConnection; const aMessage: string);
  json: TJSONValue;
  jObj: TJSONObject;
  t, id, s, lID: string;
  i: Integer;
  json := TJSONObject.ParseJSONValue(AMessage);
    if json.TryGetValue<string>('type', t) then
      if (t = 'user-data') and not Assigned(TTMSFNCWebSocketServerConnection(AConnection).UserData) then
        json.TryGetValue<string>('id', id);
        TTMSFNCWebSocketServerConnection(AConnection).OwnsUserData := True;
        TTMSFNCWebSocketServerConnection(AConnection).UserData := TMyDataObject.Create;
        TMyDataObject(TTMSFNCWebSocketServerConnection(AConnection).UserData).ID := id;
      else if t = 'join' then 

When the server is the one that automatically assigns some data, it needs to be inspected where that should happen.

For example: The server wants to assign a unique ID for each new connection. In this case we can use the OnHandshakeResponseSent event where the server responds to the websocket handshake so the connection is estabilished.

procedure TForm1.TMSFNCWebSocketServer1HandshakeResponseSent(Sender: TObject;
  AConnection: TTMSFNCWebSocketServerConnection);
  AConnection.OwnsUserData := True;
  AConnection.UserData := TMyDataObject.Create;
  TMyDataObject(AConnection.UserData).ID := GetMyUniqueID;

Secure connection

Traffic over a websocket server can be protected via TLS. In order to enable this, set the UseSSL property to True.

The CertificateFile, CertificateKeyFile and RootCertificateFile properties can be used to define the path to the certificate file(s).

For secure connection OpenSSL libraries are required.


Property name Description
Active: Boolean Start or stop the server.
CertificateFile: string Path to the certificate file. Used when UseSSL is set to True.
CertificateKeyFile: string Path to the certificate key file. Used when UseSSL is set to True.
FrameSize: UIn64 The size of each frame to be sent. Used when SplitMessage is set to True.
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
PathName: string Name of the path.
For example: ws://localhost:8888/path
Port: Integer Port number. Default setting is 8888.
RootCertificateFile: string Path to the root certificate file. Used when UseSSL is set to True.
SplitMessage: Boolean If set to True, messages are split into multiple frames based on FrameSize.
UseSSL: Boolean If set to True, the server communication is protected via TLS.


Method name Description
BroadcastMessage(AMessage: string) Broadcasts a string message to all connected clients.
BroadcastData(AData: TBytes) Broadcasts a binary message to all connected clients.
SendMessageTo(AMessage: string; ASelector: TTMSFNCWebSocketSendToCallback) Sends a string message to connected clients. The ASelector callback determines to which clients the message should be sent.
SendDataTo(AData: TBytes; ASelector: TTMSFNCWebSocketSendToCallback) Sends a binary message to connected clients. The ASelector callback determines to which clients the message should be sent.


Event name Description
OnAllow Event triggered to allow or disallow a client connection.
OnBinaryDataReceived Event triggered when a binary message arrives to the server.
OnClose Event triggered when a close frame is sent by the client.
OnConnect Event triggered when a clients connects to the server. This is not equal to when the client is connected (handshake successfully finished).
OnDisconnect Event triggered when a client disconnects.
OnHandshakeResponseSent Event triggered when the handshake response is sent to the client.
OnMessageReceived Event triggered when a string message arrives to the server.
OnPing Event triggered when a ping message arrives from a client.
OnPong Event triggered when a pong message arrives from a client.