Trait netstack3_datagram::DatagramSocketSpec

pub trait DatagramSocketSpec: Sized + 'static {
    type AddrSpec: SocketMapAddrSpec;
    type SocketId<I: IpExt, D: WeakDeviceIdentifier>: Clone + Debug + Eq + Send + Borrow<StrongRc<I, D, Self>> + From<StrongRc<I, D, Self>>;
    type OtherStackIpOptions<I: IpExt, D: WeakDeviceIdentifier>: Clone + Debug + Default + Send + Sync;
    type ListenerIpAddr<I: IpExt>: Clone + Debug + Into<(Option<SpecifiedAddr<I::Addr>>, NonZeroU16)> + Send + Sync + 'static;
    type SharingState: Clone + Debug + Default + Send + Sync + 'static;
    type ConnIpAddr<I: IpExt>: Clone + Debug + Into<ConnInfoAddr<I::Addr, <Self::AddrSpec as SocketMapAddrSpec>::RemoteIdentifier>>;
    type ConnState<I: IpExt, D: WeakDeviceIdentifier>: Debug + AsRef<IpOptions<I, D, Self>> + AsMut<IpOptions<I, D, Self>> + Send + Sync;
    type ConnStateExtra: Debug + Send + Sync;
    type SocketMapSpec<I: IpExt + DualStackIpExt, D: WeakDeviceIdentifier>: DatagramSocketMapSpec<I, D, Self::AddrSpec, ListenerSharingState = Self::SharingState, ConnSharingState = Self::SharingState>;
    type ExternalData<I: Ip>: Debug + Send + Sync + 'static;
    type Serializer<I: IpExt, B: BufferMut>: TransportPacketSerializer<I, Buffer = B>;
    type SerializeError;

    const NAME: &'static str;

    // Required methods
    fn ip_proto<I: IpProtoExt>() -> I::Proto;
    fn make_bound_socket_map_id<I: IpExt, D: WeakDeviceIdentifier>(
        s: &Self::SocketId<I, D>,
    ) -> <Self::SocketMapSpec<I, D> as DatagramSocketMapSpec<I, D, Self::AddrSpec>>::BoundSocketId;
    fn make_packet<I: IpExt, B: BufferMut>(
        body: B,
        addr: &ConnIpAddr<I::Addr, <Self::AddrSpec as SocketMapAddrSpec>::LocalIdentifier, <Self::AddrSpec as SocketMapAddrSpec>::RemoteIdentifier>,
    ) -> Result<Self::Serializer<I, B>, Self::SerializeError>;
    fn try_alloc_listen_identifier<I: IpExt, D: WeakDeviceIdentifier>(
        rng: &mut impl RngContext,
        is_available: impl Fn(<Self::AddrSpec as SocketMapAddrSpec>::LocalIdentifier) -> Result<(), InUseError>,
    ) -> Option<<Self::AddrSpec as SocketMapAddrSpec>::LocalIdentifier>;
    fn conn_info_from_state<I: IpExt, D: WeakDeviceIdentifier>(
        state: &Self::ConnState<I, D>,
    ) -> ConnInfo<I::Addr, D>;
    fn try_alloc_local_id<I: IpExt, D: WeakDeviceIdentifier, BC: RngContext>(
        bound: &BoundSocketMap<I, D, Self::AddrSpec, Self::SocketMapSpec<I, D>>,
        bindings_ctx: &mut BC,
        flow: DatagramFlowId<I::Addr, <Self::AddrSpec as SocketMapAddrSpec>::RemoteIdentifier>,
    ) -> Option<<Self::AddrSpec as SocketMapAddrSpec>::LocalIdentifier>;
}

Types and behavior for datagram sockets.

These sockets may or may not support dual-stack operation.

Required Associated Types

type AddrSpec: SocketMapAddrSpec

The socket address spec for the datagram socket type.

This describes the types of identifiers the socket uses, e.g. local/remote port for UDP.

type SocketId<I: IpExt, D: WeakDeviceIdentifier>: Clone + Debug + Eq + Send + Borrow<StrongRc<I, D, Self>> + From<StrongRc<I, D, Self>>

Identifier for an individual socket for a given IP version.

Corresponds uniquely to a socket resource. This is the type that will be returned by [create] and used to identify which socket is being acted on by calls like [listen], [connect], [remove], etc.

type OtherStackIpOptions<I: IpExt, D: WeakDeviceIdentifier>: Clone + Debug + Default + Send + Sync

IP-level options for sending I::OtherVersion IP packets.

type ListenerIpAddr<I: IpExt>: Clone + Debug + Into<(Option<SpecifiedAddr<I::Addr>>, NonZeroU16)> + Send + Sync + 'static

The type of a listener IP address.

For dual-stack-capable datagram protocols like UDP, this should use [DualStackIpExt::ListenerIpAddr], which will be one of ListenerIpAddr or DualStackListenerIpAddr. Non-dual-stack-capable protocols (like ICMP and raw IP sockets) should just use ListenerIpAddr.

