Kea: isc::dns::AbstractMessageRenderer Class Reference

| Kea 2.2.0

Public Types | List of all members
isc::dns::AbstractMessageRenderer Class Referenceabstract

The `AbstractMessageRenderer` class is an abstract base class that provides common interfaces for rendering a DNS message into a buffer in wire format. More...

`#include <messagerenderer.h>`

Inheritance diagram for isc::dns::AbstractMessageRenderer:
[legend]

## Public Types
enum | CompressMode { CASE_INSENSITIVE , CASE_SENSITIVE }
| Compression mode constants. More...

## Public Member Functions
Getter Methods
const void * | getData () const
| Return a pointer to the head of the data stored in the internal buffer. More...
size_t | getLength () const
| Return the length of data written in the internal buffer. More...
virtual bool | isTruncated () const =0
| Return whether truncation has occurred while rendering. More...
virtual size_t | getLengthLimit () const =0
| Return the maximum length of rendered data that can fit in the corresponding DNS message without truncation. More...
virtual CompressMode | getCompressMode () const =0
| Return the compression mode of the renderer class object. More...
Setter Methods
void | setBuffer (isc::util::OutputBuffer *buffer)
| Set or reset a temporary output buffer. More...
virtual void | setTruncated ()=0
| Mark the renderer to indicate truncation has occurred while rendering. More...
virtual void | setLengthLimit (size_t len)=0
| Set the maximum length of rendered data that can fit in the corresponding DNS message without truncation. More...
virtual void | setCompressMode (CompressMode mode)=0
| Set the compression mode of the renderer class object. More...
Methods for writing data into the internal buffer.
void | skip (size_t len)
| Insert a specified length of gap at the end of the buffer. More...
void | trim (size_t len)
| Trim the specified length of data from the end of the internal buffer. More...
virtual void | clear ()
| Clear the internal buffer and other internal resources. More...
void | writeUint8 (const uint8_t data)
| Write an unsigned 8-bit integer into the internal buffer. More...
void | writeUint16 (uint16_t data)
| Write an unsigned 16-bit integer in host byte order into the internal buffer in network byte order. More...
void | writeUint16At (uint16_t data, size_t pos)
| Write an unsigned 16-bit integer in host byte order at the specified position of the internal buffer in network byte order. More...
void | writeUint32 (uint32_t data)
| Write an unsigned 32-bit integer in host byte order into the internal buffer in network byte order. More...
void | writeData (const void *data, size_t len)
| Copy an arbitrary length of data into the internal buffer of the renderer object. More...
virtual void | writeName (const Name &name, bool compress=true)=0
| Write a `Name` object into the internal buffer in wire format, with or without name compression. More...
virtual void | writeName (const LabelSequence &ls, bool compress=true)=0
| Write a `LabelSequence` object into the internal buffer in wire format, with or without name compression. More...

## Constructors and Destructor
| AbstractMessageRenderer ()
| The default constructor. More...
const isc::util::OutputBuffer & | getBuffer () const
| Return the output buffer we render into. More...
isc::util::OutputBuffer & | getBuffer ()
virtual | ~AbstractMessageRenderer ()
| The destructor. More...

## Detailed Description

The `AbstractMessageRenderer` class is an abstract base class that provides common interfaces for rendering a DNS message into a buffer in wire format.

A specific derived class of `AbstractMessageRenderer` (we call it a renderer class hereafter) is simply responsible for name compression at least in the current design. A renderer class object (conceptually) manages the positions of names rendered in some sort of buffer and uses that information to render subsequent names with compression.

A renderer class is mainly intended to be used as a helper for a more comprehensive `Message` class internally; normal applications won't have to care about details of this class.

By default any (derived) renderer class object is associated with an internal buffer, and subsequent write operations will be performed on that buffer. The rendering result can be retrieved via the `getData()` method.

If an application wants a separate buffer can be (normally temporarily) set for rendering operations via the `setBuffer()` method. In that case, it is generally expected that all rendering operations are performed via that object. If the application modifies the buffer in parallel with the renderer, the result will be undefined.

Note to developers: we introduced a separate class for name compression because previous benchmark with BIND9 showed compression affects overall response performance very much. By having a separate class dedicated for this purpose, we'll be able to change the internal implementation of name compression in the future without affecting other part of the API and implementation.

In addition, by introducing a class hierarchy from `AbstractMessageRenderer`, we allow an application to use a customized renderer class for specific purposes. For example, a high performance DNS server may want to use an optimized renderer class assuming some specific underlying data representation.

