Trait ParsablePacket

pub trait ParsablePacket<B: SplitByteSlice, ParseArgs>: Sized {
    type Error;

    // Required methods
    fn parse<BV: BufferView<B>>(
        buffer: BV,
        args: ParseArgs,
    ) -> Result<Self, Self::Error>;
    fn parse_metadata(&self) -> ParseMetadata;

    // Provided method
    fn parse_mut<BV: BufferViewMut<B>>(
        buffer: BV,
        args: ParseArgs,
    ) -> Result<Self, Self::Error>
       where B: SplitByteSliceMut { ... }
}

A packet which can be parsed from a buffer.

A ParsablePacket is a packet which can be parsed from the body of a buffer. For performance reasons, it is recommended that as much of the packet object as possible be stored as references into the body in order to avoid copying.

Required Associated Types

type Error

The type of errors returned from parse and parse_mut.

Required Methods

fn parse<BV: BufferView<B>>( buffer: BV, args: ParseArgs, ) -> Result<Self, Self::Error>

Parses a packet from a buffer.

Given a view into a buffer, parse parses a packet by consuming bytes from the buffer’s body. This works slightly differently for normal packets and inner packets (those which do not contain other packets).

Packets

When parsing a packet which contains another packet, the outer packet’s header and footer should be consumed from the beginning and end of the buffer’s body respectively. The packet’s body should be constructed from a reference to the buffer’s body (i.e., BufferView::into_rest), but the buffer’s body should not be consumed. This allows the next encapsulated packet to be parsed from the remaining buffer body. See the crate documentation for more details.

Inner Packets

When parsing packets which do not contain other packets, the entire packet’s contents should be consumed from the beginning of the buffer’s body. The buffer’s body should be empty after parse has returned.

Padding

There may be post-packet padding (coming after the entire packet, including any footer) which was added in order to satisfy the minimum body length requirement of an encapsulating packet. If the packet currently being parsed describes its own length (and thus, it’s possible to determine whether there’s any padding), parse is required to consume any post-packet padding from the buffer’s suffix. If this invariant is not upheld, future calls to ParseBuffer::parse or GrowBuffer::undo_parse may behave incorrectly.

Pre-packet padding is not supported; if a protocol supports such padding, it must be handled in a way that is transparent to this API. In particular, that means that the parse_metadata method must treat that padding as part of the packet.

fn parse_metadata(&self) -> ParseMetadata

Gets metadata about this packet required by GrowBuffer::undo_parse.

The returned ParseMetadata records the number of header and footer bytes consumed by this packet during parsing, and the number of bytes left in the body (not consumed from the buffer). For packets which encapsulate other packets, the header length must be equal to the number of bytes consumed from the prefix, and the footer length must be equal to the number of bytes consumed from the suffix. For inner packets, use ParseMetadata::from_inner_packet.

There is one exception: if any post-packet padding was consumed from the suffix, this should not be included, as it is not considered part of the packet. For example, consider a packet with 8 bytes of footer followed by 8 bytes of post-packet padding. Parsing this packet would consume 16 bytes from the suffix, but calling parse_metadata on the resulting object would return a ParseMetadata with only 8 bytes of footer.

Provided Methods

fn parse_mut<BV: BufferViewMut<B>>( buffer: BV, args: ParseArgs, ) -> Result<Self, Self::Error>

where B: SplitByteSliceMut,

Parses a packet from a mutable buffer.

parse_mut is like parse, except that it operates on a mutable buffer view.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors