A low-level, RR type-independent representation of DNS RDATA. More...

#include <rdatafields.h>

Classes
struct	FieldSpec
	Structure that specifies a single `RdataFields` field. More...

struct	RdataFieldsDetail
	This is a helper class for `RdataFields`. More...

Public Types
enum	Type { DATA, COMPRESSIBLE_NAME, INCOMPRESSIBLE_NAME }
	Types of `RdataFields` fields. More...

Public Member Functions
Getter Methods
unsigned int	getDataLength () const
	Return the length of the entire RDATA encoded in the `RdataFields` in bytes. More...

const void *	getData () const
	Return a pointer to the RDATA encoded in the `RdataFields`. More...

unsigned int	getFieldSpecDataSize () const
	Return the number of bytes the buffer returned by getFieldSpecData() will occupy. More...

unsigned int	getFieldCount () const
	Return the number of specs fields. More...

const void *	getFieldSpecData () const
	Return a pointer to a sequence of `FieldSpec` for the `RdataFields`. More...

FieldSpec	getFieldSpec (const unsigned int field_id) const
	Return the specification of the field identified by the given index. More...

Converter Methods
void	toWire (AbstractMessageRenderer &renderer) const
	Render the RdataFields in the wire format with name compression. More...

void	toWire (isc::util::OutputBuffer &buffer) const
	Render the RdataFields in the wire format without name compression. More...

Constructors and Destructor.
Note: The copy constructor and the assignment operator are intentionally defined as private, making this class non copyable.
	RdataFields (const Rdata &rdata)
	Constructor from Rdata. More...

	RdataFields (const void fields, const unsigned int fields_length, const void data, const size_t data_length)
	Constructor from field parameters. More...

	~RdataFields ()
	The destructor. More...

Detailed Description

A low-level, RR type-independent representation of DNS RDATA.

Purpose of the Class

This class intends to help "serialization" of the content of RDATA in a space-efficient manner. Specific derived classes of Rdata focus on the convenience of accessing RDATA fields for RR type-specific protocol operations, and can be inefficient in terms of space. For example, a DNS character string may be internally represented as a std::string object with all of the overhead of the richer class. If an application needs to maintain a very large number of RRs and it does not have to perform RR specific operation so often, it may make more sense to store the data in memory in a lower-level but space efficient form.

Another purpose of this class is to improve rendering performance for RDATA. If the only requirement were space efficiency, it would be just sufficient to convert the RDATA into a binary sequence in the wire format. However, to render the data in a DNS message, we'd have to re-construct a corresponding Rdata object in the case where name compression is necessary. This is not desirable, and this class is provided to avoid such unnecessary overhead.

Data Format

To meet these goals, this class helps convert an Rdata object into two pieces of information: Wire-format representation of the Rdata and associated meta information for efficient rendering.

Specifically, it maintains the wire-format data as a sequence of typed fields. The types are:

Compressible name: a domain name as an RDATA field that can be compressed
Incompressible name: a domain name as an RDATA field that cannot be compressed
Other data: any other fields of RDATA, which should be treated as opaque

(See also the description of RdataFields::Type) Whether a name can or cannot be compressed is determined according to RFC3597.

A "other data" field may not always correspond to a single RDATA field. A RdataFields field (of other data) is just a contiguous region of the wire-format data that does not involve name compression. For example, the SOA RDATA begins with two "compressible" names followed by 5 32-bit fields. In RdataFields the last 5 fields would be considered a single 20-byte field.

Each RdataFields field is identified by the FieldSpec structure, which provides the type and length of the field. An RdataFields object internally maintains a sequence of FieldSpec objects in a form of plain C-style array, which can be referenced via a pointer returned by the getFieldSpecData() method. The FieldSpec for a specific field can also be retrieved by the getFieldSpec() method.

The following diagram shows the internal memory representation of an SOA RDATA in the form of RdataFields object and how an application can get access to the memory region.

accessible via      |0                               getDataLength() bytes
getData()----------> <MNAME><RNAME><Rest of the data>
                     <---------- 3 * sizeof(FieldSpec) bytes ------------->
getFieldSpecData()-> { compressible name { compressible name { other data
                       len: MNAME-len }    len: RNAME-len }    len: 20    }

where MNAME and RNAME are wire format representations of the MNAME and RNAME fields of the SOA RDATA, respectively, and "Rest of the data" encodes the remaining 20 bytes of the RDATA in network byte order.

