Struct lightws::stream::Stream

pub struct Stream<IO, Role, Guard = Direct> { /* private fields */ }

Websocket stream.

Depending on IO, Stream implements std::io::Read and std::io::Write or tokio::io::AsyncRead and tokio::io::AsyncWrite.

Role decides whether to mask payload data. It is reserved to provide extra infomation to apply optimizations.

See also: Stream::read, Stream::write.

Implementations

impl<IO, Role, Guard> Stream<IO, Role, Guard>

where Role: RoleHelper,

pub fn mask_key(&self) -> Mask

Get mask for upcoming writes.

pub fn set_mask_key(&mut self, key: [u8; 4]) -> Result<(), CtrlError>

Set mask for upcoming writes. An attempt to set mask during a write will fail with CtrlError::SetMaskInWrite.

impl<IO, Role, Guard> Stream<IO, Role, Guard>

Check status.

pub const fn is_pinged(&self) -> bool

Check if a Ping frame is received.

pub const fn is_ping_completed(&self) -> bool

Check if a Ping frame is completely read.

pub const fn ping_data(&self) -> &[u8]

Get the most recent ping.

pub const fn is_read_eof(&self) -> bool

Check if EOF is reached.

pub const fn is_read_close(&self) -> bool

Check if a Close frame is received.

pub const fn is_read_end(&self) -> bool

Check if a Close frame is received or EOF is reached.

pub const fn is_write_zero(&self) -> bool

Check if a WriteZero error occurred.

pub const fn is_read_partial_head(&self) -> bool

Check if a frame head is partially read.

pub const fn is_write_partial_head(&self) -> bool

Check if frame head is partially written.

impl<Role: RoleHelper> Stream<TcpStream, Role>

pub fn try_clone(&self) -> Result<Self>

Creates a new independently owned handle to the underlying IO source.

Caution: states are not shared among instances!

impl<IO, Role> Stream<IO, Role>

pub const fn new(io: IO, role: Role) -> Self

Create websocket stream from IO source directly, without a handshake.

pub fn guard(self) -> Stream<IO, Role, Guarded>

Convert to a guarded stream.

Trait Implementations

impl<IO, Role, Guard> AsMut<IO> for Stream<IO, Role, Guard>

fn as_mut(&mut self) -> &mut IO

Converts this type into a mutable reference of the (usually inferred) input type.

impl<IO, Role, Guard> AsRef<IO> for Stream<IO, Role, Guard>

fn as_ref(&self) -> &IO

Converts this type into a shared reference of the (usually inferred) input type.

impl<IO, Role> AsyncRead for Stream<IO, Role>

where IO: AsyncRead + Unpin, Stream<IO, Role>: Unpin, Role: RoleHelper,

fn poll_read( self: Pin<&mut Self>, cx: &mut Context<'_>, buf: &mut ReadBuf<'_> ) -> Poll<Result<()>>

Async version of Stream::read.

impl<IO, Role> AsyncRead for Stream<IO, Role, Guarded>

where IO: AsyncRead + Unpin, Stream<IO, Role, Guarded>: Unpin, Role: RoleHelper,

fn poll_read( self: Pin<&mut Self>, cx: &mut Context<'_>, buf: &mut ReadBuf<'_> ) -> Poll<Result<()>>

Async version of Stream::read. Continue to read if frame head is not complete.

impl<IO, Role> AsyncWrite for Stream<IO, Role>

where IO: AsyncWrite + Unpin, Stream<IO, Role>: Unpin, Role: RoleHelper,

