HostUdpSocket

wasmtime_wasi::p3::bindings::sockets::types

Trait HostUdpSocket 

Source 
pub trait HostUdpSocket: Send {

Show 14 methods    // Required methods
    fn create(
        &mut self,
        address_family: IpAddressFamily,
    ) -> Result<Resource<UdpSocket>, SocketError>;
    fn bind(
        &mut self,
        self_: Resource<UdpSocket>,
        local_address: IpSocketAddress,
    ) -> impl Future<Output = Result<(), SocketError>> + Send;
    fn connect(
        &mut self,
        self_: Resource<UdpSocket>,
        remote_address: IpSocketAddress,
    ) -> impl Future<Output = Result<(), SocketError>> + Send;
    fn disconnect(
        &mut self,
        self_: Resource<UdpSocket>,
    ) -> Result<(), SocketError>;
    fn get_local_address(
        &mut self,
        self_: Resource<UdpSocket>,
    ) -> Result<IpSocketAddress, SocketError>;
    fn get_remote_address(
        &mut self,
        self_: Resource<UdpSocket>,
    ) -> Result<IpSocketAddress, SocketError>;
    fn get_address_family(
        &mut self,
        self_: Resource<UdpSocket>,
    ) -> Result<IpAddressFamily>;
    fn get_unicast_hop_limit(
        &mut self,
        self_: Resource<UdpSocket>,
    ) -> Result<u8, SocketError>;
    fn set_unicast_hop_limit(
        &mut self,
        self_: Resource<UdpSocket>,
        value: u8,
    ) -> Result<(), SocketError>;
    fn get_receive_buffer_size(
        &mut self,
        self_: Resource<UdpSocket>,
    ) -> Result<u64, SocketError>;
    fn set_receive_buffer_size(
        &mut self,
        self_: Resource<UdpSocket>,
        value: u64,
    ) -> Result<(), SocketError>;
    fn get_send_buffer_size(
        &mut self,
        self_: Resource<UdpSocket>,
    ) -> Result<u64, SocketError>;
    fn set_send_buffer_size(
        &mut self,
        self_: Resource<UdpSocket>,
        value: u64,
    ) -> Result<(), SocketError>;
    fn drop(&mut self, rep: Resource<UdpSocket>) -> Result<()>;

}
Available on crate feature p3 only.

Required Methods§

Source

fn create( &mut self, address_family: IpAddressFamily, ) -> Result<Resource<UdpSocket>, SocketError>

Create a new UDP socket.

Similar to socket(AF_INET or AF_INET6, SOCK_DGRAM, IPPROTO_UDP) in POSIX. On IPv6 sockets, IPV6_V6ONLY is enabled by default and can’t be configured otherwise.

Unlike POSIX, WASI sockets have no notion of a socket-level O_NONBLOCK flag. Instead they fully rely on the Component Model’s async support.

§References:
Source

fn bind( &mut self, self_: Resource<UdpSocket>, local_address: IpSocketAddress, ) -> impl Future<Output = Result<(), SocketError>> + Send

Bind the socket to 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 can be bound to. (EADDRNOTAVAIL)
§References
Source

fn connect( &mut self, self_: Resource<UdpSocket>, remote_address: IpSocketAddress, ) -> impl Future<Output = Result<(), SocketError>> + Send

Associate this socket with a specific peer address.

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. If the socket was not already explicitly bound, this function will implicitly bind the socket to a random free port.

When a UDP socket is “connected”, the send and receive methods are limited to communicating with that peer only:

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

The name “connect” was kept to align with the existing POSIX terminology. Other than that, this function only changes the local socket configuration and does not generate any network traffic. The peer is not aware of this “connection”.

This method may be called multiple times on the same socket to change its association, but only the most recent one will be effective.

§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)
  • address-in-use: Tried to perform an implicit bind, but there were no ephemeral ports available. (EADDRINUSE, EADDRNOTAVAIL on Linux, EAGAIN on BSD)
§Implementors note

If the socket is already connected, some platforms (e.g. Linux) require a disconnect before connecting to a different peer address.

§References
Source

fn disconnect(&mut self, self_: Resource<UdpSocket>) -> Result<(), SocketError>

Dissociate this socket from its peer address.

After calling this method, send & receive are free to communicate with any address again.

The POSIX equivalent of this is calling connect with an AF_UNSPEC address.

§Typical errors
  • invalid-state: The socket is not connected.
§References
Source

fn get_local_address( &mut self, self_: Resource<UdpSocket>, ) -> Result<IpSocketAddress, SocketError>

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 get-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
Source

fn get_remote_address( &mut self, self_: Resource<UdpSocket>, ) -> Result<IpSocketAddress, SocketError>

Get the address the socket is currently “connected” to.

§Typical errors
  • invalid-state: The socket is not “connected” to a specific remote address. (ENOTCONN)
§References
Source

fn get_address_family( &mut self, self_: Resource<UdpSocket>, ) -> Result<IpAddressFamily>

