Trait wasmtime_wasi::bindings::sockets::udp::HostUdpSocket
source · pub trait HostUdpSocket {
Show 14 methods
// Required methods
fn start_bind<'life0, 'async_trait>(
&'life0 mut self,
self_: Resource<UdpSocket>,
network: Resource<Network>,
local_address: IpSocketAddress,
) -> Pin<Box<dyn Future<Output = Result<(), SocketError>> + Send + 'async_trait>>
where Self: 'async_trait,
'life0: 'async_trait;
fn finish_bind(
&mut self,
self_: Resource<UdpSocket>,
) -> Result<(), SocketError>;
fn stream<'life0, 'async_trait>(
&'life0 mut self,
self_: Resource<UdpSocket>,
remote_address: Option<IpSocketAddress>,
) -> Pin<Box<dyn Future<Output = Result<(Resource<IncomingDatagramStream>, Resource<OutgoingDatagramStream>), SocketError>> + Send + 'async_trait>>
where Self: 'async_trait,
'life0: 'async_trait;
fn local_address(
&mut self,
self_: Resource<UdpSocket>,
) -> Result<IpSocketAddress, SocketError>;
fn remote_address(
&mut self,
self_: Resource<UdpSocket>,
) -> Result<IpSocketAddress, SocketError>;
fn address_family(
&mut self,
self_: Resource<UdpSocket>,
) -> Result<IpAddressFamily>;
fn 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 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 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 subscribe(
&mut self,
self_: Resource<UdpSocket>,
) -> Result<Resource<Pollable>>;
fn drop(&mut self, rep: Resource<UdpSocket>) -> Result<()>;
}
Required Methods§
sourcefn start_bind<'life0, 'async_trait>(
&'life0 mut self,
self_: Resource<UdpSocket>,
network: Resource<Network>,
local_address: IpSocketAddress,
) -> Pin<Box<dyn Future<Output = Result<(), SocketError>> + Send + 'async_trait>>where
Self: 'async_trait,
'life0: 'async_trait,
fn start_bind<'life0, 'async_trait>(
&'life0 mut self,
self_: Resource<UdpSocket>,
network: Resource<Network>,
local_address: IpSocketAddress,
) -> Pin<Box<dyn Future<Output = Result<(), SocketError>> + Send + 'async_trait>>where
Self: 'async_trait,
'life0: 'async_trait,
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
: Thelocal-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 thenetwork
can bind to. (EADDRNOTAVAIL)not-in-progress
: Abind
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
fn finish_bind(&mut self, self_: Resource<UdpSocket>) -> Result<(), SocketError>
sourcefn stream<'life0, 'async_trait>(
&'life0 mut self,
self_: Resource<UdpSocket>,
remote_address: Option<IpSocketAddress>,
) -> Pin<Box<dyn Future<Output = Result<(Resource<IncomingDatagramStream>, Resource<OutgoingDatagramStream>), SocketError>> + Send + 'async_trait>>where
Self: 'async_trait,
'life0: 'async_trait,
fn stream<'life0, 'async_trait>(
&'life0 mut self,
self_: Resource<UdpSocket>,
remote_address: Option<IpSocketAddress>,
) -> Pin<Box<dyn Future<Output = Result<(Resource<IncomingDatagramStream>, Resource<OutgoingDatagramStream>), SocketError>> + Send + 'async_trait>>where
Self: 'async_trait,
'life0: 'async_trait,
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 providedremote-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
: Theremote-address
has the wrong address family. (EAFNOSUPPORT)invalid-argument
: The IP address inremote-address
is set to INADDR_ANY (0.0.0.0
/::
). (EDESTADDRREQ, EADDRNOTAVAIL)invalid-argument
: The port inremote-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
sourcefn local_address(
&mut self,
self_: Resource<UdpSocket>,
) -> Result<IpSocketAddress, SocketError>
fn 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 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
sourcefn remote_address(
&mut self,
self_: Resource<UdpSocket>,
) -> Result<IpSocketAddress, SocketError>
fn remote_address( &mut self, self_: Resource<UdpSocket>, ) -> Result<IpSocketAddress, SocketError>
sourcefn address_family(
&mut self,
self_: Resource<UdpSocket>,
) -> Result<IpAddressFamily>
fn address_family( &mut self, self_: Resource<UdpSocket>, ) -> Result<IpAddressFamily>
Whether this is a IPv4 or IPv6 socket.
Equivalent to the SO_DOMAIN socket option.
sourcefn unicast_hop_limit(
&mut self,
self_: Resource<UdpSocket>,
) -> Result<u8, SocketError>
fn 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.
fn set_unicast_hop_limit( &mut self, self_: Resource<UdpSocket>, value: u8, ) -> Result<(), SocketError>
sourcefn receive_buffer_size(
&mut self,
self_: Resource<UdpSocket>,
) -> Result<u64, SocketError>
fn 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.
fn set_receive_buffer_size( &mut self, self_: Resource<UdpSocket>, value: u64, ) -> Result<(), SocketError>
fn 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>
sourcefn subscribe(
&mut self,
self_: Resource<UdpSocket>,
) -> Result<Resource<Pollable>>
fn subscribe( &mut self, self_: Resource<UdpSocket>, ) -> Result<Resource<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.
fn drop(&mut self, rep: Resource<UdpSocket>) -> Result<()>
Implementations on Foreign Types§
source§impl<_T: HostUdpSocket + ?Sized + Send> HostUdpSocket for &mut _T
impl<_T: HostUdpSocket + ?Sized + Send> HostUdpSocket for &mut _T
source§fn start_bind<'life0, 'async_trait>(
&'life0 mut self,
self_: Resource<UdpSocket>,
network: Resource<Network>,
local_address: IpSocketAddress,
) -> Pin<Box<dyn Future<Output = Result<(), SocketError>> + Send + 'async_trait>>where
Self: 'async_trait,
'life0: 'async_trait,
fn start_bind<'life0, 'async_trait>(
&'life0 mut self,
self_: Resource<UdpSocket>,
network: Resource<Network>,
local_address: IpSocketAddress,
) -> Pin<Box<dyn Future<Output = Result<(), SocketError>> + Send + 'async_trait>>where
Self: 'async_trait,
'life0: 'async_trait,
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
: Thelocal-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 thenetwork
can bind to. (EADDRNOTAVAIL)not-in-progress
: Abind
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
source§fn stream<'life0, 'async_trait>(
&'life0 mut self,
self_: Resource<UdpSocket>,
remote_address: Option<IpSocketAddress>,
) -> Pin<Box<dyn Future<Output = Result<(Resource<IncomingDatagramStream>, Resource<OutgoingDatagramStream>), SocketError>> + Send + 'async_trait>>where
Self: 'async_trait,
'life0: 'async_trait,
fn stream<'life0, 'async_trait>(
&'life0 mut self,
self_: Resource<UdpSocket>,
remote_address: Option<IpSocketAddress>,
) -> Pin<Box<dyn Future<Output = Result<(Resource<IncomingDatagramStream>, Resource<OutgoingDatagramStream>), SocketError>> + Send + 'async_trait>>where
Self: 'async_trait,
'life0: 'async_trait,
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 providedremote-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
: Theremote-address
has the wrong address family. (EAFNOSUPPORT)invalid-argument
: The IP address inremote-address
is set to INADDR_ANY (0.0.0.0
/::
). (EDESTADDRREQ, EADDRNOTAVAIL)invalid-argument
: The port inremote-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
source§fn local_address(
&mut self,
self_: Resource<UdpSocket>,
) -> Result<IpSocketAddress, SocketError>
fn 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 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 remote_address(
&mut self,
self_: Resource<UdpSocket>,
) -> Result<IpSocketAddress, SocketError>
fn remote_address( &mut self, self_: Resource<UdpSocket>, ) -> Result<IpSocketAddress, SocketError>
source§fn address_family(
&mut self,
self_: Resource<UdpSocket>,
) -> Result<IpAddressFamily>
fn address_family( &mut self, self_: Resource<UdpSocket>, ) -> Result<IpAddressFamily>
Whether this is a IPv4 or IPv6 socket.
Equivalent to the SO_DOMAIN socket option.
source§fn unicast_hop_limit(
&mut self,
self_: Resource<UdpSocket>,
) -> Result<u8, SocketError>
fn 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 receive_buffer_size(
&mut self,
self_: Resource<UdpSocket>,
) -> Result<u64, SocketError>
fn 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 subscribe(
&mut self,
self_: Resource<UdpSocket>,
) -> Result<Resource<Pollable>>
fn subscribe( &mut self, self_: Resource<UdpSocket>, ) -> Result<Resource<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.