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.

Returns Err(BindError::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.

Returns Err(BindError::InvalidState) if the socket is already bound (see is_open), and Err(BindError::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 being bound or closed.

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.

Returns Err(RecvError::InvalidState) if the socket is not bound, and Err(RecvError::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.

Note: when the size of the provided buffer is smaller than the size of the packet, the packet is dropped and Err(RecvError::Truncated) is returned.

See also recv.

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

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

Returns Err(RecvError::InvalidState) if the socket is not bound, and Err(RecvError::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.

Note: when the size of the provided buffer is smaller than the size of the packet, no data is copied and Err(RecvError::Truncated) is returned. The packet stays in the queue.

See also peek.

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

Returns Err(SendError::InvalidState) if the socket is not bound. Returns Err(SendError::Unaddressable) if there is no route to the packet’s destination (IP mode) or no Ethernet interface to send on (Ethernet mode). Returns Err(SendError::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. Returns Err(SendError::BufferFull) if the packet cannot fit in a packet buffer. Returns Err(SendError::NoBuffer) if every packet buffer is in use.

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.