Kea: isc::dns::RRParamRegistry Class Reference

| Kea 3.2.0-git

isc::dns::RRParamRegistry Class Reference

The `RRParamRegistry` class represents a registry of parameters to manipulate DNS resource records (RRs). More...

`#include <rrparamregistry.h>`

## Public Member Functions
Registry Update Methods
void | add (const std::string &type_string, uint16_t type_code, const std::string &class_string, uint16_t class_code, rdata::RdataFactoryPtr rdata_factory)
| Add a set of parameters for a pair of RR type and class.
void | add (const std::string &type_string, uint16_t type_code, rdata::RdataFactoryPtr rdata_factory)
| Add a set of parameters for a class-independent RR type.
bool | addType (const std::string &type_string, uint16_t type_code)
| Add mappings between RR type code and textual representation.
bool | removeType (uint16_t type_code)
| Remove mappings between RR type code and textual representation for a given type.
bool | addClass (const std::string &class_string, uint16_t class_code)
| Add mappings between RR class code and textual representation.
bool | removeClass (uint16_t class_code)
| Remove mappings between RR class code and textual representation for a given class.
bool | removeRdataFactory (const RRType &rrtype, const RRClass &rrclass)
| Remove registered RDATA factory for the given pair of `RRType` and `RRClass`.
bool | removeRdataFactory (const RRType &rrtype)
| Remove registered RDATA factory for the given pair of `RRType` and `RRClass`.
Parameter Conversion Methods
bool | textToTypeCode (const std::string &type_string, uint16_t &type_code) const
| Convert a textual representation of an RR type to the corresponding 16-bit integer code.
std::string | codeToTypeText (uint16_t type_code) const
| Convert type code into its textual representation.
bool | textToClassCode (const std::string &class_string, uint16_t &class_code) const
| Convert a textual representation of an RR class to the corresponding 16-bit integer code.
std::string | codeToClassText (uint16_t class_code) const
| Convert class code into its textual representation.

