Struct ws_stream_wasm::WsStream

pub struct WsStream { /* fields omitted */ }

The meta data related to a websocket.

Most of the methods on this type directly map to the web API. For more documentation, check the MDN WebSocket documentation.

Methods

impl WsStream

pub async fn connect<'_>(
    url: impl AsRef<str>,
    protocols: impl Into<Option<Vec<&'_ str>>>
) -> Result<(Self, WsIo), WsErr>

Connect to the server. The future will resolve when the connection has been established with a successful WebSocket handshake.

This returns both a WsStream (allow manipulating and requesting meta data for the connection) and a WsIo (AsyncRead/AsyncWrite + Stream/Sink over WsMessage).

A WsStream instance is observable through the pharos::Observable and pharos::ObservableUnbounded traits. The type of event is WsEvent. In the case of a Close event, there will be additional information included as a CloseEvent.

When you drop this, the connection does not get closed, however when you drop WsIo it does. Streams of events will be dropped, so you will no longer receive events. One thing is possible if you really need it, that's dropping WsStream but keeping WsIo. Now through WsIo::wrapped you can access the underlying web_sys::WebSocket and set event handlers on it for on_open, on_close, on_error. If you would do that while WsStream is still around, that would break the event system and can lead to errors if you still call methods on WsStream.

Note: Sending protocols to a server that doesn't support them will make the connection fail.

Errors

Browsers will forbid making websocket connections to certain ports. See this Stack Overflow question. connect will return a WsErrKind::ForbiddenPort.

If the URL is invalid, a WsErrKind::InvalidUrl is returned. See the HTML Living Standard for more information.

When the connection fails (server port not open, wrong ip, wss:// on ws:// server, ... See the HTML Living Standard for details on all failure possibilities), a WsErrKind::ConnectionFailed is returned.

pub async fn close<'_>(&'_ self) -> Result<CloseEvent, WsErr>

Close the socket. The future will resolve once the socket's state has become WsState::CLOSED. See: MDN Documentation

pub async fn close_code<'_>(&'_ self, code: u16) -> Result<CloseEvent, WsErr>

Close the socket. The future will resolve once the socket's state has become WsState::CLOSED. See: MDN Documentation

pub async fn close_reason<'_>(
    &'_ self,
    code: u16,
    reason: impl AsRef<str>
) -> Result<CloseEvent, WsErr>

Close the socket. The future will resolve once the socket's state has become WsState::CLOSED. See: MDN Documentation

pub fn ready_state(&self) -> WsState

Verify the WsState of the connection.

pub fn wrapped(&self) -> &WebSocket

Access the wrapped web_sys::WebSocket directly.

ws_stream_wasm tries to expose all useful functionality through an idiomatic rust API, so hopefully you won't need this, however if I missed something, you can.

Caveats

If you call set_onopen, set_onerror, set_onmessage or set_onclose on this, you will overwrite the event listeners from ws_stream_wasm, and things will break.

pub fn buffered_amount(&self) -> u32

The number of bytes of data that have been queued but not yet transmitted to the network.

NOTE: that this is the number of bytes buffered by the underlying platform WebSocket implementation. It does not reflect any buffering performed by ws_stream.

pub fn extensions(&self) -> String

The extensions selected by the server as negotiated during the connection.

NOTE: This is an untested feature. The back-end server we use for testing (tungstenite) does not support Extensions.

pub fn protocol(&self) -> String

The name of the sub-protocol the server selected during the connection.

This will be one of the strings specified in the protocols parameter when creating this WsStream instance.

pub fn url(&self) -> String

Retrieve the address to which this socket is connected.

Trait Implementations

impl Drop for WsStream

fn drop(&mut self)

Executes the destructor for this type.

impl Debug for WsStream

fn fmt(&self, f: &mut Formatter) -> Result

Formats the value using the given formatter.

impl Observable<WsEvent> for WsStream

type Error = Error

The error type that is returned if observing is not possible.

fn observe(
    &mut self,
    options: ObserveConfig<WsEvent>
) -> Result<Events<WsEvent>, Self::Error>

Add an observer to the observable. Options allow chosing the channel type and to filter events with a predicate.