Struct MessageBuilder

pub struct MessageBuilder<Target> { /* private fields */ }

Starts building a DNS message.

This type wraps an OctetsBuilder and starts the process of building a message. It allows access to the header section. The message builder can be traded in for any section builder or the underlying octets builder.

For more details see the module documentation.

Implementations

impl<Target: OctetsBuilder + Truncate> MessageBuilder<Target>

Creating Message Builders

pub fn from_target(target: Target) -> Result<Self, Target::AppendError>

Creates a new message builder using the given target.

The target must be an OctetsBuilder. It will be truncated to zero size before appending the header section. That is, all data that was in the builder before will be lost.

The function will result in an error if the builder doesn’t have enough space for the header section.

impl MessageBuilder<Vec<u8>>

pub fn new_vec() -> Self

Creates a new message builder atop a Vec<u8>.

impl MessageBuilder<StreamTarget<Vec<u8>>>

pub fn new_stream_vec() -> Self

Creates a new builder for a streamable message atop a Vec<u8>.

impl MessageBuilder<BytesMut>

pub fn new_bytes() -> Self

Creates a new message builder atop a bytes value.

impl MessageBuilder<StreamTarget<BytesMut>>

pub fn new_stream_bytes() -> Self

Creates a new streamable message builder atop a bytes value.

impl<Target: Composer> MessageBuilder<Target>

pub fn start_answer<Octs: Octets + ?Sized>( self, msg: &Message<Octs>, rcode: Rcode, ) -> Result<AnswerBuilder<Target>, PushError>

Starts creating an answer for the given message.

Specifically, this sets the ID, QR, OPCODE, RD, and RCODE fields in the header and attempts to push the message’s questions to the builder.

The method converts the message builder into an answer builder ready to receive the answer for the question.

pub fn start_error<Octs: Octets + ?Sized>( self, msg: &Message<Octs>, rcode: Rcode, ) -> AnswerBuilder<Target>

Starts creating an error for the given message.

Like start_answer() but infallible. Questions will be pushed if possible.

pub fn request_axfr<N: ToName>( self, apex: N, ) -> Result<AnswerBuilder<Target>, PushError>

Creates an AXFR request for the given domain.

Sets a random ID, pushes the domain and the AXFR record type into the question section, and converts the builder into an answer builder.

impl<Target: Composer> MessageBuilder<Target>

Limiting message size

pub fn set_push_limit(&mut self, limit: usize)

Limit how much of the underlying buffer may be used.

When a limit is set, calling push() on a message section (e.g. AdditionalBuilder::push()) will fail if the limit is exceeded just as if the actual end of the underlying buffer had been reached.

Note: Calling this function does NOT truncate the underlying buffer. If the new limit is lees than the amount of the buffer that has already been used, exisitng content beyond the limit will remain untouched, the length will remain larger than the limit, and calls to push() will fail until the buffer is truncated to a size less than the limit.

pub fn clear_push_limit(&mut self)

Clear the push limit, if set.

Removes any push limit previously set via [set_push_limit()].

pub fn push_limit(&self) -> Option<usize>

Returns the current push limit, if set.

impl<Target: OctetsBuilder + AsRef<[u8]>> MessageBuilder<Target>

Access to the Message Header

pub fn header(&self) -> Header

Return the current value of the message header.

pub fn counts(&self) -> HeaderCounts

Return the current value of the message header counts.

impl<Target: OctetsBuilder + AsMut<[u8]>> MessageBuilder<Target>

pub fn header_mut(&mut self) -> &mut Header

Returns a mutable reference to the message header for manipulations.

impl<Target> MessageBuilder<Target>

Conversions

pub fn builder(self) -> MessageBuilder<Target>

Converts the message builder into a message builder

This is a no-op.

impl<Target: Composer> MessageBuilder<Target>

pub fn question(self) -> QuestionBuilder<Target>

Converts the message builder into a question builder.

pub fn answer(self) -> AnswerBuilder<Target>

Converts the message builder into an answer builder.

This will leave the question section empty.

pub fn authority(self) -> AuthorityBuilder<Target>

Converts the message builder into an authority builder.

This will leave the question and answer sections empty.

pub fn additional(self) -> AdditionalBuilder<Target>

Converts the message builder into an additional builder.

This will leave the question, answer, and authority sections empty.

pub fn finish(self) -> Target

Converts the message into the underlying octets builder.

This will leave the all sections empty.

impl<Target: FreezeBuilder> MessageBuilder<Target>

pub fn into_message(self) -> Message<Target::Octets>

Converts the builder into a message.

The method will return a message atop whatever octets sequence the builder’s octets builder converts into.

