Struct RawSocket 

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

An Raw socket.

Implementations

impl<'d> RawSocket<'d>

pub fn new( stack: Stack<'d>, ip_version: Option<IpVersion>, ip_protocol: Option<IpProtocol>, ) -> Result<Self, Full>

Create a new raw socket using the provided stack, receiving IP packets of the given version and protocol (None for any).

Errors

• Full: if the stack has no room for another raw socket. Only possible without the alloc feature, where the limit is RAW_SOCKET_COUNT, set by the raw-socket-count-N feature of xarxa.

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

Create a new raw socket using the provided stack, without binding it.

Errors

• Full: if the stack has no room for another raw socket. Only possible without the alloc feature, where the limit is RAW_SOCKET_COUNT, set by the raw-socket-count-N feature of xarxa.

pub fn bind(&mut self, mode: RawMode) -> Result<(), BindError>

Bind the socket to the given mode.

Errors

• InvalidState: if the socket is already bound (see is_open).
• InvalidMedium: if an Ethernet-mode bind is made on a socket bound (with bind_to_iface, feature iface-bind) to an interface whose medium is not Medium::Ethernet.

Panics

Panics if the socket is bound to a stale interface handle.

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 iface, or have a route through it.
• Broadcast and multicast destinations go out on that iface only

In Ethernet mode the bound interface’s medium must be Medium::Ethernet, checked at bind.

The socket must be unbound (no mode set). The binding is kept across close.

Errors

• InvalidState: if the socket is bound.

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 packet can be read.

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

Dequeue a received packet, copying it into the given slice, and return the number of octets copied.

This method will wait until a packet is received.

Errors

• InvalidState: if the socket is not bound.
• Truncated: if buf is smaller than the packet. The packet is dropped.

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

Dequeue a received packet, copying it into the given slice, and return the number of octets copied.

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

Errors

• WouldBlock: if the RX queue is empty.
• InvalidState: if the socket is not bound.
• Truncated: if buf is smaller than the packet. The packet is dropped.

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

Dequeue a received packet, copying it into the given slice, and return the number of octets copied.

Errors

• InvalidState: if the socket is not bound.
• Truncated: if buf is smaller than the packet. The packet is dropped.

pub async fn recv_packet(&self) -> Result<PacketBuf, RecvError>

Dequeue a received packet.

The buffer holds the whole Ethernet frame (Ethernet mode) or IP packet (IP mode), headers included, exactly as received. This is zero-copy: the returned value is the buffer the packet arrived in, and dropping it frees it.

This method will wait until a packet is received.

Errors

• InvalidState: if the socket is not bound.

pub async fn recv_with<R>( &mut self, f: impl FnOnce(&[u8], PacketMeta) -> R, ) -> Result<R, RecvError>

Receive a packet with a zero-copy function.

This method will wait until a packet is received.

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

Peek at the next received packet without dequeueing it, copying it into the given slice.

This method will wait until a packet is received.

Errors

• InvalidState: if the socket is not bound.
• Truncated: if buf is smaller than the packet. No data is copied and the packet stays in the queue.

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

Peek at the next received packet without dequeueing it, copying it into the given slice.

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

Errors

• WouldBlock: if no packet is available.
• Other(InvalidState): if the socket is not bound.
• Other(Truncated): if buf is smaller than the packet. No data is copied and the packet stays in the queue.

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

Peek at the next received packet without dequeueing it, copying it into the given slice.

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

Errors

• InvalidState: if the socket is not bound.
• Truncated: if buf is smaller than the packet. No data is copied and the packet stays in the queue.

pub async fn peek_with<R>( &self, f: impl FnOnce(&[u8]) -> R, ) -> Result<R, RecvError>

Peek at the next received packet without dequeueing it, calling f with it.

This method will wait until a packet is received.

Errors

• InvalidState: if the socket is not bound.

pub fn try_peek_with<R>( &self, f: impl FnOnce(&[u8]) -> R, ) -> Result<R, TryError<RecvError>>

Peek at the next received packet without dequeueing it, calling f with it.

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

Errors

• WouldBlock: if no packet is available.
• Other(InvalidState): if the socket is not bound.

pub fn can_recv(&self) -> bool

Check whether the RX queue is not empty.

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

Wait until the socket becomes writable.

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

Wait until a packet can be sent.

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

Send a packet, copying it from a slice.

This method will wait until the packet has been sent.

See send_with.

pub async fn send_with_meta( &self, buf: &[u8], meta: PacketMeta, ) -> Result<(), SendError>

Send a packet with the given PacketMeta attached, copying it from a slice.

The metadata is handed to the driver along with the frame. This is how a packet is tagged with an id, or a transmit timestamp is requested for it (see Stack::poll_tx_timestamp). Everything else is exactly send.

This method will wait until the packet has been sent.

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

Send a packet, copying it from a slice.

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

See send_with.

Errors

• WouldBlock: if every packet buffer is in use, or the interface the packet would go out of has no room for it right now.

pub fn poll_send_with_meta( &self, buf: &[u8], meta: PacketMeta, cx: &mut Context<'_>, ) -> Poll<Result<(), SendError>>

Send a packet with the given PacketMeta attached, copying it from a slice.

See send_with_meta.

pub async fn send_with<R>( &mut self, max_size: usize, f: impl FnOnce(&mut [u8]) -> (usize, R), ) -> Result<R, SendError>

Send a packet, building it in place.

The closure gets a max_size-byte slice inside a freshly allocated packet buffer, and returns how many bytes it wrote, along with a value that is returned from this method. The packet is then sent immediately.

This method will wait until a packet buffer is available before passing it to the closure.

The packet must be complete, headers included: a whole Ethernet frame (at most 1514 octets) in Ethernet mode, a whole IP packet (at most 1500 octets, or the full 1514 in a build without medium-ethernet, which reserves no link-layer headroom) in IP mode. It is emitted exactly as written, so the user is responsible for every header field, including the IPv4 header checksum.

In Ethernet mode the frame is transmitted as-is, on the bound interface if the socket is bound to one, else on the first Ethernet interface. In IP mode the destination address is read from the IP header, and the packet is routed like any other egress packet (through the bound interface only, if the socket is bound to one). If the destination’s neighbor is unresolved, the packet is queued inside the stack and sent when resolution completes. This still counts as a successful send.

Errors

• InvalidState: if the socket is not bound.
• Unaddressable: if there is no route to the packet’s destination or the destination is the unspecified address (IP mode), or no Ethernet interface to send on (Ethernet mode).
• Malformed: if the packet fails basic validation (too short for an Ethernet header in Ethernet mode, malformed IP header in IP mode), or does not match the socket’s bind filters.
• BufferFull: if the packet cannot fit in a packet buffer.

Panics

Panics if the socket is bound to an interface that has been removed.

pub fn is_open(&self) -> bool

Check whether the socket is open (bound to a mode).

pub fn mode(&self) -> Option<RawMode>

Return the mode the socket is bound to, or None if it is unbound.

pub fn close(&mut self)

Close the socket, unbinding it and dropping any queued packets.

Trait Implementations

impl Drop for RawSocket<'_>

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.