Struct wasi::sockets::udp::UdpSocket

pub struct UdpSocket { /* private fields */ }

A UDP socket handle.

Implementations

impl UdpSocket

pub fn start_bind( &self, network: &Network, local_address: IpSocketAddress ) -> Result<(), ErrorCode>

Bind the socket to a specific network on the provided IP address and port.

If the IP address is zero (0.0.0.0 in IPv4, :: in IPv6), it is left to the implementation to decide which network interface(s) to bind to. If the port is zero, the socket will be bound to a random free port.

Typical errors

• invalid-argument: The local-address has the wrong address family. (EAFNOSUPPORT, EFAULT on Windows)
• invalid-state: The socket is already bound. (EINVAL)
• address-in-use: No ephemeral ports available. (EADDRINUSE, ENOBUFS on Windows)
• address-in-use: Address is already in use. (EADDRINUSE)
• address-not-bindable: local-address is not an address that the network can bind to. (EADDRNOTAVAIL)
• not-in-progress: A bind operation is not in progress.
• would-block: Can’t finish the operation, it is still in progress. (EWOULDBLOCK, EAGAIN)

Implementors note

Unlike in POSIX, in WASI the bind operation is async. This enables interactive WASI hosts to inject permission prompts. Runtimes that don’t want to make use of this ability can simply call the native bind as part of either start-bind or finish-bind.

References

• https://pubs.opengroup.org/onlinepubs/9699919799/functions/bind.html
• https://man7.org/linux/man-pages/man2/bind.2.html
• https://learn.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-bind
• https://man.freebsd.org/cgi/man.cgi?query=bind&sektion=2&format=html

impl UdpSocket

pub fn finish_bind(&self) -> Result<(), ErrorCode>

impl UdpSocket

pub fn stream( &self, remote_address: Option<IpSocketAddress> ) -> Result<(IncomingDatagramStream, OutgoingDatagramStream), ErrorCode>

Set up inbound & outbound communication channels, optionally to a specific peer.

This function only changes the local socket configuration and does not generate any network traffic. On success, the remote-address of the socket is updated. The local-address may be updated as well, based on the best network path to remote-address.

When a remote-address is provided, the returned streams are limited to communicating with that specific peer:

• send can only be used to send to this destination.
• receive will only return datagrams sent from the provided remote-address.

This method may be called multiple times on the same socket to change its association, but only the most recently returned pair of streams will be operational. Implementations may trap if the streams returned by a previous invocation haven’t been dropped yet before calling stream again.

The POSIX equivalent in pseudo-code is:

if (was previously connected) {
connect(s, AF_UNSPEC)
}
if (remote_address is Some) {
connect(s, remote_address)
}

Unlike in POSIX, the socket must already be explicitly bound.

Typical errors

• invalid-argument: The remote-address has the wrong address family. (EAFNOSUPPORT)
• invalid-argument: The IP address in remote-address is set to INADDR_ANY (0.0.0.0 / ::). (EDESTADDRREQ, EADDRNOTAVAIL)
• invalid-argument: The port in remote-address is set to 0. (EDESTADDRREQ, EADDRNOTAVAIL)
• invalid-state: The socket is not bound.
• address-in-use: Tried to perform an implicit bind, but there were no ephemeral ports available. (EADDRINUSE, EADDRNOTAVAIL on Linux, EAGAIN on BSD)
• remote-unreachable: The remote address is not reachable. (ECONNRESET, ENETRESET, EHOSTUNREACH, EHOSTDOWN, ENETUNREACH, ENETDOWN, ENONET)
• connection-refused: The connection was refused. (ECONNREFUSED)

References

• https://pubs.opengroup.org/onlinepubs/9699919799/functions/connect.html
• https://man7.org/linux/man-pages/man2/connect.2.html
• https://learn.microsoft.com/en-us/windows/win32/api/winsock2/nf-winsock2-connect
• https://man.freebsd.org/cgi/man.cgi?connect

impl UdpSocket

pub fn local_address(&self) -> Result<IpSocketAddress, ErrorCode>

Get the current bound address.

POSIX mentions:

If the socket has not been bound to a local name, the value stored in the object pointed to by address is unspecified.

WASI is stricter and requires local-address to return invalid-state when the socket hasn’t been bound yet.

Typical errors

• invalid-state: The socket is not bound to any local address.

References

• https://pubs.opengroup.org/onlinepubs/9699919799/functions/getsockname.html
• https://man7.org/linux/man-pages/man2/getsockname.2.html
• https://learn.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-getsockname
• https://man.freebsd.org/cgi/man.cgi?getsockname

impl UdpSocket

pub fn remote_address(&self) -> Result<IpSocketAddress, ErrorCode>

Get the address the socket is currently streaming to.

Typical errors

• invalid-state: The socket is not streaming to a specific remote address. (ENOTCONN)

References

• https://pubs.opengroup.org/onlinepubs/9699919799/functions/getpeername.html
• https://man7.org/linux/man-pages/man2/getpeername.2.html
• https://learn.microsoft.com/en-us/windows/win32/api/winsock/nf-winsock-getpeername
• https://man.freebsd.org/cgi/man.cgi?query=getpeername&sektion=2&n=1

impl UdpSocket

pub fn address_family(&self) -> IpAddressFamily

Whether this is a IPv4 or IPv6 socket.

Equivalent to the SO_DOMAIN socket option.

impl UdpSocket

pub fn unicast_hop_limit(&self) -> Result<u8, ErrorCode>

Equivalent to the IP_TTL & IPV6_UNICAST_HOPS socket options.

If the provided value is 0, an invalid-argument error is returned.

Typical errors

• invalid-argument: (set) The TTL value must be 1 or higher.

impl UdpSocket

pub fn set_unicast_hop_limit(&self, value: u8) -> Result<(), ErrorCode>

impl UdpSocket

pub fn receive_buffer_size(&self) -> Result<u64, ErrorCode>

The kernel buffer space reserved for sends/receives on this socket.

If the provided value is 0, an invalid-argument error is returned. Any other value will never cause an error, but it might be silently clamped and/or rounded. I.e. after setting a value, reading the same setting back may return a different value.

Equivalent to the SO_RCVBUF and SO_SNDBUF socket options.

Typical errors

• invalid-argument: (set) The provided value was 0.

impl UdpSocket

pub fn set_receive_buffer_size(&self, value: u64) -> Result<(), ErrorCode>

impl UdpSocket

pub fn send_buffer_size(&self) -> Result<u64, ErrorCode>

impl UdpSocket

pub fn set_send_buffer_size(&self, value: u64) -> Result<(), ErrorCode>

impl UdpSocket

pub fn subscribe(&self) -> Pollable

Create a pollable which will resolve once the socket is ready for I/O.

Note: this function is here for WASI Preview2 only. It’s planned to be removed when future is natively supported in Preview3.

Trait Implementations

impl Debug for UdpSocket

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.