impl<Target> MessageBuilder<Target>

pub fn as_target(&self) -> &Target

Returns a reference to the underlying octets builder.

pub fn as_slice(&self) -> &[u8]

where Target: AsRef<[u8]>,

Returns an octets slice of the octets assembled so far.

pub fn as_message(&self) -> Message<&[u8]>

where Target: AsRef<[u8]>,

Returns a message atop for the octets assembled so far.

This message is atop the octets slices derived from the builder, so it can be created cheaply.

Trait Implementations

impl<Target> AsMut<MessageBuilder<Target>> for AdditionalBuilder<Target>

fn as_mut(&mut self) -> &mut MessageBuilder<Target>

Converts this type into a mutable reference of the (usually inferred) input type.

impl<Target> AsMut<MessageBuilder<Target>> for AnswerBuilder<Target>

fn as_mut(&mut self) -> &mut MessageBuilder<Target>

Converts this type into a mutable reference of the (usually inferred) input type.

impl<Target> AsMut<MessageBuilder<Target>> for AuthorityBuilder<Target>

fn as_mut(&mut self) -> &mut MessageBuilder<Target>

Converts this type into a mutable reference of the (usually inferred) input type.

impl<Target> AsMut<MessageBuilder<Target>> for QuestionBuilder<Target>

fn as_mut(&mut self) -> &mut MessageBuilder<Target>

Converts this type into a mutable reference of the (usually inferred) input type.

impl<Target: AsRef<[u8]>> AsRef<[u8]> for MessageBuilder<Target>

fn as_ref(&self) -> &[u8]

Converts this type into a shared reference of the (usually inferred) input type.

impl<Target> AsRef<MessageBuilder<Target>> for AdditionalBuilder<Target>

fn as_ref(&self) -> &MessageBuilder<Target>

Converts this type into a shared reference of the (usually inferred) input type.

impl<Target> AsRef<MessageBuilder<Target>> for AnswerBuilder<Target>

fn as_ref(&self) -> &MessageBuilder<Target>

Converts this type into a shared reference of the (usually inferred) input type.

impl<Target> AsRef<MessageBuilder<Target>> for AuthorityBuilder<Target>

fn as_ref(&self) -> &MessageBuilder<Target>

Converts this type into a shared reference of the (usually inferred) input type.

impl<Target> AsRef<MessageBuilder<Target>> for QuestionBuilder<Target>

fn as_ref(&self) -> &MessageBuilder<Target>

Converts this type into a shared reference of the (usually inferred) input type.

impl<Target> AsRef<Target> for MessageBuilder<Target>

fn as_ref(&self) -> &Target

Converts this type into a shared reference of the (usually inferred) input type.

impl<Target: Clone> Clone for MessageBuilder<Target>

fn clone(&self) -> MessageBuilder<Target>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<Target: Debug> Debug for MessageBuilder<Target>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<Target> From<AdditionalBuilder<Target>> for MessageBuilder<Target>

where Target: Composer,

fn from(src: AdditionalBuilder<Target>) -> Self

Converts to this type from the input type.

impl<Target> From<AnswerBuilder<Target>> for MessageBuilder<Target>

where Target: Composer,

fn from(src: AnswerBuilder<Target>) -> Self

Converts to this type from the input type.

impl<Target> From<AuthorityBuilder<Target>> for MessageBuilder<Target>

where Target: Composer,

fn from(src: AuthorityBuilder<Target>) -> Self

Converts to this type from the input type.

impl<Target> From<MessageBuilder<Target>> for AdditionalBuilder<Target>

where Target: Composer,

fn from(src: MessageBuilder<Target>) -> Self

Converts to this type from the input type.

impl<Target> From<MessageBuilder<Target>> for AnswerBuilder<Target>

where Target: Composer,

fn from(src: MessageBuilder<Target>) -> Self

Converts to this type from the input type.

impl<Target> From<MessageBuilder<Target>> for AuthorityBuilder<Target>

where Target: Composer,

fn from(src: MessageBuilder<Target>) -> Self

Converts to this type from the input type.

impl<Target> From<MessageBuilder<Target>> for Message<Target::Octets>

where Target: FreezeBuilder,

fn from(src: MessageBuilder<Target>) -> Self

Converts to this type from the input type.

impl<Target> From<MessageBuilder<Target>> for QuestionBuilder<Target>

where Target: Composer,

fn from(src: MessageBuilder<Target>) -> Self

Converts to this type from the input type.

impl<Target> From<QuestionBuilder<Target>> for MessageBuilder<Target>

where Target: Composer,

fn from(src: QuestionBuilder<Target>) -> Self

Converts to this type from the input type.