Kea  2.3.5-git
isc::dns::Message Class Reference

The Message class encapsulates a standard DNS message. More...

#include <message.h>

Public Types

enum  HeaderFlag {
  HEADERFLAG_QR = 0x8000, HEADERFLAG_AA = 0x0400, HEADERFLAG_TC = 0x0200, HEADERFLAG_RD = 0x0100,
  HEADERFLAG_RA = 0x0080, HEADERFLAG_AD = 0x0020, HEADERFLAG_CD = 0x0010
}
 Constants for flag bit fields of a DNS message header. More...
 
enum  Mode { PARSE = 0, RENDER = 1 }
 Constants to specify the operation mode of the Message. More...
 
enum  ParseOptions { PARSE_DEFAULT = 0, PRESERVE_ORDER = 1 }
 Parse options. More...
 
enum  Section { SECTION_QUESTION = 0, SECTION_ANSWER = 1, SECTION_AUTHORITY = 2, SECTION_ADDITIONAL = 3 }
 Constants to specify sections of a DNS message. More...
 

Public Member Functions

void addQuestion (QuestionPtr question)
 Add a (pointer like object of) Question to the message. More...
 
void addQuestion (const Question &question)
 Add a (pointer like object of) Question to the message. More...
 
void addRRset (const Section section, RRsetPtr rrset)
 Add a (pointer like object of) RRset to the given section of the message. More...
 
void appendSection (const Section section, const Message &source)
 Adds all rrsets from the source the given section in the source message to the same section of this message. More...
 
const QuestionIterator beginQuestion () const
 Return an iterator corresponding to the beginning of the Question section of the message. More...
 
const RRsetIterator beginSection (const Section section) const
 Return an iterator corresponding to the beginning of the given section (other than Question) of the message. More...
 
void clear (Mode mode)
 Clear the message content (if any) and reinitialize it in the specified mode. More...
 
void clearSection (const Section section)
 Remove all RRSets from the given Section. More...
 
const QuestionIterator endQuestion () const
 Return an iterator corresponding to the end of the Question section of the message. More...
 
const RRsetIterator endSection (const Section section) const
 Return an iterator corresponding to the end of the given section (other than Question) of the message. More...
 
void fromWire (isc::util::InputBuffer &buffer, ParseOptions options=PARSE_DEFAULT)
 (Re)build a Message object from wire-format data. More...
 
ConstEDNSPtr getEDNS () const
 Return, if any, the EDNS associated with the message. More...
 
bool getHeaderFlag (const HeaderFlag flag) const
 Return whether the specified header flag bit is set in the header section. More...
 
const OpcodegetOpcode () const
 Return the OPCODE given in the header section of the message. More...
 
qid_t getQid () const
 Return the query ID given in the header section of the message. More...
 
const RcodegetRcode () const
 Return the Response Code of the message. More...
 
unsigned int getRRCount (const Section section) const
 Returns the number of RRs contained in the given section. More...
 
const TSIGRecordgetTSIGRecord () const
 Return, if any, the TSIG record contained in the received message. More...
 
bool hasRRset (const Section section, const Name &name, const RRClass &rrclass, const RRType &rrtype) const
 Determine whether the given section already has an RRset matching the given name, RR class and RR type. More...
 
bool hasRRset (const Section section, const RRsetPtr &rrset) const
 Determine whether the given section already has an RRset matching the one pointed to by the argument. More...
 
void makeResponse ()
 Prepare for making a response from a request. More...
 
void parseHeader (isc::util::InputBuffer &buffer)
 Parse the header section of the Message. More...
 
bool removeRRset (const Section section, RRsetIterator &iterator)
 Remove RRSet from Message. More...
 
void setEDNS (ConstEDNSPtr edns)
 Set EDNS for the message. More...
 
void setHeaderFlag (const HeaderFlag flag, const bool on=true)
 Set or clear the specified header flag bit in the header section. More...
 
void setOpcode (const Opcode &opcode)
 Set the OPCODE of the header section of the message. More...
 
