Kea: isc::dns::rdata Namespace Reference

| Kea 3.2.0-git

isc::dns::rdata Namespace Reference

## Namespaces
namespace | any
namespace | ch
namespace | generic
namespace | in

## Classes
class | AbstractRdataFactory
| The `AbstractRdataFactory` class is an abstract base class to encapsulate a set of Rdata factory methods in a polymorphic way. More...
class | CharStringTooLong
| A standard DNS module exception that is thrown if RDATA parser encounters a character-string (as defined in RFC1035) exceeding the maximum allowable length (`MAX_CHARSTRING_LEN`). More...
class | InvalidRdataLength
| A standard DNS module exception that is thrown if RDATA parser encounters an invalid or inconsistent data length. More...
class | InvalidRdataText
| A standard DNS module exception that is thrown if RDATA parser fails to recognize a given textual representation. More...
class | Rdata
| The `Rdata` class is an abstract base class that provides a set of common interfaces to manipulate concrete RDATA objects. More...

## Typedefs
typedef boost::shared_ptr< const Rdata > | ConstRdataPtr
typedef boost::shared_ptr< AbstractRdataFactory > | RdataFactoryPtr
| The `RdataFactoryPtr` type is a pointer-like type, pointing to an object of some concrete derived class of `AbstractRdataFactory`.
typedef boost::shared_ptr< Rdata > | RdataPtr
| The `RdataPtr` type is a pointer-like type, pointing to an object of some concrete derived class of `Rdata`.

## Functions
Parameterized Polymorphic RDATA Factories
This set of global functions provide a unified interface to create an `Rdata` object in a parameterized polymorphic way, that is, these functions take a pair of `RRType` and `RRClass` objects and data specific to that pair, and create an object of the corresponding concrete derived class of `Rdata`. These will be useful when parsing/constructing a DNS message or parsing a master file, where information for a specific type of RDATA is given but the resulting object, once created, should better be used in a polymorphic way. For example, if a master file parser encounters an NS RR
    example.com. 3600 IN NS ns.example.com.
it stores the text fragments "IN", "NS", and "ns.example.com." in `std::string` objects `class_txt`, `type_txt`, and `nsname_txt`, respectively, then it would create a new `RdataPtr` object as follows: RdataPtr rdata = createRdata(RRType(type_txt), RRClass(class_txt), nsname_txt); isc::dns::RRClass The RRClass class encapsulates DNS resource record classes. Definition rrclass.h:89 isc::dns::RRType The RRType class encapsulates DNS resource record types. Definition rrtype.h:96 isc::dns::rdata Definition char_string.cc:27 isc::dns::rdata::createRdata RdataPtr createRdata(const RRType &rrtype, const RRClass &rrclass, const std::string &rdata_string) Create RDATA of a given pair of RR type and class from a string. Definition rdata.cc:54 isc::dns::rdata::RdataPtr boost::shared_ptr< Rdata > RdataPtr The RdataPtr type is a pointer-like type, pointing to an object of some concrete derived class of Rda... Definition master_loader_callbacks.h:24 On success, `rdata` will point to an object of the `generic::NS` class that internally holds a domain name of "ns.example.com." Internally, these functions uses the corresponding `RRParamRegistry::createRdata` methods of the `RRParamRegistry`. See also the description on these methods for related notes.
RdataPtr | createRdata (const RRType &rrtype, const RRClass &rrclass, const std::string &rdata_string)
| Create RDATA of a given pair of RR type and class from a string.
RdataPtr | createRdata (const RRType &rrtype, const RRClass &rrclass, isc::util::InputBuffer &buff, size_t len)
| Create RDATA of a given pair of RR type and class from wire-format data.
RdataPtr | createRdata (const RRType &rrtype, const RRClass &rrclass, const Rdata &source)
| Create RDATA of a given pair of RR type and class, copying of another RDATA of same kind.
RdataPtr | createRdata (const RRType &rrtype, const RRClass &rrclass, MasterLexer &lexer, const Name *origin, MasterLoader::Options options, MasterLoaderCallbacks &callbacks)
| Create RDATA of a given pair of RR type and class using the master lexer.
int | compareNames (const Name &n1, const Name &n2)
| Gives relative ordering of two names in terms of DNSSEC RDATA ordering.

## Variables
const unsigned int | MAX_CHARSTRING_LEN = 255
| The maximum allowable length of character-string containing in RDATA as defined in RFC1035, not including the 1-byte length field.
const size_t | MAX_RDLENGTH = 65535
| Possible maximum length of RDATA, which is the maximum unsigned 16 bit value.

