WebSocket
| Module | ejs |
| Definition | class WebSocket |
| Inheritance | WebSocket  Object |
| Specified | ejscript-2.5 |
| Stability | Evolving. |
WebSocket class to implement the WebSockets RFC 6455 specification for client-side communications.
WebSockets is a technology providing interactive communication between a server and client. Normal HTML connections follow a request / response paradigm and do not easily support asynchronous communications or unsolicited data pushed from the server to the client. WebSockets solves this by supporting bi-directional, full-duplex communications over persistent connections. A WebSocket connection is established over a standard HTTP connection and is then upgraded without impacting the original connection. This means it will work with existing networking infrastructure including firewalls and proxies.
See Also
Properties
| Qualifiers | Property | Type | Description |
|---|---|---|---|
| static const | BLOCK | << sendBlock mode to block waiting for the content to be sent. | |
| static const | BUFFER | << sendBlock mode to buffer the content. | |
| static const | CLOSED | The readyState value when the WebSockets connection is closed. | |
| static const | CLOSING | The readyState value when a closing handshake has commenced (. | |
| static const | MSG_BINARY | << WebSocket binary message. | |
| static const | MSG_CLOSE | << WebSocket close message. | |
| static const | MSG_CONT | << Continuation of WebSocket message. | |
| static const | MSG_PING | << WebSocket ping message. | |
| static const | MSG_PONG | << WebSocket pong message. | |
| static const | MSG_TEXT | << WebSocket text message. | |
| static const | NON_BLOCK | << sendBlock mode to not block and absorb only what can fit into the queue. | |
| static const | CONNECTING | The readyState value while waiting for the WebSockets open handshake to complete with the peer. | |
| static const | OPEN | The readyState value once the WebSockets open handshake is complete and ready for communications. | |
| get | binaryType | String | Type of binary data. Set to "ByteArray". |
| onclose | Function | Event callback invoked when the connection is closed. The readyState will be CLOSED. | |
| onerror | Function | Event callback invoked when an error occurs. | |
| onmessage | Function | Event callback invoked when a message has been received from the server. The readyState will be OPEN. | |
| get | bufferedAmount | Number | The number of bytes of buffered data to send. |
| get | extensions | String | Return the list of supported extensions. |
| onopen | Function | Event callback invoked when the WebSocket is ready to send and receive data. The readyState will be set to OPEN. | |
| get | protocol | String | Return the application-level protocol selected by the server. Protocols are defined when creating the WebSocket. |
| get | readyState | Number | The readystate value. This value can be compared with the WebSocket constants: CONNECTING = 0, OPEN = 1, CLOSING = 2, CLOSED = 3. |
| get | url | Uri | The URI provided to the constructor. |
WebSocket Class Methods
| Qualifiers | Method |
|---|
WebSocket Instance Methods
| Qualifiers | Method |
|---|---|
| WebSocket(uri: Uri, protocols = null, options = null) | |
| Create a new WebSocket and connect to the server using the supplied URI. | |
| close(code: Number = 1000, reason: String = ): Void | |
| Send a close message and close the web socket connection. | |
| send(content: Array): Number | |
| Send data with the request. | |
| sendBlock(content, options): Number | |
| Send a block of data with options to control message framing and buffering. | |
| wait(state: Number, timeout: Number = -1): Boolean | |
| Wait for the WebSocket to achieve a desired state. |
Method Detail
WebSocket(uri: Uri, protocols = null, options = null)
- Description
- Create a new WebSocket and connect to the server using the supplied URI.
- Parameters
uri: Uri URL to connect to. protocols Optional set of protocols supported by the application. These are application-level protocols. This argument may be an array or a string of comma separated values. [default: null] options null [default: null] options null [default: null]
- Options
certificate Path|String Optional path to file containing certificates to validate the server certificate. verify Boolean Set to true to verify the server certificate. The certificate is verified and the issuer chain is verified. Defaults to true. Set to false to accept a self-signed certificate. frames Preserve individual message frames to onmessage. P.
- Description
- Send a close message and close the web socket connection.
- Parameters
code: Number WebSocket status code to send to the peer explaining why the connection is being closed. Defaults to 1000 which means a successful, graceful closure. [default: 1000] reason: String Optional reason string to indicate why the connection was closed. Must be less than 124 bytes of UTF-8 text in length. [default: ]
- Description
- Send data with the request.
- Parameters
content: Array Data to send with the request. If the content is a ByteArray, the message will be sent as a WebSocket Binary message. Otherwise, the message is converted to a String and sent as a WebSockets UTF-8 Text message. If multiple arguments are provided, each is sent as a separate message. The message is buffered and so this call will never fail. Sending very large messages can consume a lot of memory. Use sendBlock to efficiently send large messages.
- Returns
- Count of bytes written. Returns null if the WebSocket is closed.
- Throws
sendBlock(content, options): Number
- Description
- Send a block of data with options to control message framing and buffering. This API is useful for sending multipart or large messages, or wherever you need to control the framing of WebSockets messages.
- Parameters
content The content may be a ByteArray or any other type which is then converted to a string. options null
- Options
last Set to false to indicate there is more data to complete this message. Set to true for the last portion of the message. Defaults to true if unspecified. type Message type. Masked to the valid WebSockets message types. Defaults to Text. mode API transmission mode. Set to BUFFER to buffer the entire contents before transmitting. Set to BLOCK to have the API wait until all the content is accepted. Set to NON_BLOCK for the API to accept whatever data can fit into the HTTP pipeline and return without waiting. In this mode, the call may return having written less than the requested amount of data. It is the callers responsibility to handle this occurrence.
- Returns
- Count of bytes written. Returns null if the WebSocket is closed.
- Throws
- ArgError: for bad options
- Description
- Wait for the WebSocket to achieve a desired state.
- Parameters
state: Number Desired ready state value. timeout: Number Timeout in milliseconds to wait for the desired state. A timeout of zero means don't block. A timeout of < 0 (default), means wait forever. [default: -1]
- Returns
- True if the desired state was achieved.