WebSocket

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.

ValueNameDescription
1000NormalNormal closure.
1001GoingAwayGoing away.
1002ProtocolErrorProtocol error.
1003DatatypeNotSupportedUnsupported data.
1004Reserved1004Reserved.
1005MissingStatusCodeNo status received.
1006AbnormalDisconnectionabnormal closure.
1007WrongDatatypeInvalid frame payload data.
1008PolicyViolatedPolicy violation.
1009TooMuchDataMessage too big.
1010MissingExtensionMandatory extension missing.
1011BadOperationInternal server error.
1015TlsHandshakeFailedTLS 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.

ValueNameDescription
0CONNECTINGThe connection is opening.
1OPENThe connection is open.
2CLOSINGThe connection is closing.
3CLOSEDThe connection is closed.
SocketError
Type: number

The type of socket error.

ValueNameDescription
0ConnectionRefusedErrorThe connection was refused or timed out.
1RemoteHostClosedErrorThe remote host closed the connection.
2HostNotFoundErrorThe host address was not found.
3SocketAccessErrorThe socket operation failed because the application doesn't have the necessary privileges.
4SocketResourceErrorThe local system ran out of resources (e.g., too many sockets).
5SocketTimeoutErrorThe socket operation timed out.
6DatagramTooLargeErrorThe datagram was larger than the OS's limit.
7NetworkErrorAn error occurred with the network.
8AddressInUseErrorThe is already in use and cannot be reused.
9SocketAddressNotAvailableErrorThe address specified does not belong to the host.
10UnsupportedSocketOperationErrorThe requested socket operation is not supported by the local OS.
11ProxyAuthenticationRequiredErrorThe socket is using a proxy and requires authentication.
12SslHandshakeFailedErrorThe SSL/TLS handshake failed.
13UnfinishedSocketOperationErrorThe last operation has not finished yet.
14ProxyConnectionRefusedErrorCould not contact the proxy server because connection was denied.
15ProxyConnectionClosedErrorThe connection to the proxy server was unexpectedly closed.
16ProxyConnectionTimeoutErrorThe connection to the proxy server timed out.
17ProxyNotFoundErrorThe proxy address was not found.
18ProxyProtocolErrorConnection to the proxy server failed because the server response could not be understood.
19OperationErrorAn operation failed because the socket state did not permit it.
20SslInternalErrorInternal error in the SSL library being used.
21SslInvalidUserDataErrorError in the SSL library because of invalid data.
22TemporaryErrorA temporary error occurred.
-1UnknownSocketErrorAn 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

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