WebSocketStream Class
- Experimental (WEBPLATEXP0027)
A WebSocket connection whose messages are read and written with streams (https://whatpr.org/websockets/48.html#the-websocketstream-interface): the opened promise gives a ReadableStream of the received messages (a string for a text message, a Uint8Array for a binary message) and a WritableStream to which the messages are written (a string is sent as a text message, a BufferSource as a binary message), and the closed promise gives the status code and the reason of the closing handshake.
[Experimental("WEBPLATEXP0027", UrlFormat = "https://github.com/meziantou/Meziantou.Framework/blob/main/src/Meziantou.Framework.WebPlatform/docs/experimental-apis.md#{0}")]
public sealed class WebSocketStreamRemarks
The connection is a WebSocket of the current global object (the window or the worker of the script that creates the stream): it is established, closed and made to disappear (when its document is unloaded or its worker ends) as a WebSocket is, and its promises are settled by tasks of the event loop of that global object.
The readable stream applies backpressure: a message is read from the network only when the queue of the readable stream is not full (its high water mark is one message), so a server that sends faster than the page reads is slowed down by the network. A write is fulfilled once the message is sent. The streams exist only for the scripts: the WebSocketStream.Opened task of the .NET API gives the extensions and the subprotocol.
See also
Constructors
| Name | Description |
|---|---|
| WebSocketStream(string, WebSocketStreamOptions?) | Creates a WebSocketStream and starts to establish its connection (https://whatpr.org/websockets/48.html#dom-websocketstream-websocketstream). |
WebSocketStream(string, WebSocketStreamOptions?)
WebSocketStream.csCreates a WebSocketStream and starts to establish its connection (https://whatpr.org/websockets/48.html#dom-websocketstream-websocketstream).
public WebSocketStream(string url, WebSocketStreamOptions? options = null)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 current global object, without fragment. optionsWebSocketStreamOptions?- The subprotocols and the signal that aborts the opening handshake.
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 |
|---|---|
| Closed | Gets a task that completes when the connection is closed cleanly, with the status code and the reason of the closing handshake. It fails with a WebSocketError when the connection is not closed cleanly, or with the abort reason of the signal. |
| Opened | Gets a task that completes when the connection is established, with the extensions and the subprotocol selected by the server. It fails with a WebSocketError when the connection cannot be established, or with the abort reason of the signal. |
| Url | Gets the URL of the connection, serialized. |
Closed
WebSocketStream.csGets a task that completes when the connection is closed cleanly, with the status code and the reason of the closing handshake. It fails with a WebSocketError when the connection is not closed cleanly, or with the abort reason of the signal.
public Task<WebSocketCloseInfo> Closed { get; }Property value
See also
Opened
WebSocketStream.csGets a task that completes when the connection is established, with the extensions and the subprotocol selected by the server. It fails with a WebSocketError when the connection cannot be established, or with the abort reason of the signal.
public Task<WebSocketOpenInfo> Opened { get; }Property value
Remarks
For the scripts, the opened promise also gives the readable and writable streams of the messages.
See also
Gets the URL of the connection, serialized.
public string Url { get; }Methods
| Name | Description |
|---|---|
| Close(WebSocketCloseInfo?) | Closes the connection (https://whatpr.org/websockets/48.html#dom-websocketstream-close): starts the closing handshake, or fails the connection when it is not established yet. |
Close(WebSocketCloseInfo?)
WebSocketStream.csCloses the connection (https://whatpr.org/websockets/48.html#dom-websocketstream-close): starts the closing handshake, or fails the connection when it is not established yet.
public void Close(WebSocketCloseInfo? closeInfo = null)Parameters
closeInfoWebSocketCloseInfo?- The status code (
1000or a code from3000to4999;1000when only a reason is given) and the reason (at most 123 bytes in UTF-8) of the Close frame, or null for a Close frame without status code.
Exceptions
DomException- An
InvalidAccessErrorwhen the code is not valid, or aSyntaxErrorwhen the reason is too long.