void setQid (qid_t qid)
 Set the query ID of the header section of the message. More...
 
void setRcode (const Rcode &rcode)
 Set the Response Code of the message. More...
 
std::string toText () const
 Convert the Message to a string. More...
 
void toWire (AbstractMessageRenderer &renderer, TSIGContext *tsig_ctx=NULL)
 Render the message in wire formant into a message renderer object with (or without) TSIG. More...
 

Static Public Attributes

Protocol constants
static const uint16_t DEFAULT_MAX_UDPSIZE = 512
 The default maximum size of UDP DNS messages that don't cause truncation. More...
 
static const uint16_t DEFAULT_MAX_EDNS0_UDPSIZE = 4096
 The default maximum size of UDP DNS messages we can handle. More...
 

Constructors and Destructor

Note: The copy constructor and the assignment operator are intentionally defined as private.

The intended use case wouldn't require copies of a Message object; once created, it would normally be expected to be reused, changing the mode from PARSE to RENDER, and vice versa.

 Message (Mode mode)
 The constructor. More...
 
 ~Message ()
 The destructor. More...
 

Detailed Description

The Message class encapsulates a standard DNS message.

Details of the design and interfaces of this class are still in flux. Here are some notes about the current design.

Since many realistic DNS applications deal with messages, message objects will be frequently used, and can be performance sensitive. To minimize the performance overhead of constructing and destructing the objects, this class is designed to be reusable. The clear() method is provided for this purpose.

A Message class object is in either the PARSE or the RENDER mode. A PARSE mode object is intended to be used to convert wire-format message data into a complete Message object. A RENDER mode object is intended to be used to convert a Message object into wire-format data. Some of the method functions of this class are limited to a specific mode. In general, "set" type operations are only allowed for RENDER mode objects. The initial mode must be specified on construction, and can be changed through some method functions.

This class uses the "pimpl" idiom, and hides detailed implementation through the impl_ pointer. Since a Message object is expected to be reused, the construction overhead of this approach should be acceptable.

Open issues (among other things):

  • We may want to provide an "iterator" for all RRsets/RRs for convenience. This will be for applications that do not care about performance much, so the implementation can only be moderately efficient.
  • We may want to provide a "find" method for a specified type of RR in the message.

Definition at line 150 of file message.h.

Member Enumeration Documentation

◆ HeaderFlag

Constants for flag bit fields of a DNS message header.

Only the defined constants are valid where a header flag is required in this library (e.g., in Message::setHeaderFlag()). Since these are enum constants, however, an invalid value could be passed via casting without an error at compilation time. It is generally the callee's responsibility to check and reject invalid values. Of course, applications shouldn't pass invalid values even if the callee does not perform proper validation; the result in such usage is undefined.

In the current implementation, the defined values happen to be a 16-bit integer with one bit being set corresponding to the specified flag in the second 16 bits of the DNS Header section in order to make the internal implementation simpler. For example, HEADERFLAG_QR is defined to be 0x8000 as the QR bit is the most significant bit of the second 16 bits of the header. However, applications should not assume this coincidence and must solely use the enum representations. Any usage based on the assumption of the underlying values is invalid and the result is undefined.

Likewise, bit wise operations such as AND or OR on the flag values are invalid and are not guaranteed to work, even if it could compile with casting. For example, the following code will compile:

const uint16_t combined_flags =
static_cast<uint16_t>(Message::HEADERFLAG_AA) |
static_cast<uint16_t>(Message::HEADERFLAG_CD);
message->setHeaderFlag(static_cast<Message::HeaderFlag>(combined_flags));

and (with the current definition) happens to work as if it were validly written as follows:

message->setHeaderFlag(Message::HEADERFLAG_AA);
message->setHeaderFlag(Message::HEADERFLAG_CD);

But the former notation is invalid and may not work in future versions. We did not try to prohibit such usage at compilation time, e.g., by introducing a separately defined class considering the balance between the complexity and advantage, but hopefully the cast notation is sufficiently ugly to prevent proliferation of the usage.

Enumerator
HEADERFLAG_QR 

