blackwriter-server/doc/tokio-tungstenite.md

Crate Documentation

Version: 0.28.0

Format Version: 56

Module tokio_tungstenite

Async WebSocket usage.

This library is an implementation of WebSocket handshakes and streams. It is based on the crate which implements all required WebSocket protocol logic. So this crate basically just brings tokio support / tokio integration to it.

Each WebSocket stream implements the required Stream and Sink traits, so the socket is just a stream of messages coming in and going out.

Types

Struct WebSocketStream

A wrapper around an underlying raw stream which implements the WebSocket protocol.

A WebSocketStream<S> represents a handshake that has been completed successfully and both the server and the client are ready for receiving and sending data. Message from a WebSocketStream<S> are accessible through the respective Stream and Sink. Check more information about them in futures-rs crate documentation or have a look on the examples and unit tests for this crate.

pub struct WebSocketStream<S> {
    // Some fields omitted
}

Fields

Name	Type	Documentation
private fields	...	Some fields have been omitted

Implementations

Methods

• pub async fn from_raw_socket(stream: S, role: Role, config: Option<WebSocketConfig>) -> Self
  

where S: AsyncRead + AsyncWrite + Unpin { /* ... */ }

Convert a raw socket into a WebSocketStream without performing a

- ```rust
pub async fn from_partially_read(stream: S, part: Vec<u8>, role: Role, config: Option<WebSocketConfig>) -> Self
where
  S: AsyncRead + AsyncWrite + Unpin { /* ... */ }

Convert a raw socket into a WebSocketStream without performing a

• pub fn into_inner(self: Self) -> S { /* ... */ }
  

  Consumes the WebSocketStream and returns the underlying stream.

• pub fn get_ref(self: &Self) -> &S
  

where S: AsyncRead + AsyncWrite + Unpin { /* ... */ }

Returns a shared reference to the inner stream.

- ```rust
pub fn get_mut(self: &mut Self) -> &mut S
where
  S: AsyncRead + AsyncWrite + Unpin { /* ... */ }

Returns a mutable reference to the inner stream.

• pub fn get_config(self: &Self) -> &WebSocketConfig { /* ... */ }
  

  Returns a reference to the configuration of the tungstenite stream.

• pub async fn close(self: &mut Self, msg: Option<CloseFrame>) -> Result<(), WsError>
  

where S: AsyncRead + AsyncWrite + Unpin { /* ... */ }

Close the underlying web socket

##### Trait Implementations

- **Any**
- ```rust
  fn type_id(self: &Self) -> TypeId { /* ... */ }
  ```

- **Borrow**
- ```rust
  fn borrow(self: &Self) -> &T { /* ... */ }
  ```

- **BorrowMut**
- ```rust
  fn borrow_mut(self: &mut Self) -> &mut T { /* ... */ }
  ```

- **Debug**
- ```rust
  fn fmt(self: &Self, f: &mut $crate::fmt::Formatter<''_>) -> $crate::fmt::Result { /* ... */ }
  ```

- **ErasedDestructor**
- **Freeze**
- **From**
- ```rust
  fn from(t: T) -> T { /* ... */ }
  ```
  Returns the argument unchanged.

- **FusedStream**
- ```rust
  fn is_terminated(self: &Self) -> bool { /* ... */ }
  ```

- **Into**
- ```rust
  fn into(self: Self) -> U { /* ... */ }
  ```
  Calls `U::from(self)`.

- **RefUnwindSafe**
- **Same**
- **Send**
- **Sink**
- ```rust
  fn poll_ready(self: Pin<&mut Self>, cx: &mut Context<''_>) -> Poll<Result<(), <Self as >::Error>> { /* ... */ }
  ```

- ```rust
  fn start_send(self: Pin<&mut Self>, item: Message) -> Result<(), <Self as >::Error> { /* ... */ }
  ```

- ```rust
  fn poll_flush(self: Pin<&mut Self>, cx: &mut Context<''_>) -> Poll<Result<(), <Self as >::Error>> { /* ... */ }
  ```

- ```rust
  fn poll_close(self: Pin<&mut Self>, cx: &mut Context<''_>) -> Poll<Result<(), <Self as >::Error>> { /* ... */ }
  ```

- **SinkExt**
- **Stream**
- ```rust
  fn poll_next(self: Pin<&mut Self>, cx: &mut Context<''_>) -> Poll<Option<<Self as >::Item>> { /* ... */ }
  ```

- **StreamExt**
- **Sync**
- **TryFrom**
- ```rust
  fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error> { /* ... */ }
  ```

- **TryInto**
- ```rust
  fn try_into(self: Self) -> Result<U, <U as TryFrom<T>>::Error> { /* ... */ }
  ```

- **TryStream**
- ```rust
  fn try_poll_next(self: Pin<&mut S>, cx: &mut Context<''_>) -> Poll<Option<Result<<S as TryStream>::Ok, <S as TryStream>::Error>>> { /* ... */ }
  ```

- **TryStreamExt**
- **Unpin**
- **UnwindSafe**
- **VZip**
- ```rust
  fn vzip(self: Self) -> V { /* ... */ }
  ```

