Struct domain::base::message_builder::StreamTarget

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

A builder target for sending messages on stream transports.

When messages are sent over stream-oriented transports such as TCP, a DNS message is preceded by a 16 bit length value in order to determine the end of a message. This type transparently adds this length value as the first two octets of an octets builder and itself presents an octets builder interface for building the actual message. Whenever data is pushed to that builder interface, the type will update the length value.

Because the length is 16 bits long, the assembled message can be at most 65536 octets long, independently of the maximum length the underlying builder allows.

Implementations

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

pub fn new(target: Target) -> Result<Self, ShortBuf>

Creates a new stream target wrapping an octets builder.

The function will truncate the builder back to empty and appends the length value. Because of the latter, this can fail if the octets builder doesn’t even have space for that.

impl StreamTarget<Vec<u8>>

pub fn new_vec() -> Self

Creates a stream target atop an empty Vec<u8>.

impl<Target: OctetsBuilder> StreamTarget<Target>

pub fn as_target(&self) -> &Target

Returns a reference to the underlying octets builder.

pub fn into_target(self) -> Target

Converts the stream target into the underlying octets builder.

The returned builder will contain the 16 bit length value with the correct content and the assembled message.

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

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

Returns an octets slice of the message for stream transports.

The slice will start with the length octets and can be send as is through a stream transport such as TCP.

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

Returns an octets slice of the message for datagram transports.

The slice will not contain the length octets but only the actual message itself. This slice can be used for sending via datagram transports such as UDP.

Trait Implementations

impl<Target: AsMut<[u8]>> AsMut<[u8]> for StreamTarget<Target>

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

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

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

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

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

impl<Target: Clone> Clone for StreamTarget<Target>

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

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<Target: Debug> Debug for StreamTarget<Target>

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

Formats the value using the given formatter.

impl<Target> OctetsBuilder for StreamTarget<Target>where
    Target: OctetsBuilder + AsMut<[u8]>,

type Octets = <Target as OctetsBuilder>::Octets

The type of the octets the builder can be converted into.

fn append_slice(&mut self, slice: &[u8]) -> Result<(), ShortBuf>

Appends the content of a slice to the builder.

fn truncate(&mut self, len: usize)

Truncates the builder back to a length of len octets.

fn freeze(self) -> Self::Octets

Converts the builder into immutable octets.

fn len(&self) -> usize

Returns the length of the already assembled data.

fn is_empty(&self) -> bool

Returns whether the builder is currently empty.

fn append_all<F>(&mut self, op: F) -> Result<(), ShortBuf>where
    F: FnOnce(&mut Self) -> Result<(), ShortBuf>,

Appends all data or nothing.

fn append_compressed_dname<N: ToDname>(
    &mut self,
    name: &N
) -> Result<(), ShortBuf>

Appends a domain name using name compression if supported.

fn u16_len_prefixed<F>(&mut self, op: F) -> Result<(), ShortBuf>where
    Self: AsMut<[u8]>,
    F: FnOnce(&mut Self) -> Result<(), ShortBuf>,

Prepends some appended data with its length as a u16.