## RDATA Factories
This set of methods provide a unified interface to create an `rdata::Rdata` object in a parameterized polymorphic way, that is, these methods 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::Rdata`. These methods first search the `RRParamRegistry` for a factory method (a member of a concrete derived class of `AbstractRdataFactory`) for the given RR type and class pair. If the search fails, they then search for a factory method for the given type ignoring the class, in case a RRClass independent factory method is registered. If it still fails, these methods assume the RDATA is of an "unknown" type, and creates a new object by calling a constructor of the `rdata::generic::Generic` class.
rdata::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.
rdata::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.
rdata::RdataPtr | createRdata (const RRType &rrtype, const RRClass &rrclass, const rdata::Rdata &source)
| Create RDATA of a given pair of RR type and class, copying of another RDATA of same kind.
rdata::RdataPtr | createRdata (const RRType &rrtype, const RRClass &rrclass, MasterLexer &lexer, const Name *origin, MasterLoader::Options options, MasterLoaderCallbacks &callbacks)
| Create RDATA using MasterLexer.

## Constructors and Destructor
These are intentionally hidden (see the class description).
static RRParamRegistry & | getRegistry ()
| Return the singleton instance of `RRParamRegistry`.

## Detailed Description

The `RRParamRegistry` class represents a registry of parameters to manipulate DNS resource records (RRs).

A `RRParamRegistry` class object stores a mapping between RR types or classes and their textual representations. It will also have knowledge of how to create an RDATA object for a specific pair of RR type and class (not implemented in this version).

Normal applications that only handle standard DNS protocols won't have to care about this class. This is mostly an internal class to the DNS library to manage standard parameters. Some advanced applications may still need to use this class explicitly. For example, if an application wants to define and use an experimental non-standard RR type, it may want to register related protocol parameters for its convenience. This class is designed to allow such usage without modifying the library source code or rebuilding the library.

It is assumed that at most one instance of this class can exist so that the application uses the consistent set of registered parameters. To ensure this, this class is designed and implemented as a "singleton class": the constructor is intentionally private, and applications must get access to the single instance via the `getRegistry()` static member function.

In the current implementation, access to the singleton `RRParamRegistry` object is not thread safe. The application should ensure that multiple threads don't race in the first invocation of `getRegistry()`, and, if the registry needs to be changed dynamically, read and write operations are performed exclusively. Since this class should be static in common usage this restriction would be acceptable in practice. In the future, we may extend the implementation so that multiple threads can get access to the registry fully concurrently without any restriction.

Note: the implementation of this class is incomplete: we should at least add RDATA related parameters. This will be done in a near future version, at which point some of method signatures will be changed.

Definition at line 172 of file rrparamregistry.h.

## Member Function Documentation

## ◆ add() [1/2]

void isc::dns::RRParamRegistry::add | ( | const std::string & | type_string,
|  | uint16_t | type_code,
|  | const std::string & | class_string,
|  | uint16_t | class_code,
|  | rdata::RdataFactoryPtr | rdata_factory )

Add a set of parameters for a pair of RR type and class.

This method adds to the registry a specified set of RR parameters, including mappings between type/class codes and their textual representations.

Regarding the mappings between textual representations and integer codes, this method behaves in the same way as `addType()` and `addClass()`. That is, it ignores any overriding attempt as long as the mapping is the same; otherwise the corresponding exception will be thrown.

This method provides the strong exception guarantee: unless an exception is thrown the entire specified set of parameters must be stored in the registry; if this method throws an exception the registry will remain in the state before this method is called.

Parameters

  type_string | The textual representation of the RR type.
  type_code | The integer code of the RR type.
  class_string | The textual representation of the RR class.
  class_code | The integer code of the RR class.
  rdata_factory | An `RdataFactoryPtr` object pointing to a concrete RDATA factory.

Definition at line 342 of file rrparamregistry.cc.

References addClass(), addType(), removeClass(), and removeType().

Here is the call graph for this function:

## ◆ add() [2/2]

void isc::dns::RRParamRegistry::add | ( | const std::string & | type_string,
|  | uint16_t | type_code,
|  | rdata::RdataFactoryPtr | rdata_factory )

Add a set of parameters for a class-independent RR type.

This method behaves as exactly same as the other `add` method except that it handles class-independent types (such as NS, CNAME, or SOA).

Parameters

  type_string | The textual representation of the RR type.
  type_code | The integer code of the RR type.
  rdata_factory | An `RdataFactoryPtr` object pointing to a concrete RDATA factory.

Definition at line 325 of file rrparamregistry.cc.

References addType(), and removeType().

Here is the call graph for this function:

## ◆ addClass()

bool isc::dns::RRParamRegistry::addClass | ( | const std::string & | class_string,
|  | uint16_t | class_code )

Add mappings between RR class code and textual representation.

This method adds a mapping from the class code of an RR to its textual representation and the reverse mapping in the registry.

If the given RR class is already registered with the same textual representation, this method simply ignores the duplicate mapping; if the given class is registered and a new pair with a different textual representation is being added,an exception of class `RRClassExist` will be thrown. To replace an existing mapping with a different textual representation, the existing one must be removed by the `removeClass()` method beforehand.

In addition, if resource allocation for the new mapping entries fails, a corresponding standard exception will be thrown.

This method provides the strong exception guarantee: unless an exception is thrown the specified mappings must be stored in the registry (although it may be an already existing one) on completion of the method; if this method throws an exception the registry will remain in the state before this method is called.

Parameters

  class_string | The textual representation of the RR class.
  class_code | The integer code of the RR class.

Returns
  `true` if a new mapping is added to the repository; `false` if the same mapping is already registered.

Definition at line 545 of file rrparamregistry.cc.

Referenced by add().

## ◆ addType()

bool isc::dns::RRParamRegistry::addType | ( | const std::string & | type_string,
|  | uint16_t | type_code )

Add mappings between RR type code and textual representation.

This method adds a mapping from the type code of an RR to its textual representation and the reverse mapping in the registry.

If the given RR type is already registered with the same textual representation, this method simply ignores the duplicate mapping; if the given type is registered and a new pair with a different textual representation is being added,an exception of class `RRTypeExist` will be thrown. To replace an existing mapping with a different textual representation, the existing one must be removed by the `removeType()` method beforehand.

In addition, if resource allocation for the new mapping entries fails, a corresponding standard exception will be thrown.

This method provides the strong exception guarantee: unless an exception is thrown the specified mappings must be stored in the registry (although it may be an already existing one) on completion of the method; if this method throws an exception the registry will remain in the state before this method is called.

Parameters

  type_string | The textual representation of the RR type.
  type_code | The integer code of the RR type.

Returns
  `true` if a new mapping is added to the repository; `false` if the same mapping is already registered.

Definition at line 521 of file rrparamregistry.cc.

Referenced by add(), and add().

## ◆ codeToClassText()

string isc::dns::RRParamRegistry::codeToClassText | ( | uint16_t | class_code | ) | const

Convert class code into its textual representation.

This method searches the `RRParamRegistry` for the mapping from the given RR class code to its textual representation. If a mapping is found, it returns (a copy of) the associated string; otherwise, this method creates a new string in the form of "CLASSnnnn" where "nnnn" is the decimal representation of the class code, and returns the new string.

If resource allocation for the returned string fails, a corresponding standard exception will be thrown. This method never fails otherwise.

Parameters

  class_code | The integer code of the RR class.

Returns
  A textual representation of the RR class for code `class_code`.

Definition at line 565 of file rrparamregistry.cc.

## ◆ codeToTypeText()

string isc::dns::RRParamRegistry::codeToTypeText | ( | uint16_t | type_code | ) | const

Convert type code into its textual representation.

This method searches the `RRParamRegistry` for the mapping from the given RR type code to its textual representation. If a mapping is found, it returns (a copy of) the associated string; otherwise, this method creates a new string in the form of "TYPEnnnn" where "nnnn" is the decimal representation of the type code, and returns the new string.

If resource allocation for the returned string fails, a corresponding standard exception will be thrown. This method never fails otherwise.

Parameters

  type_code | The integer code of the RR type.

Returns
  A textual representation of the RR type for code `type_code`.

Definition at line 540 of file rrparamregistry.cc.

## ◆ createRdata() [1/4]

RdataPtr isc::dns::RRParamRegistry::createRdata | ( | const RRType & | rrtype,
|  | const RRClass & | rrclass,
|  | const rdata::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`.

