Trait domain::base::octets::OctetsBuilder
source · pub trait OctetsBuilder: Sized {
type Octets;
// Required methods
fn append_slice(&mut self, slice: &[u8]) -> Result<(), ShortBuf>;
fn truncate(&mut self, len: usize);
fn freeze(self) -> Self::Octets;
fn len(&self) -> usize;
fn is_empty(&self) -> bool;
// Provided methods
fn append_all<F>(&mut self, op: F) -> Result<(), ShortBuf>
where F: FnOnce(&mut Self) -> Result<(), ShortBuf> { ... }
fn append_compressed_dname<N: ToDname>(
&mut self,
name: &N
) -> Result<(), ShortBuf> { ... }
fn u16_len_prefixed<F>(&mut self, op: F) -> Result<(), ShortBuf>
where Self: AsMut<[u8]>,
F: FnOnce(&mut Self) -> Result<(), ShortBuf> { ... }
}Expand description
A buffer to construct an octet sequence.
Octet builders represent a buffer of space available for building an octets sequence by appending the contents of octet slices. The buffers may consist of a predefined amount of space or grow as needed.
The trait does not require octet builder to provide access to the already
assembled data. However, implementations are likely to do so, anyway, via
implementations of AsRef<[u8]> and AsMut<[u8]>. If access becomes
necessary when using an octets builder, simply add these as extra trait
bounds.
Required Associated Types§
sourcetype Octets
type Octets
The type of the octets the builder can be converted into.
If Octets implements IntoBuilder, the Builder associated
type of that trait must be Self.
Required Methods§
Provided Methods§
sourcefn append_all<F>(&mut self, op: F) -> Result<(), ShortBuf>where
F: FnOnce(&mut Self) -> Result<(), ShortBuf>,
fn append_all<F>(&mut self, op: F) -> Result<(), ShortBuf>where F: FnOnce(&mut Self) -> Result<(), ShortBuf>,
Appends all data or nothing.
The method executes the provided closure that presumably will try to append data to the builder and propagates an error from the builder. If the closure returns with an error, the builder is truncated back to the length from before the closure was executed.
Note that upon an error the builder is only truncated. If the
closure modified any already present data via AsMut<[u8]>, these
modification will survive.
sourcefn append_compressed_dname<N: ToDname>(
&mut self,
name: &N
) -> Result<(), ShortBuf>
fn append_compressed_dname<N: ToDname>( &mut self, name: &N ) -> Result<(), ShortBuf>
Appends a domain name using name compression if supported.
Domain name compression attempts to lower the size of a DNS message by avoiding to include repeated domain name suffixes. Instead of adding the full suffix, a pointer to the location of the previous occurence is added. Since that occurence may itself contain a compressed suffix, doing name compression isn’t cheap and therefore optional. However, in order to be able to opt in, we need to know if we are dealing with a domain name that ought to be compressed.
The trait provides a default implementation which simply appends the name uncompressed.
sourcefn u16_len_prefixed<F>(&mut self, op: F) -> Result<(), ShortBuf>where
Self: AsMut<[u8]>,
F: FnOnce(&mut Self) -> Result<(), ShortBuf>,
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.
The method will append the data being added via the closure op to
the builder prepended with a 16 bit unsigned value of its length.
The implementation will prepend a 0u16 before executing the closure
and update it to the number of octets added afterwards. If the
closure adds more than 65535 octets or if any appending fails, the
builder will be truncated to its previous length.