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.

References isc::dns::rdata::AbstractRdataFactory::create().

Here is the call graph for this function:

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

References isc::dns::rdata::AbstractRdataFactory::create().

Here is the call graph for this function:

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

References isc::dns::rdata::AbstractRdataFactory::create().

Here is the call graph for this function:

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

References isc::dns::rdata::AbstractRdataFactory::create().

Here is the call graph for this function:

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

Public Member Functions

RDATA Factories

Constructors and Destructor

Detailed Description

Member Function Documentation

◆ add() [1/2]

◆ add() [2/2]

◆ addClass()

◆ addType()

◆ codeToClassText()

◆ codeToTypeText()

◆ createRdata() [1/4]

◆ createRdata() [2/4]

◆ createRdata() [3/4]

◆ createRdata() [4/4]

◆ getRegistry()

◆ removeClass()

◆ removeRdataFactory() [1/2]

◆ removeRdataFactory() [2/2]

◆ removeType()

◆ textToClassCode()

◆ textToTypeCode()