Kea: isc::dns::Message Class Reference

| Kea 3.2.0-git

isc::dns::Message Class Reference

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

`#include <message.h>`

## Public Types
enum | HeaderFlag : uint16_t { 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 : uint16_t { 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 : uint16_t

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));
isc::dns::Message::HeaderFlag
HeaderFlag
Constants for flag bit fields of a DNS message header.
Definition message.h:202
isc::dns::Message::HEADERFLAG_AA
@ HEADERFLAG_AA
Definition message.h:204
isc::dns::Message::HEADERFLAG_CD
@ HEADERFLAG_CD
Definition message.h:209

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 : uint16_t

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
}
isc::dns::Message::Section
Section
Constants to specify sections of a DNS message.
Definition message.h:242
isc::dns::Message::SECTION_ADDITIONAL
@ SECTION_ADDITIONAL
Definition message.h:246

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.

Referenced by ~Message(), and appendSection().

## ◆ ~Message()

isc::dns::Message::~Message | ( |  | ) |
| default

The destructor.

References Message().

Here is the call graph for this function:

## 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(), and appendSection().

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

References Message(), 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 1126 of file dns/message.cc.

Referenced by appendSection().

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

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

Referenced by appendSection().

## ◆ clear()

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

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

Definition at line 989 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.

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

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

Referenced by appendSection().

## ◆ 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().

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

## ◆ 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.

## ◆ 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.

## ◆ 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.

## ◆ 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 1012 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 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.

## ◆ 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.

## ◆ 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.

## ◆ 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 890 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.

## 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:

- message.h
- dns/message.cc