Whether this is a IPv4 or IPv6 socket.

This is the value passed to the constructor.

Equivalent to the SO_DOMAIN socket option.

Source

fn get_unicast_hop_limit( &mut self, self_: Resource<UdpSocket>, ) -> Result<u8, SocketError>

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.
Source

fn set_unicast_hop_limit( &mut self, self_: Resource<UdpSocket>, value: u8, ) -> Result<(), SocketError>

Source

fn get_receive_buffer_size( &mut self, self_: Resource<UdpSocket>, ) -> Result<u64, SocketError>

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.
Source

fn set_receive_buffer_size( &mut self, self_: Resource<UdpSocket>, value: u64, ) -> Result<(), SocketError>

Source

fn get_send_buffer_size( &mut self, self_: Resource<UdpSocket>, ) -> Result<u64, SocketError>

Source

fn set_send_buffer_size( &mut self, self_: Resource<UdpSocket>, value: u64, ) -> Result<(), SocketError>

Source

fn drop(&mut self, rep: Resource<UdpSocket>) -> Result<()>

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.

Implementations on Foreign Types§

Source§

impl<_T: HostUdpSocket + ?Sized + Send> HostUdpSocket for &mut _T

Source§

fn create( &mut self, address_family: IpAddressFamily, ) -> Result<Resource<UdpSocket>, SocketError>

Create a new UDP socket.

Similar to socket(AF_INET or AF_INET6, SOCK_DGRAM, IPPROTO_UDP) in POSIX. On IPv6 sockets, IPV6_V6ONLY is enabled by default and can’t be configured otherwise.

Unlike POSIX, WASI sockets have no notion of a socket-level O_NONBLOCK flag. Instead they fully rely on the Component Model’s async support.

§References:
Source§

fn bind( &mut self, self_: Resource<UdpSocket>, local_address: IpSocketAddress, ) -> impl Future<Output = Result<(), SocketError>> + Send

Bind the socket to 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 can be bound to. (EADDRNOTAVAIL)
§References
Source§

fn connect( &mut self, self_: Resource<UdpSocket>, remote_address: IpSocketAddress, ) -> impl Future<Output = Result<(), SocketError>> + Send

Associate this socket with a specific peer address.

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. If the socket was not already explicitly bound, this function will implicitly bind the socket to a random free port.

When a UDP socket is “connected”, the send and receive methods are limited to communicating with that peer only:

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

The name “connect” was kept to align with the existing POSIX terminology. Other than that, this function only changes the local socket configuration and does not generate any network traffic. The peer is not aware of this “connection”.

This method may be called multiple times on the same socket to change its association, but only the most recent one will be effective.

§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)
  • address-in-use: Tried to perform an implicit bind, but there were no ephemeral ports available. (EADDRINUSE, EADDRNOTAVAIL on Linux, EAGAIN on BSD)
§Implementors note

If the socket is already connected, some platforms (e.g. Linux) require a disconnect before connecting to a different peer address.

§References
Source§

fn disconnect(&mut self, self_: Resource<UdpSocket>) -> Result<(), SocketError>

Dissociate this socket from its peer address.

After calling this method, send & receive are free to communicate with any address again.

The POSIX equivalent of this is calling connect with an AF_UNSPEC address.

§Typical errors
  • invalid-state: The socket is not connected.
§References
Source§

fn get_local_address( &mut self, self_: Resource<UdpSocket>, ) -> Result<IpSocketAddress, SocketError>

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 get-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
Source§

fn get_remote_address( &mut self, self_: Resource<UdpSocket>, ) -> Result<IpSocketAddress, SocketError>

Get the address the socket is currently “connected” to.

§Typical errors
  • invalid-state: The socket is not “connected” to a specific remote address. (ENOTCONN)
§References
Source§

fn get_address_family( &mut self, self_: Resource<UdpSocket>, ) -> Result<IpAddressFamily>

Whether this is a IPv4 or IPv6 socket.

This is the value passed to the constructor.

Equivalent to the SO_DOMAIN socket option.

Source§

fn get_unicast_hop_limit( &mut self, self_: Resource<UdpSocket>, ) -> Result<u8, SocketError>

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.
Source§

fn get_receive_buffer_size( &mut self, self_: Resource<UdpSocket>, ) -> Result<u64, SocketError>

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.
Source§

fn set_unicast_hop_limit( &mut self, self_: Resource<UdpSocket>, value: u8, ) -> Result<(), SocketError>

Source§

fn set_receive_buffer_size( &mut self, self_: Resource<UdpSocket>, value: u64, ) -> Result<(), SocketError>

Source§

fn get_send_buffer_size( &mut self, self_: Resource<UdpSocket>, ) -> Result<u64, SocketError>

Source§

fn set_send_buffer_size( &mut self, self_: Resource<UdpSocket>, value: u64, ) -> Result<(), SocketError>

Source§

fn drop(&mut self, rep: Resource<UdpSocket>) -> Result<()>

Implementors§