Trait UdpStack

pub trait UdpStack {
    type Error: Error;
    type Connected: ConnectedUdp<Error = Self::Error>;
    type UniquelyBound: UnconnectedUdp<Error = Self::Error>;
    type MultiplyBound: UnconnectedUdp<Error = Self::Error>;

    // Required methods
    async fn connect_from(
        &self,
        local: SocketAddr,
        remote: SocketAddr,
    ) -> Result<(SocketAddr, Self::Connected), Self::Error>;
    async fn bind_single(
        &self,
        local: SocketAddr,
    ) -> Result<(SocketAddr, Self::UniquelyBound), Self::Error>;
    async fn bind_multiple(
        &self,
        local: SocketAddr,
    ) -> Result<Self::MultiplyBound, Self::Error>;

    // Provided method
    async fn connect(
        &self,
        remote: SocketAddr,
    ) -> Result<(SocketAddr, Self::Connected), Self::Error> { ... }
}

This trait is implemented by UDP/IP stacks. The trait allows the underlying driver to construct multiple connections that implement the I/O traits from embedded-io-async.

Note that stacks with exotic connection creation methods may still not implement this, yet have objects that implement ConnectedUdp or similar.

Required Associated Types

type Error: Error

Error type returned on socket creation failure.

type Connected: ConnectedUdp<Error = Self::Error>

Eventual socket return type of the [.connect()] method

type UniquelyBound: UnconnectedUdp<Error = Self::Error>

Eventual socket return type of the [.bind_single()] method

type MultiplyBound: UnconnectedUdp<Error = Self::Error>

Eventual return type of the [.bind_multiple()] method

Required Methods

async fn connect_from( &self, local: SocketAddr, remote: SocketAddr, ) -> Result<(SocketAddr, Self::Connected), Self::Error>

Create a socket that has a fixed remote address.

The local address is given explicitly, but may be partially unspecified; it is fixed by the network stack at connection time. The full local address is returned along with the connected socket, primarily for debugging purposes.

async fn bind_single( &self, local: SocketAddr, ) -> Result<(SocketAddr, Self::UniquelyBound), Self::Error>

Create a socket that has a fixed local address.

Note that the giving an unspecified address here is not the same as a POSIX bind() – if the underlying stack supports multiple local addresses, it will pick one of the applicable addresses, rather than binding to all of them.

The full local address is returned along with the bound socket; it may then be passed on to other protocols for advertising purposes.

async fn bind_multiple( &self, local: SocketAddr, ) -> Result<Self::MultiplyBound, Self::Error>

Create a socket that has no single fixed local address.

The IP address part of the local address is typically left unspecified, and the port is given. There are use cases for other constellations, and this interface does not rule out that they can be used, but they are rare (e.g. using the same IP address on different network interfaces, and listening to datagrams arriving at any of them) or not well supported by operating systems (e.g., binding to all ports at the same is not possible on POSIX systems, where giving port 0 to a bind makes the OS pick some suitable port).

Caveats:

• There is currently no way to pass in a local address that has an unspecified address family (which would effectively create a single socket that servers both IPv4 and IPv6); it is not specified whether stacks that use V6MAPPED IPv4 addresses could simply used that mechanism.

• It is currently not specified whether this mechanism can be used to join multicast groups.

• There is currently no hybrid binding that allows emulating what POSIX systems do when binding to [::]:0, that is, picking some available port but then still leaving the interface and IP address unspecified.

Provided Methods

async fn connect( &self, remote: SocketAddr, ) -> Result<(SocketAddr, Self::Connected), Self::Error>

Create a socket that has a fixed remote address.

The local address is chosen automatically.

There is a provided implementation that implements this from the maximally unspecified local address and [.connect_from()], but may be provided more efficiently by implementers.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors

impl UdpStack for UdpStack