`source` must be an object of the concrete derived class of `rdata::Rdata` for the given pair of RR type and class; otherwise, an exception of class `std::bad_cast` will be thrown. In case the `RRParamRegistry` doesn't have a factory method for the given pair and it is assumed to be of an "unknown" type, `source` must reference an object of class `rdata::generic::Generic`; otherwise, an exception of class `std::bad_cast` will be thrown.

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::Rdata` object whose content is to be copied to the created `rdata::Rdata` object.

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

Definition at line 618 of file rrparamregistry.cc.

## ◆ createRdata() [2/4]

RdataPtr isc::dns::RRParamRegistry::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 `rdata::RdataPtr` object pointing to the created `Rdata` object.

Definition at line 591 of file rrparamregistry.cc.

Referenced by isc::dns::rdata::createRdata(), and isc::dns::rdata::createRdata().

## ◆ createRdata() [3/4]

RdataPtr isc::dns::RRParamRegistry::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.

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 `rdata::RdataPtr` object pointing to the created `Rdata` object.

Definition at line 606 of file rrparamregistry.cc.

## ◆ createRdata() [4/4]

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

Create RDATA using MasterLexer.

This method is expected to be used as the underlying implementation of the same signature of `rdata::createRdata()`. One main difference is that this method is only responsible for constructing the Rdata; it doesn't update the lexer to reach the end of line or file or doesn't care about whether there's an extra (garbage) token after the textual RDATA representation. Another difference is that this method can throw on error and never returns a null pointer.

For other details and parameters, see the description of `rdata::createRdata()`.

Definition at line 631 of file rrparamregistry.cc.

## ◆ getRegistry()

RRParamRegistry & isc::dns::RRParamRegistry::getRegistry | ( |  | ) |
| static

Return the singleton instance of `RRParamRegistry`.

This method is a unified access point to the singleton instance of the RR parameter registry (`RRParamRegistry`). On first invocation it internally constructs an instance of the `RRParamRegistry` class and returns a reference to it. This is a static object inside this method and will remain valid throughout the rest of the application lifetime. On subsequent calls this method simply returns a reference to the singleton object.

If resource allocation fails in the first invocation, a corresponding standard exception will be thrown. This method never fails otherwise. In particular, this method doesn't throw an exception once the singleton instance is constructed.

Returns
  A reference to the singleton instance of `RRParamRegistry`.

Definition at line 318 of file rrparamregistry.cc.

Referenced by isc::dns::RRClass::RRClass(), isc::dns::RRType::RRType(), isc::dns::RRClass::createFromText(), isc::dns::rdata::createRdata(), isc::dns::rdata::createRdata(), isc::dns::rdata::createRdata(), isc::dns::rdata::createRdata(), isc::dns::RRClass::toText(), and isc::dns::RRType::toText().

## ◆ removeClass()

bool isc::dns::RRParamRegistry::removeClass | ( | uint16_t | class_code | ) |

Remove mappings between RR class code and textual representation for a given class.

This method can safely be called whether or not the specified mappings exist in the registry. If not, this method simply ignores the attempt and returns `false`.

This method never throws an exception.

Parameters

  class_code | The integer code of the RR class.

Returns
  `true` if mappings for the specified RR type exists and is removed; `false` if no such mapping is in the registry.

Definition at line 551 of file rrparamregistry.cc.

Referenced by add().

## ◆ removeRdataFactory() [1/2]

bool isc::dns::RRParamRegistry::removeRdataFactory | ( | const RRType & | rrtype | ) |

Remove registered RDATA factory for the given pair of `RRType` and `RRClass`.

This method can safely be called whether or not the specified factory object exist in the registry. If not, this method simply ignores the attempt and returns `false`.

This method never throws an exception.

Parameters

  rrtype | An `RRType` object specifying the type/class pair.

Returns
  `true` if a factory object for the specified RR type/class pair exists and is removed; `false` if no such object is in the registry.

Definition at line 386 of file rrparamregistry.cc.

## ◆ removeRdataFactory() [2/2]

bool isc::dns::RRParamRegistry::removeRdataFactory | ( | const RRType & | rrtype,
|  | const RRClass & | rrclass )

Remove registered RDATA factory for the given pair of `RRType` and `RRClass`.

This method can safely be called whether or not the specified factory object exist in the registry. If not, this method simply ignores the attempt and returns `false`.

This method never throws an exception.

Parameters

  rrtype | An `RRType` object specifying the type/class pair.
  rrclass | An `RRClass` object specifying the type/class pair.

Returns
  `true` if a factory object for the specified RR type/class pair exists and is removed; `false` if no such object is in the registry.

Definition at line 373 of file rrparamregistry.cc.

## ◆ removeType()

bool isc::dns::RRParamRegistry::removeType | ( | uint16_t | type_code | ) |

Remove mappings between RR type code and textual representation for a given type.

This method can safely be called whether or not the specified mappings exist in the registry. If not, this method simply ignores the attempt and returns `false`.

This method never throws an exception.

Parameters

  type_code | The integer code of the RR type.

Returns
  `true` if mappings for the specified RR type exists and is removed; `false` if no such mapping is in the registry.

Definition at line 527 of file rrparamregistry.cc.

Referenced by add(), and add().

## ◆ textToClassCode()

bool isc::dns::RRParamRegistry::textToClassCode | ( | const std::string & | class_string,
|  | uint16_t & | class_code ) const

Convert a textual representation of an RR class to the corresponding 16-bit integer code.

This method searches the `RRParamRegistry` for the mapping from the given textual representation of RR class to the corresponding integer code. If a mapping is found, it returns true with the associated class code in `class_code`; otherwise, if the given string is in the form of "CLASSnnnn", it returns true with the corresponding number as the class code in `class_code`; otherwise, it returns false and `class_code` is untouched.

It returns `false` and avoids throwing an exception in the case of an error to avoid the exception overhead in some situations.

Parameters

  class_string | The textual representation of the RR class.
  class_code | Returns the RR class code in this argument.

Returns
  true if conversion is successful, false otherwise.

Definition at line 558 of file rrparamregistry.cc.

## ◆ textToTypeCode()

bool isc::dns::RRParamRegistry::textToTypeCode | ( | const std::string & | type_string,
|  | uint16_t & | type_code ) const

Convert a textual representation of an RR type to the corresponding 16-bit integer code.

This method searches the `RRParamRegistry` for the mapping from the given textual representation of RR type to the corresponding integer code. If a mapping is found, it returns true with the associated type code in `type_code`; otherwise, if the given string is in the form of "TYPEnnnn", it returns true with the corresponding number as the type code in `type_code`; otherwise, it returns false and `type_code` is untouched.

It returns `false` and avoids throwing an exception in the case of an error to avoid the exception overhead in some situations.

Parameters

  type_string | The textual representation of the RR type.
  type_code | Returns the RR type code in this argument.

Returns
  true if conversion is successful, false otherwise.

Definition at line 533 of file rrparamregistry.cc.

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

- rrparamregistry.h
- rrparamregistry.cc