Query (if cleared) or response (if set)

HEADERFLAG_AA 

Authoritative answer.

HEADERFLAG_TC 

Truncation.

HEADERFLAG_RD 

Recursion desired.

HEADERFLAG_RA 

Recursion available.

HEADERFLAG_AD 

Authentic data (RFC4035)

HEADERFLAG_CD 

DNSSEC checking disabled (RFC4035)

Definition at line 200 of file message.h.

◆ Mode

Constants to specify the operation mode of the Message.

Enumerator
PARSE 

Parse mode (handling an incoming message)

RENDER 

Render mode (building an outgoing message)

Definition at line 153 of file message.h.

◆ ParseOptions

Parse options.

describe PRESERVE_ORDER: note doesn't affect EDNS or TSIG.

The option values are used as a parameter for fromWire(). These are values of a bitmask type. Bitwise operations can be performed on these values to express compound options.

Enumerator
PARSE_DEFAULT 

The default options.

PRESERVE_ORDER 

Preserve RR order and don't combine them.

Definition at line 594 of file message.h.

◆ Section

Constants to specify sections of a DNS message.

The sections are those defined in RFC 1035 excluding the Header section; the fields of the Header section are accessed via specific methods of the Message class (e.g., getQid()).

Open Design Issue: In the current implementation the values for the constants are sorted in the order of appearance in DNS messages, i.e., from Question to Additional. So, for example, code section >= Message::SECTION_AUTHORITY can be used to do something in or after the Authority section. This would be convenient, but it is not clear if it's really a good idea to rely on relationship between the underlying values of enum constants. At the moment, applications are discouraged to rely on this implementation detail. We will see if such usage is sufficiently common to officially support it.

Note also that since we don't define operator++ for this enum, the following code intending to iterate over all sections will not compile:

for (Section s; s <= SECTION_ADDITIONAL; ++s) { // ++s undefined
// do something
}

This is intentional at this moment, and we'll see if we need to allow that as we have more experiences with this library.

Future Extension: We'll probably also define constants for the section names used in dynamic updates in future versions.

Enumerator
SECTION_QUESTION 

Question section

SECTION_ANSWER 

Answer section.

SECTION_AUTHORITY 

Authority section.

SECTION_ADDITIONAL 

Additional section.

Definition at line 240 of file message.h.

Constructor & Destructor Documentation

◆ Message()

isc::dns::Message::Message ( Mode  mode)

The constructor.

The mode of the message is specified by the mode parameter.

Definition at line 382 of file dns/message.cc.

◆ ~Message()

isc::dns::Message::~Message ( )

The destructor.

Definition at line 386 of file dns/message.cc.

Member Function Documentation

◆ addQuestion() [1/2]

void isc::dns::Message::addQuestion ( QuestionPtr  question)

Add a (pointer like object of) Question to the message.

This method is only allowed in the RENDER mode; if the Message is in other mode, an exception of class InvalidMessageOperation will be thrown.

Definition at line 585 of file dns/message.cc.

References isc::dns::MessageImpl::counts_, isc_throw, isc::dns::MessageImpl::mode_, isc::dns::MessageImpl::questions_, RENDER, and SECTION_QUESTION.

Referenced by addQuestion(), appendSection(), and isc::d2::D2UpdateMessage::setZone().

◆ addQuestion() [2/2]

void isc::dns::Message::addQuestion ( const Question question)

Add a (pointer like object of) Question to the message.

This version internally creates a QuestionPtr object from the given question and calls the other version of this method. So this is inherently less efficient, but is provided because this form may be more intuitive and may make more sense for performance insensitive applications.

This method is only allowed in the RENDER mode; if the Message is in other mode, an exception of class InvalidMessageOperation will be thrown.

Definition at line 596 of file dns/message.cc.

References addQuestion().

+ Here is the call graph for this function:

◆ addRRset()

void isc::dns::Message::addRRset ( const Section  section,
RRsetPtr  rrset 
)

Add a (pointer like object of) RRset to the given section of the message.

