WebSocket

Listen for WebSocket connections (server) or connect to existing WebSocket servers (client).

Here is a list of events and functions:

Note: firewall rules might need to be changed to allow WebSocket connections.

🔧 WebSocket Object

Property Type Description
Topic string The topic listening for.
Port number The port listening on.
Address string The IP address listening on
IsServer boolean True if the WebSocket is of type server, false if it’s a client socket.
IsSecure boolean True if the WebSocket server is secure.

⚡ Events

Two events can be registered using SubscribeAll and UnSubscribeAll:

  • OnMessage: Incoming message received

SubscribeAll("OnMessage", "WebSocket", MyWebSocketMessageHandler);

function MyWebSocketMessageHandler(messageObject) {
    LogDebug("Message: " + messageObject.Message);
}

  • OnError: WebSocket error event

SubscribeAll("OnError", "WebSocket", MyWebSocketErrorHandler);

function MyWebSocketErrorHandler(errorObject) {
    LogDebug("Error Message: " + errorObject.Message);
}

The event data object is shared between OnMessage and OnError events and have the following fields:

Field Type OnMessage OnError
EventId number An unique ID of the current event
Type number Indicates the event type: 0=Message; 1=Error
SessionId number The Sym3 simulation session ID
ClientId string WebSocket Server: The ID of the client that sent this message
WebSocket Client: Empty string		 The WebSocket session ID or client ID if the error was caused a client
Message string The received message text The error message text
Topic string Event WebSocket Topic
Port number Event WebSocket Port
Address string Event WebSocket Address
IsServer boolean Event WebSocket Server or Client

Server

A WebSocket server listens on a specified port for clients to connect and send messages. The listening address should be a local IP address of a specific network interface, or ‘0.0.0.0’ to listen on all of the network interfaces. A WebSocket should specify a topic to listen on or send to. This allows the same port to be used for different WebSocket applications.
The url of a WebSocket is defined as follows:
ws://{address}:{port}/{topic} => ws://0.0.0.0:85/sym3, or
wss://{address}:{port}/{topic} => wss://0.0.0.0:85/sym3 for secure sockets.

🔁 WebSocketServer_Create

To create a new WebSocket server, use the WebSocketServer_Create function. Creating the same WebSocket more than once does not create multiples.

⚙️ Parameters

Name Type Description
topic string The topic to listen for. Example: “Sym3”
port number The port to listen on.
address string [OPTIONAL] The IP address to listen on. This defaults to “0.0.0.0” to listen on all interfaces.
isSecure boolean [OPTIONAL] If a secure websocket should be created using a certificate.
certThumbprint string [REQUIRED IF SECURE] The text string representing the thumbprint of the certificate to use to secure the connection. The certificate should be in the LocalMachine/Personal store.

↩️ Return Value

This function returns a WebSocket object.

📝 Example

var server = WebSocketServer_Create("sym3", 85); 
var anotherOne = WebSocketServer_Create("Sym3", 85, "0.0.0.0"); //this one is ignored as it is effectively the same as 'server'

var secure = WebSocketServer_Create("Sym3", 88, "0.0.0.0", true, "5370b14d45abdc68e410b1fe54d190bbca75900c");

LogDebug(`Server: ws${server.IsSecure ? "s":""}://${server.Address}:${server.Port}/${server.Topic}`); //outputs "Server: ws://0.0.0.0:85/sym3" 
LogDebug(`Server: ws${secure.IsSecure ? "s":""}://${secure.Address}:${secure.Port}/${secure.Topic}`); //outputs "Server: wss://0.0.0.0:88/sym3"

Secure WebSocket Certificate

Creating a secure websocket server requires a valid certificate. The certificate is identified by its thumbprint and must be available in the Windows ‘LocalMachine Personal’ certificate store.

🔁 WebSocketServer_Delete

To stop listening and delete a WebSocket server, use the WebSocketServer_Delete function.
This command only deletes server sockets and if a client socket is specified, it will ignore the command.
To specify the WebSocket delete, either a WebSocket object can be passed, or the WebSocket properties separately:

📝 Example

WebSocketServer_Delete(server); //deletes the 'server' WebSocket
WebSocketServer_Delete("sym3", 85); //same effect as before as the address defaults to 0.0.0.0
WebSocketServer_Delete("sym3", 85, "0.0.0.0"); //making sure of the address

🔁 WebSocketServer_BroadcastMessage

