Struct domain::base::ParsedDname

pub struct ParsedDname<Ref> { /* fields omitted */ }

A domain name parsed from a DNS message.

In an attempt to keep messages small, DNS uses a procedure called ‘name compression.’ It tries to minimize the space used for repeatedly appearing domain names by simply refering to the first occurence of the name. This works not only for complete names but also for suffixes. In this case, the first unique labels of the name are included and then a pointer is included for the remainder of the name.

A consequence of this is that when parsing a domain name, its labels can be scattered all over the message and we would need to allocate some space to re-assemble the original name. However, in many cases we don’t need the complete name. Many operations can be performed by just iterating over the labels which we can do in place.

ParsedDname deals with such names. It takes a copy of a Parser representing a reference to the underlying DNS message and, if nedded, traverses over the name starting at the current position of the parser. When being created, the type quickly walks over the name to check that it is, indeed, a valid name. While this does take a bit of time, it spares you having to deal with possible parse errors later on.

ParsedDname implementes the ToDname trait, so you can use it everywhere where a generic absolute domain name is accepted. In particular, you can compare it to other names or chain it to the end of a relative name. If necessary, ToDname::to_name can be used to produce a flat, self-contained Dname.

Implementations

impl<Ref> ParsedDname<Ref>

Properties

pub fn is_compressed(&self) -> bool

Returns whether the name is compressed.

pub fn is_root(&self) -> bool

Returns whether the name is the root label only.

impl<Ref: AsRef<[u8]>> ParsedDname<Ref>

Working with Labels

pub fn iter(&self) -> ParsedDnameIter

Returns an iterator over the labels of the name.

pub fn iter_suffixes(&self) -> ParsedSuffixIter<Ref> where
    Ref: Clone, 

Returns an iterator over the suffixes of the name.

The returned iterator starts with the full name and then for each additional step returns a name with the left-most label stripped off until it reaches the root label.

pub fn label_count(&self) -> usize

Returns the number of labels in the domain name.

pub fn first(&self) -> &Label

Returns a reference to the first label.

pub fn last(&self) -> &'static Label

Returns a reference to the last label.

Because the last label in an absolute name is always the root label, this method can return a static reference. It is also a wee bit silly, but here for completeness.

pub fn starts_with<'a, N: ToLabelIter<'a>>(&'a self, base: &'a N) -> bool

Determines whether base is a prefix of self.

pub fn ends_with<'a, N: ToLabelIter<'a>>(&'a self, base: &'a N) -> bool

Determines whether base is a suffix of self.

pub fn split_first(&mut self) -> Option<RelativeDname<Ref::Range>> where
    Ref: OctetsRef, 

Splits off the first label.

If this name is longer than just the root label, returns the first label as a relative name and removes it from the name itself. If the name is only the root label, returns None and does nothing.

pub fn parent(&mut self) -> bool

Reduces the name to the parent of the current name.

If the name consists of the root label only, returns false and does nothing. Otherwise, drops the first label and returns true.

Trait Implementations

impl<Ref, N: ?Sized> CanonicalOrd<N> for ParsedDname<Ref> where
    Ref: AsRef<[u8]>,
    N: ToDname, 

fn canonical_cmp(&self, other: &N) -> Ordering

Returns the canonical ordering between self and other.

#[must_use]fn canonical_lt(&self, other: &Rhs) -> bool

Returns whether self is canonically less than other.

#[must_use]fn canonical_le(&self, other: &Rhs) -> bool

Returns whether self is canonically less than or equal to other.

#[must_use]fn canonical_gt(&self, other: &Rhs) -> bool

Returns whether self is canonically greater than other.

#[must_use]fn canonical_ge(&self, other: &Rhs) -> bool

Returns whether self is canonically greater than or equal to other.

impl<Ref: Clone> Clone for ParsedDname<Ref>

fn clone(&self) -> ParsedDname<Ref>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<Ref: AsRef<[u8]>> Compose for ParsedDname<Ref>

fn compose<T: OctetsBuilder>(&self, target: &mut T) -> Result<(), ShortBuf>

Appends the concrete representation of the value to the target.

fn compose_canonical<T: OctetsBuilder>(
    &self,
    target: &mut T
) -> Result<(), ShortBuf>

Appends the canonical representation of the value to the target.

impl<Ref: Copy> Copy for ParsedDname<Ref>

impl<Ref: AsRef<[u8]>> Debug for ParsedDname<Ref>

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

Formats the value using the given formatter.

impl<Ref: AsRef<[u8]>> Display for ParsedDname<Ref>

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

Formats the domain name.

This will produce the domain name in common display format without the trailing dot.

impl<Ref: AsRef<[u8]>> Eq for ParsedDname<Ref>

