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.

size_t	getLength () const
	Return the length of data written in the internal buffer.

virtual bool	isTruncated () const =0
	Return whether truncation has occurred while rendering.

virtual size_t	getLengthLimit () const =0
	Return the maximum length of rendered data that can fit in the corresponding DNS message without truncation.

virtual CompressMode	getCompressMode () const =0
	Return the compression mode of the renderer class object.

Setter Methods
void	setBuffer (isc::util::OutputBuffer *buffer)
	Set or reset a temporary output buffer.

virtual void	setTruncated ()=0
	Mark the renderer to indicate truncation has occurred while rendering.

virtual void	setLengthLimit (size_t len)=0
	Set the maximum length of rendered data that can fit in the corresponding DNS message without truncation.

virtual void	setCompressMode (CompressMode mode)=0
	Set the compression mode of the renderer class object.

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.

void	trim (size_t len)
	Trim the specified length of data from the end of the internal buffer.

virtual void	clear ()
	Clear the internal buffer and other internal resources.

void	writeUint8 (const uint8_t data)
	Write an unsigned 8-bit integer into the internal buffer.

void	writeUint16 (uint16_t data)
	Write an unsigned 16-bit integer in host byte order into the internal buffer in network byte order.

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.

void	writeUint32 (uint32_t data)
	Write an unsigned 32-bit integer in host byte order into the internal buffer in network byte order.

void	writeData (const void *data, size_t len)
	Copy an arbitrary length of data into the internal buffer of the renderer object.

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.

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.

Constructors and Destructor
	AbstractMessageRenderer ()
	The default constructor.

const isc::util::OutputBuffer &	getBuffer () const
	Return the output buffer we render into.

isc::util::OutputBuffer &	getBuffer ()

virtual	~AbstractMessageRenderer ()
	The destructor.

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 69 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 94 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 362 of file messagerenderer.cc.

◆ ~AbstractMessageRenderer()

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

inlinevirtual

The destructor.

Definition at line 110 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 388 of file messagerenderer.cc.

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

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

Here is the call graph for this function:

◆ getBuffer() [1/2]

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

inlineprotected

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

◆ 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 140 of file messagerenderer.h.

◆ getLength()

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

inline

Return the length of data written in the internal buffer.

Definition at line 145 of file messagerenderer.h.

Referenced by isc::dns::MessageRenderer::setCompressMode(), 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.

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

◆ 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 367 of file messagerenderer.cc.

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

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.

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

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

◆ 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 242 of file messagerenderer.h.

◆ 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 256 of file messagerenderer.h.

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

◆ 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 277 of file messagerenderer.h.

Referenced by 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::OutOfRange 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.

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

◆ 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 269 of file messagerenderer.h.

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

Public Types

Public Member Functions

Constructors and Destructor

Detailed Description

Member Enumeration Documentation

◆ CompressMode

Constructor & Destructor Documentation

◆ AbstractMessageRenderer()

◆ ~AbstractMessageRenderer()

Member Function Documentation

◆ clear()

◆ getBuffer() [1/2]

◆ getBuffer() [2/2]

◆ getCompressMode()

◆ getData()

◆ getLength()

◆ getLengthLimit()

◆ isTruncated()

◆ setBuffer()

◆ setCompressMode()

◆ setLengthLimit()

◆ setTruncated()

◆ skip()

◆ trim()

◆ writeData()

◆ writeName() [1/2]

◆ writeName() [2/2]

◆ writeUint16()

◆ writeUint16At()

◆ writeUint32()

◆ writeUint8()