Module smoltcp::wire
[−]
[src]
Low-level packet access and construction.
The wire
module deals with the packet representation. It provides two levels
of functionality.
- First, it provides functions to extract fields from sequences of octets,
and to insert fields into sequences of octets. This happens
Packet
family of structures, e.g. EthernetFrame or Ipv4Packet. Second, in cases where the space of valid field values is much smaller than the space of possible field values, it provides a compact, high-level representation of packet data that can be parsed from and emitted into a sequence of octets. This happens through the
Repr
family of structs and enums, e.g. ArpRepr or Ipv4Repr.
The functions in the wire
module are designed for use together with -Cpanic=abort
.
The Packet
family of data structures guarantees that, if the Packet::check_len()
method
returned Ok(())
, then no accessor or setter method will panic; however, the guarantee
provided by Packet::check_len()
may no longer hold after changing certain fields,
which are listed in the documentation for the specific packet.
The Packet::new_checked
method is a shorthand for a combination of Packet::new
and
Packet::check_len
.
When parsing untrusted input, it is necessary to use Packet::new_checked()
;
so long as the buffer is not modified, no accessor will fail.
When emitting output, though, it is incorrect to use Packet::new_checked()
;
the length check is likely to succeed on a zeroed buffer, but fail on a buffer
filled with data from a previous packet, such as when reusing buffers, resulting
in nondeterministic panics with some network devices but not others.
The buffer length for emission is not calculated by the Packet
layer.
In the Repr
family of data structures, the Repr::parse()
method never panics
as long as Packet::new_checked()
(or Packet::check_len()
) has succeeded, and
the Repr::emit()
method never panics as long as the underlying buffer is exactly
Repr::buffer_len()
octets long.
Examples
To emit an IP packet header into an octet buffer, and then parse it back:
use smoltcp::wire::*; let repr = Ipv4Repr { src_addr: Ipv4Address::new(10, 0, 0, 1), dst_addr: Ipv4Address::new(10, 0, 0, 2), protocol: IpProtocol::Tcp, payload_len: 10 }; let mut buffer = vec![0; repr.buffer_len() + repr.payload_len]; { // emission let mut packet = Ipv4Packet::new(&mut buffer); repr.emit(&mut packet); } { // parsing let packet = Ipv4Packet::new_checked(&buffer) .expect("truncated packet"); let parsed = Ipv4Repr::parse(&packet) .expect("malformed packet"); assert_eq!(repr, parsed); }
Reexports
pub use self::pretty_print::PrettyPrinter; |
Modules
pretty_print |
Pretty-printing of packet representation. |
Structs
ArpPacket |
A read/write wrapper around an Address Resolution Protocol packet buffer. |
EthernetAddress |
A six-octet Ethernet II address. |
EthernetFrame |
A read/write wrapper around an Ethernet II frame buffer. |
Icmpv4Packet |
A read/write wrapper around an Internet Control Message Protocol version 4 packet buffer. |
IpEndpoint |
An internet endpoint address. |
Ipv4Address |
A four-octet IPv4 address. |
Ipv4Packet |
A read/write wrapper around an Internet Protocol version 4 packet buffer. |
Ipv4Repr |
A high-level representation of an Internet Protocol version 4 packet header. |
TcpPacket |
A read/write wrapper around a Transmission Control Protocol packet buffer. |
TcpRepr |
A high-level representation of a Transmission Control Protocol packet. |
TcpSeqNumber |
A TCP sequence number. |
UdpPacket |
A read/write wrapper around an User Datagram Protocol packet buffer. |
UdpRepr |
A high-level representation of an User Datagram Protocol packet. |
Enums
ArpHardware |
ARP hardware type. |
ArpOperation |
ARP operation type. |
ArpRepr |
A high-level representation of an Address Resolution Protocol packet. |
EthernetProtocol |
Ethernet protocol type. |
Icmpv4DstUnreachable |
Internet protocol control message subtype for type "Destination Unreachable". |
Icmpv4Message |
Internet protocol control message type. |
Icmpv4ParamProblem |
Internet protocol control message subtype for type "Parameter Problem". |
Icmpv4Redirect |
Internet protocol control message subtype for type "Redirect Message". |
Icmpv4Repr |
A high-level representation of an Internet Control Message Protocol version 4 packet header. |
Icmpv4TimeExceeded |
Internet protocol control message subtype for type "Time Exceeded". |
IpAddress |
An internetworking address. |
IpProtocol |
IP datagram encapsulated protocol. |
IpRepr |
An IP packet representation. |
IpVersion |
Internet protocol version. |
TcpControl |
The possible control flags of a Transmission Control Protocol packet. |
TcpOption |
A representation of a single TCP option. |