Struct domain::base::message::Message

pub struct Message<Octets> { /* fields omitted */ }

A DNS message.

This type wraps an octets sequence containing the complete wire-format DNS message and allows access to the various components of the message.

You create a message by passing an octets sequence to the from_octets associate function which does some basic sanity checks and, if they succeed, returns a message for the sequence. All further parsing happens lazily when you access more of the message. This means that a message is not necessarily well-formatted and further parsing may fail later on.

Section 4 of RFC 1035 defines DNS messages as being divded into five sections named header, question, answer, authority, and additional.

The header section is of a fixed sized and can be accessed at any time through the methods given under Header Section. Most likely, you will be interested in the first part of the header which is returned by the header method. The second part of the header section contains the number of entries in the following four sections and is of less interest as there are more sophisticated ways of accessing these sections. If you do care, you can get access through header_counts.

The meaning of the next four sections depends on the type of message as described by the opcode field of the header. Since the most common type is a query, the sections are named after their function in this type and the following description will focus on it.

The question section contains what was asked of the DNS by a query. It contains a number of questions that consist of a domain name, a record type, and class. A query asks for all records of the given record type that are owned by the domain name within the class. In queries, there will be exactly one question. With other opcodes, there may be multiple questions.

You can acquire an iterator over the questions through the question method. It returns a QuestionSection value that is an iterator over questions. Since a single question is such a common case, there is a convenience method first_question that returns the first question only.

The following three section all contain DNS resource records. In queries, they are empty in a request and may or may not contain records in a response. The answer section contains all the records that answer the given question. The authority section contains records declaring which name server provided authoritative information for the question, and the additional section can contain records that the name server thought might be useful for processing the question. For instance, if you trying to find out the mail server of a domain by asking for MX records, you likely also want the IP addresses for the server, so the name server may include these right away and free of charge.

There are functions to access all three sections directly: answer, authority, and additional. Each method returns a value of type RecordSection which acts as an iterator over the records in the section. Since there are no pointers to where the later sections start, accessing them directly means iterating over the previous sections. This is why it is more efficitent to call RecordSection::next_section to progress to a later section. Alternatively, you can use the message’s sections method that gives you all four sections at once with the minimal amount of iterating necessary.

When iterating over the record section, you will receive values of type ParsedRecord, an intermediary type that only parsed the parts common to all records. In order to access the data of the record, you will want to convert it into a Record which is generic over the actual record type data. This can be done via ParsedRecord::into_record.

Alternatively, you can trade the record section for one that only returns the types you are interested in via the RecordSection::limit_to method. The iterator returned by that method will quietly skip over all records that aren’t of the type you are interested in.

So, if you want to iterate over the MX records in the answer section, you would do something like this:

use domain::base::Message;
use domain::rdata::Mx;

let msg = Message::from_octets(octets).unwrap();
for record in msg.answer().unwrap().limit_to::<Mx<_>>() {
    if let Ok(record) = record {
        // Do something with the record ...
    }
}

The limit_to method takes the record type as a type argument. Many record types, like Mx, are generic over octet sequences but the compiler generally can figure out the concrete type itself, so in most cases you get away with the underscore there.

Note how the iterator doesn’t actually return records but results of records and parse errors. This is because only now can it check whether the record is actually properly formatted. An error signals that something went wrong while parsing. If only the record data is broken, the message remains useful and parsing can continue with the next record. If the message is fully broken, the next iteration will return None to signal that.

Implementations

impl<Octets> Message<Octets>

Creation and Conversion

pub fn from_octets(octets: Octets) -> Result<Self, ShortBuf> where
    Octets: AsRef<[u8]>, 

Creates a message from an octets sequence.

This fails if the slice is too short to even contain a complete header section. No further checks are done, though, so if this function returns ok, the message may still be broken with other methods returning errors later one.

pub fn as_octets(&self) -> &Octets

Returns a reference to the underlying octets sequence.

pub fn into_octets(self) -> Octets

Converts the message into the underlying octets sequence.

pub fn as_slice(&self) -> &[u8] where
    Octets: AsRef<[u8]>, 

Returns a slice to the underlying octets sequence.

pub fn for_slice(&self) -> Message<&[u8]> where
    Octets: AsRef<[u8]>, 

Returns a message for a slice of the octets sequence.

impl<Octets: AsRef<[u8]>> Message<Octets>

Header Section

pub fn header(&self) -> Header

Returns the message header.

pub fn header_mut(&mut self) -> &mut Header where
    Octets: AsMut<[u8]>, 

Returns a mutable reference to the message header.

pub fn header_counts(&self) -> HeaderCounts

Returns the header counts of the message.

pub fn header_section(&self) -> HeaderSection

Returns the entire header section.

pub fn no_error(&self) -> bool

Returns whether the rcode of the header is NoError.

pub fn is_error(&self) -> bool

Returns whether the rcode of the header is one of the error values.

impl<Octets> Message<Octets> where
    &'a Octets: OctetsRef, 

Access to Sections

pub fn question(&self) -> QuestionSection<&Octets>

Returns the question section.

pub fn zone(&self) -> QuestionSection<&Octets>

Returns the zone section of an UPDATE message.

This is identical to self.question().

pub fn answer(&self) -> Result<RecordSection<&Octets>, ParseError>