Usage of the Class

One major and common use case of the RdataFields class is to convert a Rdata object (possibly given from a DNS message or some configuration source such as a zone file) in the serialized format and store a copy of the data somewhere in memory. The following code sample implements this scenario:

 // assume "rdata" is a reference type to Rdata
const RdataFields fields(rdata);
const unsigned int fields_size = fields.getFieldDataSize();
memcpy(some_place, fields.getFieldSpecData(), fields_size);
const size_t data_length = fields.getDataLength();
memcpy(other_place, fields.getData(), data_length);
// (fields_size and data_length should be stored somewhere, too)

Another typical usage is to render the stored data in the wire format as efficiently as possible. The following code is an example of such usage:

 // assume "renderer" is of type MessageRenderer
// retrieve data_length and fields_size from the storage
RdataFields(some_place, fields_size, other_place,
            data_length).toWire(renderer);

Notes to Users

The main purposes of this class is to help efficient operation for some (limited classes of) performance sensitive application. For this reason the interface and implementation rely on relatively lower-level, riskier primitives such as passing around bare pointers.

It is therefore discouraged to use this class for general purpose applications that do not need to maximize performance in terms of either memory footprint or rendering speed. All functionality provided by this class can be achieved via higher level interfaces such as the Rdata class variants. Normal applications should use those interfaces.

The data format is public information so that an application can examine and use selected parts of data. For example, an application may want to encode domain names in RDATA in a different way while storing the other data in a separate place. However, at this moment the format is still in flux, and it may not be compatible with future versions (see below).

Development Notes

We should conduct benchmark tests to measure rendering performance.

The current implementation needs to re-construct name objects from compressible and incompressible name fields as wire-format data. This is not efficient, and we'll probably want to improve this in a future version. One possibility is to store offset information as well as the name data (at the cost of increasing memory footprint), and to use the pair of data for faster rendering.

Definition at line 151 of file rdatafields.h.

Member Enumeration Documentation

enum isc::dns::rdata::RdataFields::Type

Types of RdataFields fields.

COMPRESSIBLE_NAME and INCOMPRESSIBLE_NAME represent a domain name used as a field of an RDATA that can and cannot be compressed per RFC3597. DATA means all other types of fields.

Enumerator
DATA	Plain data.
COMPRESSIBLE_NAME	A domain name subject to name compression.
INCOMPRESSIBLE_NAME	A domain name that shouldn't be compressed.

Definition at line 159 of file rdatafields.h.

Constructor & Destructor Documentation

isc::dns::rdata::RdataFields::RdataFields ( const Rdata & rdata )

Constructor from Rdata.

This constructor converts the data of a given Rdata object into an RdataFields object so that the resulting data can be stored in memory in a space-efficient way.

It makes a local copy of the original data and dynamically allocates necessary memory, so is not very efficient. The basic idea is to perform the expensive conversion once and keep using the result as long as possible to improve overall performance in a longer term.

If the internal resource allocation fails, a corresponding standard exception will be thrown. The current implementation of this constructor internally calls the Rdata::toWire(AbstractMessageRenderer&) const method for the conversion. If that method throws an exception it will be propagated to the caller of this constructor.

Parameters

rdata The RDATA for which the RdataFields to be constructed.

Definition at line 124 of file rdatafields.cc.

References isc::dns::rdata::RdataFields::RdataFieldsDetail::allocated_data_, fields_, and isc::dns::rdata::Rdata::toWire().

Here is the call graph for this function:

isc::dns::rdata::RdataFields::RdataFields	(	const void *	fields,
		const unsigned int	fields_length,
		const void *	data,
		const size_t	data_length
	)

Constructor from field parameters.

The intended usage of this version of constructor is to form a structured representation of RDATA encoded by the other constructor so that the resulting object can be used for subsequent operations such as rendering in the wire format. This version is intended to be efficient by not making any copy of variable length data or expensive data inspection.

This constructor is basically exception free, except against bogus input parameters. Specifically, the parameters must meet the following conditions; otherwise an exception of class InvalidParameter will be thrown.

fields can be NULL if and only if nfields is 0
data can be NULL if and only if data_length is 0
the sum of the lengths of fields entries must be equal to data_length

