Struct EndpointRead

pub struct EndpointRead<EpType: BulkOrInterrupt> { /* private fields */ }

Wrapper for a Bulk or Interrupt IN Endpoint that manages transfers to provide a higher-level buffered API.

Most of the functionality of this type is provided through standard IO traits; you’ll want to use one of the following:

• std::io::Read and BufRead for blocking IO.
• With the tokio cargo feature, tokio::io::AsyncRead and AsyncBufRead for async IO. Tokio also provides AsyncReadExt and AsyncBufReadExt with additional methods.
• With the smol cargo feature, futures_io::AsyncRead and AsyncBufRead for async IO. futures_lite provides AsyncReadExt and AsyncBufReadExt with additional methods.

By default, this type ignores USB packet lengths and boundaries. For protocols that use short or zero-length packets as delimiters, you can use the until_short_packet() method to get an EndpointReadUntilShortPacket adapter that observes these delimiters.

Implementations

impl<EpType: BulkOrInterrupt> EndpointRead<EpType>

pub fn new(endpoint: Endpoint<EpType, In>, transfer_size: usize) -> Self

Create a new EndpointRead wrapping the given endpoint.

The transfer_size parameter is the size of the buffer passed to the OS for each transfer. It will be rounded up to the next multiple of the endpoint’s max packet size.

pub fn set_num_transfers(&mut self, num_transfers: usize)

Set the number of concurrent transfers.

A value of 1 (default) means that transfers will only be submitted when calling read() or fill_buf() and the buffer is empty. To maximize throughput, a value of 2 or more is recommended for applications that stream data continuously so that the host controller can continue to receive data while the application processes the data from a completed transfer.

A value of 0 means no further transfers will be submitted. Existing transfers will complete normally, and subsequent calls to read() and fill_buf() will return zero bytes (EOF).

This submits more transfers when increasing the number, but does not cancel transfers when decreasing it.

pub fn with_num_transfers(self, num_transfers: usize) -> Self

Set the number of concurrent transfers.

See Self::set_num_transfers (this version is for method chaining).

pub fn set_read_timeout(&mut self, timeout: Duration)

Set the timeout for waiting for a transfer in the blocking read APIs.

This affects the std::io::Read and std::io::BufRead implementations only, and not the async trait implementations.

When a timeout occurs, the call fails but the transfer is not cancelled and may complete later if the read is retried.

pub fn with_read_timeout(self, timeout: Duration) -> Self

Set the timeout for an individual transfer for the blocking read APIs.

See Self::set_read_timeout – this is for method chaining with EndpointWrite::new().

pub fn cancel_all(&mut self)

Cancel all pending transfers.

This sets num_transfers to 0, so no further transfers will be submitted. Any data buffered before the transfers are cancelled can be read, and then the read methods will return 0 bytes (EOF).

Call num_transfers with a non-zero value to resume receiving data.

pub fn into_inner(self) -> Endpoint<EpType, In>

Destroy this EndpointRead and return the underlying Endpoint.

Any pending transfers are not cancelled.

pub fn until_short_packet(&mut self) -> EndpointReadUntilShortPacket<'_, EpType>

Get an EndpointReadUntilShortPacket adapter that will read only until the end of a short or zero-length packet.

Some USB protocols use packets shorter than the endpoint’s max packet size as a delimiter marking the end of a message. By default, EndpointRead ignores packet boundaries, but this adapter allows you to observe these delimiters.

Trait Implementations

impl<EpType: BulkOrInterrupt> AsyncBufRead for EndpointRead<EpType>

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

Attempts to return the contents of the internal buffer, filling it with more data from the inner reader if it is empty.

fn consume(self: Pin<&mut Self>, amt: usize)

Tells this buffer that amt bytes have been consumed from the buffer, so they should no longer be returned in calls to poll_read.

impl<EpType: BulkOrInterrupt> AsyncBufRead for EndpointRead<EpType>

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

Attempt to return the contents of the internal buffer, filling it with more data from the inner reader if it is empty.

fn consume(self: Pin<&mut Self>, amt: usize)

Tells this buffer that amt bytes have been consumed from the buffer, so they should no longer be returned in calls to poll_read.

impl<EpType: BulkOrInterrupt> AsyncRead for EndpointRead<EpType>

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

Attempts to read from the AsyncRead into buf.

impl<EpType: BulkOrInterrupt> AsyncRead for EndpointRead<EpType>

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

Attempt to read from the AsyncRead into buf.

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

Attempt to read from the AsyncRead into bufs using vectored IO operations.

impl<EpType: BulkOrInterrupt> BufRead for EndpointRead<EpType>

fn fill_buf(&mut self) -> Result<&[u8], Error>

Returns the contents of the internal buffer, filling it with more data, via Read methods, if empty.

fn consume(&mut self, len: usize)

Marks the given amount of additional bytes from the internal buffer as having been read. Subsequent calls to read only return bytes that have not been marked as read.

fn has_data_left(&mut self) -> Result<bool, Error>

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

Checks if there is any data left to be read.

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

Reads all bytes into buf until the delimiter byte or EOF is reached.

fn skip_until(&mut self, byte: u8) -> Result<usize, Error>

Skips all bytes until the delimiter byte or EOF is reached.

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

Reads all bytes until a newline (the 0xA byte) is reached, and append them to the provided String buffer.

fn split(self, byte: u8) -> Split<Self>

where Self: Sized,

Returns an iterator over the contents of this reader split on the byte byte.

fn lines(self) -> Lines<Self>

where Self: Sized,

Returns an iterator over the lines of this reader.

impl<EpType: BulkOrInterrupt> Read for EndpointRead<EpType>

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

Pull some bytes from this source into the specified buffer, returning how many bytes were read.

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_end(&mut self, buf: &mut Vec<u8>) -> Result<usize, Error>

Reads all bytes until EOF in this source, placing them into buf.

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

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

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

Reads 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)

Reads 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.