WebSocket¶

Description¶

The WebSocket object provides WebSockets-based communication with a WebSockets server. WebSockets is a web technology providing full-duplex communications channels over a single TCP connection. The WebSocket protocol was standardized by the IETF as RFC 6455 in 2011.

The object can be used in two ways. When used as IoDevice, IoDevice.open() needs to be called and data can afterwards be read and written using the corresponding IoDevice methods. Alternatively text and binary messages can be sent and received directly after calling connectToHost().

This object was introduced in InCore 2.3.

› Inherits:	IoDevice

Overview¶

Properties¶

autoConnect¶

This property holds whether the TCP connection should be established automatically. Keeping this option enabled will also make the object reconnect on connection errors.

› Type:	Boolean
› Default:	`true`
› Signal:	autoConnectChanged()
› Attributes:	Writable

error¶

This property holds the most recently occurred error or WebSocket.NoError if no error occurred. If the same error occurs multiple times this property does not change. Use the errorOccurred() signal to detect multiple occurrences of the same error.

› Type:	Error
› Signal:	errorChanged()
› Attributes:	Readonly

errorString¶

This property holds the current human readable error string corresponding to the current value in the error property. It may include additional information such as failure reasons or locations.

› Type:	String
› Signal:	errorStringChanged()
› Attributes:	Readonly

state¶

This property holds the current state of the WebSocket.

› Type:	State
› Default:	WebSocket.Closed
› Signal:	stateChanged()
› Attributes:	Writable

subProtocol¶

This property holds the application-specific subprotocol to request from the WebSockets server. See RFC6455 Section 1.9 for details.

› Type:	String
› Signal:	subProtocolChanged()
› Attributes:	Writable

url¶

This property holds the URL of the WebSockets server, e.g. ws://ws.example.org:8000 or wss://ws.example.org:8000.

› Type:	String
› Signal:	urlChanged()
› Attributes:	Writable

Methods¶

connectToHost()¶

This method initiates a connection to the WebSockets server specified in the url property. It’s called automatically by IoDevice.open().

disconnectFromHost()¶

This method disconnects from the WebSockets server. It’s called automatically by IoDevice.close().

sendBinaryMessage(ArrayBuffer message)¶

This method sends the specified binary message to the WebSockets server. This method is also called by IoDevice.write().

› Returns:	SignedBigInteger

sendTextMessage(String message)¶

This method sends the specified text message to the WebSockets server.

› Returns:	SignedBigInteger

Signals¶

binaryMessageReceived(ArrayBuffer message)¶

This signal is emitted when a binary message is received. message contains the bytes received. When the IoDevice is opened, this signal is also handled internally to fill the internal read buffer and emit the IoDevice.readyRead() signal.

connected()¶

This signal is emitted after the WebSockets connection has been established successfully.

disconnected()¶

This signal is emitted when the WebSockets connection has been disconnected.

errorOccurred()¶

This signal is emitted whenever an error has occurred, regardless of whether the error property has changed or not. In contrast to the change notification signal of the error property this signal is also emitted several times if a certain error occurs several times in succession.

ipSocketErrorOccurred(IpSocket.Error socketError)¶

This signal is emitted when an IpSocket-specific error has occurred.

sslErrorOccurred(String errorString)¶

This signal is emitted when an TLS/SSL-related error has occurred.

textMessageReceived(String message)¶

This signal is emitted when a text message is received. message contains the bytes received.

Enumerations¶

Error¶

This enumeration describes all errors which can occur in WebSocket objects. The most recently occurred error is stored in the error property.

Name	Value	Description
`WebSocket.NoError`	`0`	No error occurred or was detected.
`WebSocket.IpSocketError`	`1`	IpSocket-specific error occurred.
`WebSocket.NotOpenError`	`2`	Socket is not opened, so messages can’t be sent.
`WebSocket.SslError`	`3`	Error while establishing TLS/SSL connection.

State¶

This enumeration describes the different states in which a WebSocket can be.

Name	Value	Description
`WebSocket.Connecting`	`0`	The WebSocket has started establishing a connection.
`WebSocket.Open`	`1`	The WebSocket connection is established and ready for sending/receiving messages.
`WebSocket.Closing`	`2`	The WebSocket is about to close (data may still be waiting to be written).
`WebSocket.Closed`	`3`	The WebSocket is not connected.

Example¶

import InCore.Foundation 2.5

Application {
    WebSocket {
        url: "wss://echo.websocket.org"
        onConnected: {
            console.log("Connected to", url)
            sendTextMessage("Hello world, this is a message from InCore!")
        }
        onTextMessageReceived: console.log("Received message:", message)
    }
}