Kea  2.3.2-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. More...
 
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. More...
 
bool addType (const std::string &type_string, uint16_t type_code)
 Add mappings between RR type code and textual representation. More...
 
bool removeType (uint16_t type_code)
 Remove mappings between RR type code and textual representation for a given type. More...
 
bool addClass (const std::string &class_string, uint16_t class_code)
 Add mappings between RR class code and textual representation. More...
 
bool removeClass (uint16_t class_code)
 Remove mappings between RR class code and textual representation for a given class. More...
 
bool removeRdataFactory (const RRType &rrtype, const RRClass &rrclass)
 Remove registered RDATA factory for the given pair of RRType and RRClass. More...
 
bool removeRdataFactory (const RRType &rrtype)
 Remove registered RDATA factory for the given pair of RRType and RRClass. More...
 
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. More...
 
std::string codeToTypeText (uint16_t type_code) const
 Convert type code into its textual representation. More...
 
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. More...
 
std::string codeToClassText (uint16_t class_code) const
 Convert class code into its textual representation. More...
 
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. More...
 
rdata::RdataPtr createRdata (const RRType &rrtype, const RRClass &rrclass, isc::util::InputBuffer &buffer, size_t len)
 Create RDATA of a given pair of RR type and class from wire-format data. More...
 
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. More...
 
rdata::RdataPtr createRdata (const RRType &rrtype, const RRClass &rrclass, MasterLexer &lexer, const Name *origin, MasterLoader::Options options, MasterLoaderCallbacks &callbacks)
 Create RDATA using MasterLexer. More...
 

Static Public Member Functions

static RRParamRegistrygetRegistry ()
 Return the singleton instance of RRParamRegistry. More...
 

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 171 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_stringThe textual representation of the RR type.
type_codeThe integer code of the RR type.
class_stringThe textual representation of the RR class.
class_codeThe integer code of the RR class.
rdata_factoryAn RdataFactoryPtr object pointing to a concrete RDATA factory.

Definition at line 348 of file rrparamregistry.cc.

◆ 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_stringThe textual representation of the RR type.
type_codeThe integer code of the RR type.
rdata_factoryAn RdataFactoryPtr object pointing to a concrete RDATA factory.

Definition at line 330 of file rrparamregistry.cc.

◆ 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_stringThe textual representation of the RR class.
class_codeThe 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 555 of file rrparamregistry.cc.

◆ 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_stringThe textual representation of the RR type.
type_codeThe 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 530 of file rrparamregistry.cc.

◆ 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_codeThe integer code of the RR class.
Returns
A textual representation of the RR class for code class_code.

Definition at line 576 of file rrparamregistry.cc.

References isc::dns::RRParamRegistryImpl::genericrdata_factories, and isc::dns::RRParamRegistryImpl::rdata_factories.

◆ 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_codeThe integer code of the RR type.
Returns
A textual representation of the RR type for code type_code.

Definition at line 550 of file rrparamregistry.cc.

◆ createRdata() [1/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
rrtypeAn RRType object specifying the type/class pair.
rrclassAn RRClass object specifying the type/class pair.
rdata_stringA string of textual representation of the Rdata.
Returns
An rdata::RdataPtr object pointing to the created Rdata object.

Definition at line 603 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,
isc::util::InputBuffer buffer,
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
rrtypeAn RRType object specifying the type/class pair.
rrclassAn RRClass object specifying the type/class pair.
bufferA reference to an InputBuffer object storing the Rdata to parse.
lenThe length in buffer of the Rdata. In bytes.
Returns
An rdata::RdataPtr object pointing to the created Rdata object.

Definition at line 619 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,
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
rrtypeAn RRType object specifying the type/class pair.
rrclassAn RRClass object specifying the type/class pair.
sourceA 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 632 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 646 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 323 of file rrparamregistry.cc.

◆ 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_codeThe 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 561 of file rrparamregistry.cc.

◆ removeRdataFactory() [1/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
rrtypeAn RRType object specifying the type/class pair.
rrclassAn 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 380 of file rrparamregistry.cc.

◆ removeRdataFactory() [2/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
rrtypeAn 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 394 of file rrparamregistry.cc.

References isc_throw.

◆ 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_codeThe 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 536 of file rrparamregistry.cc.

◆ 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_stringThe textual representation of the RR class.
class_codeReturns the RR class code in this argument.
Returns
true if conversion is successful, false otherwise.

Definition at line 568 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_stringThe textual representation of the RR type.
type_codeReturns the RR type code in this argument.
Returns
true if conversion is successful, false otherwise.

Definition at line 542 of file rrparamregistry.cc.


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