Trait embedded_nal_async::UnconnectedUdp

pub trait UnconnectedUdp {
    type Error: Error;

    // Required methods
    async fn send(
        &mut self,
        local: SocketAddr,
        remote: SocketAddr,
        data: &[u8]
    ) -> Result<(), Self::Error>;
    async fn receive_into(
        &mut self,
        buffer: &mut [u8]
    ) -> Result<(usize, SocketAddr, SocketAddr), Self::Error>;
}

This trait is implemented by UDP sockets.

The socket it represents is not necessarily bound (may not have a single local IP address, port and interface), and is typically not connected (has no remote IP address and port). Both are addresses are explicitly given in every call.

If there were constraints in place at socket creation time (typically on the local side), the caller MUST pass in the same (or compatible) values, MAY and pass in unspecified values where applicable. The implementer MAY check them for compatibility, and SHOULD do that in debug mode.

Required Associated Types

type Error: Error

Error type returned by send and receive operations.

Required Methods

async fn send( &mut self, local: SocketAddr, remote: SocketAddr, data: &[u8] ) -> Result<(), Self::Error>

Send the provided data to a peer

Sending initial messages

The local address can be left unspecified by leaving any of its component zero – that gives the “any” address ([::] / 0.0.0.0), the uncspecified port (0) or the unspecified zone identifier (0). Unless the operating system provides facilities exceeding this crate’s traits for enumerating local interfaces and addresses, this is the only way to initiate outbound traffic.

Responding to messages

Users who have previously received data from a peer and want to respond have a choice of sending from the address to which the original datagram was addressed, or from an unbound address. Both are valid choices in some situations, and the right choice depends on the protocol used.

Note that users of sockets created through UdpStack::bind_single() should always pass in that single address – even though they’ve made their intention clear at construction. They can pass either the one obtained at socket creation time, or the one obtained at receive time; these should be equal. This allows implementations of the trait to use a single kind of socket for both sockets bound to a single and sockets bound to multiple addresses.

async fn receive_into( &mut self, buffer: &mut [u8] ) -> Result<(usize, SocketAddr, SocketAddr), Self::Error>

Receive a datagram into the provided buffer.

If the received datagram exceeds the buffer’s length, it is received regardless, and the remaining bytes are discarded. The full datagram size is still indicated in the result, allowing the recipient to detect that truncation.

The local and remote address are given, in that order, in the result along with the number of bytes.

Object Safety

This trait is not object safe.

Implementors