type SharingState: Clone + Debug + Default + Send + Sync + 'static

The sharing state for a socket.

NB: The underlying BoundSocketMap` uses separate types for the sharing state of connected vs listening sockets. At the moment, datagram sockets have no need for differentiated sharing states, so consolidate them under one type.

type ConnIpAddr<I: IpExt>: Clone + Debug + Into<ConnInfoAddr<I::Addr, <Self::AddrSpec as SocketMapAddrSpec>::RemoteIdentifier>>

The type of an IP address for a connected socket.

For dual-stack-capable datagram protocols like UDP, this should use [DualStackIpExt::ConnIpAddr], which will be one of ConnIpAddr or DualStackConnIpAddr. Non-dual-stack-capable protocols (like ICMP and raw IP sockets) should just use ConnIpAddr.

type ConnState<I: IpExt, D: WeakDeviceIdentifier>: Debug + AsRef<IpOptions<I, D, Self>> + AsMut<IpOptions<I, D, Self>> + Send + Sync

The type of a state held by a connected socket.

For dual-stack-capable datagram protocols like UDP, this should use [DualStackIpExt::ConnState], which will be one of ConnState or DualStackConnState. Non-dual-stack-capable protocols (like ICMP and raw IP sockets) should just use ConnState.

type ConnStateExtra: Debug + Send + Sync

The extra state that a connection state want to remember.

For example: UDP sockets does not have any extra state to remember, so it should just be (); ICMP sockets need to remember the remote ID the socket is ‘connected’ to, the remote ID is not used when sending nor participating in the demuxing decisions. So it will be stored in the extra state so that it can be retrieved later, i.e, it should be NonZeroU16 for ICMP sockets.

type SocketMapSpec<I: IpExt + DualStackIpExt, D: WeakDeviceIdentifier>: DatagramSocketMapSpec<I, D, Self::AddrSpec, ListenerSharingState = Self::SharingState, ConnSharingState = Self::SharingState>

The specification for the BoundSocketMap for a given IP version.

Describes the per-address and per-socket values held in the demultiplexing map for a given IP version.

type ExternalData<I: Ip>: Debug + Send + Sync + 'static

External data kept by datagram sockets.

This is used to store opaque bindings data alongside the core data inside the socket references.

type Serializer<I: IpExt, B: BufferMut>: TransportPacketSerializer<I, Buffer = B>

The type of serializer returned by DatagramSocketSpec::make_packet for a given IP version and buffer type.

type SerializeError

The potential error for serializing a packet. For example, in UDP, this should be infallible but for ICMP, there will be an error if the input is not an echo request.

Required Associated Constants

const NAME: &'static str

Name of this datagram protocol.

Required Methods

fn ip_proto<I: IpProtoExt>() -> I::Proto

Returns the IP protocol of this datagram specification.

fn make_bound_socket_map_id<I: IpExt, D: WeakDeviceIdentifier>( s: &Self::SocketId<I, D>, ) -> <Self::SocketMapSpec<I, D> as DatagramSocketMapSpec<I, D, Self::AddrSpec>>::BoundSocketId

Converts Self::SocketId to DatagramSocketMapSpec::BoundSocketId.

Constructs a socket identifier to its in-demultiplexing map form. For protocols with dual-stack sockets, like UDP, implementations should perform a transformation. Otherwise it should be the identity function.

fn make_packet<I: IpExt, B: BufferMut>( body: B, addr: &ConnIpAddr<I::Addr, <Self::AddrSpec as SocketMapAddrSpec>::LocalIdentifier, <Self::AddrSpec as SocketMapAddrSpec>::RemoteIdentifier>, ) -> Result<Self::Serializer<I, B>, Self::SerializeError>

Constructs a packet serializer with addr and body.

fn try_alloc_listen_identifier<I: IpExt, D: WeakDeviceIdentifier>( rng: &mut impl RngContext, is_available: impl Fn(<Self::AddrSpec as SocketMapAddrSpec>::LocalIdentifier) -> Result<(), InUseError>, ) -> Option<<Self::AddrSpec as SocketMapAddrSpec>::LocalIdentifier>

Attempts to allocate a local identifier for a listening socket.

Returns the identifier on success, or None on failure.

fn conn_info_from_state<I: IpExt, D: WeakDeviceIdentifier>( state: &Self::ConnState<I, D>, ) -> ConnInfo<I::Addr, D>

Retrieves the associated connection info from the connection state.

fn try_alloc_local_id<I: IpExt, D: WeakDeviceIdentifier, BC: RngContext>( bound: &BoundSocketMap<I, D, Self::AddrSpec, Self::SocketMapSpec<I, D>>, bindings_ctx: &mut BC, flow: DatagramFlowId<I::Addr, <Self::AddrSpec as SocketMapAddrSpec>::RemoteIdentifier>, ) -> Option<<Self::AddrSpec as SocketMapAddrSpec>::LocalIdentifier>

Tries to allocate a local identifier.

Object Safety

This trait is not object safe.

Implementors