Struct netstack3_udp::UdpApi

pub struct UdpApi<I: Ip, C>(/* private fields */);

The UDP socket API.

Implementations

impl<I: Ip, C> UdpApi<I, C>

pub fn new(ctx: C) -> Self

Creates a new UdpApi from ctx.

impl<I, C> UdpApi<I, C>

where I: IpExt, C: ContextPair, C::CoreContext: StateContext<I, C::BindingsContext> + CounterContext<UdpCounters<I>> + DatagramStateContext<I, C::BindingsContext, Udp<C::BindingsContext>>, C::BindingsContext: UdpBindingsContext<I, <C::CoreContext as DeviceIdContext<AnyDevice>>::DeviceId>,

pub fn create( &mut self, ) -> UdpSocketId<I, <<C as ContextPair>::CoreContext as DeviceIdContext<AnyDevice>>::WeakDeviceId, <C as ContextPair>::BindingsContext>

where <C::BindingsContext as UdpBindingsTypes>::ExternalData<I>: Default,

Creates a new unbound UDP socket with default external data.

pub fn create_with( &mut self, external_data: <C::BindingsContext as UdpBindingsTypes>::ExternalData<I>, ) -> UdpSocketId<I, <<C as ContextPair>::CoreContext as DeviceIdContext<AnyDevice>>::WeakDeviceId, <C as ContextPair>::BindingsContext>

Creates a new unbound UDP socket with provided external data.

pub fn connect( &mut self, id: &UdpSocketId<I, <<C as ContextPair>::CoreContext as DeviceIdContext<AnyDevice>>::WeakDeviceId, <C as ContextPair>::BindingsContext>, remote_ip: Option<ZonedAddr<SpecifiedAddr<I::Addr>, <C::CoreContext as DeviceIdContext<AnyDevice>>::DeviceId>>, remote_port: UdpRemotePort, ) -> Result<(), ConnectError>

Connect a UDP socket

connect binds id as a connection to the remote address and port. It is also bound to a local address and port, meaning that packets sent on this connection will always come from that address and port. The local address will be chosen based on the route to the remote address, and the local port will be chosen from the available ones.

Errors

connect will fail in the following cases:

• If both local_ip and local_port are specified but conflict with an existing connection or listener
• If one or both are left unspecified but there is still no way to satisfy the request (e.g., local_ip is specified but there are no available local ports for that address)
• If there is no route to remote_ip
• If id belongs to an already-connected socket

pub fn set_device( &mut self, id: &UdpSocketId<I, <<C as ContextPair>::CoreContext as DeviceIdContext<AnyDevice>>::WeakDeviceId, <C as ContextPair>::BindingsContext>, device_id: Option<&<C::CoreContext as DeviceIdContext<AnyDevice>>::DeviceId>, ) -> Result<(), SocketError>

Sets the bound device for a socket.

Sets the device to be used for sending and receiving packets for a socket. If the socket is not currently bound to a local address and port, the device will be used when binding.

pub fn get_bound_device( &mut self, id: &UdpSocketId<I, <<C as ContextPair>::CoreContext as DeviceIdContext<AnyDevice>>::WeakDeviceId, <C as ContextPair>::BindingsContext>, ) -> Option<<C::CoreContext as DeviceIdContext<AnyDevice>>::WeakDeviceId>

Gets the device the specified socket is bound to.

pub fn set_dual_stack_enabled( &mut self, id: &UdpSocketId<I, <<C as ContextPair>::CoreContext as DeviceIdContext<AnyDevice>>::WeakDeviceId, <C as ContextPair>::BindingsContext>, enabled: bool, ) -> Result<(), SetDualStackEnabledError>

Enable or disable dual stack operations on the given socket.

This is notionally the inverse of the IPV6_V6ONLY socket option.

Errors

Returns an error if the socket does not support the IPV6_V6ONLY socket option (e.g. an IPv4 socket).

pub fn get_dual_stack_enabled( &mut self, id: &UdpSocketId<I, <<C as ContextPair>::CoreContext as DeviceIdContext<AnyDevice>>::WeakDeviceId, <C as ContextPair>::BindingsContext>, ) -> Result<bool, NotDualStackCapableError>

Get the enabled state of dual stack operations on the given socket.

This is notionally the inverse of the IPV6_V6ONLY socket option.

Errors

Returns an error if the socket does not support the IPV6_V6ONLY socket option (e.g. an IPv4 socket).

pub fn set_posix_reuse_addr( &mut self, id: &UdpSocketId<I, <<C as ContextPair>::CoreContext as DeviceIdContext<AnyDevice>>::WeakDeviceId, <C as ContextPair>::BindingsContext>, reuse_addr: bool, ) -> Result<(), ExpectedUnboundError>