Note that addRRset() does not currently check for duplicate data before inserting RRsets. The caller is responsible for checking for these (see hasRRset() below).

Exceptions
InvalidParameterrrset is NULL
InvalidMessageOperationThe message is not in the RENDER mode.
OutOfRangesection doesn't specify a valid Section value.
Parameters
sectionThe message section to which the rrset is to be added
rrsetThe rrset to be added. Must not be NULL.

Definition at line 499 of file dns/message.cc.

References isc::dns::MessageImpl::counts_, isc_throw, isc::dns::MessageImpl::mode_, isc::dns::MessageImpl::NUM_SECTIONS, RENDER, and isc::dns::MessageImpl::rrsets_.

Referenced by isc::d2::D2UpdateMessage::addRRset(), and appendSection().

◆ appendSection()

void isc::dns::Message::appendSection ( const Section  section,
const Message source 
)

Adds all rrsets from the source the given section in the source message to the same section of this message.

Parameters
sectionthe section to append
sourceThe source Message

Definition at line 987 of file dns/message.cc.

References addQuestion(), addRRset(), beginQuestion(), beginSection(), endQuestion(), endSection(), isc_throw, isc::dns::MessageImpl::NUM_SECTIONS, and SECTION_QUESTION.

+ Here is the call graph for this function:

◆ beginQuestion()

const QuestionIterator isc::dns::Message::beginQuestion ( ) const

Return an iterator corresponding to the beginning of the Question section of the message.

Question iterator.

Definition at line 1120 of file dns/message.cc.

Referenced by appendSection(), and isc::d2::D2UpdateMessage::fromWire().

◆ beginSection()

const SectionIterator< RRsetPtr > isc::dns::Message::beginSection ( const Section  section) const

Return an iterator corresponding to the beginning of the given section (other than Question) of the message.

RRsets iterators.

section must be a valid constant of the Section type; otherwise, an exception of class OutOfRange will be thrown.

Definition at line 1133 of file dns/message.cc.

References isc_throw, and isc::dns::MessageImpl::NUM_SECTIONS.

Referenced by appendSection(), and isc::d2::D2UpdateMessage::beginSection().

◆ clear()

void isc::dns::Message::clear ( Mode  mode)

Clear the message content (if any) and reinitialize it in the specified mode.

Definition at line 981 of file dns/message.cc.

Referenced by fromWire().

◆ clearSection()

void isc::dns::Message::clearSection ( const Section  section)

Remove all RRSets from the given Section.

This method is only allowed in the RENDER mode, and the given section must be valid.

Exceptions
InvalidMessageOperationMessage is not in the RENDER mode
OutOfRangeThe specified section is not valid
Parameters
sectionSection to remove all rrsets from

Definition at line 568 of file dns/message.cc.

References isc::dns::MessageImpl::counts_, isc_throw, isc::dns::MessageImpl::mode_, isc::dns::MessageImpl::NUM_SECTIONS, isc::dns::MessageImpl::questions_, RENDER, isc::dns::MessageImpl::rrsets_, and SECTION_QUESTION.

Referenced by isc::d2::D2UpdateMessage::setZone().

◆ endQuestion()

const QuestionIterator isc::dns::Message::endQuestion ( ) const

Return an iterator corresponding to the end of the Question section of the message.

Definition at line 1125 of file dns/message.cc.

Referenced by appendSection().

◆ endSection()

const SectionIterator< RRsetPtr > isc::dns::Message::endSection ( const Section  section) const

Return an iterator corresponding to the end of the given section (other than Question) of the message.

section must be a valid constant of the Section type; otherwise, an exception of class OutOfRange will be thrown.

Definition at line 1146 of file dns/message.cc.

References isc_throw, and isc::dns::MessageImpl::NUM_SECTIONS.

Referenced by appendSection(), and isc::d2::D2UpdateMessage::endSection().

◆ fromWire()

void isc::dns::Message::fromWire ( isc::util::InputBuffer buffer,
ParseOptions  options = PARSE_DEFAULT 
)

(Re)build a Message object from wire-format data.

