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>

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

Create a socket using the given buffers.

pub fn handle(&self) -> SocketHandle

Return the socket handle.

pub fn timeout(&self) -> Option<Duration>

Return the timeout duration.

See also the set_timeout method.

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

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.

pub fn keep_alive(&self) -> Option<Duration>

Return the keep-alive interval.

See also the set_keep_alive method.

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

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.

pub fn hop_limit(&self) -> Option<u8>

Return the time-to-live (IPv4) or hop limit (IPv6) value used in outgoing packets.

See also the set_hop_limit method

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

Set the time-to-live (IPv4) or hop limit (IPv6) value used in outgoing packets.

A socket without an explicitly set hop limit value uses the default IANA recommended value (64).

Panics

This function panics if a hop limit value of 0 is given. See RFC 1122 § 3.2.1.7.

pub fn local_endpoint(&self) -> IpEndpoint

Return the local endpoint.

pub fn remote_endpoint(&self) -> IpEndpoint

Return the remote endpoint.

pub fn state(&self) -> State

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

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

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

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

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

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

pub 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 not be in the CLOSED or TIME-WAIT states.

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

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

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.

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.

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

pub fn send<'b, F, R>(&'b mut self, f: F) -> Result<R> where
    F: FnOnce(&'b 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.

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

pub 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 octets actually enqueued, which is limited by the amount of free space in the transmit buffer; down to zero.

See also send.

pub fn recv<'b, F, R>(&'b mut self, f: F) -> Result<R> where
    F: FnOnce(&'b 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.

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

pub 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 octets actually dequeued, which is limited by the amount of occupied space in the receive buffer; down to zero.

See also recv.

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

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

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

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.

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

Trait Implementations

impl<'a, 'b> AnySocket<'a, 'b> for TcpSocket<'a>

fn downcast<'c>(
    ref_: SocketRef<'c, Socket<'a, 'b>>
) -> Option<SocketRef<'c, Self>>

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

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

Formats the value using the given formatter.

impl<'a> Into<Socket<'a, 'a>> for TcpSocket<'a>

fn into(self) -> Socket<'a, 'a>

Performs the conversion.

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

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

Writes a string slice 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.