Sets the POSIX SO_REUSEADDR option for the specified socket.

Errors

Returns an error if the socket is already bound.

pub fn get_posix_reuse_addr( &mut self, id: &UdpSocketId<I, <<C as ContextPair>::CoreContext as DeviceIdContext<AnyDevice>>::WeakDeviceId, <C as ContextPair>::BindingsContext>, ) -> bool

Gets the POSIX SO_REUSEADDR option for the specified socket.

pub fn set_posix_reuse_port( &mut self, id: &UdpSocketId<I, <<C as ContextPair>::CoreContext as DeviceIdContext<AnyDevice>>::WeakDeviceId, <C as ContextPair>::BindingsContext>, reuse_port: bool, ) -> Result<(), ExpectedUnboundError>

Sets the POSIX SO_REUSEPORT option for the specified socket.

Errors

Returns an error if the socket is already bound.

pub fn get_posix_reuse_port( &mut self, id: &UdpSocketId<I, <<C as ContextPair>::CoreContext as DeviceIdContext<AnyDevice>>::WeakDeviceId, <C as ContextPair>::BindingsContext>, ) -> bool

Gets the POSIX SO_REUSEPORT option for the specified socket.

pub fn set_multicast_membership( &mut self, id: &UdpSocketId<I, <<C as ContextPair>::CoreContext as DeviceIdContext<AnyDevice>>::WeakDeviceId, <C as ContextPair>::BindingsContext>, multicast_group: MulticastAddr<I::Addr>, interface: MulticastMembershipInterfaceSelector<I::Addr, <C::CoreContext as DeviceIdContext<AnyDevice>>::DeviceId>, want_membership: bool, ) -> Result<(), SetMulticastMembershipError>

Sets the specified socket’s membership status for the given group.

An error is returned if the membership change request is invalid (e.g. leaving a group that was not joined, or joining a group multiple times) or if the device to use to join is unspecified or conflicts with the existing socket state.

pub fn set_unicast_hop_limit( &mut self, id: &UdpSocketId<I, <<C as ContextPair>::CoreContext as DeviceIdContext<AnyDevice>>::WeakDeviceId, <C as ContextPair>::BindingsContext>, unicast_hop_limit: Option<NonZeroU8>, ip_version: IpVersion, ) -> Result<(), NotDualStackCapableError>

Sets the hop limit for packets sent by the socket to a unicast destination.

Sets the IPv4 TTL when ip_version is IpVersion::V4, and the IPv6 hop limits when ip_version is IpVersion::V6.

Returns NotDualStackCapableError if called on an IPv4 Socket with an ip_version of IpVersion::V6.

pub fn set_multicast_hop_limit( &mut self, id: &UdpSocketId<I, <<C as ContextPair>::CoreContext as DeviceIdContext<AnyDevice>>::WeakDeviceId, <C as ContextPair>::BindingsContext>, multicast_hop_limit: Option<NonZeroU8>, ip_version: IpVersion, ) -> Result<(), NotDualStackCapableError>

Sets the hop limit for packets sent by the socket to a multicast destination.

Sets the IPv4 TTL when ip_version is IpVersion::V4, and the IPv6 hop limits when ip_version is IpVersion::V6.

Returns NotDualStackCapableError if called on an IPv4 Socket with an ip_version of IpVersion::V6.

pub fn get_unicast_hop_limit( &mut self, id: &UdpSocketId<I, <<C as ContextPair>::CoreContext as DeviceIdContext<AnyDevice>>::WeakDeviceId, <C as ContextPair>::BindingsContext>, ip_version: IpVersion, ) -> Result<NonZeroU8, NotDualStackCapableError>

Gets the hop limit for packets sent by the socket to a unicast destination.

Gets the IPv4 TTL when ip_version is IpVersion::V4, and the IPv6 hop limits when ip_version is IpVersion::V6.

Returns NotDualStackCapableError if called on an IPv4 Socket with an ip_version of IpVersion::V6.

pub fn get_multicast_hop_limit( &mut self, id: &UdpSocketId<I, <<C as ContextPair>::CoreContext as DeviceIdContext<AnyDevice>>::WeakDeviceId, <C as ContextPair>::BindingsContext>, ip_version: IpVersion, ) -> Result<NonZeroU8, NotDualStackCapableError>

Gets the hop limit for packets sent by the socket to a multicast destination.

Gets the IPv4 TTL when ip_version is IpVersion::V4, and the IPv6 hop limits when ip_version is IpVersion::V6.