## Functions

### Function `client_async`

**Attributes:**

- `Other("#[<cfg>(feature = \"handshake\")]")`

Creates a WebSocket handshake from a request and a stream.
For convenience, the user may call this with a url string, a URL,
or a `Request`. Calling with `Request` allows the user to add
a WebSocket protocol or other custom headers.

Internally, this custom creates a handshake representation and returns
a future representing the resolution of the WebSocket handshake. The
returned future will resolve to either `WebSocketStream<S>` or `Error`
depending on whether the handshake is successful.

This is typically used for clients who have already established, for
example, a TCP connection to the remote server.

```rust
pub async fn client_async<''a, R, S>(request: R, stream: S) -> Result<(WebSocketStream<S>, tungstenite::handshake::client::Response), tungstenite::error::Error>
where
  R: IntoClientRequest + Unpin,
  S: AsyncRead + AsyncWrite + Unpin { /* ... */ }

Function client_async_with_config

Attributes:

• Other("#[<cfg>(feature = \"handshake\")]")

The same as client_async() but the one can specify a websocket configuration. Please refer to client_async() for more details.

pub async fn client_async_with_config<''a, R, S>(request: R, stream: S, config: Option<tungstenite::protocol::WebSocketConfig>) -> Result<(WebSocketStream<S>, tungstenite::handshake::client::Response), tungstenite::error::Error>
where
    R: IntoClientRequest + Unpin,
    S: AsyncRead + AsyncWrite + Unpin { /* ... */ }

Function accept_async

Attributes:

• Other("#[<cfg>(feature = \"handshake\")]")

Accepts a new WebSocket connection with the provided stream.

This function will internally call server::accept to create a handshake representation and returns a future representing the resolution of the WebSocket handshake. The returned future will resolve to either WebSocketStream<S> or Error depending if it's successful or not.

This is typically used after a socket has been accepted from a TcpListener. That socket is then passed to this function to perform the server half of the accepting a client's websocket connection.

pub async fn accept_async<S>(stream: S) -> Result<WebSocketStream<S>, tungstenite::error::Error>
where
    S: AsyncRead + AsyncWrite + Unpin { /* ... */ }

Function accept_async_with_config

Attributes:

• Other("#[<cfg>(feature = \"handshake\")]")

The same as accept_async() but the one can specify a websocket configuration. Please refer to accept_async() for more details.

pub async fn accept_async_with_config<S>(stream: S, config: Option<tungstenite::protocol::WebSocketConfig>) -> Result<WebSocketStream<S>, tungstenite::error::Error>
where
    S: AsyncRead + AsyncWrite + Unpin { /* ... */ }

Function accept_hdr_async

Attributes:

• Other("#[<cfg>(feature = \"handshake\")]")

Accepts a new WebSocket connection with the provided stream.

This function does the same as accept_async() but accepts an extra callback for header processing. The callback receives headers of the incoming requests and is able to add extra headers to the reply.

pub async fn accept_hdr_async<S, C>(stream: S, callback: C) -> Result<WebSocketStream<S>, tungstenite::error::Error>
where
    S: AsyncRead + AsyncWrite + Unpin,
    C: Callback + Unpin { /* ... */ }

Function accept_hdr_async_with_config

Attributes:

• Other("#[<cfg>(feature = \"handshake\")]")

The same as accept_hdr_async() but the one can specify a websocket configuration. Please refer to accept_hdr_async() for more details.

pub async fn accept_hdr_async_with_config<S, C>(stream: S, callback: C, config: Option<tungstenite::protocol::WebSocketConfig>) -> Result<WebSocketStream<S>, tungstenite::error::Error>
where
    S: AsyncRead + AsyncWrite + Unpin,
    C: Callback + Unpin { /* ... */ }

Re-exports

Re-export tungstenite

pub use tungstenite;

Re-export Connector

Attributes:

• Other("#[<cfg>(any(feature = \"native-tls\", feature = \"__rustls-tls\", feature =\n\"connect\"))]")

pub use tls::Connector;

Re-export client_async_tls

Attributes:

• Other("#[<cfg>(any(feature = \"native-tls\", feature = \"__rustls-tls\"))]")

pub use tls::client_async_tls;

Re-export client_async_tls_with_config

Attributes:

• Other("#[<cfg>(any(feature = \"native-tls\", feature = \"__rustls-tls\"))]")

pub use tls::client_async_tls_with_config;

Re-export connect_async

Attributes:

• Other("#[<cfg>(feature = \"connect\")]")

pub use connect::connect_async;

Re-export connect_async_with_config

Attributes:

• Other("#[<cfg>(feature = \"connect\")]")

pub use connect::connect_async_with_config;

Re-export connect_async_tls_with_config

Attributes:

• Other("#[<cfg>(all(any(feature = \"native-tls\", feature = \"__rustls-tls\"), feature =\n\"connect\"))]")

pub use connect::connect_async_tls_with_config;

Re-export MaybeTlsStream

Attributes:

• Other("#[<cfg>(feature = \"stream\")]")

pub use stream::MaybeTlsStream;