Trait packet::GrowBuffer

source ·

pub trait GrowBuffer: FragmentedBuffer {
    // Required methods
    fn with_parts<O, F>(&self, f: F) -> O
       where F: for<'a, 'b> FnOnce(&'a [u8], FragmentedBytes<'a, 'b>, &'a [u8]) -> O;
    fn grow_front(&mut self, n: usize);
    fn grow_back(&mut self, n: usize);

    // Provided methods
    fn capacity(&self) -> usize { ... }
    fn prefix_len(&self) -> usize { ... }
    fn suffix_len(&self) -> usize { ... }
    fn reset(&mut self) { ... }
    fn undo_parse(&mut self, meta: ParseMetadata) { ... }
}

Expand description

A buffer that can grow its body by taking space from its prefix and suffix.

A GrowBuffer is a byte buffer with a prefix, a body, and a suffix. The size of the buffer is referred to as its “capacity”, and the size of the body is referred to as its “length”. The body of the buffer can shrink or grow as allowed by the capacity as packets are parsed or serialized.

A GrowBuffer guarantees never to discard bytes from the prefix or suffix, which is an important requirement for serialization. [1] For parsing, this guarantee is not needed. The subset of methods which do not require this guarantee are defined in the ShrinkBuffer trait, which does not have this requirement.

While a GrowBuffer allows the ranges covered by its prefix, body, and suffix to be modified, it only provides immutable access to their contents. For mutable access, see GrowBufferMut.

If a type implements GrowBuffer, then its implementations of the methods on FragmentedBuffer provide access only to the buffer’s body. In particular, len returns the body’s length, with_bytes provides access to the body, and to_flattened_vec returns a copy of the body.

[1] If GrowBuffers could shrink their prefix or suffix, then it would not be possible to guarantee that a call to undo_parse wouldn’t panic. undo_parse is used when retaining previously-parsed packets for serialization, which is useful in scenarios such as packet forwarding.

Required Methods§

source

fn with_parts<O, F>(&self, f: F) -> O
where F: for<'a, 'b> FnOnce(&'a [u8], FragmentedBytes<'a, 'b>, &'a [u8]) -> O,

Gets a view into the parts of this GrowBuffer.

Calls f, passing the prefix, body, and suffix as arguments (in that order).

source

fn grow_front(&mut self, n: usize)

Grows the front of the body towards Growf the buffer.

grow_front consumes the right-most n bytes of the prefix, and adds them to the body.

§Panics

Panics if n is larger than the prefix.

source

fn grow_back(&mut self, n: usize)

Grows the back of the body towards the end of the buffer.

grow_back consumes the left-most n bytes of the suffix, and adds them to the body.

§Panics

Panics if n is larger than the suffix.

Provided Methods§

source

fn capacity(&self) -> usize

The capacity of the buffer.

b.capacity() is equivalent to b.prefix_len() + b.len() + b.suffix_len().

source

fn prefix_len(&self) -> usize

The length of the prefix.

source

fn suffix_len(&self) -> usize

The length of the suffix.

source

fn reset(&mut self)

Resets the body to be equal to the entire buffer.

reset consumes the entire prefix and suffix, adding them to the body.

source

fn undo_parse(&mut self, meta: ParseMetadata)

Undoes the effects of a previous parse in preparation for serialization.

undo_parse undoes the effects of having previously parsed a packet by consuming the appropriate number of bytes from the prefix and suffix. After a call to undo_parse, the buffer’s body will contain the bytes of the previously-parsed packet, including any headers or footers. This allows a previously-parsed packet to be used in serialization.

undo_parse takes a ParseMetadata, which can be obtained from ParsablePacket::parse_metadata.

undo_parse must always be called starting with the most recently parsed packet, followed by the second most recently parsed packet, and so on. Otherwise, it may panic, and in any case, almost certainly won’t produce the desired buffer contents.

§Padding

If, during parsing, a packet encountered post-packet padding that was discarded (see the documentation on ParsablePacket::parse), calling undo_parse on the ParseMetadata from that packet will not undo the effects of consuming and discarding that padding. The reason for this is that the padding is not considered part of the packet itself (the body it was parsed from can be thought of comprising the packet and post-packet padding back-to-back).

Calling undo_parse on the next encapsulating packet (the one whose body contained the padding) will undo those effects.