Note
  Some functions (like writeUint8) are not virtual. It is because it is hard to imagine any version of message renderer that would do anything else than just putting the data into a buffer, so we provide a default implementation and having them virtual would only hurt the performance with no real gain. If it would happen a different implementation is really needed, we can make them virtual in future. The only one that is virtual is writeName and it's because this function is much more complicated, therefore there's a lot of space for different implementations or different behavior.

Definition at line 68 of file messagerenderer.h.

## Member Enumeration Documentation

## ◆ CompressMode

enum isc::dns::AbstractMessageRenderer::CompressMode

Compression mode constants.

The `CompressMode` enum type represents the name compression mode for renderer classes. `CASE_INSENSITIVE` means compress names in case-insensitive manner; `CASE_SENSITIVE` means compress names in case-sensitive manner. By default, a renderer compresses names in case-insensitive manner. Compression mode can be dynamically modified by the `setCompressMode()` method. The mode can be changed even in the middle of rendering, although this is not an intended usage. In this case the names already compressed are intact; only names being compressed after the mode change are affected by the change. If a renderer class object is reinitialized by the `clear()` method, the compression mode will be reset to the default, which is `CASE_INSENSITIVE`

One specific case where case-sensitive compression is required is AXFR as described in draft-ietf-dnsext-axfr-clarify. A primary authoritative DNS server implementation using this API would specify `CASE_SENSITIVE` before rendering outgoing AXFR messages.

Enumerator
CASE_INSENSITIVE | Compress names case-insensitive manner (default)
CASE_SENSITIVE | Compress names case-sensitive manner.

Definition at line 93 of file messagerenderer.h.

## Constructor & Destructor Documentation

## ◆ AbstractMessageRenderer()

isc::dns::AbstractMessageRenderer::AbstractMessageRenderer | ( |  | ) |
| protected

The default constructor.

This is intentionally defined as `protected` as this base class should never be instantiated (except as part of a derived class).

Definition at line 365 of file messagerenderer.cc.

## ◆ ~AbstractMessageRenderer()

virtual isc::dns::AbstractMessageRenderer::~AbstractMessageRenderer | ( |  | ) |
| inlinevirtual

The destructor.

Definition at line 109 of file messagerenderer.h.

## Member Function Documentation

## ◆ clear()

void isc::dns::AbstractMessageRenderer::clear | ( |  | ) |
| virtual

Clear the internal buffer and other internal resources.

This method can be used to re-initialize and reuse the renderer without constructing a new one.

Reimplemented in isc::dns::MessageRenderer.

Definition at line 392 of file messagerenderer.cc.

References isc::util::OutputBuffer::clear().

Referenced by isc::dns::MessageRenderer::clear(), setBuffer(), and isc::dns::MessageImpl::toWire().

Here is the call graph for this function:

## ◆ getBuffer() [1/2]

isc::util::OutputBuffer & isc::dns::AbstractMessageRenderer::getBuffer | ( |  | ) |
| inlineprotected

Definition at line 114 of file messagerenderer.h.

## ◆ getBuffer() [2/2]

const isc::util::OutputBuffer & isc::dns::AbstractMessageRenderer::getBuffer | ( |  | ) | const
| inlineprotected

Return the output buffer we render into.

Definition at line 113 of file messagerenderer.h.

Referenced by isc::dns::MessageRenderer::writeName().

## ◆ getCompressMode()

virtual CompressMode isc::dns::AbstractMessageRenderer::getCompressMode | ( |  | ) | const
| pure virtual

Return the compression mode of the renderer class object.

This method never throws an exception.

Returns
  The current compression mode.

Implemented in isc::dns::MessageRenderer.

Referenced by isc::dns::MessageImpl::toWire().

## ◆ getData()

const void * isc::dns::AbstractMessageRenderer::getData | ( |  | ) | const
| inline

Return a pointer to the head of the data stored in the internal buffer.

This method works exactly same as the same method of the `OutputBuffer` class; all notes for `OutputBuffer` apply.

Definition at line 139 of file messagerenderer.h.

Referenced by isc::dns::MessageImpl::toWire().

## ◆ getLength()

size_t isc::dns::AbstractMessageRenderer::getLength | ( |  | ) | const
| inline

Return the length of data written in the internal buffer.

Definition at line 144 of file messagerenderer.h.

Referenced by isc::dns::MessageRenderer::setCompressMode(), isc::dns::Question::toWire(), isc::dns::TSIGRecord::toWire(), isc::dns::EDNS::toWire(), isc::dns::BasicRRsetImpl::toWire(), isc::dns::MessageImpl::toWire(), and isc::dns::MessageRenderer::writeName().

## ◆ getLengthLimit()

