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

The Question class encapsulates the common search key of DNS lookup, consisting of owner name, RR type and RR class. More...

#include <question.h>

Public Member Functions

Constructors and Destructor

We use the default versions of destructor, copy constructor, and assignment operator.

The default constructor is hidden as a result of defining the other constructors. This is intentional; we don't want to allow a Question object to be constructed with an invalid state.

 Question (isc::util::InputBuffer &buffer)
 Constructor from wire-format data. More...
 
 Question (const Name &name, const RRClass &rrclass, const RRType &rrtype)
 Constructor from fixed parameters of the Question. More...
 
Getter Methods
const NamegetName () const
 Returns the owner name of the Question. More...
 
const RRTypegetType () const
 Returns the RR Class of the Question. More...
 
const RRClassgetClass () const
 Returns the RR Type of the Question. More...
 
Converter Methods
std::string toText (bool newline=false) const
 Convert the Question to a string. More...
 
unsigned int toWire (AbstractMessageRenderer &renderer) const
 Render the Question in the wire format with name compression. More...
 
unsigned int toWire (isc::util::OutputBuffer &buffer) const
 Render the Question in the wire format without name compression. More...
 
Comparison Operators
bool operator< (const Question &rhs) const
 A "less than" operator is needed for this class so it can function as an index to std::map. More...
 
bool operator== (const Question &rhs) const
 Equality operator. More...
 
bool operator!= (const Question &rhs) const
 Inequality operator. More...
 

Detailed Description

The Question class encapsulates the common search key of DNS lookup, consisting of owner name, RR type and RR class.

The primarily intended use case of this class is an entry of the question section of DNS messages. This could also be used as a general purpose lookup key, e.g., in a custom implementation of DNS database.

In this initial implementation, the Question class is defined as a concrete class; it's not expected to be inherited by a user-defined customized class. It may be worth noting that it's different from the design of the RRset classes (AbstractRRset and its derived classes). The RRset classes form an inheritance hierarchy from the base abstract class. This may look odd in that an "RRset" and "Question" are similar from the protocol point of view: Both are used as a semantics unit of DNS messages; both share the same set of components (name, RR type and RR class).

In fact, BIND9 didn't introduce a separate data structure for Questions, and use the same "rdataset" structure for both RRsets and Questions. We could take the same approach, but chose to adopt the different design. One reason for that is because a Question and an RRset are still different, and a Question might not be cleanly defined, e.g., if it were a derived class of some "RRset-like" class. For example, we couldn't give a reasonable semantics for getTTL() or setTTL() methods for a Question, since it's not associated with the TTL. In fact, the BIND9 implementation ended up often separating the case where a "rdataset" is from the Question section of a DNS message and the case where it comes from other sections. If we cannot treat them completely transparently anyway, separating the class (type) would make more sense because we can exploit compilation time type checks.

On the other hand, we do not expect a strong need for customizing the Question class, unlike the RRset. Handling the "Question" section of a DNS message is relatively a simple work comparing to RRset-involved operations, so a unified straightforward implementation should suffice for any use cases including performance sensitive ones.

We may, however, still want to have a customized version of Question for, e.g, highly optimized behavior, and may revisit this design choice as we have more experience with this implementation.

One disadvantage of defining RRsets and Questions as unrelated classes is that we cannot handle them in a polymorphic way. For example, we might want to iterate over DNS message sections and render the data in the wire format, whether it's an RRset or a Question. If a Question were a derived class of some common RRset-like class, we could do this by calling rrset_or_question->toWire(). But the actual design doesn't allow this approach, which may require duplicate code for almost the same operation. To mitigate this problem, we intentionally used the same names with the same signature for some common methods of Question and AbstractRRset such as getName() or toWire(). So the user class may use a template function that is applicable to both Question and RRset to avoid writing duplicate code logic.

Definition at line 95 of file question.h.

Constructor & Destructor Documentation

◆ Question() [1/2]

isc::dns::Question::Question ( isc::util::InputBuffer buffer)

Constructor from wire-format data.

It simply constructs a set of Name, RRType, and RRClass object from the buffer in this order, and constructs a Question object in a straightforward way.

It may throw an exception if the construction of these component classes fails.

Parameters
bufferA buffer storing the wire format data.

Definition at line 24 of file question.cc.

◆ Question() [2/2]

isc::dns::Question::Question ( const Name name,
const RRClass rrclass,
const RRType rrtype 
)
inline

Constructor from fixed parameters of the Question.

This constructor is basically expected to be exception free, but copying the name may involve resource allocation, and if it fails the corresponding standard exception will be thrown.

Parameters
nameThe owner name of the Question.
rrclassThe RR class of the Question.
rrtypeThe RR type of the Question.

Definition at line 128 of file question.h.

References name_.

