Struct Parser

pub struct Parser { /* private fields */ }

The raw data and state of a DNS message being parsed.

Because of name compression, a full message needs to be available for parsing of DNS data. This type is a small layer atop a Bytes value. You can wrap one using the from_bytes() function.

The parser allows you to successively parse one item after another out of the message via a few methods prefixed with parse_. Additional methods are available for repositioning the parser’s position or access the raw, underlying bytes.

The methods of a parser never panic if you try to go beyond the end of the parser’s data. Instead, they will return a ShortBuf error, making it more straightforward to implement a complex parser. Since an error normally leads to processing being aborted, functions that return an error can leave the parser at whatever position they like. In the rare case that you actually need to backtrack on the parser in case of an error, you will have to remember and reposition yourself.

Parsers are Clone, so you can keep around a copy of a parser for later use. This is, for instance, done by ParsedDname in order to be able to rummage around the message bytes to find all its labels. Because copying a Bytes value is relatively cheap, cloning a parser is cheap, too.

Implementations

impl Parser

pub fn from_bytes(bytes: Bytes) -> Self

Creates a new parser atop a bytes value.

pub fn from_static(slice: &'static [u8]) -> Self

Creates a new parser atop a static byte slice.

This function is most useful for testing.

pub fn unwrap(self) -> Bytes

Extracts the underlying bytes value from the parser.

This will be the same bytes value the parser was created with. It will not be modified by parsing at all.

impl Parser

pub fn as_bytes(&self) -> &Bytes

Returns a reference to the underlying bytes.

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

Returns a reference to the underlying byte slice.

pub fn pos(&self) -> usize

Returns the current parse position as an index into the byte slice.

pub fn remaining(&self) -> usize

Returns the number of remaining bytes to parse.

pub fn peek(&self, len: usize) -> Result<&[u8], ShortBuf>

Returns a slice containing the next len bytes.

If less than len bytes are left, returns an error.

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

Returns a byte slice of the data left to parse.

pub fn seek(&mut self, pos: usize) -> Result<(), ShortBuf>

Repositions the parser to the given index.

If pos is larger than the length of the parser, an error is returned.

pub fn advance(&mut self, len: usize) -> Result<(), ShortBuf>

Advances the parser‘s position by len bytes.

If this would take the parser beyond its end, an error is returned.

pub fn check_len(&self, len: usize) -> Result<(), ShortBuf>

Checks that there are len bytes left to parse.

If there aren’t, returns an error.

pub fn parse_bytes(&mut self, len: usize) -> Result<Bytes, ShortBuf>

Takes the next len bytes and returns them as a Bytes value.

Advances the parser by len bytes. If there aren’t enough bytes left, leaves the parser untouched and returns an error, instead.

pub fn parse_buf(&mut self, buf: &mut [u8]) -> Result<(), ShortBuf>

Fills the provided buffer by taking bytes from the parser.

pub fn parse_i8(&mut self) -> Result<i8, ShortBuf>

Takes an i8 from the beginning of the parser.

Advances the parser by one byte. If there aren’t enough bytes left, leaves the parser untouched and returns an error, instead.

pub fn parse_u8(&mut self) -> Result<u8, ShortBuf>

Takes a u8 from the beginning of the parser.

Advances the parser by one byte. If there aren’t enough bytes left, leaves the parser untouched and returns an error, instead.

pub fn parse_i16(&mut self) -> Result<i16, ShortBuf>

Takes an i16 from the beginning of the parser.

The value is converted from network byte order into the system’s own byte order if necessary. The parser is advanced by two bytes. If there aren’t enough bytes left, leaves the parser untouched and returns an error, instead.

pub fn parse_u16(&mut self) -> Result<u16, ShortBuf>

Takes a u16 from the beginning of the parser.

The value is converted from network byte order into the system’s own byte order if necessary. The parser is advanced by two bytes. If there aren’t enough bytes left, leaves the parser untouched and returns an error, instead.

pub fn parse_i32(&mut self) -> Result<i32, ShortBuf>

Takes an i32 from the beginning of the parser.

The value is converted from network byte order into the system’s own byte order if necessary. The parser is advanced by four bytes. If there aren’t enough bytes left, leaves the parser untouched and returns an error, instead.

pub fn parse_u32(&mut self) -> Result<u32, ShortBuf>

Takes a u32 from the beginning of the parser.

The value is converted from network byte order into the system’s own byte order if necessary. The parser is advanced by four bytes. If there aren’t enough bytes left, leaves the parser untouched and returns an error, instead.

Trait Implementations

impl Clone for Parser

fn clone(&self) -> Parser

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Parser

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

Formats the value using the given formatter.