virtual size_t isc::dns::AbstractMessageRenderer::getLengthLimit | ( |  | ) | const
| pure virtual

Return the maximum length of rendered data that can fit in the corresponding DNS message without truncation.

This method never throws an exception.

Returns
  The maximum length in bytes.

Implemented in isc::dns::MessageRenderer.

Referenced by isc::dns::Question::toWire(), isc::dns::BasicRRset::toWire(), isc::dns::TSIGRecord::toWire(), isc::dns::AbstractRRset::toWire(), isc::dns::EDNS::toWire(), and isc::dns::MessageImpl::toWire().

## ◆ isTruncated()

virtual bool isc::dns::AbstractMessageRenderer::isTruncated | ( |  | ) | const
| pure virtual

Return whether truncation has occurred while rendering.

Once the return value of this method is `true`, it doesn't make sense to try rendering more data, although this class itself doesn't reject the attempt.

This method never throws an exception.

Returns
  true if truncation has occurred; otherwise `false`.

Implemented in isc::dns::MessageRenderer.

Referenced by isc::dns::MessageImpl::toWire().

## ◆ setBuffer()

void isc::dns::AbstractMessageRenderer::setBuffer | ( | isc::util::OutputBuffer * | buffer | ) |

Set or reset a temporary output buffer.

This method can be used for an application that manages an output buffer separately from the message renderer and wants to keep reusing the renderer. When the renderer is associated with the default buffer and the given pointer is non NULL, the given buffer will be (temporarily) used for subsequent message rendering; if the renderer is associated with a temporary buffer and the given pointer is NULL, the renderer will be reset with the default buffer. In the latter case any additional resources (possibly specific to a derived renderer class) will be cleared, but the temporary buffer is kept as the latest state (which would normally store the rendering result).

This method imposes some restrictions to prevent accidental misuse that could cause disruption such as dereferencing an invalid object. First, a temporary buffer must not be set when the associated buffer is in use, that is, any data are stored in the buffer. Also, the default buffer cannot be "reset"; when NULL is specified a temporary buffer must have been set beforehand. If these conditions aren't met an isc::InvalidParameter exception will be thrown. This method is exception free otherwise.

Exceptions

  isc::InvalidParameter | A restrictions of the method usage isn't met.

Parameters

  buffer | A pointer to a temporary output buffer or NULL for reset it.

Definition at line 371 of file messagerenderer.cc.

References clear(), isc::util::OutputBuffer::getLength(), and isc_throw.

Referenced by isc::d2::DNSClientImpl::doUpdate().

Here is the call graph for this function:

## ◆ setCompressMode()

virtual void isc::dns::AbstractMessageRenderer::setCompressMode | ( | CompressMode | mode | ) |
| pure virtual

Set the compression mode of the renderer class object.

This method never throws an exception.

Parameters

  mode | A `CompressMode` value representing the compression mode.

Implemented in isc::dns::MessageRenderer.

Referenced by isc::dns::MessageImpl::toWire().

## ◆ setLengthLimit()

virtual void isc::dns::AbstractMessageRenderer::setLengthLimit | ( | size_t | len | ) |
| pure virtual

Set the maximum length of rendered data that can fit in the corresponding DNS message without truncation.

This method never throws an exception.

Parameters

  len | The maximum length in bytes.

Implemented in isc::dns::MessageRenderer.

Referenced by isc::dns::MessageImpl::toWire().

## ◆ setTruncated()

virtual void isc::dns::AbstractMessageRenderer::setTruncated | ( |  | ) |
| pure virtual

Mark the renderer to indicate truncation has occurred while rendering.

This method never throws an exception.

Implemented in isc::dns::MessageRenderer.

Referenced by isc::dns::Question::toWire(), isc::dns::BasicRRset::toWire(), isc::dns::RRset::toWire(), isc::dns::TSIGRecord::toWire(), and isc::dns::AbstractRRset::toWire().

## ◆ skip()

void isc::dns::AbstractMessageRenderer::skip | ( | size_t | len | ) |
| inline

Insert a specified length of gap at the end of the buffer.

The caller should not assume any particular value to be inserted. This method is provided as a shortcut to make a hole in the buffer that is to be filled in later, e.g, by writeUint16At().

Parameters

  len | The length of the gap to be inserted in bytes.

Definition at line 241 of file messagerenderer.h.

Referenced by isc::dns::BasicRRsetImpl::toWire(), and isc::dns::MessageImpl::toWire().

## ◆ trim()

void isc::dns::AbstractMessageRenderer::trim | ( | size_t | len | ) |
| inline

