Skip to main content
Version: v20 R4 BETA

WebSocket

History
VersionChanges
v20 R2Added

The WebSocket class allows you to open a WebSocket client connection with a server, send and receive data, and close the connection.

WebSocket client connections are useful, for example, to receive financial data in real time or send and receive messages from a chat.

Example

In this example, we create a very basic WebSocket client.

  1. Create the WSConnectionHandler user class containing callback function(s) used to handle WebSocket event callbacks:
// WSConnectionHandler class

Class constructor

Function onMessage($ws : 4D.WebSocket; $event : Object)
ALERT($event.data)

Function onTerminate($ws : 4D.WebSocket; $event : Object)
ALERT("Connection closed")
  1. Connect to the WebSocket server from a 4D form by instantiating a 4D.WebSocket:
Form.webSocket:=4D.WebSocket.new($wssUrl; cs.WSConnectionHandler.new())
  1. To send messages to the WebSocket server from the 4D form, you can write:
Form.webSocket.send("Hello world")

WebSocket object

WebSocket objects provide the following properties and functions:

.dataType : Text    the type of the response body content
.handler : Object    the accessor that gets the connectionHandler object used to initiate the connection
.id : Longint    the unique identifier of the connection
.send( message : Text )
.send( message : Blob )
.send( message : Object )
    sends message to the WebSocket server in the defined data type (Text, Blob, or Object)
.status : Text    the current connection status (can be "Connecting", "Closing", "Closed", or "Connected")
.terminate( { code : Integer { ; reason : Text } } )    closes the WebSocket connection, along with optional code and reason parameters
.url : Text    the URL to which the WebSocket has connected

4D.WebSocket.new()

History
VersionChanges
v20 R3Support of headers property in connectionHandler

4D.WebSocket.new( url : Text { ; connectionHandler : Object } ) : 4D.WebSocket

ParameterTypeDescription
urlText->URL to which to connect
connectionHandlerObject->Object declaring WebSocket callbacks
Result4D.WebSocket<-New WebSocket object

The 4D.WebSocket.new() function creates and returns a new 4D.WebSocket object connected to the WebSocket server at the address you passed in url. The 4D.WebSocket object provides an API for creating and managing a WebSocket connection to a server, as well as sending and receiving data to and from the server.

In url, pass the URL to which the WebSocket server will respond. The following URL patterns can be used:

  • ws://host[:port]path[?query] for standard connections
  • wss://host[:port]path[?query] for TLS secured connections

If the connection is not possible, a null object is returned and an error is generated (that you can intercept using a method installed with ON ERR CALL).

connectionHandler parameter

In connectionHandler, you can pass an object containing callback functions to be called according to connection events, as well as data type and headers to handle.

  • Callbacks are automatically called in the context of the form or worker that initiates the connection.
  • The WebSocket will be valid as long as the form or worker is not closed.
PropertyTypeDescription
onMessageFunctionCallback function for WebSocket data. Called each time the WebSocket has received data. The callback receives the following parameters:
  • $1: WebSocket object
  • $2: Object
    • $2.type (text): always "message"
    • $2.data (text, blob, or object, see dataType): Received data
    onErrorFunctionCallback function for execution errors. The callback receives the following parameters:
  • $1: WebSocket object
  • $2: Object
    • $2.type (text): always "error"
    • $2.errors: collection of 4D errors stack in case of execution error.
      • [].errCode (number): 4D error code
      • [].message (text): Description of the 4D error
      • [].componentSignature (text): Signature of the internal component which returned the error
    onTerminateFunctionCallback function when the WebSocket is terminated. The callback receives the following parameters:
  • $1: WebSocket object
  • $2: Object
    • $2.code (number, read-only): unsigned short containing the close code sent by the server.
    • $2.reason (text, read-only): Reason why the server closed the connection. This is specific to the particular server and sub-protocol.
    • $2.wasClean (boolean, read-only): Indicates whether or not the connection was cleanly closed.
    onOpenFunctionCallback function when the websocket is open. The callback receives the following parameters:
  • $1: WebSocket object
  • $2: Object
    • $2.type (text): always "open"
    dataTypeTextType of the data received or sent. Available values: "text" (default), "blob", "object". "text" = utf-8
    headersObjectHeaders of the WebSocket.
  • Syntax for standard key assignment: headers.*key*:=*value* (value can be a Collection if the same key appears multiple times)
  • Syntax for Cookie assignment (particular case): headers.Cookie:="*name*=*value* {; *name2*=*value2*{; ... } }"
  • Here is the sequence of callback calls:

    1. onOpen is executed once
    2. Zero or several onMessage are executed
    3. Zero or one onError is executed (stops the processing)
    4. onTerminate is always executed

    Example

    You want to set headers in the WSConnectionHandler user class:

    // WSConnectionHandler class

    Class constructor($myToken:Text)

    // Creation of the headers sent to the server
    This.headers:=New object("x-authorization";$myToken)
    // We define two cookies
    This.headers.Cookie:="yummy_cookie=choco; tasty_cookie=strawberry"
    ...

    .dataType

    .dataType : Text

    Description

    The .dataType property contains the type of the response body content. It can be "text", "blob", or "object".

    This property is read-only.

    .handler

    .handler : Object

    Description

    The .handler property contains the accessor that gets the connectionHandler object used to initiate the connection.

    This property is read-only.

    .id

    .id : Longint

    Description

    The .id property contains the unique identifier of the connection.

    This property is read-only.

    .send()

    .send( message : Text )
    .send( message : Blob )
    .send( message : Object )

    ParameterTypeDescription
    messageText, Blob, Object->Message to be sent

    Description

    The .send() function sends message to the WebSocket server in the defined data type (Text, Blob, or Object).

    The following contents are sent depending on the message type:

    TypeContent
    TextText in UTF-8
    BlobBinary data
    ObjectText in JSON UTF-8 (same result as with JSON Stringify)

    .status

    .status : Text

    Description

    The .status property contains the current connection status (can be "Connecting", "Closing", "Closed", or "Connected").

    This property is read-only.

    .terminate()

    .terminate( { code : Integer { ; reason : Text } } )

    ParameterTypeDescription
    codeInteger->Status code explaining why the connection is being closed
    reasonText->The reason why the connection is closing

    Description

    The .terminate() function closes the WebSocket connection, along with optional code and reason parameters.

    In code, you can pass a status code explaining why the connection is being closed (see also WebSocket Connection Close Code in the RFC6455):

    • If unspecified, a close code for the connection is automatically set to 1000 for a normal closure, or otherwise to another standard value in the range 1001-1015 that indicates the actual reason the connection was closed.
    • If specified, the value of this code parameter overrides the automatic setting. The value must be an integer. Either 1000, or a custom code in the range 3000-4999. If you specify a code value, you should also specify a reason value.

    In reason, you can pass a string describing why the connection is being closed.

    .url

    .url : Text

    Description

    The .url property contains the URL to which the WebSocket has connected. It is the URL you passed to the new() function.

    This property is read-only.