This method parses the given wire format data to build a complete Message object. On success, the values of the header section fields can be accessible via corresponding get methods, and the question and following sections can be accessible via the corresponding iterators. If the message contains an EDNS or TSIG, they can be accessible via getEDNS() and getTSIGRecord(), respectively.

This Message must be in the PARSE mode.

This method performs strict validation on the given message based on the DNS protocol specifications. If the given message data is invalid, this method throws an exception (see the exception list).

By default, this method combines RRs of the same name, RR type and RR class in a section into a single RRset, even if they are interleaved with a different type of RR (though it would be a rare case in practice). If the PRESERVE_ORDER option is specified, it handles each RR separately, in the appearing order, and converts it to a separate RRset (so this RRset should contain exactly one Rdata). This mode will be necessary when the higher level protocol is ordering conscious. For example, in AXFR and IXFR, the position of the SOA RRs are crucial.

Exceptions
InvalidMessageOperationMessage is in the RENDER mode
DNSMessageFORMERRThe given message data is syntactically
MessageTooShortThe given data is shorter than a valid header section
std::bad_allocMemory allocation failure
OthersName, Rdata, and EDNS classes can also throw
Parameters
bufferA input buffer object that stores the wire data. This method reads from position 0 in the passed buffer.
optionsParse options

Definition at line 635 of file dns/message.cc.

References clear(), isc::dns::MessageImpl::counts_, isc_throw, isc::dns::MessageImpl::mode_, PARSE, parseHeader(), isc::dns::MessageImpl::parseQuestion(), isc::dns::MessageImpl::parseSection(), SECTION_ADDITIONAL, SECTION_ANSWER, SECTION_AUTHORITY, SECTION_QUESTION, and isc::util::InputBuffer::setPosition().

Referenced by isc::d2::D2UpdateMessage::fromWire().

+ Here is the call graph for this function:

◆ getEDNS()

ConstEDNSPtr isc::dns::Message::getEDNS ( ) const

Return, if any, the EDNS associated with the message.

This method never throws an exception.

Returns
A shared pointer to the EDNS. This will be a null shared pointer if the message is not associated with EDNS.

Definition at line 467 of file dns/message.cc.

References isc::dns::MessageImpl::edns_.

◆ getHeaderFlag()

bool isc::dns::Message::getHeaderFlag ( const HeaderFlag  flag) const

Return whether the specified header flag bit is set in the header section.

This method is basically exception free, but if flag is not a valid constant of the HeaderFlag type, an exception of class InvalidParameter will be thrown.

Parameters
flagThe header flag constant to test.
Returns
true if the specified flag is set; otherwise false.

Definition at line 391 of file dns/message.cc.

References isc::dns::MessageImpl::flags_, and isc_throw.

Referenced by isc::d2::D2UpdateMessage::getQRFlag(), and toText().

◆ getOpcode()

const Opcode & isc::dns::Message::getOpcode ( ) const

Return the OPCODE given in the header section of the message.

The message must have been properly parsed (in the case of the PARSE mode) or an Opcode has been set (in the case of the RENDER mode) beforehand. Otherwise, an exception of class InvalidMessageOperation will be thrown.

Definition at line 450 of file dns/message.cc.

References isc_throw, and isc::dns::MessageImpl::opcode_.

Referenced by isc::d2::D2UpdateMessage::fromWire().

◆ getQid()

qid_t isc::dns::Message::getQid ( ) const

Return the query ID given in the header section of the message.

Definition at line 419 of file dns/message.cc.

References isc::dns::MessageImpl::qid_.

Referenced by isc::d2::D2UpdateMessage::getId().

◆ getRcode()

const Rcode & isc::dns::Message::getRcode ( ) const

Return the Response Code of the message.

This includes extended codes specified by an EDNS OPT RR (when included). In the PARSE mode, if the received message contains an EDNS OPT RR, the corresponding extended code is identified and returned.

The message must have been properly parsed (in the case of the PARSE mode) or an Rcode has been set (in the case of the RENDER mode) beforehand. Otherwise, an exception of class InvalidMessageOperation will be thrown.