Trim the specified length of data from the end of the internal buffer.

This method is provided for such cases as DNS message truncation.

The specified length must not exceed the current data size of the buffer; otherwise an exception of class `isc::OutOfRange` will be thrown.

Parameters

  len | The length of data that should be trimmed.

Definition at line 255 of file messagerenderer.h.

Referenced by isc::dns::Question::toWire(), and isc::dns::BasicRRsetImpl::toWire().

## ◆ writeData()

void isc::dns::AbstractMessageRenderer::writeData | ( | const void * | data,
|  | size_t | len
| ) |  |
| inline

Copy an arbitrary length of data into the internal buffer of the renderer object.

No conversion on the copied data is performed.

Parameters

  data | A pointer to the data to be copied into the internal buffer.
  len | The length of the data in bytes.

Definition at line 310 of file messagerenderer.h.

Referenced by isc::dns::rdata::generic::Generic::toWire(), isc::dns::rdata::RdataFields::toWire(), and isc::dns::MessageRenderer::writeName().

## ◆ writeName() [1/2]

virtual void isc::dns::AbstractMessageRenderer::writeName | ( | const LabelSequence & | ls,
|  | bool | compress = `true`
| ) |  |
| pure virtual

Write a `LabelSequence` object into the internal buffer in wire format, with or without name compression.

This is the same as the other version, which takes `Name` instead of `LabelSequence`, except for the parameter type. The passed `LabelSequence` must be absolute.

Parameters

  ls | A `LabelSequence` object to be written.
  compress | A boolean indicating whether to enable name compression.

Implemented in isc::dns::MessageRenderer.

## ◆ writeName() [2/2]

virtual void isc::dns::AbstractMessageRenderer::writeName | ( | const Name & | name,
|  | bool | compress = `true`
| ) |  |
| pure virtual

Write a `Name` object into the internal buffer in wire format, with or without name compression.

If the optional parameter `compress` is `true`, this method tries to compress the `name` if possible, searching the entire message that has been rendered. Otherwise name compression is omitted. Its default value is `true`.

Note: even if `compress` is `true`, the position of the `name` (and possibly its ancestor names) in the message is recorded and may be used for compressing subsequent names.

Parameters

  name | A `Name` object to be written.
  compress | A boolean indicating whether to enable name compression.

Implemented in isc::dns::MessageRenderer.

Referenced by isc::dns::Name::toWire(), isc::dns::Question::toWire(), isc::dns::rdata::RdataFields::toWire(), and isc::dns::TSIGRecord::toWire().

## ◆ writeUint16()

void isc::dns::AbstractMessageRenderer::writeUint16 | ( | uint16_t | data | ) |
| inline

Write an unsigned 16-bit integer in host byte order into the internal buffer in network byte order.

Parameters

  data | The 16-bit integer to be written into the buffer.

Definition at line 276 of file messagerenderer.h.

Referenced by isc::dns::RRClass::toWire(), isc::dns::RRType::toWire(), isc::dns::BasicRRsetImpl::toWire(), and isc::dns::MessageRenderer::writeName().

## ◆ writeUint16At()

void isc::dns::AbstractMessageRenderer::writeUint16At | ( | uint16_t | data,
|  | size_t | pos
| ) |  |
| inline

Write an unsigned 16-bit integer in host byte order at the specified position of the internal buffer in network byte order.

The buffer must have a sufficient room to store the given data at the given position, that is, `pos + 2 < getLength()`; otherwise an exception of class `isc::dns::InvalidBufferPosition` will be thrown. Note also that this method never extends the internal buffer.

Parameters

  data | The 16-bit integer to be written into the internal buffer.
  pos | The beginning position in the buffer to write the data.

Definition at line 291 of file messagerenderer.h.

Referenced by isc::dns::BasicRRsetImpl::toWire(), and isc::dns::MessageImpl::toWire().

## ◆ writeUint32()

void isc::dns::AbstractMessageRenderer::writeUint32 | ( | uint32_t | data | ) |
| inline

Write an unsigned 32-bit integer in host byte order into the internal buffer in network byte order.

Parameters

  data | The 32-bit integer to be written into the buffer.

Definition at line 299 of file messagerenderer.h.

Referenced by isc::dns::RRTTL::toWire().

## ◆ writeUint8()

void isc::dns::AbstractMessageRenderer::writeUint8 | ( | const uint8_t | data | ) |
| inline

Write an unsigned 8-bit integer into the internal buffer.

Parameters

  data | The 8-bit integer to be written into the internal buffer.

Definition at line 268 of file messagerenderer.h.

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

- messagerenderer.h
- messagerenderer.cc