Struct RawSocket 

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

A raw socket borrowed from a Stack, returned by Stack::raw_socket.

Implementations

impl RawSocket<'_, '_>

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

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

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 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 close(&mut self)

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

pub fn is_open(&self) -> bool

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

pub fn register_recv_waker(&mut self, waker: &Waker)

Register a waker for receive operations.

The waker is woken on state changes that might affect the return value of recv calls, such as receiving a packet, or the socket closing.

Notes:

• Only one waker can be registered at a time. If another waker was previously registered, it is overwritten and will no longer be woken.
• The Waker is woken only once. Once woken, you must register it again before incoming data may wake it again.
• “Spurious wakes” are allowed: a wake doesn’t guarantee the result of recv has changed.

pub fn register_send_waker(&mut self, waker: &Waker)

Register a waker for send operations.

The waker is woken on state changes that might affect the return value of send calls, such as:

• the socket is bound or closed.
• A send failed with SendError::DeviceBusy and the driver becomes no longer busy.

It is not woken when a packet buffer is freed after SendError::NoBuffer. Retry that on your own.

Notes:

• Only one waker can be registered at a time. If another waker was previously registered, it is overwritten and will no longer be woken.
• The Waker is woken only once. Once woken, you must register it again before it may be woken again.
• “Spurious wakes” are allowed: a wake doesn’t guarantee the result of send has changed.

pub fn can_recv(&self) -> bool

Check whether the RX queue is not empty.

pub fn recv(&mut 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.

Errors

• InvalidState: if the socket is not bound.
• Exhausted: if the RX queue is empty.

pub fn recv_slice(&mut self, data: &mut [u8]) -> Result<usize, RecvError>

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

See also recv.

Errors

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

pub fn peek(&self) -> Result<&[u8], RecvError>

Peek at the next received packet without dequeueing it, as a borrow into the queue.

Errors

• InvalidState: if the socket is not bound.
• Exhausted: if the RX queue is empty.

pub fn peek_slice(&self, data: &mut [u8]) -> Result<usize, RecvError>

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

See also peek.

Errors

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

pub fn send_slice(&mut self, data: &[u8]) -> Result<(), SendError>

Send a packet, copying it from a slice.

See send_with.

pub fn send_slice_with_meta( &mut self, data: &[u8], meta: PacketMeta, ) -> Result<(), SendError>

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

See send_with_meta.

pub fn send_with( &mut self, max_size: usize, f: impl FnOnce(&mut [u8]) -> usize, ) -> Result<(), 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. The packet is then sent immediately.

The packet must be complete, headers included:

• In Ethernet mode, a whole Ethernet frame (including header, not including FCS). It is transmitted as-is, on the bound interface if the socket is bound to one, else on the first Ethernet interface.
• In IP mode, a whole IP packet, with checksum calculated. 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).

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.
• NoBuffer: if every packet buffer is in use.
• DeviceBusy: if the interface the packet would go out of has no room for it right now.

Panics

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

pub fn send_with_meta( &mut self, max_size: usize, meta: PacketMeta, f: impl FnOnce(&mut [u8]) -> usize, ) -> Result<(), SendError>

Send a packet with the given PacketMeta attached, building it in place.

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

pub fn alloc(&self) -> Option<PacketBuf>

Allocate an empty packet buffer with headroom for this socket.

Allocation works before binding. Returns None if every packet buffer is in use. Set the payload length with PacketBuf::set_len before writing.

pub fn send_headroom(&self) -> usize

Headroom to reserve in a buffer for send_packet, so that the packet isn’t moved.

• In Ethernet mode, what the driver of the interface the socket sends on needs.
• In IP mode, what any interface needs in front of an IP packet. It grows if an interface that needs more is added.

Zero if the socket isn’t bound, or has no interface to send on.

Panics

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

pub fn send_packet( &mut self, buf: PacketBuf, ) -> Result<(), (SendError, PacketBuf)>

Send an owned packet, preserving its packet metadata.

The buffer contains a complete Ethernet frame or IP packet, as in send_with. Reserve send_headroom to avoid moving it.

Errors return the buffer unchanged. Errors match send_with, except this method allocates no payload buffer and never returns SendError::NoBuffer. Success transfers ownership to the stack; it does not guarantee delivery.