Kea  2.1.7-git
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:

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

Protected Member Functions

const isc::util::OutputBuffergetBuffer () const
 Return the output buffer we render into. More...
 
isc::util::OutputBuffergetBuffer ()
 

Constructors and Destructor

 AbstractMessageRenderer ()
 The default constructor. More...
 
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

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(), isc::dns::MessageImpl::toWire(), and trim().

+ Here is the call graph for this function:

◆ getBuffer() [1/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().

◆ getBuffer() [2/2]

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

Definition at line 114 of file messagerenderer.h.

References getData(), and isc::util::OutputBuffer::getData().

+ Here is the call graph for this function:

◆ 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 getLength(), and 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 getBuffer().

◆ getLength()

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

◆ 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 getLength(), isc::dns::MessageImpl::toWire(), isc::dns::Question::toWire(), isc::dns::TSIGRecord::toWire(), isc::dns::EDNS::toWire(), isc::dns::AbstractRRset::toWire(), and isc::dns::BasicRRset::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 getLength().

◆ 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::InvalidParameterA restrictions of the method usage isn't met.
Parameters
bufferA 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(), getLength(), and isc::asiodns::IOFetch::IOFetch().

+ 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
modeA CompressMode value representing the compression mode.

Implemented in isc::dns::MessageRenderer.

Referenced by getLength(), and 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
lenThe maximum length in bytes.

Implemented in isc::dns::MessageRenderer.

Referenced by getLength(), and 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 getLength(), isc::dns::Question::toWire(), isc::dns::TSIGRecord::toWire(), isc::dns::BasicRRset::toWire(), and isc::dns::RRset::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
lenThe length of the gap to be inserted in bytes.

Definition at line 241 of file messagerenderer.h.

Referenced by getLength(), isc::dns::MessageImpl::toWire(), and isc::dns::BasicRRsetImpl::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
lenThe length of data that should be trimmed.

Definition at line 255 of file messagerenderer.h.

References clear(), and isc::util::OutputBuffer::trim().

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

+ Here is the call graph for this function:

◆ 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
dataA pointer to the data to be copied into the internal buffer.
lenThe length of the data in bytes.

Definition at line 310 of file messagerenderer.h.

References isc::util::OutputBuffer::writeData(), and writeName().

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

+ Here is the call graph for this function:

◆ writeName() [1/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
nameA Name object to be written.
compressA boolean indicating whether to enable name compression.

Implemented in isc::dns::MessageRenderer.

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

◆ writeName() [2/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
lsA LabelSequence object to be written.
compressA boolean indicating whether to enable name compression.

Implemented in isc::dns::MessageRenderer.

◆ 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
dataThe 16-bit integer to be written into the buffer.

Definition at line 276 of file messagerenderer.h.

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

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

+ Here is the call graph for this function:

◆ 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
dataThe 16-bit integer to be written into the internal buffer.
posThe beginning position in the buffer to write the data.

Definition at line 291 of file messagerenderer.h.

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

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

+ Here is the call graph for this function:

◆ 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
dataThe 32-bit integer to be written into the buffer.

Definition at line 299 of file messagerenderer.h.

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

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

+ Here is the call graph for this function:

◆ writeUint8()

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

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

Parameters
dataThe 8-bit integer to be written into the internal buffer.

Definition at line 268 of file messagerenderer.h.

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

+ Here is the call graph for this function:

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