Returns NotDualStackCapableError if called on an IPv4 Socket with an ip_version of IpVersion::V6.

pub fn get_multicast_interface( &mut self, id: &UdpSocketId<I, <<C as ContextPair>::CoreContext as DeviceIdContext<AnyDevice>>::WeakDeviceId, <C as ContextPair>::BindingsContext>, ip_version: IpVersion, ) -> Result<Option<<C::CoreContext as DeviceIdContext<AnyDevice>>::WeakDeviceId>, NotDualStackCapableError>

Returns the configured multicast interface for the socket.

pub fn set_multicast_interface( &mut self, id: &UdpSocketId<I, <<C as ContextPair>::CoreContext as DeviceIdContext<AnyDevice>>::WeakDeviceId, <C as ContextPair>::BindingsContext>, interface: Option<&<C::CoreContext as DeviceIdContext<AnyDevice>>::DeviceId>, ip_version: IpVersion, ) -> Result<(), NotDualStackCapableError>

Sets the multicast interface to interface for a socket.

pub fn get_transparent( &mut self, id: &UdpSocketId<I, <<C as ContextPair>::CoreContext as DeviceIdContext<AnyDevice>>::WeakDeviceId, <C as ContextPair>::BindingsContext>, ) -> bool

Gets the transparent option.

pub fn set_transparent( &mut self, id: &UdpSocketId<I, <<C as ContextPair>::CoreContext as DeviceIdContext<AnyDevice>>::WeakDeviceId, <C as ContextPair>::BindingsContext>, value: bool, )

Sets the transparent option.

pub fn get_mark( &mut self, id: &UdpSocketId<I, <<C as ContextPair>::CoreContext as DeviceIdContext<AnyDevice>>::WeakDeviceId, <C as ContextPair>::BindingsContext>, domain: MarkDomain, ) -> Mark

Gets the socket mark at the mark domain.

pub fn set_mark( &mut self, id: &UdpSocketId<I, <<C as ContextPair>::CoreContext as DeviceIdContext<AnyDevice>>::WeakDeviceId, <C as ContextPair>::BindingsContext>, domain: MarkDomain, mark: Mark, )

Sets the socket mark at the mark domain.

pub fn get_broadcast( &mut self, id: &UdpSocketId<I, <<C as ContextPair>::CoreContext as DeviceIdContext<AnyDevice>>::WeakDeviceId, <C as ContextPair>::BindingsContext>, ) -> bool

Gets the broadcast option.

pub fn set_broadcast( &mut self, id: &UdpSocketId<I, <<C as ContextPair>::CoreContext as DeviceIdContext<AnyDevice>>::WeakDeviceId, <C as ContextPair>::BindingsContext>, value: bool, )

Sets the broadcast option.

pub fn get_multicast_loop( &mut self, id: &UdpSocketId<I, <<C as ContextPair>::CoreContext as DeviceIdContext<AnyDevice>>::WeakDeviceId, <C as ContextPair>::BindingsContext>, ip_version: IpVersion, ) -> Result<bool, NotDualStackCapableError>

Gets the loopback multicast option.

pub fn set_multicast_loop( &mut self, id: &UdpSocketId<I, <<C as ContextPair>::CoreContext as DeviceIdContext<AnyDevice>>::WeakDeviceId, <C as ContextPair>::BindingsContext>, value: bool, ip_version: IpVersion, ) -> Result<(), NotDualStackCapableError>

Sets the loopback multicast option.

pub fn get_dscp_and_ecn( &mut self, id: &UdpSocketId<I, <<C as ContextPair>::CoreContext as DeviceIdContext<AnyDevice>>::WeakDeviceId, <C as ContextPair>::BindingsContext>, ip_version: IpVersion, ) -> Result<DscpAndEcn, NotDualStackCapableError>

Gets the TCLASS/TOS option.

pub fn set_dscp_and_ecn( &mut self, id: &UdpSocketId<I, <<C as ContextPair>::CoreContext as DeviceIdContext<AnyDevice>>::WeakDeviceId, <C as ContextPair>::BindingsContext>, value: DscpAndEcn, ip_version: IpVersion, ) -> Result<(), NotDualStackCapableError>

Sets the TCLASS/TOS option.

pub fn disconnect( &mut self, id: &UdpSocketId<I, <<C as ContextPair>::CoreContext as DeviceIdContext<AnyDevice>>::WeakDeviceId, <C as ContextPair>::BindingsContext>, ) -> Result<(), ExpectedConnError>

Disconnects a connected UDP socket.

disconnect removes an existing connected socket and replaces it with a listening socket bound to the same local address and port.