## Typedef Documentation

## ◆ ConstRdataPtr

typedef boost::shared_ptr<const Rdata> isc::dns::rdata::ConstRdataPtr

Definition at line 69 of file rdata.h.

## ◆ RdataFactoryPtr

typedef boost::shared_ptr<AbstractRdataFactory> isc::dns::rdata::RdataFactoryPtr

The `RdataFactoryPtr` type is a pointer-like type, pointing to an object of some concrete derived class of `AbstractRdataFactory`.

Definition at line 131 of file rrparamregistry.h.

## ◆ RdataPtr

typedef boost::shared_ptr< Rdata > isc::dns::rdata::RdataPtr

The `RdataPtr` type is a pointer-like type, pointing to an object of some concrete derived class of `Rdata`.

Definition at line 24 of file master_loader_callbacks.h.

## Function Documentation

## ◆ compareNames()

int isc::dns::rdata::compareNames | ( | const Name & | n1,
|  | const Name & | n2 )

Gives relative ordering of two names in terms of DNSSEC RDATA ordering.

This method compares two names as defined in Sections 6.2 and 6.3 of RFC4034: Comparing two names in their canonical form (i.e., converting upper case ASCII characters to lower ones) and as a left-justified unsigned octet sequence. Note that the ordering is different from that for owner names. For example, "a.example" should be sorted before "example" as RDATA, but the ordering is the opposite when compared as owner names.

Normally, applications would not need this function directly. This is mostly an internal helper function for `Rdata` related classes to implement their `compare()` method. This function is publicly open, however, for the convenience of external developers who want to implement new or experimental RR types.

This function never throws an exception as long as the given names are valid `Name` objects.

Additional note about applicability: In fact, BIND9's similar function, `dns_name_rdatacompare()`, is only used in rdata implementations and for testing purposes.

Parameters

  n1,n2 | `Name` class objects to compare.

Returns
  -1 if `n1` would be sorted before `n2`.
  0 if `n1` is identical to `n2` in terms of sorting order.
  1 if `n1` would be sorted after `n2`.

Definition at line 174 of file rdata.cc.

References isc::dns::Name::at(), and isc::dns::Name::getLength().

Here is the call graph for this function:

## ◆ createRdata() [1/4]

RdataPtr isc::dns::rdata::createRdata | ( | const RRType & | rrtype,
|  | const RRClass & | rrclass,
|  | const Rdata & | source )

Create RDATA of a given pair of RR type and class, copying of another RDATA of same kind.

This method creates an `Rdata` object of the given pair of RR type and class, copying the content of the given `Rdata`, `source`.

Parameters

  rrtype | An `RRType` object specifying the type/class pair.
  rrclass | An `RRClass` object specifying the type/class pair.
  source | A reference to an `Rdata` object whose content is to be copied to the created `Rdata` object.

Returns
  An `RdataPtr` object pointing to the created `Rdata` object.

Definition at line 82 of file rdata.cc.

References createRdata(), and isc::dns::RRParamRegistry::getRegistry().

Here is the call graph for this function:

## ◆ createRdata() [2/4]

RdataPtr isc::dns::rdata::createRdata | ( | const RRType & | rrtype,
|  | const RRClass & | rrclass,
|  | const std::string & | rdata_string )

Create RDATA of a given pair of RR type and class from a string.

This method creates from a string an `Rdata` object of the given pair of RR type and class.

Parameters

  rrtype | An `RRType` object specifying the type/class pair.
  rrclass | An `RRClass` object specifying the type/class pair.
  rdata_string | A string of textual representation of the `Rdata`.

Returns
  An `RdataPtr` object pointing to the created `Rdata` object.

Definition at line 54 of file rdata.cc.

References createRdata(), and isc::dns::RRParamRegistry::getRegistry().

Referenced by isc::dns::AbstractRRset::addRdata(), isc::dns::BasicRRset::addRdata(), createRdata(), createRdata(), isc::dns::MasterLoader::MasterLoaderImpl::loadIncremental(), and isc::dns::MessageImpl::parseSection().

Here is the call graph for this function:

## ◆ createRdata() [3/4]

RdataPtr isc::dns::rdata::createRdata | ( | const RRType & | rrtype,
|  | const RRClass & | rrclass,
|  | isc::util::InputBuffer & | buff,
|  | size_t | len )

Create RDATA of a given pair of RR type and class from wire-format data.

