Struct TcpSocket

pub struct TcpSocket<'a> { /* private fields */ }

A TCP socket.

Implementations

impl<'a> TcpSocket<'a>

pub fn new( stack: Stack<'a>, rx_buffer: &'a mut [u8], tx_buffer: &'a mut [u8], ) -> Self

Create a new TCP socket on the given stack, with the given buffers.

pub fn recv_capacity(&self) -> usize

Return the maximum number of bytes inside the recv buffer.

pub fn send_capacity(&self) -> usize

Return the maximum number of bytes inside the transmit buffer.

pub fn send_queue(&self) -> usize

Return the amount of octets queued in the transmit buffer.

pub fn recv_queue(&self) -> usize

Return the amount of octets queued in the receive buffer. This value can be larger than the slice read by the next recv or peek call because it includes all queued octets, and not only the octets that may be returned as a contiguous slice.

pub async fn write_with<F, R>(&mut self, f: F) -> Result<R, Error>

where F: FnOnce(&mut [u8]) -> (usize, R),

Call f with the largest contiguous slice of octets in the transmit buffer, and enqueue the amount of elements returned by f.

If the socket is not ready to accept data, it waits until it is.

pub async fn read_with<F, R>(&mut self, f: F) -> Result<R, Error>

where F: FnOnce(&mut [u8]) -> (usize, R),

Call f with the largest contiguous slice of octets in the receive buffer, and dequeue the amount of elements returned by f.

If no data is available, it waits until there is at least one byte available.

pub fn split(&mut self) -> (TcpReader<'_>, TcpWriter<'_>)

Split the socket into reader and a writer halves.

pub async fn connect<T>( &mut self, remote_endpoint: T, ) -> Result<(), ConnectError>

where T: Into<IpEndpoint>,

Connect to a remote host.

pub async fn accept<T>(&mut self, local_endpoint: T) -> Result<(), AcceptError>

where T: Into<IpListenEndpoint>,

Accept a connection from a remote host.

This function puts the socket in listening mode, and waits until a connection is received.

pub async fn wait_read_ready(&self)

Wait until the socket becomes readable.

A socket becomes readable when the receive half of the full-duplex connection is open (see may_recv), and there is some pending data in the receive buffer.

This is the equivalent of read, without buffering any data.

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

Read data from the socket.

Returns how many bytes were read, or an error. If no data is available, it waits until there is at least one byte available.

A return value of Ok(0) means that the socket was closed and is longer able to receive any data.

pub async fn wait_write_ready(&self)

Wait until the socket becomes writable.

A socket becomes writable when the transmit half of the full-duplex connection is open (see may_send), and the transmit buffer is not full.

This is the equivalent of write, without sending any data.

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

Write data to the socket.

Returns how many bytes were written, or an error. If the socket is not ready to accept data, it waits until it is.

pub async fn flush(&mut self) -> Result<(), Error>

Flushes the written data to the socket.

This waits until all data has been sent, and ACKed by the remote host. For a connection closed with abort() it will wait for the TCP RST packet to be sent.

pub fn set_timeout(&mut self, duration: Option<Duration>)

Set the timeout for the socket.

If the timeout is set, the socket will be closed if no data is received for the specified duration.

Note:

Set a keep alive interval ([set_keep_alive] to prevent timeouts when the remote could still respond.

pub fn set_keep_alive(&mut self, interval: Option<Duration>)

Set the keep-alive interval for the socket.

If the keep-alive interval is set, the socket will send keep-alive packets after the specified duration of inactivity.

If not set, the socket will not send keep-alive packets.

By setting a timeout larger then the keep alive you can detect a remote endpoint that no longer answers.

pub fn set_hop_limit(&mut self, hop_limit: Option<u8>)

Set the hop limit field in the IP header of sent packets.

pub fn local_endpoint(&self) -> Option<IpEndpoint>

Get the local endpoint of the socket.

Returns None if the socket is not bound (listening) or not connected.

pub fn remote_endpoint(&self) -> Option<IpEndpoint>

Get the remote endpoint of the socket.

Returns None if the socket is not connected.

pub fn state(&self) -> State

Get the state of the socket.

pub fn close(&mut self)

Close the write half of the socket.

This closes only the write half of the socket. The read half side remains open, the socket can still receive data.

Data that has been written to the socket and not yet sent (or not yet ACKed) will still still sent. The last segment of the pending to send data is sent with the FIN flag set.

pub fn abort(&mut self)

Forcibly close the socket.

This instantly closes both the read and write halves of the socket. Any pending data that has not been sent will be lost.

Note that the TCP RST packet is not sent immediately - if the TcpSocket is dropped too soon the remote host may not know the connection has been closed. abort() callers should wait for a flush() call to complete before dropping or reusing the socket.

pub fn may_send(&self) -> bool

Return whether the transmit half of the full-duplex connection is open.

This function returns true if it’s possible to send data and have it arrive to the remote endpoint. However, it does not make any guarantees about the state of the transmit buffer, and even if it returns true, write may not be able to enqueue any octets.

In terms of the TCP state machine, the socket must be in the ESTABLISHED or CLOSE-WAIT state.

pub fn can_send(&self) -> bool

Check whether the transmit half of the full-duplex connection is open (see may_send), and the transmit buffer is not full.

pub fn may_recv(&self) -> bool

return whether the receive half of the full-duplex connection is open. This function returns true if it’s possible to receive data from the remote endpoint. It will return true while there is data in the receive buffer, and if there isn’t, as long as the remote endpoint has not closed the connection.

pub fn can_recv(&self) -> bool

Get whether the socket is ready to receive data, i.e. whether there is some pending data in the receive buffer.

Trait Implementations

impl<'a> Drop for TcpSocket<'a>

fn drop(&mut self)

Executes the destructor for this type.

impl<'d> ErrorType for TcpSocket<'d>

type Error = Error

Error type of all the IO operations on this type.

impl<'d> Read for TcpSocket<'d>

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

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

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

Read the exact number of bytes required to fill buf.

impl<'d> ReadReady for TcpSocket<'d>

fn read_ready(&mut self) -> Result<bool, Self::Error>

Get whether the reader is ready for immediately reading.

impl<'d> Write for TcpSocket<'d>

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

Write a buffer into this writer, returning how many bytes were written.

async fn flush(&mut self) -> Result<(), Self::Error>

Flush this output stream, ensuring that all intermediately buffered contents reach their destination.

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

Write an entire buffer into this writer.

impl<'d> WriteReady for TcpSocket<'d>

fn write_ready(&mut self) -> Result<bool, Self::Error>

Get whether the writer is ready for immediately writing.