Struct MessageBuilder

pub struct MessageBuilder { /* private fields */ }

Starts building a DNS message.

This type starts building a DNS message and allows adding questions to its question section. See the module documentation for an overview of how to build a message.

Message builders operate atop a BytesMut byte buffer. There are a number of functions to create a builder either using an existing buffer or with a newly created buffer.

Once created, it is possible to access the message header or append questions to the question section before proceeding to the subsequent parts of the message.

Implementations

impl MessageBuilder

Creation and Preparation

pub fn new_udp() -> Self

Creates a new builder for a UDP message.

The builder will use a new bytes buffer. The buffer will have a capacity of 512 bytes and will also be limited to that.

This will result in a UDP message following the original limit. If you want to create larger messages, you should signal this through the use of EDNS.

pub fn new_tcp(capacity: usize) -> Self

Creates a new builder for a TCP message.

The builder will use a new buffer. It will be limited to 65535 bytes, starting with the capacity given and also growing by that amount.

Since DNS messages are preceded on TCP by a two octet length inicator, the function will add two bytes with zero before the message. Once you have completed your message, you can use can set these two bytes to the size of the message. But remember that they are in network byte order.

pub fn from_buf(buf: BytesMut) -> Self

Creates a new message builder using an existing bytes buffer.

The builder’s initial limit will be equal to whatever capacity is left in the buffer. As a consequence, the builder will never grow beyond that remaining capacity.

pub fn with_capacity(capacity: usize) -> Self

Creates a message builder with the given capacity.

The builder will have its own newly created bytes buffer. Its inital limit will be equal to the capacity of that buffer. This may be larger than capacity. If you need finer control over the limit, use with_params instead.

pub fn with_params(initial: usize, limit: usize, page_size: usize) -> Self

Creates a new message builder.

A new buffer will be created for this builder. It will initially allocate space for at least initial bytes. The message will never exceed a size of limit bytes. Whenever the buffer’s capacity is exhausted, the builder will allocate at least another page_size bytes. If page_size is set to 0, the builder will allocate at most once and then enough bytes to have room for the limit.

pub fn enable_compression(&mut self)

Enables support for domain name compression.

After this method is called, the domain names in questions, the owner domain names of resource records, and domain names appearing in the record data of record types defined in RFC 1035 will be compressed.

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

Sets the maximum size of the constructed DNS message.

After this method was called, additional data will not be added to the message if that would result in the message exceeding a size of limit bytes. If the message is already larger than limit when the method is called, it will not be truncated. That is, you can never actually set a limit smaller than the current message size.

Note also that the limit only regards the message constructed by the builder itself. If a builder was created atop a buffer that already contained some data, this pre-existing data is not considered.

pub fn set_page_size(&mut self, page_size: usize)

Sets the amount of data by which to grow the underlying buffer.

Whenever the buffer runs out of space but the message size limit has not yet been reached, the builder will grow the buffer by at least page_size bytes.

A special case is a page size of zero, in which case the buffer will be grown only once to have enough space to reach the current limit.

impl MessageBuilder

Building

pub fn push<N: ToDname, Q: Into<Question<N>>>( &mut self, question: Q, ) -> Result<(), ShortBuf>

Appends a new question to the message.

This function is generic over anything that can be converted into a Question. In particular, triples of a domain name, a record type, and a class as well as pairs of just a domain name and a record type fulfill this requirement with the class assumed to be Class::In in the latter case.

The method will fail if by appending the question the message would exceed its size limit.

pub fn answer(self) -> AnswerBuilder

Proceeds to building the answer section.

pub fn authority(self) -> AuthorityBuilder

Proceeds to building the authority section, skipping the answer.

pub fn additional(self) -> AdditionalBuilder

Proceeds to building the additional section.

Leaves the answer and additional sections empty.

Trait Implementations

impl Clone for MessageBuilder

fn clone(&self) -> MessageBuilder

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for MessageBuilder

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

Formats the value using the given formatter.

impl SectionBuilder for MessageBuilder

fn into_target(self) -> MessageTarget

Converts into target

fn get_target(&self) -> &MessageTarget

Returns message target

fn get_target_mut(&mut self) -> &mut MessageTarget

Returns message target

fn set_limit(&mut self, limit: usize)

Updates the message’s size limit.

fn header(&self) -> &Header

Returns a reference to the messages header.

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

Returns a mutable reference to the messages header.

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

Returns a reference to the message assembled so far.

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

Returns a reference to the slice preceeding the message.

fn prelude_mut(&mut self) -> &mut [u8]

Returns a mutable reference to the slice preceeding the message.

fn finish(self) -> BytesMut

Finishes the message and returns the underlying bytes buffer.

fn freeze(self) -> Message

Finishes the message and returns the resulting bytes value.

fn snapshot(&self) -> Snapshot<Self>

Returns a snapshot indicating the current state of the message.

fn rewind(&mut self, snapshot: &Snapshot<Self>)

Rewinds the message to the state it had at snapshot.