Struct StreamTarget

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

A builder target for sending messages on stream transports.

TODO: Rename this type and adjust the doc comments as it is usable both for datagram AND stream transports via as_dgram_slice and as_stream_slice.

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: Composer> StreamTarget<Target>

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

Creates a new stream target wrapping an octets builder.

The function will truncate the builder back to empty and append 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 StreamTarget<BytesMut>

pub fn new_bytes() -> Self

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

impl<Target> 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: 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> Composer for StreamTarget<Target>

where Target: Composer, Target::AppendError: Into<ShortBuf>,

fn append_compressed_name<N: ToName + ?Sized>( &mut self, name: &N, ) -> Result<(), Self::AppendError>

Appends a domain name using name compression if supported.

fn can_compress(&self) -> bool

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

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

Formats the value using the given formatter.

impl<Target: Default> Default for StreamTarget<Target>

fn default() -> StreamTarget<Target>

Returns the “default value” for a type.

impl<Target> OctetsBuilder for StreamTarget<Target>

where Target: OctetsBuilder + AsRef<[u8]> + AsMut<[u8]>, Target::AppendError: Into<ShortBuf>,

type AppendError = ShortBuf

The error type when appending data fails.

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

Appends the content of a slice to the builder.

impl<Target: Composer> Truncate for StreamTarget<Target>

fn truncate(&mut self, len: usize)

Truncate the sequence to len octets.