fn poll_write( self: Pin<&mut Self>, cx: &mut Context<'_>, buf: &[u8] ) -> Poll<Result<usize>>

Async version of Stream::write.

fn poll_flush(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<()>>

This is a no-op since we do not buffer any data.

fn poll_shutdown(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<()>>

Shutdown the underlying IO source.

fn poll_write_vectored( self: Pin<&mut Self>, cx: &mut Context<'_>, bufs: &[IoSlice<'_>] ) -> Poll<Result<usize, Error>>

Like poll_write, except that it writes from a slice of buffers.

fn is_write_vectored(&self) -> bool

Determines if this writer has an efficient poll_write_vectored implementation.

impl<IO, Role> AsyncWrite for Stream<IO, Role, Guarded>

where IO: AsyncWrite + Unpin, Stream<IO, Role, Guarded>: Unpin, Role: RoleHelper,

fn poll_write( self: Pin<&mut Self>, cx: &mut Context<'_>, buf: &[u8] ) -> Poll<Result<usize>>

Async version of Stream::write. Continue to write if frame head is not completely written.

fn poll_flush(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<()>>

This is a no-op since we do not buffer any data.

fn poll_shutdown(self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<Result<()>>

Shutdown the underlying IO source.

fn poll_write_vectored( self: Pin<&mut Self>, cx: &mut Context<'_>, bufs: &[IoSlice<'_>] ) -> Poll<Result<usize, Error>>

Like poll_write, except that it writes from a slice of buffers.

fn is_write_vectored(&self) -> bool

Determines if this writer has an efficient poll_write_vectored implementation.

impl<IO, Role, Guard> Debug for Stream<IO, Role, Guard>

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

Formats the value using the given formatter.

impl<IO: Read, Role: RoleHelper> Read for Stream<IO, Role>

fn read(&mut self, buf: &mut [u8]) -> Result<usize>

Read some data from the underlying IO source, returns Ok(0) until a complete frame head is present. Caller should ensure the available buffer size is larger than 14 before a read.

Read a control frame(like Ping) returns Ok(0), which could be detected via Stream::is_pinged.

Any read after receiving a Close frame or reaching EOF will return Ok(0), which could be checked via Stream::is_read_end, Stream::is_read_close, Stream::is_read_eof.

fn read_to_end(&mut self, _: &mut Vec<u8>) -> Result<usize>

This is NOT supported!

fn read_exact(&mut self, _: &mut [u8]) -> Result<()>

This is NOT supported!

fn read_to_string(&mut self, _: &mut String) -> Result<usize>

This is NOT supported!

fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> Result<usize, Error>

Like read, except that it reads into a slice of buffers.

fn is_read_vectored(&self) -> bool

🔬This is a nightly-only experimental API. (can_vector)

Determines if this Reader has an efficient read_vectored implementation.

fn read_buf(&mut self, buf: BorrowedCursor<'_>) -> Result<(), Error>

🔬This is a nightly-only experimental API. (read_buf)

Pull some bytes from this source into the specified buffer.

fn read_buf_exact(&mut self, cursor: BorrowedCursor<'_>) -> Result<(), Error>

🔬This is a nightly-only experimental API. (read_buf)

Read the exact number of bytes required to fill cursor.

fn by_ref(&mut self) -> &mut Self

where Self: Sized,

Creates a “by reference” adaptor for this instance of Read.

fn bytes(self) -> Bytes<Self>

where Self: Sized,

Transforms this Read instance to an Iterator over its bytes.

fn chain<R>(self, next: R) -> Chain<Self, R>

where R: Read, Self: Sized,

Creates an adapter which will chain this stream with another.

fn take(self, limit: u64) -> Take<Self>

where Self: Sized,

Creates an adapter which will read at most limit bytes from it.

impl<IO: Read, Role: RoleHelper> Read for Stream<IO, Role, Guarded>

fn read(&mut self, buf: &mut [u8]) -> Result<usize>

Wrap read in a loop. Continue to read if frame head is not complete.

fn read_to_end(&mut self, buf: &mut Vec<u8>) -> Result<usize>

Override default implement, extend reserved buffer size, so that there is enough space to accommodate frame head.

fn read_vectored(&mut self, bufs: &mut [IoSliceMut<'_>]) -> Result<usize, Error>

Like read, except that it reads into a slice of buffers.

fn is_read_vectored(&self) -> bool

🔬This is a nightly-only experimental API. (can_vector)

Determines if this Reader has an efficient read_vectored implementation.

fn read_to_string(&mut self, buf: &mut String) -> Result<usize, Error>

Read all bytes until EOF in this source, appending them to buf.

fn read_exact(&mut self, buf: &mut [u8]) -> Result<(), Error>

Read the exact number of bytes required to fill buf.

fn read_buf(&mut self, buf: BorrowedCursor<'_>) -> Result<(), Error>

🔬This is a nightly-only experimental API. (read_buf)

Pull some bytes from this source into the specified buffer.

fn read_buf_exact(&mut self, cursor: BorrowedCursor<'_>) -> Result<(), Error>

🔬This is a nightly-only experimental API. (read_buf)

Read the exact number of bytes required to fill cursor.

fn by_ref(&mut self) -> &mut Self

where Self: Sized,

Creates a “by reference” adaptor for this instance of Read.

fn bytes(self) -> Bytes<Self>

where Self: Sized,

Transforms this Read instance to an Iterator over its bytes.

fn chain<R>(self, next: R) -> Chain<Self, R>

where R: Read, Self: Sized,

Creates an adapter which will chain this stream with another.

fn take(self, limit: u64) -> Take<Self>

where Self: Sized,

Creates an adapter which will read at most limit bytes from it.

impl<IO: Write, Role: RoleHelper> Write for Stream<IO, Role>

fn write(&mut self, buf: &[u8]) -> Result<usize>

Write some data to the underlying IO source, returns Ok(0) until the frame head is completely written.

if WriteZero occurs, it will also return Ok(0), which could be detected via Stream::is_write_zero.

Frame head will be generated automatically, according to the length of the provided buffer.

A standard client should mask payload data before sending it.

fn flush(&mut self) -> Result<()>

The writer does not buffer any data, simply flush the underlying IO source.

fn write_all(&mut self, _: &[u8]) -> Result<()>

This is NOT supported!

fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> Result<usize, Error>

Like write, except that it writes from a slice of buffers.

fn is_write_vectored(&self) -> bool

🔬This is a nightly-only experimental API. (can_vector)

Determines if this Writer has an efficient write_vectored implementation.

fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> Result<(), Error>

🔬This is a nightly-only experimental API. (write_all_vectored)

Attempts to write multiple buffers into this writer.

fn write_fmt(&mut self, fmt: Arguments<'_>) -> Result<(), Error>

Writes a formatted string into this writer, returning any error encountered.

fn by_ref(&mut self) -> &mut Self

where Self: Sized,

Creates a “by reference” adapter for this instance of Write.

impl<IO: Write, Role: RoleHelper> Write for Stream<IO, Role, Guarded>

fn write(&mut self, buf: &[u8]) -> Result<usize>

Wrap write in a loop. Continue to write if frame head is not completely written.

fn flush(&mut self) -> Result<()>

The writer does not buffer any data, simply flush the underlying IO source.

fn write_vectored(&mut self, bufs: &[IoSlice<'_>]) -> Result<usize, Error>

Like write, except that it writes from a slice of buffers.

fn is_write_vectored(&self) -> bool

🔬This is a nightly-only experimental API. (can_vector)

Determines if this Writer has an efficient write_vectored implementation.

fn write_all(&mut self, buf: &[u8]) -> Result<(), Error>

Attempts to write an entire buffer into this writer.

fn write_all_vectored(&mut self, bufs: &mut [IoSlice<'_>]) -> Result<(), Error>

🔬This is a nightly-only experimental API. (write_all_vectored)

Attempts to write multiple buffers into this writer.

fn write_fmt(&mut self, fmt: Arguments<'_>) -> Result<(), Error>

Writes a formatted string into this writer, returning any error encountered.

fn by_ref(&mut self) -> &mut Self

where Self: Sized,

Creates a “by reference” adapter for this instance of Write.