WebSocket

History

Version	Changes
v20 R2	Added

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")

2. Connect to the WebSocket server from a 4D form by instantiating a 4D.WebSocket:

Form.webSocket:=4D.WebSocket.new($wssUrl; cs.WSConnectionHandler.new())

3. 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

Version	Changes
v20 R3	Support of headers property in connectionHandler

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

Parameter	Type		Description
url	Text	->	URL to which to connect
connectionHandler	Object	->	Object declaring WebSocket callbacks
Result	4D.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.

Property	Type	Description
onMessage	Function	Callback 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
onError	Function	Callback 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
onTerminate	Function	Callback 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.
onOpen	Function	Callback function when the websocket is open. The callback receives the following parameters: $1: WebSocket object $2: Object $2.type (text): always "open"
dataType	Text	Type of the data received or sent. Available values: "text" (default), "blob", "object". "text" = utf-8
headers	Object	Headers 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 )

Parameter	Type		Description
message	Text, 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:

Type	Content
Text	Text in UTF-8
Blob	Binary data
Object	Text 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 } } )

Parameter	Type		Description
code	Integer	->	Status code explaining why the connection is being closed
reason	Text	->	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.