Definition at line 433 of file dns/message.cc.

References isc_throw, and isc::dns::MessageImpl::rcode_.

Referenced by isc::d2::D2UpdateMessage::getRcode().

◆ getRRCount()

unsigned int isc::dns::Message::getRRCount ( const Section  section) const

Returns the number of RRs contained in the given section.

In the PARSE mode, the returned value may not be identical to the actual number of RRs of the incoming message that is parsed. The Message class handles some "meta" RRs such as EDNS OPT RR separately. This method doesn't include such RRs. Also, a future version of the parser will detect and unify duplicate RRs (which should be rare in practice though), in which case the stored RRs in the Message object will be fewer than the RRs originally contained in the incoming message.

Likewise, in the RENDER mode, even if EDNS is set in the Message, this method doesn't count the corresponding OPT RR in the Additional section.

This method is basically exception free, but if section is not a valid constant of the Section type, an exception of class OutOfRange will be thrown.

Parameters
sectionThe section in the message where RRs should be counted.
Returns
The number of RRs stored in the specified section of the message.

Definition at line 491 of file dns/message.cc.

References isc::dns::MessageImpl::counts_, isc_throw, and isc::dns::MessageImpl::NUM_SECTIONS.

Referenced by isc::d2::D2UpdateMessage::getRRCount(), and isc::d2::D2UpdateMessage::setZone().

◆ getTSIGRecord()

const TSIGRecord * isc::dns::Message::getTSIGRecord ( ) const

Return, if any, the TSIG record contained in the received message.

Currently, this method is only intended to return a TSIG record for an incoming message built via the fromWire() method in the PARSE mode. A call to this method in the RENDER mode is invalid and result in an exception. Also, calling this method is meaningless unless fromWire() is performed.

The returned pointer is valid only during the lifetime of the Message object and until clear() is called. The Message object retains the ownership of TSIGRecord; the caller must not try to delete it.

Exceptions
InvalidMessageOperationMessage is not in the PARSE mode.
Returns
A pointer to the stored TSIGRecord or NULL.

Definition at line 481 of file dns/message.cc.

References isc_throw, isc::dns::MessageImpl::mode_, PARSE, and isc::dns::MessageImpl::tsig_rr_.

Referenced by isc::d2::D2UpdateMessage::fromWire().

◆ hasRRset() [1/2]

bool isc::dns::Message::hasRRset ( const Section  section,
const Name name,
const RRClass rrclass,
const RRType rrtype 
) const

Determine whether the given section already has an RRset matching the given name, RR class and RR type.

section must be a valid constant of the Section type; otherwise, an exception of class OutOfRange will be thrown.

This should probably be extended to be a "find" method that returns a matching RRset if found.

Definition at line 518 of file dns/message.cc.

References isc_throw, isc::dns::MessageImpl::NUM_SECTIONS, and isc::dns::MessageImpl::rrsets_.

Referenced by hasRRset().

◆ hasRRset() [2/2]

bool isc::dns::Message::hasRRset ( const Section  section,
const RRsetPtr rrset 
) const

Determine whether the given section already has an RRset matching the one pointed to by the argument.

section must be a valid constant of the Section type; otherwise, an exception of class OutOfRange will be thrown.

Definition at line 537 of file dns/message.cc.

References hasRRset().

+ Here is the call graph for this function:

◆ makeResponse()

void isc::dns::Message::makeResponse ( )

Prepare for making a response from a request.

This will clear the DNS header except those fields that should be kept for the response, and clear answer and the following sections. See also dns_message_reply() of BIND9.

Definition at line 1008 of file dns/message.cc.

References HEADERFLAG_QR, isc_throw, PARSE, RENDER, SECTION_ADDITIONAL, SECTION_ANSWER, SECTION_AUTHORITY, and setHeaderFlag().

+ Here is the call graph for this function:

◆ parseHeader()

void isc::dns::Message::parseHeader ( isc::util::InputBuffer buffer)

Parse the header section of the Message.