Sending a message to ALL clients connected to the WebSocket is done with the WebSocketServer_BroadcastMessage function.

There are two versions of this function.

⚙️ Parameters - Version 1

Name Type Description
topic string The topic of the WebSocket. Example: “Sym3”
port number The port of the WebSocket
address string [Can be empty] The IP address of the WebSocket. This defaults to “0.0.0.0” to listen on all interfaces.
message string The message to send to ALL listening clients.
callback string or function [OPTIONAL] Callback function that executes when all messages where delivered.

📝 Example

WebSocketServer_BroadcastMessage("sym3", 85, "", "Hi from Sym3!", () => {LogDebug("Broadcast delivered");}); //inline callback
WebSocketServer_BroadcastMessage("sym3", 85, "", "Hi from Sym3!", DeliveredFunction); //separate function callback
WebSocketServer_BroadcastMessage("sym3", 85, "", "Hi from Sym3!"); //no callback

function DeliveredFunction() {
    LogDebug("Broadcast delivered");
}

⚙️ Parameters - Version 2

Name Type Description
webSocket WebSocket The WebSocket object to use for broadcast
message string The message to send to ALL listening clients.
callback string or function [OPTIONAL] Callback function that executes when all messages where delivered.

📝 Example

WebSocketServer_BroadcastMessage(server, "Hi from Sym3!", () => {LogDebug("Broadcast delivered");}); //inline callback
WebSocketServer_BroadcastMessage(server, "Hi from Sym3!", DeliveredFunction); //separate function callback
WebSocketServer_BroadcastMessage(server, "Hi from Sym3!"); //no callback

function DeliveredFunction() {
    LogDebug("Broadcast delivered");
}

🔁 WebSocketServer_SendMessageTo

To send a message to a SPECIFIC client connected to the WebSocket is done with the WebSocketServer_SendMessageTo function.

There are two versions of this command.

⚙️ Parameters - Version 1

Name Type Description
topic string The topic of the WebSocket. Example: “Sym3”
port number The port of the WebSocket
address string [Can be empty] The IP address of the WebSocket. This defaults to “0.0.0.0” to listen on all interfaces.
clientId string The ID of the client to send to message to. This can be obtained from the OnMessage event.
message string The message to send to the specified listening client.
callback string or function [OPTIONAL] Callback function that executes with status of the message delivery.

📝 Example

WebSocketServer_SendMessageTo("sym3", 85, "", clientId, "Hi from Sym3!", (result) => {LogDebug("Message delivery result: " + result);}); //inline callback
WebSocketServer_SendMessageTo("sym3", 85, "", clientId, "Hi from Sym3!", DeliveredFunction); //separate function callback
WebSocketServer_SendMessageTo("sym3", 85, "", clientId, "Hi from Sym3!"); //no callback

function DeliveredFunction(result) {
    LogDebug("Message delivery result: " + result);
}

⚙️ Parameters - Version 2

Name Type Description
webSocket WebSocket The WebSocket object to use for broadcast
clientId string The ID of the client to send to message to. This can be obtained from the OnMessage event.
message string The message to send to ALL listening clients.
callback string or function [OPTIONAL] Callback function that executes with status of the message delivery.

📝 Example

WebSocketServer_SendMessageTo(server, clientId, "Hi from Sym3!", (result) => {LogDebug("Message delivery result: " + result);}); //inline callback
WebSocketServer_SendMessageTo(server, clientId, "Hi from Sym3!", DeliveredFunction); //separate function callback
WebSocketServer_SendMessageTo(server, clientId, "Hi from Sym3!"); //no callback

function DeliveredFunction(result) {
    LogDebug("Message delivery result: " + result);
}

Client

A WebSocket client connects to a specified WebSocket server defined by its address, port and topic. The connecting address should be a valid IP address of a specific WebSocket server.

🔁 WebSocketClient_Create

To create a new WebSocket client, use the WebSocketClient_Create function. Creating the same WebSocket more than once does not create multiples.

WebSocket WebSocketClient_Create(
    topic: string, 
    port: number, 
    address: string, 
    isSecure: boolean
);

⚙️ Parameters

Name Type Description
topic string The topic to subscribe to. Example: “Sym3”
port number The port to connect to.
address string [OPTIONAL] The IP address to connect on. This defaults to “127.0.0.1”.
isSecure boolean [OPTIONAL] If the websocket server to connect to is secure.

↩️ Return Value

This function returns a WebSocket object.

