Struct UdpSocket 

pub struct UdpSocket<'a, 'd> { /* private fields */ }

A UDP socket borrowed from a Stack, returned by Stack::udp_socket.

Implementations

impl UdpSocket<'_, '_>

pub fn local_endpoint(&self) -> IpListenEndpoint

Return the bound local endpoint. The address is the filter the bind scoped the socket to. A zero port means the socket is not bound.

pub fn remote_endpoint(&self) -> IpListenEndpoint

Return the bound remote endpoint. Unspecified parts match any remote: a fully unspecified endpoint means an ordinary unconnected socket.

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 bind( &mut self, local: impl Into<IpListenEndpoint>, remote: impl Into<IpListenEndpoint>, ) -> Result<(), BindError>

Bind the socket, fixing (parts of) its 4-tuple.

Every UDP socket is identified by the (local address, local port, remote address, remote port) tuple, and binding pins parts of it down: each part of local and remote is either exact or a wildcard (absent or unspecified address / zero port):

• bind(port, ANY): server on all addresses of both IP versions.
• bind((Ipv4Address::UNSPECIFIED, port), ANY): server on all IPv4 addresses, and no IPv6 one.
• bind((addr, port), ANY): server on one address.
• bind(0, ANY): unconnected sender. A free port in the 49152..=65535 range is allocated, picked at a random starting point.
• bind((addr, 0), ANY): pin the source address, allocate the port.
• bind(0, remote): ordinary connected client. The local address is resolved from the routing tables (a connected socket always has a concrete local address), and an ephemeral local port is allocated.

(ANY above is IpListenEndpoint::UNSPECIFIED, the fully wildcard remote.)

Specified parts of remote filter ingress, so only datagrams matching them are delivered, and are the default destination for sends. The remote half is not all-or-nothing: e.g. a remote with only the address specified accepts any port of that one peer.

A bind is rejected only if another UDP socket holds the identical 4-tuple. Sharing a local port is fine as long as the tuples differ (e.g. a connected socket next to a wildcard server socket, two sockets connected to different remotes, or the two halves of a dual stack, (Ipv4Address::UNSPECIFIED, port) and (Ipv6Address::UNSPECIFIED, port)). Distinct overlapping tuples are never ambiguous, since each datagram is handed to the most specific match. Ephemeral allocation applies the same rule, so connected sockets can reuse ports held by sockets with a different remote.

Returns Err(BindError::InvalidState) if the socket is already bound (see is_open), Err(BindError::InUse) on an identical bind, Err(BindError::NoFreePorts) if the ephemeral range is exhausted, and Err(BindError::Unaddressable) on an address family mismatch or if no local address is available for the given remote.

pub fn close(&mut self)

Close the socket, unbinding it and dropping any queued packets.

pub fn is_open(&self) -> bool

Check whether the socket is open (bound to a port).

pub fn register_recv_waker(&mut self, waker: &Waker)

Register a waker for receive operations.

The waker is woken on state changes that might affect the return value of recv calls, such as receiving data, or the socket closing.

Notes:

• Only one waker can be registered at a time. If another waker was previously registered, it is overwritten and will no longer be woken.
• The Waker is woken only once. Once woken, you must register it again before incoming data may wake it again.
• “Spurious wakes” are allowed: a wake doesn’t guarantee the result of recv has changed.

pub fn register_send_waker(&mut self, waker: &Waker)

Register a waker for send operations.

The waker is woken on state changes that might affect the return value of send calls, such as the socket being bound or closed.

Notes:

• Only one waker can be registered at a time. If another waker was previously registered, it is overwritten and will no longer be woken.
• The Waker is woken only once. Once woken, you must register it again before it may be woken again.
• “Spurious wakes” are allowed: a wake doesn’t guarantee the result of send has changed.

pub fn can_recv(&self) -> bool

Check whether the RX queue is not empty.

pub fn recv(&mut self) -> Result<RecvPacket, RecvError>

Dequeue a received datagram, as an owned packet (RecvPacket).

This is zero-copy: the returned value is the buffer the datagram arrived in.

Returns Err(RecvError::InvalidState) if the socket is not bound, and Err(RecvError::Exhausted) if the RX queue is empty.

With the icmp-errors feature, a pending ICMP error is reported first, as Err(RecvError::IcmpError { .. }), once, clearing it, before any queued datagrams. See take_icmp_error.

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

Dequeue a received datagram, copying the payload into the given slice, and return the number of octets copied along with its metadata.

Note: when the size of the provided buffer is smaller than the size of the payload, the packet is dropped and Err(RecvError::Truncated) is returned.

See also recv.

pub fn peek(&mut self) -> Result<(&[u8], UdpMetadata), RecvError>

Peek at the next received datagram without dequeueing it, returning its payload and its metadata.

Returns Err(RecvError::InvalidState) if the socket is not bound, and Err(RecvError::Exhausted) if the RX queue is empty.

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

Peek at the next received datagram without dequeueing it, copying the payload into the given slice.

Note: when the size of the provided buffer is smaller than the size of the payload, no data is copied and Err(RecvError::Truncated) is returned. The packet stays in the queue.

See also peek.

pub fn take_icmp_error(&mut self) -> Option<(IcmpError, IpEndpoint)>

Take the pending ICMP error, if one has been reported against this socket: the kind of error and the remote endpoint the erring packet was sent to.

When an ICMP error message arrives, from the network (e.g. port unreachable) or generated locally when neighbor resolution for a destination fails, it is delivered to the most specific socket matching the quoted packet’s flow, like ordinary ingress demux, and stored here. A single error is kept (the newest wins), reported once through either this method or recv, whichever is called first, and cleared by the report. The RX waker is woken when an error is recorded.

The remote endpoint is attached so that errors on unconnected sockets are attributable.

pub fn send_slice( &mut self, data: &[u8], meta: impl Into<UdpMetadata>, ) -> Result<(), SendError>

Send a datagram to the given remote endpoint, copying the payload from a slice.

See send_with.

pub fn send_with( &mut self, max_size: usize, meta: impl Into<UdpMetadata>, f: impl FnOnce(&mut [u8]) -> usize, ) -> Result<(), SendError>

Send a datagram, building the payload in place.

The destination is meta.endpoint, with unspecified parts defaulted from the socket’s bound remote endpoint. On a connected socket, sending to IpEndpoint::UNSPECIFIED sends to the connected remote. An explicitly specified destination is honored even on a connected socket.

The closure gets a max_size-byte slice inside a freshly allocated packet buffer, and returns how many bytes it wrote. The datagram is then sent immediately. If the destination’s neighbor is unresolved, the packet is queued inside the stack and sent when resolution completes. This still counts as a successful send.

meta.meta is attached to the packet and handed to the driver with it: an id to tag the packet with, or a request to timestamp its transmission (see Iface::poll_tx_timestamp).

Returns Err(SendError::InvalidState) if the socket is not bound. Returns Err(SendError::Unaddressable) if the destination address or port is still unspecified after defaulting, the destination’s address family does not match the source address, no source address is available, or the source address is not assigned to any interface. Returns Err(SendError::BufferFull) if the payload cannot fit in a packet buffer. Returns Err(SendError::NoBuffer) if every packet buffer is in use.