NOTE: If the header has already been parsed by a previous call to this method, this method simply returns (i.e., it does not read from the buffer).

Definition at line 606 of file dns/message.cc.

References isc::dns::MessageImpl::counts_, isc::dns::MessageImpl::flags_, isc::util::InputBuffer::getLength(), isc::util::InputBuffer::getPosition(), isc::dns::MessageImpl::header_parsed_, isc_throw, isc::dns::MessageImpl::mode_, PARSE, isc::dns::MessageImpl::qid_, isc::util::InputBuffer::readUint16(), SECTION_ADDITIONAL, SECTION_ANSWER, SECTION_AUTHORITY, SECTION_QUESTION, isc::dns::MessageImpl::setOpcode(), and isc::dns::MessageImpl::setRcode().

Referenced by fromWire().

+ Here is the call graph for this function:

◆ removeRRset()

bool isc::dns::Message::removeRRset ( const Section  section,
RRsetIterator iterator 
)

Remove RRSet from Message.

Removes the RRset identified by the section iterator from the message. Note: if,.for some reason, the RRset is duplicated in the section, only one occurrence is removed.

If the operation is successful, all iterators into the section are invalidated.

Parameters
sectionSection to which the iterator belongs
iteratorIterator pointing to the element to be removed
Returns
true if the element was removed, false if the iterator was not found in the specified section.

Definition at line 543 of file dns/message.cc.

References isc::dns::MessageImpl::counts_, isc_throw, isc::dns::MessageImpl::NUM_SECTIONS, and isc::dns::MessageImpl::rrsets_.

◆ setEDNS()

void isc::dns::Message::setEDNS ( ConstEDNSPtr  edns)

Set EDNS for the message.

This method is only allowed in the RENDER mode; if the Message is in other mode, an exception of class InvalidMessageOperation will be thrown.

Parameters
ednsA shared pointer to an EDNS object to be set in Message.

Definition at line 472 of file dns/message.cc.

References isc::dns::MessageImpl::edns_, isc_throw, isc::dns::MessageImpl::mode_, and RENDER.

◆ setHeaderFlag()

void isc::dns::Message::setHeaderFlag ( const HeaderFlag  flag,
const bool  on = true 
)

Set or clear the specified header flag bit in the header section.

The optional parameter on indicates the operation mode, set or clear; if it's true the corresponding flag will be set; otherwise the flag will be cleared. In either case the original state of the flag does not affect the operation; for example, if a flag is already set and the "set" operation is attempted, it effectively results in no operation.

The parameter on can be omitted, in which case a value of true (i.e., set operation) will be assumed. This is based on the observation that the flag would have to be set in the vast majority of the cases where an application needs to use this method.

This method is only allowed in the RENDER mode; if the Message is in other mode, an exception of class InvalidMessageOperation will be thrown.

If flag is not a valid constant of the HeaderFlag type, an exception of class InvalidParameter will be thrown.

Parameters
flagThe header flag constant to set or clear.
onIf true the flag will be set; otherwise the flag will be cleared.

Definition at line 401 of file dns/message.cc.

References isc::dns::MessageImpl::flags_, isc_throw, isc::dns::MessageImpl::mode_, and RENDER.

Referenced by isc::d2::D2UpdateMessage::D2UpdateMessage(), and makeResponse().

◆ setOpcode()

void isc::dns::Message::setOpcode ( const Opcode opcode)

Set the OPCODE of the header section of the message.

This method is only allowed in the RENDER mode; if the Message is in other mode, an exception of class InvalidMessageOperation will be thrown.

Definition at line 458 of file dns/message.cc.

References isc_throw, isc::dns::MessageImpl::mode_, RENDER, and isc::dns::MessageImpl::setOpcode().

Referenced by isc::d2::D2UpdateMessage::D2UpdateMessage().

+ Here is the call graph for this function:

◆ setQid()

void isc::dns::Message::setQid ( qid_t  qid)

Set the query ID of the header section of the message.

This method is only allowed in the RENDER mode; if the Message is in other mode, an exception of class InvalidMessageOperation will be thrown.

Definition at line 424 of file dns/message.cc.

References isc_throw, isc::dns::MessageImpl::mode_, isc::dns::MessageImpl::qid_, and RENDER.

Referenced by isc::d2::D2UpdateMessage::setId().

◆ setRcode()

void isc::dns::Message::setRcode ( const Rcode rcode)

Set the Response Code of the message.

This method is only allowed in the RENDER mode; if the Message is in other mode, an exception of class InvalidMessageOperation will be thrown.

If the specified code is an EDNS extended RCODE, an EDNS OPT RR will be included in the message.

Definition at line 441 of file dns/message.cc.

References isc_throw, isc::dns::MessageImpl::mode_, RENDER, and isc::dns::MessageImpl::setRcode().

Referenced by isc::dns::MessageImpl::addEDNS(), isc::d2::D2UpdateMessage::D2UpdateMessage(), and isc::d2::D2UpdateMessage::setRcode().

+ Here is the call graph for this function:

◆ toText()

string isc::dns::Message::toText ( ) const

Convert the Message to a string.

At least Opcode and Rcode must be validly set in the Message (as a result of parse in the PARSE mode or by explicitly setting in the RENDER mode); otherwise, an exception of class InvalidMessageOperation will be thrown.

Definition at line 882 of file dns/message.cc.

References getHeaderFlag(), HEADERFLAG_AA, HEADERFLAG_AD, HEADERFLAG_CD, HEADERFLAG_QR, HEADERFLAG_RA, HEADERFLAG_RD, HEADERFLAG_TC, isc_throw, SECTION_ADDITIONAL, SECTION_ANSWER, SECTION_AUTHORITY, and SECTION_QUESTION.

Referenced by isc::dns::operator<<().

+ Here is the call graph for this function:

◆ toWire()

void isc::dns::Message::toWire ( AbstractMessageRenderer renderer,
TSIGContext tsig_ctx = NULL 
)

Render the message in wire formant into a message renderer object with (or without) TSIG.

This Message must be in the RENDER mode and both Opcode and Rcode must have been set beforehand; otherwise, an exception of class InvalidMessageOperation will be thrown.

If a non-NULL tsig_ctx is passed, it will also add a TSIG RR with (in many cases) the TSIG MAC for the message along with the given TSIG context (tsig_ctx). The TSIG RR will be placed at the end of renderer. The TSIGContext at tsig_ctx will be updated based on the fact it was used for signing and with the latest MAC.

Exceptions
InvalidMessageOperationThe message is not in the Render mode, or either Rcode or Opcode is not set.
InvalidParameterThe allowable limit of renderer is too small for a TSIG or the Header section. Note that this shouldn't happen with parameters as defined in the standard protocols, so it's more likely a program bug.
UnexpectedRendering the TSIG RR fails. The implementation internally makes sure this doesn't happen, so if that ever occurs it should mean a bug either in the TSIG context or in the renderer implementation.
Note
The renderer's internal buffers and data are automatically cleared, keeping the length limit and the compression mode intact. In case truncation is triggered, the renderer is cleared completely.
Parameters
rendererDNS message rendering context that encapsulates the output buffer and name compression information.
tsig_ctxA TSIG context that is to be used for signing the message

Definition at line 601 of file dns/message.cc.

References isc::dns::MessageImpl::toWire().

Referenced by isc::d2::D2UpdateMessage::toWire().

+ Here is the call graph for this function:

Member Data Documentation

◆ DEFAULT_MAX_EDNS0_UDPSIZE

const uint16_t isc::dns::Message::DEFAULT_MAX_EDNS0_UDPSIZE = 4096
static

The default maximum size of UDP DNS messages we can handle.

Definition at line 656 of file message.h.

◆ DEFAULT_MAX_UDPSIZE

const uint16_t isc::dns::Message::DEFAULT_MAX_UDPSIZE = 512
static

The default maximum size of UDP DNS messages that don't cause truncation.

With EDNS the maximum size can be increased per message.

Definition at line 653 of file message.h.


The documentation for this class was generated from the following files: