WebSockets Server Code (CSP)

The base Caché class for implementing WebSocket Servers is%CSP.WebSocketOpens in a new tab

When the client requests a WebSocket connection, the initial HTTP request (the initial handshake message) instructs the CSP engine to initialize the application's WebSocket server. The WebSocket server is the class named in the requesting URL. For example, if your WebSocket server is called MyApp.MyWebSocketServer and is designed to operate in the USER NameSpace then the URL used to request the WebSocket connection is:

/csp/user/MyApp.MyWebSocketServer.cls

WebSocket Events

To implement a WebSocket server, create a subclass of %CSP.WebSocket and define callbacks in that class as needed. Note that the web session is unlocked before calling any of these methods. Also in all cases, the socket times out after the CSP session times out.

OnPreServer (optional)

Use this method to invoke code that should be executed before the WebSocket server is established. Changes to the SharedConnection property must be made here.

Server (Mandatory)

The WebSocket server. This is the server-side implementation of the WebSocket application. Messages can be exchanged with the client using the Read() and Write() methods. Use the EndServer() method to gracefully close the WebSocket from the server end.

OnPostServer (optional)

Use this method to invoke code that should be executed after the WebSocket server has closed.

WebSocket Methods

The following methods are provided

Method Read(ByRef len As %Integer = 32656,
     ByRef sc As %Status,
     timeout As %Integer = 86400) As %String

This method reads up to len characters from the client. If the call is successful the status (sc) is returned as $$$OK, otherwise one of the following error codes is returned:

$$$CSPWebSocketTimeout The Read method has timed-out.
$$$CSPWebSocketClosed The client has terminated the WebSocket.

Method Write(data As %String) As %Status

This method writes data to the client.

Method EndServer() As %Status

This method gracefully ends the WebSocket server by closing the connection with the client.

Method OpenServer(WebSocketID As %String = "") As %Status

This method opens an existing WebSocket Server. Only a WebSocket operating asynchronously (SharedConnection=1) can be accessed using this method.

WebSocket Properties

The following properties are provided:

SharedConnection (default: 0)

This property determines whether the communication between the client and WebSocket server should be over a dedicated Gateway connection or asynchronously over a pool of shared connections. This property must be set in the OnPreServer() method and may be set as follows:

SharedConnection=0 The WebSocket server communicates synchronously with the client via a dedicated Gateway connection. In this mode of operation the hosting connection is effectively 'private' to the application’s WebSocket Server.
SharedConnection=1 The WebSocket server communicates asynchronously with the client via a pool of shared Gateway connections.

WebSocketID

This property represents the unique identity of the WebSocket.

SessionId

This property represents the hosting CSP Session ID against which the WebSocket was created.

BinaryData

This property instrucst the Gateway to bypass functionality that would otherwise interpret the transmitted data stream as UTF-8 encoded text and set the appropriate binary data fields in the WebSocket frame header.

This should be set to 1 before writing a stream of binary data to the client. For example:

Set ..BinaryData = 1