WebSocket - XRhuman API Docs

Description

Supported Script Types: Interface Scripts • Client Entity Scripts • Avatar Scripts • Server Entity Scripts • Assignment Client Scripts

Provides a bi-directional, event-driven communication session between the script and another WebSocket connection. It is a near-complete implementation of the WebSocket API described in the Mozilla docs: https://developer.mozilla.org/en-US/docs/Web/API/WebSocket.

Create using new WebSocket(...) in Interface, client entity, avatar, and server entity scripts, or the WebSocketServer class in server entity and assignment client scripts.

Note: Does not support secure, wss: protocol.

Properties

Name	Type	Summary
binaryType	string	Not used. Default Value: "blob"
bufferedAmount	number	Not implemented. Read-only. Default Value: 0
extensions	string	Not implemented. Read-only. Default Value: ""
onopen	WebSocket~onOpenCallback	Function called when the connection opens.
onmessage	WebSocket~onMessageCallback	Function called when a message is received.
onerror	WebSocket~onErrorCallback	Function called when an error occurs.
onclose	WebSocket~onCloseCallback	Function called when the connection closes.
protocol	string	Not implemented. Read-only. Default Value: ""
readyState	WebSocket.ReadyState	The state of the connection. Read-only.
url	string	The URL to connect to. Read-only.
CONNECTING	WebSocket.ReadyState	The connection is opening. Read-only.
OPEN	WebSocket.ReadyState	The connection is open. Read-only.
CLOSING	WebSocket.ReadyState	The connection is closing. Read-only.
CLOSED	WebSocket.ReadyState	The connection is closed. Read-only.

Constructor

new WebSocket( urlOrWebSocket )

Parameters

Name	Type	Description
`urlOrWebSocket`	string \| WebSocket	The URL to connect to or an existing WebSocket to reuse the connection of.

Example

Echo a message off websocket.org.

print("Create WebSocket");
var WEBSOCKET_PING_URL = "ws://echo.websocket.org";
var webSocket = new WebSocket(WEBSOCKET_PING_URL);

webSocket.onclose = function (data) {
    print("WebSocket closed");
    print("Ready state =", webSocket.readyState);  // 3
};

webSocket.onmessage = function (data) {
    print("Message received:", data.data);

    print("Close WebSocket");
    webSocket.close();
};

webSocket.onopen = function () {
    print("WebSocket opened");
    print("Ready state =", webSocket.readyState);  // 1

    print("Send a test message");
    webSocket.send("Test message");
};

Methods

Name	Return Value	Summary
`close`	None	Closes the connection.
`send`	None	Sends a message on the connection.

Type Definitions

CloseCode
Type: number

The reason why the connection was closed.

Value	Name	Description
`1000`	Normal	Normal closure.
`1001`	GoingAway	Going away.
`1002`	ProtocolError	Protocol error.
`1003`	DatatypeNotSupported	Unsupported data.
`1004`	Reserved1004	Reserved.
`1005`	MissingStatusCode	No status received.
`1006`	AbnormalDisconnection	abnormal closure.
`1007`	WrongDatatype	Invalid frame payload data.
`1008`	PolicyViolated	Policy violation.
`1009`	TooMuchData	Message too big.
`1010`	MissingExtension	Mandatory extension missing.
`1011`	BadOperation	Internal server error.
`1015`	TlsHandshakeFailed	TLS handshake failed.

CloseData
Type: object

Information on a connection being closed.

Properties

Name	Type	Summary
code	WebSocket.CloseCode	The reason why the connection was closed.
reason	string	Description of the reason why the connection was closed.
wasClean	boolean	`true` if the connection closed cleanly, `false` if it didn't.

MessageData
Type: object

A message received on a WebSocket connection.

Properties

Name	Type	Summary
data	string	The message content.

ReadyState
Type: number

The state of a WebSocket connection.

Value	Name	Description
`0`	CONNECTING	The connection is opening.
`1`	OPEN	The connection is open.
`2`	CLOSING	The connection is closing.
`3`	CLOSED	The connection is closed.

SocketError
Type: number

The type of socket error.

Value	Name	Description
`0`	ConnectionRefusedError	The connection was refused or timed out.
`1`	RemoteHostClosedError	The remote host closed the connection.
`2`	HostNotFoundError	The host address was not found.
`3`	SocketAccessError	The socket operation failed because the application doesn't have the necessary privileges.
`4`	SocketResourceError	The local system ran out of resources (e.g., too many sockets).
`5`	SocketTimeoutError	The socket operation timed out.
`6`	DatagramTooLargeError	The datagram was larger than the OS's limit.
`7`	NetworkError	An error occurred with the network.
`8`	AddressInUseError	The is already in use and cannot be reused.
`9`	SocketAddressNotAvailableError	The address specified does not belong to the host.
`10`	UnsupportedSocketOperationError	The requested socket operation is not supported by the local OS.
`11`	ProxyAuthenticationRequiredError	The socket is using a proxy and requires authentication.
`12`	SslHandshakeFailedError	The SSL/TLS handshake failed.
`13`	UnfinishedSocketOperationError	The last operation has not finished yet.
`14`	ProxyConnectionRefusedError	Could not contact the proxy server because connection was denied.
`15`	ProxyConnectionClosedError	The connection to the proxy server was unexpectedly closed.
`16`	ProxyConnectionTimeoutError	The connection to the proxy server timed out.
`17`	ProxyNotFoundError	The proxy address was not found.
`18`	ProxyProtocolError	Connection to the proxy server failed because the server response could not be understood.
`19`	OperationError	An operation failed because the socket state did not permit it.
`20`	SslInternalError	Internal error in the SSL library being used.
`21`	SslInvalidUserDataError	Error in the SSL library because of invalid data.
`22`	TemporaryError	A temporary error occurred.
`-1`	UnknownSocketError	An unknown error occurred.

onCloseCallback( data )
Type: function

Called when the connection closes.

Parameters

Name	Type	Description
`data`	WebSocket.CloseData	Information on the connection closure.

onErrorCallback( error )
Type: function

Called when an error occurs.

Parameters

Name	Type	Description
`error`	WebSocket.SocketError	The error.

onMessageCallback( message )
Type: function

Called when a message is received.

Parameters

Name	Type	Description
`message`	WebSocket.MessageData	The message received.

onOpenCallback( ) Type: function
Called when the connection opens.

Method Details

(static) close( closeCodeopt, reasonopt )

Closes the connection.

Parameters

Name	Type	Attributes	Default Value	Description
`closeCode`	WebSocket.CloseCode	<optional>	1000	The reason for closing.
`reason`	string	<optional>	""	A description of the reason for closing.

(static) send( message )

Sends a message on the connection.

Parameters

Name	Type	Description
`message`	string \| object	The message to send. If an object, it is converted to a string.