Errors

Returns an error if the socket is not connected.

pub fn shutdown( &mut self, id: &UdpSocketId<I, <<C as ContextPair>::CoreContext as DeviceIdContext<AnyDevice>>::WeakDeviceId, <C as ContextPair>::BindingsContext>, which: ShutdownType, ) -> Result<(), ExpectedConnError>

Shuts down a socket for reading and/or writing.

Errors

Returns an error if the socket is not connected.

pub fn get_shutdown( &mut self, id: &UdpSocketId<I, <<C as ContextPair>::CoreContext as DeviceIdContext<AnyDevice>>::WeakDeviceId, <C as ContextPair>::BindingsContext>, ) -> Option<ShutdownType>

Get the shutdown state for a socket.

If the socket is not connected, or if shutdown was not called on it, returns None.

pub fn close( &mut self, id: UdpSocketId<I, <<C as ContextPair>::CoreContext as DeviceIdContext<AnyDevice>>::WeakDeviceId, <C as ContextPair>::BindingsContext>, ) -> RemoveResourceResultWithContext<<C::BindingsContext as UdpBindingsTypes>::ExternalData<I>, C::BindingsContext>

Removes a socket that was previously created.

pub fn get_info( &mut self, id: &UdpSocketId<I, <<C as ContextPair>::CoreContext as DeviceIdContext<AnyDevice>>::WeakDeviceId, <C as ContextPair>::BindingsContext>, ) -> SocketInfo<I::Addr, <C::CoreContext as DeviceIdContext<AnyDevice>>::WeakDeviceId>

Gets the SocketInfo associated with the UDP socket referenced by id.

pub fn listen( &mut self, id: &UdpSocketId<I, <<C as ContextPair>::CoreContext as DeviceIdContext<AnyDevice>>::WeakDeviceId, <C as ContextPair>::BindingsContext>, addr: Option<ZonedAddr<SpecifiedAddr<I::Addr>, <C::CoreContext as DeviceIdContext<AnyDevice>>::DeviceId>>, port: Option<NonZeroU16>, ) -> Result<(), Either<ExpectedUnboundError, LocalAddressError>>

Use an existing socket to listen for incoming UDP packets.

listen_udp converts id into a listening socket and registers the new socket as a listener for incoming UDP packets on the given port. If addr is None, the listener is a “wildcard listener”, and is bound to all local addresses. See the [crate::transport] module documentation for more details.

If addr is Some``, and addris already bound on the given port (either by a listener or a connection),listen_udpwill fail. IfaddrisNone, and a wildcard listener is already bound to the given port, listen_udp` will fail.

Errors

Returns an error if the socket is not currently unbound.

pub fn send<B: BufferMut>( &mut self, id: &UdpSocketId<I, <<C as ContextPair>::CoreContext as DeviceIdContext<AnyDevice>>::WeakDeviceId, <C as ContextPair>::BindingsContext>, body: B, ) -> Result<(), Either<SendError, ExpectedConnError>>

Sends a UDP packet on an existing socket.

Errors

Returns an error if the socket is not connected or the packet cannot be sent. On error, the original body is returned unmodified so that it can be reused by the caller.

pub fn send_to<B: BufferMut>( &mut self, id: &UdpSocketId<I, <<C as ContextPair>::CoreContext as DeviceIdContext<AnyDevice>>::WeakDeviceId, <C as ContextPair>::BindingsContext>, remote_ip: Option<ZonedAddr<SpecifiedAddr<I::Addr>, <C::CoreContext as DeviceIdContext<AnyDevice>>::DeviceId>>, remote_port: UdpRemotePort, body: B, ) -> Result<(), Either<LocalAddressError, SendToError>>

Sends a UDP packet to the provided destination address.

If this is called with an unbound socket, the socket will be implicitly bound. If that succeeds, the ID for the new socket is returned.

Errors

Returns an error if the socket is unbound and connecting fails, or if the packet could not be sent. If the socket is unbound and connecting succeeds but sending fails, the socket remains connected.

pub fn collect_all_sockets( &mut self, ) -> Vec<UdpSocketId<I, <<C as ContextPair>::CoreContext as DeviceIdContext<AnyDevice>>::WeakDeviceId, <C as ContextPair>::BindingsContext>>

Collects all currently opened sockets, returning a cloned reference for each one.

pub fn inspect<N>(&mut self, inspector: &mut N)

where N: Inspector + InspectorDeviceExt<<C::CoreContext as DeviceIdContext<AnyDevice>>::WeakDeviceId>,

Provides inspect data for UDP sockets.