📝 Example

var client = WebSocketClient_Create("sym3", 85); 
var anotherOne = WebSocketClient_Create("Sym3", 85, "127.0.0.1"); //this one is ignored as it is effectively the same client

var secure = WebSocketClient_Create("Sym3", 86, "127.0.0.1", true);

LogDebug(`Client: ws${client.IsSecure ? "s":""}://${client.Address}:${client.Port}/${client.Topic}`); //outputs "Client: ws://127.0.0.1:85/sym3"
LogDebug(`Secure: ws${secure.IsSecure ? "s":""}://${secure.Address}:${secure.Port}/${secure.Topic}`); //outputs "Secure: wss://127.0.0.1:86/sym3"

🔁 WebSocketClient_Delete

To stop and delete a WebSocket client, use the WebSocketClient_Delete function.

This command only deletes client sockets and if a server socket is specified, it will ignore the command.

To specify the WebSocket to delete, either a WebSocket object can be passed, or the WebSocket properties separately:

WebSocketClient_Delete(client); //deletes the 'client' WebSocket
WebSocketClient_Delete("sym3", 85); //same effect as before as the address defaults to 127.0.0.1
WebSocketClient_Delete("sym3", 85, "127.0.0.1"); //making sure of the address

🔁 WebSocketClient_SendMessageTo

To send a message to the server connected to is done with the WebSocketClient_SendMessageTo function.

There are two versions of this command.

⚙️ Parameters - Version 1

Name Type Description
topic string The topic of the client WebSocket. Example: “Sym3”
port number The port of the client WebSocket
address string [Can be empty] The IP address of the client WebSocket. This defaults to “127.0.0.1”.
isSecure boolean If the websocket server to connect to is secure.
message string The message to send to the server.
callback string or function [OPTIONAL] Callback function that executes with the status of the message delivery.

📝 Example

WebSocketClient_SendMessage("sym3", 85, "", false, "Hi from Sym3!", (result) => {LogDebug("Message delivery result: " + result);}); //inline callback
WebSocketClient_SendMessage("sym3", 85, "", false, "Hi from Sym3!", DeliveredFunction); //separate function callback
WebSocketClient_SendMessage("sym3", 85, "", false, "Hi from Sym3!"); //no callback

WebSocketClient_SendMessage("sym3", 86, "", true, "Hi from Sym3, securely!"); //secure websocket

function DeliveredFunction(result) {
    LogDebug("Message delivery result: " + result);
}

⚙️ Parameters - Version 2

Name Type Description
webSocket WebSocket The WebSocket object to use for broadcast
clientId string The ID of the client to send to message to. This can be obtained from the OnMessage event.
message string The message to send to ALL listening clients.
callback string or function [OPTIONAL] Callback function that executes with the status of the message delivery.

📝 Example

WebSocketClient_SendMessage(server, "Hi from Sym3!", (result) => {LogDebug("Message delivery result: " + result);}); //inline callback
WebSocketClient_SendMessage(server, "Hi from Sym3!", DeliveredFunction); //separate function callback
WebSocketClient_SendMessage(server, "Hi from Sym3!"); //no callback

WebSocketClient_SendMessage(secure, "Hi from Sym3, securely!");

function DeliveredFunction(result) {
    LogDebug("Message delivery result: " + result);
}

Get WebSockets

The following three functions each return an array of WebSockets:

🔁 WebSocket_GetAll

Returns ALL current WebSockets, both server and client.

var allSockets = WebSocket_GetAll(); //returns all sockets

🔁 WebSocketServer_GetAll

Returns only current SERVER WebSockets.

var serverSockets = WebSocketServer_GetAll(); //returns only server sockets

🔁 WebSocketClient_GetAll

Returns only current CLIENT WebSockets.

var clientSockets = WebSocketClient_GetAll(); //returns only client sockets

🔁 WebSocket_ResetAll

To stop and delete ALL WebSockets as well as clear all WebSocket event subscriptions, use the WebSocket_ResetAll function.

WebSocket_ResetAll(); //Stops and deletes ALL WebSockets and unsubscribe all events

📖 Message Formatting

Messages are all text based, but with Javascript it is possible to send objects as well using the JSON class.

var myObject = {
    id: 10,
    name: "MyObject"
};

var objAsString = JSON.stringify(myObject); //send this string via WebSocket

var objFromString = JSON.parse(objAsString); //convert to object when receiving the text message (OnMessage)