Struct smoltcp::socket::TcpSocket

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

A Transmission Control Protocol socket.

A TCP socket may passively listen for connections or actively connect to another endpoint. Note that, for listening sockets, there is no "backlog"; to be able to simultaneously accept several connections, as many sockets must be allocated, or any new connection attempts will be reset.

Methods

impl<'a> TcpSocket<'a>

fn new<T>(rx_buffer: T, tx_buffer: T) -> Socket<'a, 'static> where
    T: Into<SocketBuffer<'a>>, 

Create a socket using the given buffers.

fn debug_id(&self) -> usize

Return the debug identifier.

fn set_debug_id(&mut self, id: usize)

Set the debug identifier.

The debug identifier is a number printed in socket trace messages. It could as well be used by the user code.

fn timeout(&self) -> Option<u64>

Return the timeout duration.

See also the set_timeout method.

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

Set the timeout duration.

A socket with a timeout duration set will abort the connection if either of the following occurs:

• After a connect call, the remote endpoint does not respond within the specified duration;
• After establishing a connection, there is data in the transmit buffer and the remote endpoint exceeds the specified duration between any two packets it sends;
• After enabling keep-alive, the remote endpoint exceeds the specified duration between any two packets it sends.

fn keep_alive(&self) -> Option<u64>

Return the keep-alive interval.

See also the set_keep_alive method.

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

Set the keep-alive interval.

An idle socket with a keep-alive interval set will transmit a "challenge ACK" packet every time it receives no communication during that interval. As a result, three things may happen:

• The remote endpoint is fine and answers with an ACK packet.
• The remote endpoint has rebooted and answers with an RST packet.
• The remote endpoint has crashed and does not answer.

The keep-alive functionality together with the timeout functionality allows to react to these error conditions.

fn local_endpoint(&self) -> IpEndpoint

Return the local endpoint.

fn remote_endpoint(&self) -> IpEndpoint

Return the remote endpoint.

fn state(&self) -> State

Return the connection state, in terms of the TCP state machine.

fn listen<T>(&mut self, local_endpoint: T) -> Result<()> where
    T: Into<IpEndpoint>, 

Start listening on the given endpoint.

This function returns Err(Error::Illegal) if the socket was already open (see is_open), and Err(Error::Unaddressable) if the port in the given endpoint is zero.

fn connect<T, U>(&mut self, remote_endpoint: T, local_endpoint: U) -> Result<()> where
    T: Into<IpEndpoint>,
    U: Into<IpEndpoint>, 

Connect to a given endpoint.

The local port must be provided explicitly. Assuming fn get_ephemeral_port() -> u16 allocates a port between 49152 and 65535, a connection may be established as follows:

socket.connect((IpAddress::v4(10, 0, 0, 1), 80), get_ephemeral_port())

The local address may optionally be provided.

This function returns an error if the socket was open; see is_open. It also returns an error if the local or remote port is zero, or if the remote address is unspecified.

fn close(&mut self)

Close the transmit half of the full-duplex connection.

Note that there is no corresponding function for the receive half of the full-duplex connection; only the remote end can close it. If you no longer wish to receive any data and would like to reuse the socket right away, use abort.

fn abort(&mut self)

Aborts the connection, if any.

This function instantly closes the socket. One reset packet will be sent to the remote endpoint.

In terms of the TCP state machine, the socket may be in any state and is moved to the CLOSED state.

fn is_listening(&self) -> bool

Return whether the socket is passively listening for incoming connections.

In terms of the TCP state machine, the socket must be in the LISTEN state.

fn is_open(&self) -> bool

Return whether the socket is open.

This function returns true if the socket will process incoming or dispatch outgoing packets. Note that this does not mean that it is possible to send or receive data through the socket; for that, use can_send or can_recv.

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

fn is_active(&self) -> bool

Return whether a connection is active.

This function returns true if the socket is actively exchanging packets with a remote endpoint. Note that this does not mean that it is possible to send or receive data through the socket; for that, use can_send or can_recv.

If a connection is established, abort will send a reset to the remote endpoint.

In terms of the TCP state machine, the socket must be in the CLOSED, TIME-WAIT, or LISTEN state.

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, send 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.

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.

In terms of the TCP state machine, the socket must be in the ESTABLISHED, FIN-WAIT-1, or FIN-WAIT-2 state, or have data in the receive buffer instead.

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.

fn can_recv(&self) -> bool

Check whether the receive half of the full-duplex connection buffer is open (see may_recv, and the receive buffer is not empty.

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

Enqueue a sequence of octets to be sent, and return a pointer to it.

This function may return a slice smaller than the requested size in case there is not enough contiguous free space in the transmit buffer, down to an empty slice.

This function returns `Err(Error::Illegal) if the transmit half of the connection is not open; see may_send.

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

Enqueue a sequence of octets to be sent, and fill it from a slice.

This function returns the amount of bytes actually enqueued, which is limited by the amount of free space in the transmit buffer; down to zero.

See also send.

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

Dequeue a sequence of received octets, and return a pointer to it.

This function may return a slice smaller than the requested size in case there are not enough octets queued in the receive buffer, down to an empty slice.

This function returns `Err(Error::Illegal) if the receive half of the connection is not open; see may_recv.

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

Dequeue a sequence of received octets, and fill a slice from it.

This function returns the amount of bytes actually dequeued, which is limited by the amount of free space in the transmit buffer; down to zero.

See also recv.

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

Peek at a sequence of received octets without removing them from the receive buffer, and return a pointer to it.

This function otherwise behaves identically to recv.

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

Peek at a sequence of received octets without removing them from the receive buffer, and fill a slice from it.

This function otherwise behaves identically to recv_slice.

fn send_queue(&self) -> usize

Return the amount of octets queued in the transmit buffer.

Note that the Berkeley sockets interface does not have an equivalent of this API.

fn recv_queue(&self) -> usize

Return the amount of octets queued in the receive buffer.

Note that the Berkeley sockets interface does not have an equivalent of this API.

Trait Implementations

impl<'a> Debug for TcpSocket<'a>

fn fmt(&self, __arg_0: &mut Formatter) -> Result

Formats the value using the given formatter.

impl<'a> Write for TcpSocket<'a>

fn write_str(&mut self, slice: &str) -> Result

Writes a slice of bytes into this writer, returning whether the write succeeded.

fn write_char(&mut self, c: char) -> Result<(), Error>

Writes a [char] into this writer, returning whether the write succeeded.

fn write_fmt(&mut self, args: Arguments) -> Result<(), Error>

Glue for usage of the [write!] macro with implementors of this trait.