Struct ParsedName

pub struct ParsedName<Octs> { /* private fields */ }

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.

ParsedName 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.

ParsedName implementes the ToName 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, ToName::to_name can be used to produce a flat, self-contained Name.

Implementations

impl<Octs> ParsedName<Octs>

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.

pub fn ref_octets(&self) -> ParsedName<&Octs>

Returns an equivalent name for a reference to the contained octets.

impl<'a, Octs: Octets + ?Sized> ParsedName<&'a Octs>

pub fn deref_octets(&self) -> ParsedName<Octs::Range<'a>>

impl<Octs: AsRef<[u8]>> ParsedName<Octs>

Working with Labels

pub fn iter(&self) -> ParsedNameIter<'_>

Returns an iterator over the labels of the name.

pub fn iter_suffixes(&self) -> ParsedSuffixIter<'_, Octs>

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<N: ToLabelIter>(&self, base: &N) -> bool

Determines whether base is a prefix of self.

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

Determines whether base is a suffix of self.

pub fn split_first(&mut self) -> Option<RelativeName<Octs::Range<'_>>>

where Octs: Octets,

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.

impl<Octs> ParsedName<Octs>

pub fn parse<'a, Src: Octets<Range<'a> = Octs> + ?Sized>( parser: &mut Parser<'a, Src>, ) -> Result<Self, ParseError>

impl<'a, Octs: AsRef<[u8]> + ?Sized> ParsedName<&'a Octs>

pub fn parse_ref(parser: &mut Parser<'a, Octs>) -> Result<Self, ParseError>

impl ParsedName<()>

pub fn skip<Src: AsRef<[u8]> + ?Sized>( parser: &mut Parser<'_, Src>, ) -> 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.

Trait Implementations

impl<Octs, N> CanonicalOrd<N> for ParsedName<Octs>

where Octs: AsRef<[u8]>, N: ToName + ?Sized,

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

Returns the canonical ordering between self and other.

fn canonical_lt(&self, other: &Rhs) -> bool

Returns whether self is canonically less than other.

fn canonical_le(&self, other: &Rhs) -> bool

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

fn canonical_gt(&self, other: &Rhs) -> bool

Returns whether self is canonically greater than other.

fn canonical_ge(&self, other: &Rhs) -> bool

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

impl<Octs: Clone> Clone for ParsedName<Octs>

fn clone(&self) -> ParsedName<Octs>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<Octs: AsRef<[u8]>> Debug for ParsedName<Octs>

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

Formats the value using the given formatter.

impl<Octs: AsRef<[u8]>> Display for ParsedName<Octs>

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<Octs, Target> FlattenInto<Name<Target>> for ParsedName<Octs>

where Octs: Octets, Target: FromBuilder, <Target as FromBuilder>::Builder: EmptyBuilder,

type AppendError = <<Target as FromBuilder>::Builder as OctetsBuilder>::AppendError

fn try_flatten_into(self) -> Result<Name<Target>, Self::AppendError>

impl<Octs: AsRef<[u8]>> From<Name<Octs>> for ParsedName<Octs>

fn from(name: Name<Octs>) -> ParsedName<Octs>

Converts to this type from the input type.

impl<Octs: AsRef<[u8]>> Hash for ParsedName<Octs>

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, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl<'a, Octs> IntoIterator for &'a ParsedName<Octs>

where Octs: AsRef<[u8]>,

type Item = &'a Label

The type of the elements being iterated over.

type IntoIter = ParsedNameIter<'a>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl<Octs: AsRef<[u8]>> Ord for ParsedName<Octs>

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

This method returns an Ordering between self and other.

fn max(self, other: Self) -> Self

where Self: Sized,

Compares and returns the maximum of two values.

fn min(self, other: Self) -> Self

where Self: Sized,

Compares and returns the minimum of two values.

fn clamp(self, min: Self, max: Self) -> Self

where Self: Sized,

Restrict a value to a certain interval.

impl<Octs, N> PartialEq<N> for ParsedName<Octs>

where Octs: AsRef<[u8]>, N: ToName + ?Sized,

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

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<Octs, N> PartialOrd<N> for ParsedName<Octs>

where Octs: AsRef<[u8]>, N: ToName + ?Sized,

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

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

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator.

fn le(&self, other: &Rhs) -> bool

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

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator.

fn ge(&self, other: &Rhs) -> bool

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

impl<Octs: AsRef<[u8]>> ToLabelIter for ParsedName<Octs>

type LabelIter<'s> = ParsedNameIter<'s> where Octs: 's

The type of the iterator over the labels.

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

Returns an iterator over the labels.

fn compose_len(&self) -> u16

Returns the length in octets of the encoded name.

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

Determines whether base is a prefix of self.

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

Determines whether base is a suffix of self.

impl<Octs: AsRef<[u8]>> ToName for ParsedName<Octs>

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

Returns an octets slice of the content if possible.

fn try_to_name<Octets>( &self, ) -> Result<Name<Octets>, BuilderAppendError<Octets>>

where Octets: FromBuilder, <Octets as FromBuilder>::Builder: EmptyBuilder,

Converts the name into a single, uncompressed name.

fn to_name<Octets>(&self) -> Name<Octets>

where Octets: FromBuilder, <Octets as FromBuilder>::Builder: OctetsBuilder<AppendError = Infallible> + EmptyBuilder,

Converts the name into a single, uncompressed name.

fn try_to_canonical_name<Octets>( &self, ) -> Result<Name<Octets>, BuilderAppendError<Octets>>

where Octets: FromBuilder, <Octets as FromBuilder>::Builder: EmptyBuilder,

Converts the name into a single name in canonical form.

fn to_canonical_name<Octets>(&self) -> Name<Octets>

where Octets: FromBuilder, <Octets as FromBuilder>::Builder: OctetsBuilder<AppendError = Infallible> + EmptyBuilder,

Converts the name into a single name in canonical form.

fn compose<Target: OctetsBuilder + ?Sized>( &self, target: &mut Target, ) -> Result<(), Target::AppendError>

fn compose_canonical<Target: OctetsBuilder + ?Sized>( &self, target: &mut Target, ) -> Result<(), Target::AppendError>

fn to_cow(&self) -> Name<Cow<'_, [u8]>>

Returns a cow of the domain name.

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

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

fn to_bytes(&self) -> Name<Bytes>

Returns the domain name assembled into a bytes value.

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

Tests whether self and other are equal.

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

Returns the ordering between self and other.

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

Returns the composed name ordering.

fn lowercase_composed_cmp<N: ToName + ?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<Octs: Copy> Copy for ParsedName<Octs>

impl<Octs: AsRef<[u8]>> Eq for ParsedName<Octs>