Trait packet::serialize::Serializer

source · 
pub trait Serializer: Sized {
    type Buffer;

    // Required method
    fn serialize<B: GrowBufferMut, P: BufferProvider<Self::Buffer, B>>(
        self,
        outer: PacketConstraints,
        provider: P
    ) -> Result<B, (SerializeError<P::Error>, Self)>;

    // Provided methods
    fn serialize_vec(
        self,
        outer: PacketConstraints
    ) -> Result<Either<Self::Buffer, Buf<Vec<u8>>>, (SerializeError<Never>, Self)>
       where Self::Buffer: ReusableBuffer { ... }
    fn serialize_no_alloc(
        self,
        outer: PacketConstraints
    ) -> Result<Self::Buffer, (SerializeError<BufferTooShortError>, Self)>
       where Self::Buffer: ReusableBuffer { ... }
    fn serialize_outer<B: GrowBufferMut, P: BufferProvider<Self::Buffer, B>>(
        self,
        provider: P
    ) -> Result<B, (SerializeError<P::Error>, Self)> { ... }
    fn serialize_vec_outer(
        self
    ) -> Result<Either<Self::Buffer, Buf<Vec<u8>>>, (SerializeError<Never>, Self)>
       where Self::Buffer: ReusableBuffer { ... }
    fn serialize_no_alloc_outer(
        self
    ) -> Result<Self::Buffer, (SerializeError<BufferTooShortError>, Self)>
       where Self::Buffer: ReusableBuffer { ... }
    fn encapsulate<B>(self, outer: B) -> Nested<Self, B> { ... }
    fn with_size_limit(
        self,
        limit: usize
    ) -> Nested<Self, LimitedSizePacketBuilder> { ... }
}

Required Associated Types§

source

type Buffer

The type of buffers returned from serialization methods on this trait.

Required Methods§

source

fn serialize<B: GrowBufferMut, P: BufferProvider<Self::Buffer, B>>( self, outer: PacketConstraints, provider: P ) -> Result<B, (SerializeError<P::Error>, Self)>

Serializes this Serializer, producing a buffer.

serialize accepts a PacketBuilder and a BufferProvider, and produces a buffer which contains the contents of this Serializer encapsulated in the header and footer described by the PacketBuilder.

As Serializers can be nested using the Nested type (constructed using the encapsulate method), the serialize method is recursive - calling it on a Nested will recurse into the inner Serializer, which might itself be a Nested, and so on. When the innermost Serializer is reached, the contained buffer is passed to the provider, allowing it to decide how to produce a buffer which is large enough to fit the entire packet - either by reusing the existing buffer, or by discarding it and allocating a new one.

Provided Methods§

source

fn serialize_vec( self, outer: PacketConstraints ) -> Result<Either<Self::Buffer, Buf<Vec<u8>>>, (SerializeError<Never>, Self)>
where Self::Buffer: ReusableBuffer,

Serializes this Serializer, allocating a Buf<Vec<u8>> if the contained buffer isn’t large enough.

serialize_vec is like serialize, except that, if the contained buffer isn’t large enough to contain the packet, a new Vec<u8> is allocated and wrapped in a Buf. If the buffer is large enough, but the body is too far forwards or backwards to fit the encapsulating headers or footers, the body will be moved within the buffer (this operation’s cost is linear in the size of the body).

serialize_vec is equivalent to calling serialize with new_buf_vec as the BufferProvider.

source

fn serialize_no_alloc( self, outer: PacketConstraints ) -> Result<Self::Buffer, (SerializeError<BufferTooShortError>, Self)>
where Self::Buffer: ReusableBuffer,

Serializes this Serializer, failing if the existing buffer is not large enough.

serialize_no_alloc is like serialize, except that it will fail if the existing buffer isn’t large enough. If the buffer is large enough, but the body is too far forwards or backwards to fit the encapsulating headers or footers, the body will be moved within the buffer (this operation’s cost is linear in the size of the body).

serialize_no_alloc is equivalent to calling serialize with a BufferProvider which cannot allocate a new buffer (such as ()).

source

fn serialize_outer<B: GrowBufferMut, P: BufferProvider<Self::Buffer, B>>( self, provider: P ) -> Result<B, (SerializeError<P::Error>, Self)>

Serializes this Serializer as the outermost packet.

serialize_outer is like serialize, except that it is called when this Serializer describes the outermost packet, not encapsulated in any other packets. It is equivalent to calling serialize with an empty PacketBuilder (such as ()).

source

fn serialize_vec_outer( self ) -> Result<Either<Self::Buffer, Buf<Vec<u8>>>, (SerializeError<Never>, Self)>
where Self::Buffer: ReusableBuffer,

Serializes this Serializer as the outermost packet, allocating a Buf<Vec<u8>> if the contained buffer isn’t large enough.

serialize_vec_outer is like serialize_vec, except that it is called when this Serializer describes the outermost packet, not encapsulated in any other packets. It is equivalent to calling serialize_vec with an empty PacketBuilder (such as ()).

source

fn serialize_no_alloc_outer( self ) -> Result<Self::Buffer, (SerializeError<BufferTooShortError>, Self)>
where Self::Buffer: ReusableBuffer,

Serializes this Serializer as the outermost packet, failing if the existing buffer is not large enough.

serialize_no_alloc_outer is like serialize_no_alloc, except that it is called when this Serializer describes the outermost packet, not encapsulated in any other packets. It is equivalent to calling serialize_no_alloc with an empty PacketBuilder (such as ()).

source

fn encapsulate<B>(self, outer: B) -> Nested<Self, B>

Encapsulates this Serializer in another packet, producing a new Serializer.

encapsulate consumes this Serializer and a PacketBuilder, and produces a new Serializer which describes encapsulating this one in the packet described by outer.

source

fn with_size_limit(self, limit: usize) -> Nested<Self, LimitedSizePacketBuilder>

Creates a new Serializer which will enforce a size limit.

with_size_limit consumes this Serializer and limit, and produces a new Serializer which will enforce the given limit on all serialization requests. Note that the given limit will be enforced at this layer - serialization requests will be rejected if the body produced by the request at this layer would exceed the limit. It has no effect on headers or footers added by encapsulating layers outside of this one.

Object Safety§

This trait is not object safe.

Implementors§