This method creates from wire-format binary data an `Rdata` object of the given pair of RR type and class.

`len` must not exceed the protocol defined maximum value, `MAX_RDLENGTH`; otherwise, an exception of class `InvalidRdataLength` will be thrown.

In some cases, the length of the RDATA is determined without the information of `len`. For example, the RDATA length of an IN/A RR must always be 4. If `len` is not equal to the actual length in such cases, an exception of class InvalidRdataLength will be thrown.

Parameters

  rrtype | An `RRType` object specifying the type/class pair.
  rrclass | An `RRClass` object specifying the type/class pair.
  buff | A reference to an `InputBuffer` object storing the `Rdata` to parse.
  len | The length in buffer of the `Rdata`. In bytes.

Returns
  An `RdataPtr` object pointing to the created `Rdata` object.

Definition at line 61 of file rdata.cc.

References isc::dns::RRParamRegistry::createRdata(), isc::util::InputBuffer::getPosition(), isc::dns::RRParamRegistry::getRegistry(), isc_throw, and MAX_RDLENGTH.

Here is the call graph for this function:

## ◆ createRdata() [4/4]

RdataPtr isc::dns::rdata::createRdata | ( | const RRType & | rrtype,
|  | const RRClass & | rrclass,
|  | MasterLexer & | lexer,
|  | const Name * | origin,
|  | MasterLoader::Options | options,
|  | MasterLoaderCallbacks & | callbacks )

Create RDATA of a given pair of RR type and class using the master lexer.

This is a more generic form of factory from textual RDATA, and is mainly intended to be used internally by the master file parser (`MasterLoader`) of this library.

The `lexer` is expected to be at the beginning of textual RDATA of the specified type and class. This function (and its underlying Rdata implementations) extracts necessary tokens from the lexer and constructs the RDATA from them.

Due to the intended usage of this version, this function handles error cases quite differently from other versions. It internally catches most of syntax and semantics errors of the input (reported as exceptions), calls the corresponding callback specified by the `callbacks` parameters, and returns a null smart pointer. If the caller rather wants to get an exception in these cases, it can pass a callback that internally throws on error. Some critical exceptions such as `std::bad_alloc` are still propagated to the upper layer as it doesn't make sense to try recovery from such a situation within this function.

Whether or not the creation succeeds, this function updates the lexer until it reaches either the end of line or file, starting from the end of the RDATA text (or the point of failure if the parsing fails in the middle of it). The caller can therefore assume it's ready for reading the next data (which is normally a subsequent RR in the zone file) on return, whether or not this function succeeds.

Parameters

  rrtype | An `RRType` object specifying the type/class pair.
  rrclass | An `RRClass` object specifying the type/class pair.
  lexer | A `MasterLexer` object parsing a master file for the RDATA to be created
  origin | If non null, specifies the origin of any domain name fields of the RDATA that are non absolute.
  options | Master loader options controlling how to deal with errors or non critical issues in the parsed RDATA.
  callbacks | Callback to be called when an error or non critical issue is found.

Returns
  An `RdataPtr` object pointing to the created `Rdata` object. Will be null if parsing fails.

Definition at line 127 of file rdata.cc.

References isc::dns::RRParamRegistry::createRdata(), isc::dns::MasterToken::END_OF_FILE, isc::dns::MasterToken::END_OF_LINE, isc::dns::MasterLexer::getNextToken(), isc::dns::RRParamRegistry::getRegistry(), isc::dns::MasterLexer::getSourceLine(), isc::dns::MasterLexer::getSourceName(), isc::dns::MasterToken::getType(), isc_throw_assert, isc::dns::MasterLoaderCallbacks::warning(), and isc::Exception::what().

Here is the call graph for this function:

## Variable Documentation

## ◆ MAX_CHARSTRING_LEN

const unsigned int isc::dns::rdata::MAX_CHARSTRING_LEN = 255

The maximum allowable length of character-string containing in RDATA as defined in RFC1035, not including the 1-byte length field.

Definition at line 77 of file rdata.h.

Referenced by isc::dns::rdata::generic::detail::stringToCharString().

## ◆ MAX_RDLENGTH

const size_t isc::dns::rdata::MAX_RDLENGTH = 65535

Possible maximum length of RDATA, which is the maximum unsigned 16 bit value.

Definition at line 73 of file rdata.h.

Referenced by isc::dns::rdata::generic::Generic::Generic(), isc::dns::rdata::generic::detail::TXTLikeImpl< TXT, 16 >::TXTLikeImpl(), and createRdata().