Meziantou.FrameworkWebSocket Class
A WebSocket connection (https://websockets.spec.whatwg.org/#the-websocket-interface): a two-way communication with a server, established by an opening handshake that is fetched as specified (cookies, Origin, mixed content, bad ports...), whose connection is opened by DocumentLoader.ConnectWebSocketAsync. The frames of the WebSocket protocol (https://www.rfc-editor.org/rfc/rfc6455) are read and written by WebSocket, with the permessage-deflate extension when the server accepts it.
public sealed class WebSocket : EventTargetRemarks
The relevant global object of the WebSocket is the current global object when it is created (the window or the worker of the script that creates it): its events are fired by tasks of its event loop. A WebSocket created without current global object cannot connect: its WebSocket.ReadyState is WebSocket.Closed.
A WebSocket that is connecting or closing is an asynchronous operation of its event loop (see DomEventLoop.RunUntilIdleAsync), as are the messages that are being sent. An open connection that waits for messages is not: DomEventLoop.RunUntilIdleAsync does not wait for the next message. The WebSockets of a document are closed when the document is unloaded, with the 1001 (going away) status code, and so are the WebSockets of a worker when it ends.
See also
- Inheritance
EventTargetWebSocket
Constructors
| Name | Description |
|---|---|
| WebSocket(string, object?) | Creates a WebSocket and starts to establish its connection (https://websockets.spec.whatwg.org/#dom-websocket-websocket). |
WebSocket(string, object?)
WebSocket.csCreates a WebSocket and starts to establish its connection (https://websockets.spec.whatwg.org/#dom-websocket-websocket).
Parameters
urlstring- The URL of the server: a
ws:orwss:URL (anhttp:orhttps:URL is converted), possibly relative to the API base URL of the relevant global object, without fragment. protocolsobject?- The subprotocols the server can select: null (none), a string, or a sequence of strings (e.g. a
Stringarray). The connection fails when the server does not select one of them.
Exceptions
DomException- A
SyntaxErrorwhen the URL is not valid, has another scheme or a fragment, or when a subprotocol is not a valid token or appears twice (ASCII case-insensitively).
See also
Properties
| Name | Description |
|---|---|
| BinaryType | Gets or sets how the binary messages are exposed: as a Blob (the default) or as a Byte array (an ArrayBuffer). |
| BufferedAmount | Gets the number of bytes of the messages queued by WebSocket.Send that were not yet transmitted to the network as of the last task (https://websockets.spec.whatwg.org/#dom-websocket-bufferedamount). It only increases once the connection is closed. |
| Extensions | Gets the extensions selected by the server (the Sec-WebSocket-Extensions header of its response), or the empty string. |
| OnClose | Gets or sets the event handler of the close event. |
| OnError | Gets or sets the event handler of the error event. |
| OnMessage | Gets or sets the event handler of the message event. |
| OnOpen | Gets or sets the event handler of the open event. |
| Protocol | Gets the subprotocol selected by the server (the Sec-WebSocket-Protocol header of its response), or the empty string. |
| ReadyState | Gets the state of the connection (https://websockets.spec.whatwg.org/#dom-websocket-readystate): WebSocket.Connecting, WebSocket.Open, WebSocket.Closing or WebSocket.Closed. |
| Url | Gets the URL of the WebSocket, serialized (https://websockets.spec.whatwg.org/#dom-websocket-url). |
BinaryType
WebSocket.csGets or sets how the binary messages are exposed: as a Blob (the default) or as a Byte array (an ArrayBuffer).
public BinaryType BinaryType { get; set; }BufferedAmount
WebSocket.csGets the number of bytes of the messages queued by WebSocket.Send that were not yet transmitted to the network as of the last task (https://websockets.spec.whatwg.org/#dom-websocket-bufferedamount). It only increases once the connection is closed.
public ulong BufferedAmount { get; }Extensions
WebSocket.csGets the extensions selected by the server (the Sec-WebSocket-Extensions header of its response), or the empty string.
public string Extensions { get; }OnClose
WebSocket.csGets or sets the event handler of the close event.
OnError
WebSocket.csGets or sets the event handler of the error event.
OnMessage
WebSocket.csGets or sets the event handler of the message event.
OnOpen
WebSocket.csGets or sets the event handler of the open event.
Protocol
WebSocket.csGets the subprotocol selected by the server (the Sec-WebSocket-Protocol header of its response), or the empty string.
public string Protocol { get; }ReadyState
WebSocket.csGets the state of the connection (https://websockets.spec.whatwg.org/#dom-websocket-readystate): WebSocket.Connecting, WebSocket.Open, WebSocket.Closing or WebSocket.Closed.
public ushort ReadyState { get; }Url
WebSocket.csGets the URL of the WebSocket, serialized (https://websockets.spec.whatwg.org/#dom-websocket-url).
public string Url { get; }Methods
| Name | Description |
|---|---|
| Close(ushort?, string?) | Closes the connection (https://websockets.spec.whatwg.org/#dom-websocket-close): starts the closing handshake, or fails the connection when it is not established yet. |
| Send(object?) | Sends a message (https://websockets.spec.whatwg.org/#dom-websocket-send): a text message for a string, a binary message for a Blob or bytes (a Byte array, a ReadOnlyMemory<T> of bytes, or a buffer source of the script engine). The message is not sent when the closing handshake was started, but WebSocket.BufferedAmount increases anyway. |
| Send(string) | Sends a text message (https://websockets.spec.whatwg.org/#dom-websocket-send). |
Close(ushort?, string?)
WebSocket.csCloses the connection (https://websockets.spec.whatwg.org/#dom-websocket-close): starts the closing handshake, or fails the connection when it is not established yet.
Parameters
codeushort?- The status code of the Close frame:
1000or a code from3000to4999, or null for a Close frame without status code. reasonstring?- The reason of the Close frame (at most 123 bytes in UTF-8), or null.
Exceptions
DomException- An
InvalidAccessErrorwhen the code is not valid, or aSyntaxErrorwhen the reason is too long.
See also
Send overloads
Send(object?)
WebSocket.csSends a message (https://websockets.spec.whatwg.org/#dom-websocket-send): a text message for a string, a binary message for a Blob or bytes (a Byte array, a ReadOnlyMemory<T> of bytes, or a buffer source of the script engine). The message is not sent when the closing handshake was started, but WebSocket.BufferedAmount increases anyway.
Parameters
dataobject?- The message.
Exceptions
DomException- An
InvalidStateErrorwhen the connection is not established yet.
See also
Send(string)
WebSocket.csConstants
| Name | Description |
|---|---|
| Closed | The state of a WebSocket whose connection is closed or could not be opened. |
| Closing | The state of a WebSocket whose closing handshake was started, or whose WebSocket.Close method was called. |
| Connecting | The state of a WebSocket whose connection has not yet been established. |
| Open | The state of a WebSocket whose connection is established: the messages can be sent and received. |
Closed
The state of a WebSocket whose connection is closed or could not be opened.
public const ushort Closed = 3Closing
The state of a WebSocket whose closing handshake was started, or whose WebSocket.Close method was called.
public const ushort Closing = 2Connecting
The state of a WebSocket whose connection has not yet been established.
public const ushort Connecting = 0Open
The state of a WebSocket whose connection is established: the messages can be sent and received.
public const ushort Open = 1