Returns the answer section.

Iterates over the question section in order to access the answer section. If you are accessing the question section anyway, using its next_section method may be more efficient.

pub fn prerequisite(&self) -> Result<RecordSection<&Octets>, ParseError>

Returns the prerequisite section of an UPDATE message.

This is identical to self.answer().

pub fn authority(&self) -> Result<RecordSection<&Octets>, ParseError>

Returns the authority section.

Iterates over both the question and the answer sections to determine the start of the authority section. If you are already accessing the answer section, using next_section on it is more efficient.

pub fn update(&self) -> Result<RecordSection<&Octets>, ParseError>

Returns the update section of an UPDATE message.

This is identical to self.authority().

pub fn additional(&self) -> Result<RecordSection<&Octets>, ParseError>

Returns the additional section.

Iterates over all three previous sections to determine the start of the additional section. If you are already accessing the authority section, using next_section on it is more efficient.

pub fn sections(
    &self
) -> Result<(QuestionSection<&Octets>, RecordSection<&Octets>, RecordSection<&Octets>, RecordSection<&Octets>), ParseError>

Returns all four sections in one fell swoop.

pub fn iter(&self) -> MessageIter<&Octets>

Returns an iterator over the records in the message.

The iterator’s item is a pair of a ParsedRecord and the Section it was found in.

As is customary, this iterator is also accessible via the IntoIterator trait on a reference to the message.

impl<Octets> Message<Octets> where
    Octets: AsRef<[u8]>,
    &'a Octets: OctetsRef, 

Helpers for Common Tasks

pub fn is_answer<Other>(&self, query: &Message<Other>) -> bool where
    Other: AsRef<[u8]>,
    &'o Other: OctetsRef, 

Returns whether this is the answer to some other message.

The method checks whether the ID fields of the headers are the same, whether the QR flag is set in this message, and whether the questions are the same.

pub fn first_question(&self) -> Option<Question<ParsedDname<&Octets>>>

Returns the first question, if there is any.

The method will return None both if there are no questions or if parsing fails.

pub fn sole_question(
    &self
) -> Result<Question<ParsedDname<&Octets>>, ParseError>

Returns the sole question of the message.

This is like first_question but returns an error if there isn’t exactly one question or there is a parse error.

pub fn qtype(&self) -> Option<Rtype>

Returns the query type of the first question, if any.

pub fn contains_answer<'s, Data>(&'s self) -> bool where
    Data: ParseRecordData<&'s Octets>, 

Returns whether the message contains answers of a given type.

pub fn canonical_name(&self) -> Option<ParsedDname<&Octets>>

Resolves the canonical name of the answer.

The CNAME record allows a domain name to be an alias for a different name. Aliases may be chained. The ‘canonical name’ referred to be the method’s name is the last name in this chain. A recursive resolver will support a stub resolver in figuring out this canonical name by including all necessary CNAME records in its answer. This method can be used on such an answer to determine the canonical name. As such, it will only consider CNAMEs present in the message’s answer section.

It starts with the question name and follows CNAME records until there is no next CNAME in the chain and then returns the last CNAME.

If the message doesn’t have a question, if there is a parse error, or if there is a CNAME loop the method returns None.

pub fn opt(&self) -> Option<OptRecord<<&Octets as OctetsRef>::Range>>

Returns the OPT record from the message, if there is one.

pub fn get_last_additional<'s, Data: ParseRecordData<&'s Octets>>(
    &'s self
) -> Option<Record<ParsedDname<&'s Octets>, Data>>

Returns the last additional record from the message.

The method tries to parse the last record of the additional section as the provided record type. If that succeeds, it returns that parsed record.

If the last record is of the wrong type or parsing fails, returns None.

pub fn remove_last_additional(&mut self) where
    Octets: AsMut<[u8]>, 

Drops the last additional record from the message.

Does so by decreasing the ’arcount.’ Does, however, not change the underlying octet sequence.

Panics

The method panics if the additional section is empty.

pub fn copy_records<'s, R, F, T, O>(
    &'s self,
    target: T,
    op: F
) -> Result<AdditionalBuilder<O>, CopyRecordsError> where
    &'a Octets: OctetsRef,
    R: AsRecord + 's,
    F: FnMut(ParsedRecord<&'s Octets>) -> Option<R>,
    T: Into<AnswerBuilder<O>>,
    O: OctetsBuilder, 

Copy records from a message into the target message builder.

The method uses op to process records from all record sections before inserting, caller can use this closure to filter or manipulate records before inserting.

Trait Implementations

impl<Octets: AsRef<[u8]>> AsRef<[u8]> for Message<Octets>

fn as_ref(&self) -> &[u8]

Performs the conversion.

impl<Octets> AsRef<Octets> for Message<Octets>

fn as_ref(&self) -> &Octets

Performs the conversion.

impl<Octets: Clone> Clone for Message<Octets>

fn clone(&self) -> Message<Octets>

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<Octets: Copy> Copy for Message<Octets>

impl<'a, Octets> IntoIterator for &'a Message<Octets> where
    &'s Octets: OctetsRef, 

type Item = Result<(ParsedRecord<&'a Octets>, Section), ParseError>

The type of the elements being iterated over.

type IntoIter = MessageIter<&'a Octets>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.