impl<Ref: AsRef<[u8]>> From<Dname<Ref>> for ParsedDname<Ref>

fn from(name: Dname<Ref>) -> ParsedDname<Ref>

Performs the conversion.

impl<Ref: AsRef<[u8]>> Hash for ParsedDname<Ref>

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given [Hasher].

fn hash_slice<H>(data: &[Self], state: &mut H) where
    H: Hasher, 

Feeds a slice of this type into the given [Hasher].

impl<'a, Ref: AsRef<[u8]>> IntoIterator for &'a ParsedDname<Ref>

type Item = &'a Label

The type of the elements being iterated over.

type IntoIter = ParsedDnameIter<'a>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<Ref: AsRef<[u8]>> Ord for ParsedDname<Ref>

fn cmp(&self, other: &Self) -> Ordering

This method returns an [Ordering] between self and other.

#[must_use]fn max(self, other: Self) -> Self

Compares and returns the maximum of two values.

#[must_use]fn min(self, other: Self) -> Self

Compares and returns the minimum of two values.

#[must_use]fn clamp(self, min: Self, max: Self) -> Self

🔬 This is a nightly-only experimental API. (clamp)

Restrict a value to a certain interval.

impl<Ref> Parse<Ref> for ParsedDname<Ref> where
    Ref: AsRef<[u8]> + Clone, 

fn parse(parser: &mut Parser<Ref>) -> Result<Self, ParseError>

Extracts a value from the beginning of parser.

fn skip(parser: &mut Parser<Ref>) -> Result<(), ParseError>

Skip over a domain name.

This will only check the uncompressed part of the name. If the name is compressed but the compression pointer is invalid or the name pointed to is invalid or too long, the function will still succeed.

If you need to check that the name you are skipping over is valid, you will have to use parse and drop the result.

impl<Ref, N: ?Sized> PartialEq<N> for ParsedDname<Ref> where
    Ref: AsRef<[u8]>,
    N: ToDname, 

fn eq(&self, other: &N) -> bool

This method tests for self and other values to be equal, and is used by ==.

#[must_use]fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<Ref, N: ?Sized> PartialOrd<N> for ParsedDname<Ref> where
    Ref: AsRef<[u8]>,
    N: ToDname, 

fn partial_cmp(&self, other: &N) -> Option<Ordering>

This method returns an ordering between self and other values if one exists.

#[must_use]fn lt(&self, other: &Rhs) -> bool

This method tests less than (for self and other) and is used by the < operator.

#[must_use]fn le(&self, other: &Rhs) -> bool

This method tests less than or equal to (for self and other) and is used by the <= operator.

#[must_use]fn gt(&self, other: &Rhs) -> bool

This method tests greater than (for self and other) and is used by the > operator.

#[must_use]fn ge(&self, other: &Rhs) -> bool

This method tests greater than or equal to (for self and other) and is used by the >= operator.

impl<Ref: AsRef<[u8]>> ToDname for ParsedDname<Ref>

fn as_flat_slice(&self) -> Option<&[u8]>

Returns an octets slice of the content if possible.

fn to_dname<Octets>(&self) -> Result<Dname<Octets>, PushError> where
    Octets: FromBuilder,
    <Octets as FromBuilder>::Builder: EmptyBuilder, 

Converts the name into a single, uncompressed name.

fn to_cow(&self) -> Dname<Cow<[u8]>>

Returns a cow of the domain name.

fn to_vec(&self) -> Dname<Vec<u8>>

Returns the domain name assembled into a Vec<u8>.

fn name_eq<N: ToDname + ?Sized>(&self, other: &N) -> bool

Tests whether self and other are equal.

fn name_cmp<N: ToDname + ?Sized>(&self, other: &N) -> Ordering

Returns the ordering between self and other.

fn composed_cmp<N: ToDname + ?Sized>(&self, other: &N) -> Ordering

Returns the composed name ordering.

fn lowercase_composed_cmp<N: ToDname + ?Sized>(&self, other: &N) -> Ordering

Returns the lowercase composed ordering.

fn rrsig_label_count(&self) -> u8

Returns the number of labels for the RRSIG Labels field.

impl<'a, Ref: AsRef<[u8]>> ToLabelIter<'a> for ParsedDname<Ref>

type LabelIter = ParsedDnameIter<'a>

The type of the iterator over the labels.

fn iter_labels(&'a self) -> Self::LabelIter

Returns an iterator over the labels.

fn len(&self) -> usize

Returns the length in octets of the encoded name.

fn starts_with<N: ToLabelIter<'a> + ?Sized>(&'a self, base: &'a N) -> bool

Determines whether base is a prefix of self.

fn ends_with<N: ToLabelIter<'a> + ?Sized>(&'a self, base: &'a N) -> bool

Determines whether base is a suffix of self.