Struct domain::bits::compose::Composer
[−]
[src]
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
[src]
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.
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.
fn finish(self) -> Vec<u8>
Finalizes the composition and returns the final data.
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.
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
.
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.
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
[src]
fn pos(&self) -> usize
Returns the current position.
The returned value is identical to the current overall length of the underlying bytes vec.
fn start(&self) -> usize
Returns the position where the message starts.
This is identical to having called self.pos()
right after self
was created.
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.
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.
fn is_truncated(&self) -> bool
Returns whether the target has been truncated.
impl Composer
[src]
fn compose_bytes(&mut self, data: &[u8]) -> ComposeResult<()>
Pushes a bytes slice to the end of the message.
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,
fn compose_u8(&mut self, data: u8) -> ComposeResult<()>
Pushes a single octet to the end of the message.
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.
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.
fn compose_dname<N: DName>(&mut self, name: &N) -> ComposeResult<()>
Pushes a domain name to the end of the message.
fn compose_dname_compressed<N: DName>(&mut self, name: &N) -> ComposeResult<()>
impl Composer
[src]
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.
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.
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.
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
[src]
fn clone(&self) -> Composer
Returns a copy of the value. Read more
fn clone_from(&mut self, source: &Self)
1.0.0
Performs copy-assignment from source
. Read more
impl Debug for Composer
[src]
impl AsRef<Composer> for Composer
[src]
fn as_ref(&self) -> &Self
Performs the conversion.
impl AsMut<Composer> for Composer
[src]
fn as_mut(&mut self) -> &mut Self
Performs the conversion.