Enum websockets::Frame

pub enum Frame {
    Text {
        payload: String,
        continuation: bool,
        fin: bool,
    },
    Binary {
        payload: Vec<u8>,
        continuation: bool,
        fin: bool,
    },
    Close {
        payload: Option<(u16, String)>,
    },
    Ping {
        payload: Option<Vec<u8>>,
    },
    Pong {
        payload: Option<Vec<u8>>,
    },
}

Data which is sent and received through the WebSocket connection.

Sending

To send a Frame, you can construct it normally and use the WebSocket::send() method, or use the convenience methods for each frame type (send_text(), send_binary(), close(), send_ping(), and send_pong()).

Receiving

Frames can be received through the WebSocket::receive() method. To extract the underlying data from a received Frame, you can match or use the convenience methods—for example, for text frames, you can use the method as_text to get an immutable reference to the data, as_text_mut to get a mutable reference to the data, or into_text to get ownership of the data.

Fragmentation

As per the WebSocket protocol, frames can actually be fragments in a larger message (see https://tools.ietf.org/html/rfc6455#section-5.4). However, the maximum frame size allowed by the WebSocket protocol is larger than what can be stored in a Vec. Therefore, no strategy for splitting messages into Frames is provided by this library.

If you would like to use fragmentation manually, this can be done by setting the continuation and fin flags on the Text and Binary variants. continuation signifies that the Frame is a Continuation frame in the message, and fin signifies that the Frame is the final frame in the message (see the above linked RFC for more details).

For example, if the message contains only one Frame, the single frame should have continuation set to false and fin set to true. If the message contains more than one frame, the first frame should have continuation set to false and fin set to false, all other frames except the last frame should have continuation set to true and fin set to false, and the last frame should have continuation set to true and fin set to true.

Variants

Text

A Text frame

Fields of Text

payload: String

The payload for the Text frame

continuation: bool

Whether the Text frame is a continuation frame in the message

fin: bool

Whether the Text frame is the final frame in the message

Binary

A Binary frame

Fields of Binary

payload: Vec<u8>

The payload for the Binary frame

continuation: bool

Whether the Binary frame is a continuation frame in the message

fin: bool

Whether the Binary frame is the final frame in the message

Close

A Close frame

Fields of Close

payload: Option<(u16, String)>

The payload for the Close frame

Ping

A Ping frame

Fields of Ping

payload: Option<Vec<u8>>

The payload for the Ping frame

Pong

A Pong frame

Fields of Pong

payload: Option<Vec<u8>>

The payload for the Pong frame

Implementations

impl Frame

pub fn text(payload: String) -> Self

Constructs a Text frame from the given payload. continuation will be false and fin will be true. This can be modified by chaining Frame::set_continuation() or Frame::set_fin().

pub fn is_text(&self) -> bool

Returns whether the frame is a Text frame.

pub fn as_text(&self) -> Option<(&String, &bool, &bool)>

Attempts to interpret the frame as a Text frame, returning a reference to the underlying data if it is, and None otherwise.

pub fn as_text_mut(&mut self) -> Option<(&mut String, &mut bool, &mut bool)>

Attempts to interpret the frame as a Text frame, returning a mutable reference to the underlying data if it is, and None otherwise.

pub fn into_text(self) -> Option<(String, bool, bool)>

Attempts to interpret the frame as a Text frame, consuming and returning the underlying data if it is, and returning None otherwise.

pub fn binary(payload: Vec<u8>) -> Self

Constructs a Binary frame from the given payload. continuation will be false and fin will be true. This can be modified by chaining Frame::set_continuation() or Frame::set_fin().

pub fn is_binary(&self) -> bool

Returns whether the frame is a Binary frame.

pub fn as_binary(&self) -> Option<(&Vec<u8>, &bool, &bool)>

Attempts to interpret the frame as a Binary frame, returning a reference to the underlying data if it is, and None otherwise.

pub fn as_binary_mut(&mut self) -> Option<(&mut Vec<u8>, &mut bool, &mut bool)>

Attempts to interpret the frame as a Binary frame, returning a mutable reference to the underlying data if it is, and None otherwise.

pub fn into_binary(self) -> Option<(Vec<u8>, bool, bool)>

Attempts to interpret the frame as a Binary frame, consuming and returning the underlying data if it is, and returning None otherwise.

pub fn close(payload: Option<(u16, String)>) -> Self

Constructs a Close frame from the given payload.

pub fn is_close(&self) -> bool

Returns whether the frame is a Close frame.

pub fn as_close(&self) -> Option<&(u16, String)>

Attempts to interpret the frame as a Close frame, returning a reference to the underlying data if it is, and None otherwise.

pub fn as_close_mut(&mut self) -> Option<&mut (u16, String)>

Attempts to interpret the frame as a Close frame, returning a mutable reference to the underlying data if it is, and None otherwise.

pub fn into_close(self) -> Option<(u16, String)>

Attempts to interpret the frame as a Close frame, consuming and returning the underlying data if it is, and returning None otherwise.

pub fn ping(payload: Option<Vec<u8>>) -> Self

Constructs a Ping frame from the given payload.

pub fn is_ping(&self) -> bool

Returns whether the frame is a Ping frame.

pub fn as_ping(&self) -> Option<&Vec<u8>>

Attempts to interpret the frame as a Ping frame, returning a reference to the underlying data if it is, and None otherwise.

pub fn as_ping_mut(&mut self) -> Option<&mut Vec<u8>>

Attempts to interpret the frame as a Ping frame, returning a mutable reference to the underlying data if it is, and None otherwise.

pub fn into_ping(self) -> Option<Vec<u8>>

Attempts to interpret the frame as a Ping frame, consuming and returning the underlying data if it is, and returning None otherwise.

pub fn pong(payload: Option<Vec<u8>>) -> Self

Constructs a Pong frame from the given payload.

pub fn is_pong(&self) -> bool

Returns whether the frame is a Pong frame.

pub fn as_pong(&self) -> Option<&Vec<u8>>

Attempts to interpret the frame as a Pong frame, returning a reference to the underlying data if it is, and None otherwise.

pub fn as_pong_mut(&mut self) -> Option<&mut Vec<u8>>

Attempts to interpret the frame as a Pong frame, returning a mutable reference to the underlying data if it is, and None otherwise.

pub fn into_pong(self) -> Option<Vec<u8>>

Attempts to interpret the frame as a Pong frame, consuming and returning the underlying data if it is, and returning None otherwise.

pub fn set_continuation(self, continuation: bool) -> Self

Modifies the frame to set continuation to the desired value. If the frame is not a Text or Binary frame, no operation is performed.

pub fn set_fin(self, fin: bool) -> Self

Modifies the frame to set fin to the desired value. If the frame is not a Text or Binary frame, no operation is performed.

Trait Implementations

impl Clone for Frame

fn clone(&self) -> Frame

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Frame

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

Formats the value using the given formatter.

impl From<String> for Frame

fn from(s: String) -> Self

Performs the conversion.

impl From<Vec<u8, Global>> for Frame

fn from(v: Vec<u8>) -> Self

Performs the conversion.