Member Function Documentation

◆ getClass()

const RRClass& isc::dns::Question::getClass ( ) const
inline

Returns the RR Type of the Question.

This method never throws an exception.

Returns
A reference to a RRType class object corresponding to the RR type of the Question.

Definition at line 159 of file question.h.

References name_, isc::data::operator<(), rrclass_, and rrtype_.

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

+ Here is the call graph for this function:

◆ getName()

const Name& isc::dns::Question::getName ( ) const
inline

Returns the owner name of the Question.

This method never throws an exception.

Returns
A reference to a Name class object corresponding to the Question owner name.

Definition at line 143 of file question.h.

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

◆ getType()

const RRType& isc::dns::Question::getType ( ) const
inline

Returns the RR Class of the Question.

This method never throws an exception.

Returns
A reference to a RRClass class object corresponding to the RR class of the Question.

Definition at line 151 of file question.h.

References rrtype_.

◆ operator!=()

bool isc::dns::Question::operator!= ( const Question rhs) const
inline

Inequality operator.

Primarily used to compare the question section in a response to that in the query.

Parameters
rhsQuestion to compare against
Returns
true if one or more of the name, class and type do not match, false otherwise.

Definition at line 259 of file question.h.

References name_, isc::util::operator<<(), rrclass_, and rrtype_.

+ Here is the call graph for this function:

◆ operator<()

bool isc::dns::Question::operator< ( const Question rhs) const
inline

A "less than" operator is needed for this class so it can function as an index to std::map.

Definition at line 236 of file question.h.

◆ operator==()

bool isc::dns::Question::operator== ( const Question rhs) const
inline

Equality operator.

Primarily used to compare the question section in a response to that in the query.

Parameters
rhsQuestion to compare against
Returns
true if name, class and type are equal, false otherwise

Definition at line 248 of file question.h.

References name_, rrclass_, and rrtype_.

◆ toText()

std::string isc::dns::Question::toText ( bool  newline = false) const

Convert the Question to a string.

When newline argument is true, this method terminates the resulting string with a trailing newline character (following the BIND9 convention).

This method simply calls the toText() methods of the corresponding Name, RRType and RRClass classes for this Question, and these methods may throw an exception. In particular, if resource allocation fails, a corresponding standard exception will be thrown.

Parameters
newlineWhether to add a trailing newline. If true, a trailing newline is added. If false, no trailing newline is added.
Returns
A string representation of the Question.

Definition at line 38 of file question.cc.

References isc::dns::RRType::toText(), isc::dns::RRClass::toText(), and isc::dns::Name::toText().

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

+ Here is the call graph for this function:

◆ toWire() [1/2]

unsigned int isc::dns::Question::toWire ( AbstractMessageRenderer renderer) const

Render the Question in the wire format with name compression.

This method simply calls the toWire() methods of the corresponding Name, RRType and RRClass classes for this Question, and these methods may throw an exception. In particular, if resource allocation fails, a corresponding standard exception will be thrown.

This method returns 1, which is the number of "questions" contained in the Question. This is a meaningless value, but is provided to be consistent with the corresponding method of AbstractRRset (see the detailed class description).

The owner name will be compressed if possible, although it's an unlikely event in practice because the Question section a DNS message normally doesn't contain multiple question entries and it's located right after the Header section. Nevertheless, renderer records the information of the owner name so that it can be pointed by other RRs in other sections (which is more likely to happen).

It could be possible, though very rare in practice, that an attempt to render a Question may cause truncation (when the Question section contains a large number of entries). In such a case this method avoid the rendering and indicate the truncation in the renderer. This method returns 0 in this case.

Parameters
rendererDNS message rendering context that encapsulates the output buffer and name compression information.
Returns
1 on success; 0 if it causes truncation

Definition at line 58 of file question.cc.

References isc::dns::AbstractMessageRenderer::getLength(), isc::dns::AbstractMessageRenderer::getLengthLimit(), isc::dns::AbstractMessageRenderer::setTruncated(), isc::dns::RRType::toWire(), isc::dns::RRClass::toWire(), isc::dns::AbstractMessageRenderer::trim(), and isc::dns::AbstractMessageRenderer::writeName().

+ Here is the call graph for this function:

◆ toWire() [2/2]

unsigned int isc::dns::Question::toWire ( isc::util::OutputBuffer buffer) const

Render the Question in the wire format without name compression.

This method behaves like the render version except it doesn't compress the owner name. See toWire(AbstractMessageRenderer& renderer)const.

Parameters
bufferAn output buffer to store the wire data.
Returns
1

Definition at line 49 of file question.cc.

References isc::dns::RRType::toWire(), isc::dns::RRClass::toWire(), and isc::dns::Name::toWire().

+ Here is the call graph for this function:

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