Struct domain::bits::compose::Composer

pub struct Composer { /* fields omitted */ }

A type for assembling a wire-format DNS message.

A composer can be created either anew with new() or through from_vec() atop an existing vector that may already contain some data. In either case, a ComposeMode is necessary to tell the composer what kind of message it is supposed to create.

In particular, there is something called the stream mode, requested through ComposeMode::Stream, where a sixteen bit, big-endian length shim is prepended to the actual message as required for sending DNS messages over stream transports such as TCP. It’s value, however, is not constantly updated but only when preview() or finish() are called.

A number of methods are available for adding data to the composer. Alternatively, types may implement Composable to acquire a compose() method themselves.

Since it makes composing a lot easier, methods are available to update data added earlier. These are normally used to add length markers after the fact without always having to know the eventual size of data added.

DNS messages that are sent over the wire are limited in size. If a message becomes to large, it has to be cut back to a well-known boundary and a truncation flag set in the header. To facilitate this process, a checkpoint can be set during composing. If the composition grows over the limit, it will be cut back to that checkpoint. Any further composing will fail.

Note that size limits apply to the assembled message. If a composer is created atop an exisiting vector, the size of any earlier data is not considered.

Methods

impl Composer

Creation and Finalization

pub fn new(mode: ComposeMode, compress: bool) -> Self

Creates a new composer.

A possible prefix and the maximum size of the composed message are determined through mode. If compress is true, name compression will be available for domain names. Otherwise, all names will always be uncompressed.

pub fn from_vec(vec: Vec<u8>, mode: ComposeMode, compress: bool) -> Self

Creates a new compose buffer based on an exisiting vector.

The existing content of vec will be preserved and the actual DNS message will start after it.

A possible prefix and the maximum size of the composed message are determined through mode. If compress is true, name compression will be available for domain names. Otherwise, all names will always be uncompressed.

pub fn finish(self) -> Vec<u8>

Finalizes the composition and returns the final data.

pub fn snapshot(self) -> ComposeSnapshot

Returns a snapshot of the composer at its current position.

If the snapshot is rolled back, the resulting composer will be exactly the same as self right now.

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

Returns a reference to the underlying vector as it looks now.

This method updates the length shim in stream mode, hence the need for a &mut self.

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

Returns the message bytes as far as they are assembled yet.

The returned bytes slice really only contains the message bytes and neither whatever was contained in the vector with which the composer was posssibly created nor the length prefix of stream mode.

pub fn so_far_mut(&mut self) -> &mut [u8]

Returns the message bytes as far as they are assembled yet.

The returned bytes slice really only contains the message bytes and neither whatever was contained in the vector with which the composer was posssibly created nor the length prefix of stream mode.

impl Composer

Working with Positions

pub fn pos(&self) -> usize

Returns the current position.

The returned value is identical to the current overall length of the underlying bytes vec.

pub fn start(&self) -> usize

Returns the position where the message starts.

This is identical to having called self.pos() right after self was created.

pub fn delta(&self, pos: usize) -> usize

Returns the length of data added since the given position.

Panics

Panics if pos is larger than the current position.

pub fn mark_checkpoint(&mut self)

Marks the current position as a point for truncation.

If the length of the resulting message exceeds its predefined maximum size for the first time after a call to this method, the data will be cut back to the length it had when the method was called. If this happens, any further writing will fail.

pub fn is_truncated(&self) -> bool

Returns whether the target has been truncated.

impl Composer

Composing

pub fn compose_bytes(&mut self, data: &[u8]) -> ComposeResult<()>

Pushes a bytes slice to the end of the message.

pub fn compose_empty(&mut self, len: usize) -> ComposeResult<()>

Pushes placeholder bytes to the end of the message.

In particular, if successful, the message will have been extended by len octets of value zero,

pub fn compose_u8(&mut self, data: u8) -> ComposeResult<()>

Pushes a single octet to the end of the message.

pub fn compose_u16(&mut self, data: u16) -> ComposeResult<()>

Pushes an unsigned 16-bit word to the end of the message.

Since DNS data is big-endian, data will be converted to that endianess if necessary.

pub fn compose_u32(&mut self, data: u32) -> ComposeResult<()>

Pushes a unsigned 32-bit word to the end of the message.

Since DNS data is big-endian, data will be converted to that endianess if necessary.

pub fn compose_dname<N: DName>(&mut self, name: &N) -> ComposeResult<()>

Pushes a domain name to the end of the message.

pub fn compose_dname_compressed<N: DName>(     &mut self,     name: &N ) -> ComposeResult<()>

Pushes a domain name to the end of the message using name compression.

Since compression is only allowed in a few well-known places per RFC 1123 and RFC 3597, this isn’t the default behaviour.

impl Composer

Updating Earlier Data

pub fn update_bytes(&mut self, pos: usize, data: &[u8])

Updates the bytes starting at the given position.

Panics

Panics if the bytes slice is longer than the data assembled since the given position.

pub fn update_u8(&mut self, pos: usize, data: u8)

Updates the octet at the given position.

Panics

Panics if there has not been at least one byte of data assembled since the given position.

pub fn update_u16(&mut self, pos: usize, data: u16)

Updates an unsigned 16-bit word starting at the given position.

Panics

Panics if there has not been at least two bytes of data assembled since the given position.

pub fn update_u32(&mut self, pos: usize, data: u32)

Updates an unsigned 32-bit word starting at the given position.

Panics

Panics if there has not been at least four bytes of data assembled since the given position.

Trait Implementations

impl Clone for Composer

fn clone(&self) -> Composer

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Composer

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

Formats the value using the given formatter.

impl AsRef<Composer> for Composer

fn as_ref(&self) -> &Self

Performs the conversion.

impl AsMut<Composer> for Composer

fn as_mut(&mut self) -> &mut Self

Performs the conversion.

impl AsRef<Composer> for ComposeSnapshot

fn as_ref(&self) -> &Composer

Performs the conversion.

impl AsMut<Composer> for ComposeSnapshot

fn as_mut(&mut self) -> &mut Composer

Performs the conversion.

impl<C: AsMut<Composer>> AsMut<Composer> for RecordBuilder<C>

fn as_mut(&mut self) -> &mut Composer

Performs the conversion.