This constructor assumes that the memory region pointed by data (if non NULL) is encoded as a sequence of valid RdataFields fields, and does not perform deep inspection on each field. In particular, for fields of type COMPRESSIBLE_NAME or INCOMPRESSIBLE_NAME, this constructor assumes the corresponding memory region is a valid representation of domain name. Otherwise, a subsequent method call such as toWire(AbstractMessageRenderer&) const may trigger an unexpected exception. It also expects the fields reside on address that is valid for them (eg. it has valid alignment), see getFieldSpecData() for details.

It is the caller's responsibility to ensure this assumption. In general, this constructor is expected to be used for serialized data generated by the other constructor from a valid Rdata. The result is not guaranteed if the data is generated in any other ways.

The resulting RdataFields object does not maintain a copy of fields or data. It is the caller's responsibility to ensure the memory regions pointed to by these parameters are valid and intact as long as the RdataFields object is used.

Parameters

fields	An array of `FieldSpec` entries. This can be `NULL`.
fields_length	The total length of the `fields`.
data	A pointer to memory region for the entire RDATA. This can be NULL.
data_length	The length of `data` in bytes.

Definition at line 145 of file rdatafields.cc.

References isc_throw, and isc::dns::rdata::RdataFields::FieldSpec::len.

isc::dns::rdata::RdataFields::~RdataFields ( )

The destructor.

Definition at line 178 of file rdatafields.cc.

Member Function Documentation

const void* isc::dns::rdata::RdataFields::getData ( ) const

inline

Return a pointer to the RDATA encoded in the RdataFields.

The RdataFields holds ownership of the data.

This method never throws an exception.

Definition at line 317 of file rdatafields.h.

unsigned int isc::dns::rdata::RdataFields::getDataLength ( ) const

inline

Return the length of the entire RDATA encoded in the RdataFields in bytes.

This method never throws an exception.

Definition at line 310 of file rdatafields.h.

unsigned int isc::dns::rdata::RdataFields::getFieldCount ( ) const

inline

Return the number of specs fields.

It specifies the range of parameter for getFieldSpec().

This method never throws.

Definition at line 331 of file rdatafields.h.

RdataFields::FieldSpec isc::dns::rdata::RdataFields::getFieldSpec ( const unsigned int field_id ) const

Return the specification of the field identified by the given index.

field_id is the field index, which must be in the range of [0, getFieldCount()). 0 means the first field, and getFieldCount()-1 means the last.

If the given index is not in the valid range, an exception of class OutOfRange will be thrown. This method never throws an exception otherwise.

Parameters

field_id The index of an RdataFields field to be returned.

Returns: A FieldSpec structure that contains the information of the field_id-th field.

Definition at line 183 of file rdatafields.cc.

References isc_throw.

const void* isc::dns::rdata::RdataFields::getFieldSpecData ( ) const

inline

Return a pointer to a sequence of FieldSpec for the RdataFields.

This should be treated as an opaque internal representation you can just store off somewhere and use it to construct a new RdataFields. from it. If you are really interested, you can typecast it to FieldSpec * (which is what it really is internally).

The RdataFields holds ownership of the data.

Note: You should, however, be aware of alignment issues. The pointer you pass to the constructor must be an address where the FieldSpec can live. If you store it at a wrong address (eg. even one with current implementation on most architectures), it might lead bad things from slow access to SIGBUS. The easiest way is not to interleave the fields with data from getData(). It is OK to place all the fields first (even from multiple RdataFields) and then place all the data after them.

This method never throws an exception.

Definition at line 353 of file rdatafields.h.

unsigned int isc::dns::rdata::RdataFields::getFieldSpecDataSize ( ) const

inline

Return the number of bytes the buffer returned by getFieldSpecData() will occupy.

This method never throws an exception.

Definition at line 323 of file rdatafields.h.

void isc::dns::rdata::RdataFields::toWire ( AbstractMessageRenderer & renderer ) const

Render the RdataFields in the wire format with name compression.

This method may require resource allocation in renderer. If it fails, a corresponding standard exception will be thrown. It should not throw any other exception as long as the RdataFields object was constructed from valid parameters (see the description of constructors). The result is not guaranteed if it's constructed in any other ways.

Parameters

renderer DNS message rendering context that encapsulates the output buffer and name compression information.

Definition at line 191 of file rdatafields.cc.

References COMPRESSIBLE_NAME, DATA, isc::dns::rdata::RdataFields::FieldSpec::len, isc::dns::AbstractMessageRenderer::writeData(), and isc::dns::AbstractMessageRenderer::writeName().

Here is the call graph for this function: