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	Section { SECTION_QUESTION = 0 , SECTION_ANSWER = 1 , SECTION_AUTHORITY = 2 , SECTION_ADDITIONAL = 3 }
	Constants to specify sections of a DNS message. 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.
enum	ParseOptions { PARSE_DEFAULT = 0 , PRESERVE_ORDER = 1 }
	Parse options. More...

	Message (Mode mode)
	The constructor.

	~Message ()=default
	The destructor.

bool	getHeaderFlag (const HeaderFlag flag) const
	Return whether the specified header flag bit is set in the header section.

void	setHeaderFlag (const HeaderFlag flag, const bool on=true)
	Set or clear the specified header flag bit in the header section.

qid_t	getQid () const
	Return the query ID given in the header section of the message.

void	setQid (qid_t qid)
	Set the query ID of the header section of the message.

const Rcode &	getRcode () const
	Return the Response Code of the message.

void	setRcode (const Rcode &rcode)
	Set the Response Code of the message.

const Opcode &	getOpcode () const
	Return the OPCODE given in the header section of the message.

void	setOpcode (const Opcode &opcode)
	Set the OPCODE of the header section of the message.

ConstEDNSPtr	getEDNS () const
	Return, if any, the EDNS associated with the message.

void	setEDNS (ConstEDNSPtr edns)
	Set EDNS for the message.

const TSIGRecord *	getTSIGRecord () const
	Return, if any, the TSIG record contained in the received message.

unsigned int	getRRCount (const Section section) const
	Returns the number of RRs contained in the given section.

const QuestionIterator	beginQuestion () const
	Return an iterator corresponding to the beginning of the Question section of the message.

const QuestionIterator	endQuestion () const
	Return an iterator corresponding to the end of the Question section of the message.

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

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

void	addQuestion (QuestionPtr question)
	Add a (pointer like object of) Question to the message.

void	addQuestion (const Question &question)
	Add a (pointer like object of) Question to the message.

void	addRRset (const Section section, RRsetPtr rrset)
	Add a (pointer like object of) RRset to the given section of the message.

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.

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.

bool	removeRRset (const Section section, RRsetIterator &iterator)
	Remove RRSet from Message.

void	clearSection (const Section section)
	Remove all RRSets from the given Section.

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

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.

void	makeResponse ()
	Prepare for making a response from a request.

std::string	toText () const
	Convert the Message to a string.

void	toWire (AbstractMessageRenderer &renderer, TSIGContext *tsig_ctx=0)
	Render the message in wire formant into a message renderer object with (or without) TSIG.

void	parseHeader (isc::util::InputBuffer &buffer)
	Parse the header section of the `Message`.

void	fromWire (isc::util::InputBuffer &buffer, ParseOptions options=PARSE_DEFAULT)
	(Re)build a `Message` object from wire-format data.

Protocol constants
static const uint16_t	DEFAULT_MAX_UDPSIZE = 512
	The default maximum size of UDP DNS messages that don't cause truncation.

static const uint16_t	DEFAULT_MAX_EDNS0_UDPSIZE = 4096
	The default maximum size of UDP DNS messages we can handle.

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 152 of file message.h.

Member Enumeration Documentation

◆ HeaderFlag

enum isc::dns::Message::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
HEADERFLAG_AA
HEADERFLAG_TC
HEADERFLAG_RD
HEADERFLAG_RA
HEADERFLAG_AD
HEADERFLAG_CD

Definition at line 202 of file message.h.

◆ Mode

enum isc::dns::Message::Mode

Constants to specify the operation mode of the Message.

Enumerator
PARSE
RENDER

Definition at line 155 of file message.h.

◆ ParseOptions

enum isc::dns::Message::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
PRESERVE_ORDER

Definition at line 596 of file message.h.

◆ Section

enum isc::dns::Message::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
SECTION_ANSWER
SECTION_AUTHORITY
SECTION_ADDITIONAL

Definition at line 242 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 388 of file dns/message.cc.

◆ ~Message()

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

default

The destructor.

Member Function Documentation

◆ addQuestion() [1/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:

◆ addQuestion() [2/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_throw, RENDER, and SECTION_QUESTION.

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

◆ 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

InvalidParameter	rrset is null
InvalidMessageOperation	The message is not in the `RENDER` mode.
OutOfRange	`section` doesn't specify a valid `Section` value.

Parameters

section	The message section to which the rrset is to be added
rrset	The rrset to be added. Must not be null.

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

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

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

section	the section to append
source	The source Message

Definition at line 993 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 1124 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 1137 of file dns/message.cc.

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

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 987 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

InvalidMessageOperation	Message is not in the `RENDER` mode
OutOfRange	The specified section is not valid

Parameters

section Section to remove all rrsets from

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

References isc_throw, isc::dns::MessageImpl::NUM_SECTIONS, RENDER, 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 1129 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 1150 of file dns/message.cc.

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

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

InvalidMessageOperation	`Message` is in the RENDER mode
DNSMessageFORMERR	The given message data is syntactically
MessageTooShort	The given data is shorter than a valid header section
std::bad_alloc	Memory allocation failure
Others	`Name`, `Rdata`, and `EDNS` classes can also throw

Parameters

buffer	A input buffer object that stores the wire data. This method reads from position 0 in the passed buffer.
options	Parse options

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

References clear(), isc_throw, PARSE, parseHeader(), 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 469 of file dns/message.cc.

◆ 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

flag	The header flag constant to test.

Returns: true if the specified flag is set; otherwise false.

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

References 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 452 of file dns/message.cc.

References isc_throw.

◆ getQid()

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

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

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

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 435 of file dns/message.cc.

References isc_throw.

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

section The 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 493 of file dns/message.cc.

References 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

InvalidMessageOperation Message is not in the PARSE mode.

Returns: A pointer to the stored TSIGRecord or null.

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

References isc_throw, and PARSE.

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 520 of file dns/message.cc.

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

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 538 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 1010 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::util::InputBuffer::getLength(), isc::util::InputBuffer::getPosition(), isc_throw, PARSE, isc::util::InputBuffer::readUint16(), SECTION_ADDITIONAL, SECTION_ANSWER, SECTION_AUTHORITY, and SECTION_QUESTION.

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

section	Section to which the iterator belongs
iterator	Iterator 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 544 of file dns/message.cc.

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

◆ 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

edns	A shared pointer to an `EDNS` object to be set in `Message`.

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

References isc_throw, 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

flag	The header flag constant to set or clear.
on	If `true` the flag will be set; otherwise the flag will be cleared.

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

References isc_throw, 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 460 of file dns/message.cc.

References isc_throw, and RENDER.

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

◆ 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 426 of file dns/message.cc.

References isc_throw, 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 443 of file dns/message.cc.

References isc_throw, and RENDER.

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

◆ 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 888 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 = `0`
	)

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

InvalidMessageOperation	The message is not in the Render mode, or either Rcode or Opcode is not set.
InvalidParameter	The 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.
Unexpected	Rendering 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

renderer	DNS message rendering context that encapsulates the output buffer and name compression information.
tsig_ctx	A TSIG context that is to be used for signing the message

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

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

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 657 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 654 of file message.h.

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

Public Types

Constructors and Destructor

Protocol constants

Detailed Description

Member Enumeration Documentation

◆ HeaderFlag

◆ Mode

◆ ParseOptions

◆ Section

Constructor & Destructor Documentation

◆ Message()

◆ ~Message()

Member Function Documentation

◆ addQuestion() [1/2]

◆ addQuestion() [2/2]

◆ addRRset()

◆ appendSection()

◆ beginQuestion()

◆ beginSection()

◆ clear()

◆ clearSection()

◆ endQuestion()

◆ endSection()

◆ fromWire()

◆ getEDNS()

◆ getHeaderFlag()

◆ getOpcode()

◆ getQid()

◆ getRcode()

◆ getRRCount()

◆ getTSIGRecord()

◆ hasRRset() [1/2]

◆ hasRRset() [2/2]

◆ makeResponse()

◆ parseHeader()

◆ removeRRset()

◆ setEDNS()

◆ setHeaderFlag()

◆ setOpcode()

◆ setQid()

◆ setRcode()

◆ toText()

◆ toWire()

Member Data Documentation

◆ DEFAULT_MAX_EDNS0_UDPSIZE

◆ DEFAULT_MAX_UDPSIZE