[−][src]Trait capsule::packets::Packet

pub trait Packet {
    type Envelope: Packet;
    fn envelope(&self) -> &Self::Envelope;

    fn envelope_mut(&mut self) -> &mut Self::Envelope;

    fn offset(&self) -> usize;

    fn header_len(&self) -> usize;

    unsafe fn clone(&self, internal: Internal) -> Self;

    fn try_parse(envelope: Self::Envelope, internal: Internal) -> Fallible<Self>
    where
        Self: Sized;

    fn try_push(envelope: Self::Envelope, internal: Internal) -> Fallible<Self>
    where
        Self: Sized;

    fn deparse(self) -> Self::Envelope
    where
        Self: Sized;

    fn mbuf(&self) -> &Mbuf { ... }

    fn mbuf_mut(&mut self) -> &mut Mbuf { ... }

    fn payload_offset(&self) -> usize { ... }

    fn len(&self) -> usize { ... }

    fn payload_len(&self) -> usize { ... }

    fn parse<T: Packet<Envelope = Self>>(self) -> Fallible<T>
    where
        Self: Sized,
    { ... }

    fn peek<T: Packet<Envelope = Self>>(&self) -> Fallible<Immutable<T>>
    where
        Self: Sized,
    { ... }

    fn push<T: Packet<Envelope = Self>>(self) -> Fallible<T>
    where
        Self: Sized,
    { ... }

    fn remove(self) -> Fallible<Self::Envelope>
    where
        Self: Sized,
    { ... }

    fn remove_payload(&mut self) -> Fallible<()> { ... }

    fn reset(self) -> Mbuf
    where
        Self: Sized,
    { ... }

    fn reconcile(&mut self) { ... }

    fn reconcile_all(&mut self) { ... }
}

A trait all network protocols must implement.

This is the main trait for interacting with the message buffer as statically-typed packets.

Example

let packet = Mbuf::new()?;
let ethernet = packet.push::<Ethernet>()?;
let ipv4 = ethernet.push::<Ipv4>()?;

let mut tcp = ipv4.push::<Tcp<Ipv4>>()?;
tcp.set_dst_ip(remote_ip);
tcp.set_dst_port(22);
tcp.reconcile_all();

Associated Types

type Envelope: Packet

The preceding packet type that encapsulates this packet.

The envelope behaves as a constraint to enforce strict ordering between packet types. For example, an IPv4 packet must be encapsulated by an Ethernet packet.

Loading content...

Required methods

fn envelope(&self) -> &Self::Envelope

Returns a reference to the envelope.

fn envelope_mut(&mut self) -> &mut Self::Envelope

Returns a mutable reference to the envelope.

fn offset(&self) -> usize

Returns the buffer offset where the current packet begins.

fn header_len(&self) -> usize

Returns the length of the packet header.

unsafe fn clone(&self, internal: Internal) -> Self

Returns a copy of the packet.

Remarks

This function cannot be invoked directly. It is internally used by peek.

Safety

The underlying byte buffer is not cloned. The original and the clone will share the same buffer. Both copies are independently mutable. Changes made through one copy could completely invalidate the other.

peek addresses this safety issue by wrapping the clone in an Immutable and making the clone behave as an immutable borrow of the original.

fn try_parse(envelope: Self::Envelope, internal: Internal) -> Fallible<Self> where
    Self: Sized, 

Parses the envelope's payload as this packet type.

The implementation should perform the necessary buffer boundary checks and validate the invariants if any. For example, before parsing the Ethernet's payload as an IPv4 packet, there should be a check to assert that ether_type matches the expectation.

Remarks

This function cannot be invoked directly. It is internally used by parse.

fn try_push(envelope: Self::Envelope, internal: Internal) -> Fallible<Self> where
    Self: Sized, 

Prepends a new packet to the beginning of the envelope's payload.

When the packet is inserted into an envelope with an existing payload, the original payload becomes the payload of the new packet. The implementation should validate the invariants accordingly if there's an existing payload.

Remarks

This function cannot be invoked directly. It is internally used by push.

fn deparse(self) -> Self::Envelope where
    Self: Sized, 

Deparses the packet back to the envelope's packet type.

Loading content...

Provided methods

fn mbuf(&self) -> &Mbuf

Returns a reference to the raw message buffer.

Directly reading from the buffer is error-prone and discouraged except when implementing a new protocol.

fn mbuf_mut(&mut self) -> &mut Mbuf

Returns a mutable reference to the raw message buffer.

Directly writing to the buffer is error-prone and discouraged except when implementing a new protocol.

fn payload_offset(&self) -> usize

Returns the buffer offset where the packet payload begins.

fn len(&self) -> usize

Returns the length of the packet with the payload.

fn payload_len(&self) -> usize

Returns the length of the packet payload.

fn parse<T: Packet<Envelope = Self>>(self) -> Fallible<T> where
    Self: Sized, 

Parses the packet's payload as a packet of type T.

The ownership of the packet is moved after invocation. To retain ownership, use peek instead.

fn peek<T: Packet<Envelope = Self>>(&self) -> Fallible<Immutable<T>> where
    Self: Sized, 

Peeks into the packet's payload as a packet of type T.

peek returns an immutable reference to the payload. The caller retains full ownership of the packet.

fn push<T: Packet<Envelope = Self>>(self) -> Fallible<T> where
    Self: Sized, 

Prepends a new packet of type T to the beginning of the envelope's payload.

fn remove(self) -> Fallible<Self::Envelope> where
    Self: Sized, 

Removes this packet's header from the message buffer.

After the removal, the packet's payload becomes the payload of its envelope. The result of the removal is not guaranteed to be a valid packet. The protocol should provide a custom implementation if additional fixes are necessary.

fn remove_payload(&mut self) -> Fallible<()>

Removes the packet's payload from the message buffer.

fn reset(self) -> Mbuf where
    Self: Sized, 

Resets the parsed packet back to Mbuf.

fn reconcile(&mut self)

Reconciles the derivable header fields against the changes made to the packet.

Protocols that have derivable header fields, like a checksum, should implement this to recompute those fields after changes were made to the packet.

fn reconcile_all(&mut self)

Reconciles against the changes recursively through all layers.

A change made to a packet can have cascading effects through the envelope chain. The call will recursively reconcile those changes starting at the current packet type. The recursion does not include the payload if the payload contains other packet types.

Loading content...

Implementors

impl Packet for capsule::packets::icmp::v4::EchoReply[src]

type Envelope = Ipv4

impl Packet for capsule::packets::icmp::v4::EchoRequest[src]

type Envelope = Ipv4

impl Packet for Icmpv4[src]

type Envelope = Ipv4

The preceding type for ICMPv4 packet must be IPv4.

fn try_parse(envelope: Self::Envelope, _internal: Internal) -> Fallible<Self>[src]

Parses the envelope's payload as an ICMPv4 packet.

Ipv4::protocol must be set to ProtocolNumbers::Icmpv4. Otherwise, a parsing error is returned.

fn try_push(_envelope: Self::Envelope, _internal: Internal) -> Fallible<Self>[src]

Cannot push a generic ICMPv4 header without a message body. This will always return NoIcmpv4MessageBody. Instead, push a specific message type like EchoRequest, which includes the header and the message body.

fn reconcile(&mut self)[src]

Reconciles the derivable header fields against the changes made to the packet.

  • checksum is computed based on the header and the message body.

impl Packet for Ipv4[src]

type Envelope = Ethernet

The preceding type for an IPv4 packet must be Ethernet.

fn try_parse(envelope: Self::Envelope, _internal: Internal) -> Fallible<Self>[src]

Parses the Ethernet's payload as an IPv4 packet.

ether_type must be set to EtherTypes::Ipv4. Otherwise a parsing error is returned.

fn try_push(envelope: Self::Envelope, _internal: Internal) -> Fallible<Self>[src]

Prepends an IPv4 packet to the beginning of the Ethernet's payload.

ether_type is set to EtherTypes::Ipv4.

fn reconcile(&mut self)[src]

Reconciles the derivable header fields against the changes made to the packet.

  • total_length is set to the total length of the header and the payload.
  • checksum is computed based on the IPv4 header.

impl Packet for Ipv6[src]

type Envelope = Ethernet

The preceding type for IPv6 packet must be Ethernet.

fn try_parse(envelope: Self::Envelope, _internal: Internal) -> Fallible<Self>[src]

Parses the Ethernet's payload as an IPv6 packet.

ether_type must be set to EtherTypes::Ipv6. Otherwise a parsing error is returned.

fn try_push(envelope: Self::Envelope, _internal: Internal) -> Fallible<Self>[src]

Prepends an IPv6 packet to the beginning of the Ethernet's payload.

ether_type is set to EtherTypes::Ipv6.

fn reconcile(&mut self)[src]

Reconciles the derivable header fields against the changes made to the packet.

  • payload_length is set to the length of the payload which includes any extension headers present.

impl Packet for Ethernet[src]

type Envelope = Mbuf

The preceding type for Ethernet must be Mbuf.

fn header_len(&self) -> usize[src]

Returns the length of the packet header.

The length of the Ethernet header depends on the VLAN tags.

impl Packet for Mbuf[src]

type Envelope = Mbuf

impl<E: IpPacket> Packet for Tcp<E>[src]

type Envelope = E

The preceding packet type for a TCP packet can be either an IPv4 packet, an IPv6 packet, or any IPv6 extension packets.

fn try_parse(envelope: Self::Envelope, _internal: Internal) -> Fallible<Self>[src]

Parses the envelope's payload as a TCP packet.

If the envelope is IPv4, then Ipv4::protocol must be set to ProtocolNumbers::Tcp. If the envelope is IPv6 or an extension header, then next_header must be set to ProtocolNumbers::Tcp. Otherwise, a parsing error is returned.

fn try_push(envelope: Self::Envelope, _internal: Internal) -> Fallible<Self>[src]

Prepends a TCP packet to the beginning of the envelope's payload.

If the envelope is IPv4, then Ipv4::protocol is set to ProtocolNumbers::Tcp. If the envelope is IPv6 or an extension header, then next_header is set to ProtocolNumbers::Tcp.

