Skip to main content

%CSP.WebSocket

Class %CSP.WebSocket Extends (%RegisteredObject, %CSP.Page) [ ServerOnly = 1 ]

The %CSP.WebSocket object serves as an event handler for communication between client and server using the WebSocket protocol (RFC 6455). All WebSocket servers derive from %CSP.WebSocket.

Parameters​

UseSession​

Parameter UseSession = 1;

NOCHARSETCONVERT​

Parameter NOCHARSETCONVERT = 1;

Properties​

SharedConnection​

Property SharedConnection As %Boolean [ InitialExpression = 0 ];

This property determines whether the communication between the client and WebSocket server should be over a dedicated Gateway conection or over a pool of shared connections. It may be set to one of the following:

  • SharedConnection=0 - The WebSocket server communicates with the client via a dedicated Gateway connection. In this mode of operation the hosting connection is effectively 'private' to the application session.
  • SharedConnection=1 - The WebSocket server communicates asynchronously with the client via a fixed number of shared Gateway connections.

NoDataFraming​

Property NoDataFraming As %Boolean [ InitialExpression = 0 ];

This property determines whether formal data framing should occur between the Web Gateway and InterSystems IRIS

  • NoDataFraming=0 - Use the READ and WRITE methods in this class to manage I/O with the WebSocket.
  • NoDataFraming=1 - Use the basic ObjectScript READ and WRITE commands to manage I/O with the WebSocket (SharedConnection cannot be set with this mode).

BinaryData​

Property BinaryData As %Boolean [ InitialExpression = 0 ];

This property determines whether the data streams transmitted between the client and server should be treated as binary. The default setting is to treat the incoming and outgoing data as UTF-8 encoded text.

This property may be set to one of the following:

  • BinaryData=0 - UTF-8 encoded text.
  • BinaryData=1 - Binary Data.

WebSocketID​

Property WebSocketID As %String;

The unique identity of this WebSocket.

SessionId​

Property SessionId As %String;

The CSP Session ID from which this WebSocket was created.

SessionEndOnClose​

Property SessionEndOnClose As %Boolean [ InitialExpression = 0 ];

This property determines whether WebSocket closure forces the associated CSP session to end. Must be set in either Server() or OnPostServer(). For WebSockets operating asynchronously, only takes effect if EndServer() is called in Server().

This property may be set to one of the following:

  • SessionEndOnClose=0 - Do not force the CSP session to end when the web socket closes. (For synchronous web sockets, the CSP session may still end depending on its EndSession property.)
  • SessionEndOnClose=1 - Ensure that the CSP session ends when the web socket closes.

GWClientAddress​

Property GWClientAddress As %String;

The address through which a WebSocket operating asynchronously (SharedConnection=1) can communicate with the hosting CSP Gateway.

AtEnd​

Property AtEnd As %Boolean [ InitialExpression = 1 ];

The AtEnd property is set to true (1) when, during a read, the WebSocket server has reached the end of the current data frame.

BytesAvailable​

Property BytesAvailable As %Integer [ InitialExpression = 0, Private ];

The amount of client data waiting to be read.

DataFrameType​

Property DataFrameType As %Integer [ InitialExpression = 0, Private ];

The type of the Data Frame waiting to be read.

WSDataFraming​

Property WSDataFraming As %Integer [ InitialExpression = 0, Private ];

The flag indicating that WebSocket data framing should be used for write operations.

WSClassProtocolVersion​

Property WSClassProtocolVersion As %Integer [ InitialExpression = 2, Private ];

The version of the transmission protocol between the CSP Gateway and this class.

WSInitStatus​

Property WSInitStatus As %Integer [ InitialExpression = 0, Private ];

The internal initialization status for the WebSocket.

Methods​

OnPreServer​

Method OnPreServer() As %Status

Event handler for the PreServer event: this is invoked before starting the WebSockets Server. Changes to the SharedConnection flag must be made here.

OnPostServer​

Method OnPostServer() As %Status

Event handler for the PostServer event: this is invoked after closing the WebSockets Server.

Server​

Method Server() As %Status

The WebSocket Server. Use the Read and Write methods to receive data from, and send data to, the client. Call the EndServer method to gracefully terminate the WebSocket Server. A WebSocket operating asynchronously (SharedConnection=1) can exit this method (using Quit) and subsequently open the WebSocket using the OpenServer method.

OnClientMessage​

Method OnClientMessage(data As %String = "", close As %Integer) As %Status

Event handler for the ClientMessage event: this method is only relevant to WebSockets operating in Asynchronous mode. In other words WebSockets for which the SharedConnection flag is set. If OnClientMessage successfully processes the client message it must return with 1.

Initialize​

Method Initialize(WebSocketID As %String = "", GWClientAddress As %String = "") As %Status

Internal method to initialize the WebSocket Class.

InitializeServer​

Method InitializeServer() As %Status

Internal method to initialize the WebSocket Server.

SaveServer​

Method SaveServer() As %Status [ Final, Private ]

Internal method to save the WebSocket Server.

DeleteServer​

Method DeleteServer() As %Status [ Final, Private ]

Internal method to delete the WebSocket Server.

OpenServer​

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

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

EndServer​

Method EndServer() As %Status

Gracefully terminate the WebSocket Server.

Read​

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

Reads up to len characters from the client. If the call is successful the status (sc) will be returned as $$$OK, otherwise an error code of $$$CSPWebSocketTimeout indicates a timeout and $$$CSPWebSocketClosed indicates that the client has terminated the WebSocket.

ReadAsync​

Method ReadAsync(ByRef len As %Integer = 32656, ByRef sc As %Status, timeout As %Integer = 86400) As %String [ Private ]

Write​

Method Write(data As %String) As %Status

Write to the client.

Page​

ClassMethod Page(skipheader As %Boolean = 1) As %Status [ Internal, ServerOnly = 1 ]

Internal handling of page processing

SendAsyncMessage​

ClassMethod SendAsyncMessage(websocketid As %String, gwclientaddress As %String) As %Status [ Final ]

SendNullResponse​

ClassMethod SendNullResponse() [ Internal ]

Send the basic web socket response to the gateway

Error​

ClassMethod Error(skipheader As %Boolean = 1) As %Status [ Internal, ServerOnly = 1 ]

Internal handling of error

Login​

ClassMethod Login(skipheader As %Boolean = 1) As %Status [ Internal, ServerOnly = 1 ]

Internal handling of login