Struct UdpSocket 

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

An UDP socket.

Implementations

impl<'d> UdpSocket<'d>

pub fn new(stack: Stack<'d>) -> Result<Self, Full>

Create a new UDP socket using the provided stack.

Errors:

• Full if the stack has no room for another UDP socket. The limit is set by the udp-socket-count-N feature of xarxa.

pub fn bind<T>(&mut self, endpoint: T) -> Result<(), BindError>

where T: Into<IpListenEndpoint>,

Bind the socket to a local endpoint.

A port of 0 allocates an ephemeral port.

pub fn bind_to<L, R>(&mut self, local: L, remote: R) -> Result<(), BindError>

where L: Into<IpListenEndpoint>, R: Into<IpListenEndpoint>,

Bind the socket to a local endpoint, and connect it to a remote one.

Only datagrams matching the specified parts of remote are received, and unspecified parts of a send’s destination default from it.

pub fn bind_to_iface( &mut self, iface: Option<IfaceHandle>, ) -> Result<(), BindError>

Bind the socket to an interface, or unbind it with None.

A socket bound to an interface only sends and receives packets on it:

• Destinations must be on-link on that interface, or have a route through it.
• Broadcast and multicast destinations go out on that interface only.
• Local addresses are picked from that interface only.

The socket must be closed. The binding is kept across close, so a socket stays bound to its interface when it is bound again.

Two sockets with otherwise identical tuples may coexist if they are bound to different interfaces. On ingress, a socket bound to the arrival interface wins over an unbound one with an equal tuple.

Returns Err(BindError::InvalidState) if the socket is open.

pub fn bound_iface(&self) -> Option<IfaceHandle>

Return the interface the socket is bound to, or None.

See bind_to_iface.

pub fn wait_recv_ready(&self) -> impl Future<Output = ()> + '_

Wait until the socket becomes readable.

A socket is readable when a packet has been received, or when there are queued packets in the buffer.

pub fn poll_recv_ready(&self, cx: &mut Context<'_>) -> Poll<()>

Wait until a datagram can be read.

When no datagram is readable, this method will return Poll::Pending and register the current task to be notified when a datagram is received.

When a datagram is received, this method will return Poll::Ready.

pub fn recv_from<'s>( &'s self, buf: &'s mut [u8], ) -> impl Future<Output = Result<(usize, UdpMetadata), RecvError>> + 's

Receive a datagram.

This method will wait until a datagram is received.

If the socket is not bound, this method will return Err(RecvError::InvalidState).

Returns the number of bytes received and the remote endpoint.

pub fn try_recv_from( &self, buf: &mut [u8], ) -> Result<(usize, UdpMetadata), TryError<RecvError>>

Receive a datagram.

This method will not wait for a datagram to be received.

If no datagram is available, this method will return Err(TryError::WouldBlock).

Returns the number of bytes received and the remote endpoint.

pub fn poll_recv_from( &self, buf: &mut [u8], cx: &mut Context<'_>, ) -> Poll<Result<(usize, UdpMetadata), RecvError>>

Receive a datagram.

When no datagram is available, this method will return Poll::Pending and register the current task to be notified when a datagram is received.

When a datagram is received, this method will return Poll::Ready with the number of bytes received and the remote endpoint.

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

Receive a datagram, taking ownership of its packet buffer.

This method will wait until a datagram is received.

If the socket is not bound, this method will return Err(RecvError::InvalidState).

The returned packet derefs to the payload. Dropping it frees the buffer.

pub fn try_recv(&self) -> Result<RecvPacket, TryError<RecvError>>

Receive a datagram, taking ownership of its packet buffer.

This method will not wait for a datagram to be received.

If no datagram is available, this method will return Err(TryError::WouldBlock).

pub async fn recv_from_with<F, R>(&mut self, f: F) -> Result<R, RecvError>

where F: FnOnce(&[u8], UdpMetadata) -> R,

Receive a datagram with a zero-copy function.

When no datagram is available, this method will return Poll::Pending and register the current task to be notified when a datagram is received.

When a datagram is received, this method will call the provided function with a reference to the received bytes and the remote endpoint and return Poll::Ready with the function’s returned value.

pub fn try_recv_from_with<F, R>( &mut self, f: F, ) -> Result<R, TryError<RecvError>>

where F: FnOnce(&[u8], UdpMetadata) -> R,

Receive a datagram with a zero-copy function.

This method will not wait for a datagram to be received.

If no datagram is available, this method will return Err(TryError::WouldBlock).

pub fn wait_send_ready(&self) -> impl Future<Output = ()> + '_

Wait until the socket becomes writable.

A socket becomes writable when the stack has a free packet buffer and the network device has room for a frame.

pub fn poll_send_ready(&self, cx: &mut Context<'_>) -> Poll<()>

Wait until a datagram can be sent.

When no datagram can be sent (the stack has no free packet buffer, or the network device has no room), this method will return Poll::Pending and register the current task to be notified when it can.

When a datagram can be sent, this method will return Poll::Ready.

pub async fn send_to<T>( &self, buf: &[u8], remote_endpoint: T, ) -> Result<(), SendError>

where T: Into<UdpMetadata>,

Send a datagram to the specified remote endpoint.

This method will wait until the datagram has been sent.

If the datagram does not fit in a packet buffer, this method will return Err(SendError::BufferFull)

When the remote endpoint is not reachable, this method will return Err(SendError::Unaddressable)

pub fn try_send_to<T>( &self, buf: &[u8], remote_endpoint: T, ) -> Result<(), TryError<SendError>>

where T: Into<UdpMetadata>,

Send a datagram to the specified remote endpoint.

This method will not wait for a packet buffer or device room to become free.

If the datagram cannot be sent right now, this method will return Err(TryError::WouldBlock).

If the datagram does not fit in a packet buffer, this method will return Err(TryError::Other(SendError::BufferFull))

When the remote endpoint is not reachable, this method will return Err(TryError::Other(SendError::Unaddressable))

pub fn poll_send_to<T>( &self, buf: &[u8], remote_endpoint: T, cx: &mut Context<'_>, ) -> Poll<Result<(), SendError>>

where T: Into<UdpMetadata>,

Send a datagram to the specified remote endpoint.

When the datagram has been sent, this method will return Poll::Ready(Ok()).

When the datagram cannot be sent right now, this method will return Poll::Pending and register the current task to be notified when it can.

If the datagram does not fit in a packet buffer, this method will return Poll::Ready(Err(SendError::BufferFull))

When the remote endpoint is not reachable, this method will return Poll::Ready(Err(SendError::Unaddressable)).

pub async fn send_to_with<T, F, R>( &mut self, max_size: usize, remote_endpoint: T, f: F, ) -> Result<R, SendError>

where T: Into<UdpMetadata> + Copy, F: FnOnce(&mut [u8]) -> (usize, R),

Send a datagram to the specified remote endpoint with a zero-copy function.

This method will wait until a packet buffer is available before passing it to the closure. The closure returns the number of bytes written into the buffer.

If max_size does not fit in a packet buffer, this method will return Err(SendError::BufferFull)

When the remote endpoint is not reachable, this method will return Err(SendError::Unaddressable)

pub fn try_send_to_with<T, F, R>( &mut self, size: usize, remote_endpoint: T, f: F, ) -> Result<R, TryError<SendError>>

where T: Into<UdpMetadata>, F: FnOnce(&mut [u8]) -> R,

Send a datagram to the specified remote endpoint with a zero-copy function.

This method will not wait for a packet buffer to become free.

If the datagram cannot be sent right now, this method will return Err(TryError::WouldBlock).

If size does not fit in a packet buffer, this method will return Err(TryError::Other(SendError::BufferFull))

When the remote endpoint is not reachable, this method will return Err(TryError::Other(SendError::Unaddressable))

pub fn endpoint(&self) -> IpListenEndpoint

Returns the local endpoint of the socket.

pub fn remote_endpoint(&self) -> IpListenEndpoint

Returns the remote endpoint the socket is bound to, if any.

pub fn is_open(&self) -> bool

Returns whether the socket is open.

pub fn close(&mut self)

Close the socket.

pub fn may_send(&self) -> bool

Returns whether the socket is ready to send data, i.e. it is bound and a packet buffer is free.

pub fn may_recv(&self) -> bool

Returns whether the socket is ready to receive data, i.e. it has received a packet that’s now in the queue.

pub fn set_hop_limit(&mut self, hop_limit: Option<u8>)

Set the hop limit field in the IP header of sent packets.

Trait Implementations

impl Drop for UdpSocket<'_>

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.