fn reconcile(&mut self)[src]

Reconciles the derivable header fields against the changes made to the packet.

impl<E: IpPacket> Packet for Udp<E>[src]

type Envelope = E

The preceding packet type for an UDP packet can be either an IPv4 packet, an IPv6 packet, or any IPv6 extension packets.

fn try_parse(envelope: Self::Envelope, _internal: Internal) -> Fallible<Self>[src]

Parses the envelope's payload as an UDP packet.

If the envelope is IPv4, then Ipv4::protocol must be set to ProtocolNumbers::Udp. If the envelope is IPv6 or an extension header, then next_header must be set to ProtocolNumbers::Udp. Otherwise, a parsing error is returned.

fn try_push(envelope: Self::Envelope, _internal: Internal) -> Fallible<Self>[src]

Prepends an UDP packet to the beginning of the envelope's payload.

If the envelope is IPv4, then Ipv4::protocol is set to ProtocolNumbers::Udp. If the envelope is IPv6 or an extension header, then next_header is set to ProtocolNumbers::Udp.

fn reconcile(&mut self)[src]

Reconciles the derivable header fields against the changes made to the packet.

  • length is set to the total length of the header and the payload.
  • checksum is computed based on the pseudo-header and the full packet.

impl<E: Ipv6Packet> Packet for NeighborAdvertisement<E>[src]

type Envelope = E

impl<E: Ipv6Packet> Packet for NeighborSolicitation<E>[src]

type Envelope = E

impl<E: Ipv6Packet> Packet for Redirect<E>[src]

type Envelope = E

impl<E: Ipv6Packet> Packet for RouterAdvertisement<E>[src]

type Envelope = E

impl<E: Ipv6Packet> Packet for RouterSolicitation<E>[src]

type Envelope = E

impl<E: Ipv6Packet> Packet for capsule::packets::icmp::v6::EchoReply<E>[src]

type Envelope = E

impl<E: Ipv6Packet> Packet for capsule::packets::icmp::v6::EchoRequest<E>[src]

type Envelope = E

impl<E: Ipv6Packet> Packet for Icmpv6<E>[src]

type Envelope = E

The preceding type for an ICMPv6 packet must be either an IPv6 packet or any IPv6 extension packets.

fn try_parse(envelope: Self::Envelope, _internal: Internal) -> Fallible<Self>[src]

Parses the envelope's payload as an ICMPv6 packet.

next_header must be set to ProtocolNumbers::Icmpv6. Otherwise, a parsing error is returned.

fn try_push(_envelope: Self::Envelope, _internal: Internal) -> Fallible<Self>[src]

Cannot push a generic ICMPv6 header without a message body. This will always return NoIcmpv6MessageBody. Instead, push a specific message type like EchoRequest, which includes the header and the message body.

fn reconcile(&mut self)[src]

Reconciles the derivable header fields against the changes made to the packet.

impl<E: Ipv6Packet> Packet for PacketTooBig<E>[src]

type Envelope = E

impl<E: Ipv6Packet> Packet for TimeExceeded<E>[src]

type Envelope = E

impl<E: Ipv6Packet> Packet for Fragment<E>[src]

type Envelope = E

The preceding type for an IPv6 fragment packet can be either an IPv6 packet or any possible IPv6 extension packets.

fn try_parse(envelope: Self::Envelope, _internal: Internal) -> Fallible<Self>[src]

Parses the envelope's payload as an IPv6 fragment packet.

next_header of the envelope must be set to ProtocolNumbers::Ipv6Frag. Otherwise a parsing error is returned.

fn try_push(envelope: Self::Envelope, _internal: Internal) -> Fallible<Self>[src]

Prepends an IPv6 fragment packet to the beginning of the envelope's payload.

next_header is set to the value of the next_header field of the envelope, and the envelope is set to ProtocolNumbers::Ipv6Frag.

fn remove(self) -> Fallible<Self::Envelope>[src]

Removes IPv6 fragment packet from the message buffer.

The envelope's next_header field is set to the value of the next_header field on the fragment packet.

impl<E: Ipv6Packet> Packet for SegmentRouting<E>[src]

type Envelope = E

The preceding type for an IPv6 segment routing packet can be either an IPv6 packet or any possible IPv6 extension packets.

fn try_parse(envelope: Self::Envelope, _internal: Internal) -> Fallible<Self>[src]

Parses the envelope's payload as an IPv6 segment routing packet.

next_header of the envelope must be set to ProtocolNumbers::Ipv6Route. Otherwise a parsing error is returned.

fn try_push(envelope: Self::Envelope, _internal: Internal) -> Fallible<Self>[src]

Prepends an IPv6 segment routing packet with a segment list of one to the beginning of the envelope's payload.

next_header is set to the value of the next_header field of the envelope, and the envelope is set to ProtocolNumbers::Ipv6Route.

fn remove(self) -> Fallible<Self::Envelope>[src]

Removes IPv6 segment routing packet from the message buffer.

The envelope's next_header field is set to the value of the next_header field on the segment routing packet.

Loading content...