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]
impl Composer
pub fn new(mode: ComposeMode, compress: bool) -> Self
[src]
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
[src]
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>
[src]
pub fn finish(self) -> Vec<u8>
Finalizes the composition and returns the final data.
pub fn snapshot(self) -> ComposeSnapshot
[src]
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]
[src]
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]
[src]
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]
[src]
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
[src]
impl Composer
pub fn pos(&self) -> usize
[src]
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
[src]
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
[src]
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)
[src]
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
[src]
pub fn is_truncated(&self) -> bool
Returns whether the target has been truncated.
impl Composer
[src]
impl Composer
pub fn compose_bytes(&mut self, data: &[u8]) -> ComposeResult<()>
[src]
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<()>
[src]
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<()>
[src]
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<()>
[src]
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<()>
[src]
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<()>
[src]
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<()>
[src]
pub fn compose_dname_compressed<N: DName>(
&mut self,
name: &N
) -> ComposeResult<()>
impl Composer
[src]
impl Composer
pub fn update_bytes(&mut self, pos: usize, data: &[u8])
[src]
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)
[src]
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)
[src]
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)
[src]
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
[src]
impl Clone for Composer
fn clone(&self) -> Composer
[src]
fn clone(&self) -> Composer
Returns a copy of the value. Read more
fn clone_from(&mut self, source: &Self)
1.0.0[src]
fn clone_from(&mut self, source: &Self)
Performs copy-assignment from source
. Read more
impl Debug for Composer
[src]
impl Debug for Composer
fn fmt(&self, f: &mut Formatter) -> Result
[src]
fn fmt(&self, f: &mut Formatter) -> Result
Formats the value using the given formatter. Read more
impl AsRef<Composer> for Composer
[src]
impl AsRef<Composer> for Composer
impl AsMut<Composer> for Composer
[src]
impl AsMut<Composer> for Composer
impl AsRef<Composer> for ComposeSnapshot
[src]
impl AsRef<Composer> for ComposeSnapshot
impl AsMut<Composer> for ComposeSnapshot
[src]
impl AsMut<Composer> for ComposeSnapshot
impl<C: AsMut<Composer>> AsMut<Composer> for RecordBuilder<C>
[src]
impl<C: AsMut<Composer>> AsMut<Composer> for RecordBuilder<C>