Kea  2.3.2-git
isc::dns::MasterLoader Class Reference

A class able to load DNS master files. More...

#include <master_loader.h>

+ Inheritance diagram for isc::dns::MasterLoader:

Classes

class  MasterLoaderImpl
 Private implementation class for the MasterLoader. More...
 

Public Types

enum  Options { DEFAULT = 0, MANY_ERRORS = 1 }
 Options how the parsing should work. More...
 

Public Member Functions

 MasterLoader (const char *master_file, const Name &zone_origin, const RRClass &zone_class, const MasterLoaderCallbacks &callbacks, const AddRRCallback &add_callback, Options options=DEFAULT)
 Constructor. More...
 
 MasterLoader (std::istream &input, const Name &zone_origin, const RRClass &zone_class, const MasterLoaderCallbacks &callbacks, const AddRRCallback &add_callback, Options options=DEFAULT)
 Constructor from a stream. More...
 
 ~MasterLoader ()
 Destructor. More...
 
size_t getPosition () const
 Return the position of the loader in zone. More...
 
size_t getSize () const
 Return the total size of the zone files and streams. More...
 
void load ()
 Load everything. More...
 
bool loadedSuccessfully () const
 Was the loading successful? More...
 
bool loadIncremental (size_t count_limit)
 Load some RRs. More...
 

Detailed Description

A class able to load DNS master files.

This class is able to produce a stream of RRs from a master file. It is able to load all of the master file at once, or by blocks incrementally.

It reports the loaded RRs and encountered errors by callbacks.

Definition at line 36 of file master_loader.h.

Member Enumeration Documentation

◆ Options

Options how the parsing should work.

Enumerator
DEFAULT 

Nothing special.

MANY_ERRORS 

Lenient mode (see documentation of MasterLoader constructor).

Definition at line 39 of file master_loader.h.

Constructor & Destructor Documentation

◆ MasterLoader() [1/2]

isc::dns::MasterLoader::MasterLoader ( const char *  master_file,
const Name zone_origin,
const RRClass zone_class,
const MasterLoaderCallbacks callbacks,
const AddRRCallback add_callback,
Options  options = DEFAULT 
)

Constructor.

This creates a master loader and provides it with all relevant information.

Except for the exceptions listed below, the constructor doesn't throw. Most errors (like non-existent master file) are reported by the callbacks during load() or loadIncremental().

Parameters
master_filePath to the file to load.
zone_originThe origin of zone to be expected inside the master file. Currently unused, but it is expected to be used for some validation.
zone_classThe class of zone to be expected inside the master file.
callbacksThe callbacks by which it should report problems. Usually, the callback carries a filename and line number of the input where the problem happens. There's a special case of empty filename and zero line in case the opening of the top-level master file fails.
add_callbackThe callback which would be called with each loaded RR.
optionsOptions for the parsing, which is bitwise-or of the Options values or DEFAULT. If the MANY_ERRORS option is included, the parser tries to continue past errors. If it is not included, it stops at first encountered error.
Exceptions
std::bad_allocwhen there's not enough memory.
isc::InvalidParameterif add_callback is empty.

Definition at line 1015 of file master_loader.cc.

References isc_throw.

◆ MasterLoader() [2/2]

isc::dns::MasterLoader::MasterLoader ( std::istream &  input,
const Name zone_origin,
const RRClass zone_class,
const MasterLoaderCallbacks callbacks,
const AddRRCallback add_callback,
Options  options = DEFAULT 
)

Constructor from a stream.

This is a constructor very similar to the previous one. The only difference is it doesn't take a filename, but an input stream to read the data from. It is expected to be mostly used in tests, but it is public as it may possibly be useful for other currently unknown purposes.

Definition at line 1029 of file master_loader.cc.

References isc::flex_option::impl, and isc_throw.

◆ ~MasterLoader()

isc::dns::MasterLoader::~MasterLoader ( )

Destructor.

Definition at line 1046 of file master_loader.cc.

Member Function Documentation

◆ getPosition()

size_t isc::dns::MasterLoader::getPosition ( ) const

Return the position of the loader in zone.

This method returns a conceptual "position" of the loader in the zone to be loaded. Specifically, it returns the total number of characters contained in the zone files and streams and recognized by the loader. Before starting the load it returns 0; on successful completion it will be equal to the return value of getSize() (unless the latter returns MasterLexer::SOURCE_SIZE_UNKNOWN).

Exceptions
None

Definition at line 1068 of file master_loader.cc.

◆ getSize()

size_t isc::dns::MasterLoader::getSize ( ) const

Return the total size of the zone files and streams.

This method returns the size of the source of the zone to be loaded (master zone files or streams) that is known at the time of the call. For a zone file, it's the size of the file; for a stream, it's the size of the data (in bytes) available at the start of the load. If separate zone files are included via the $INCLUDE directive, the sum of the sizes of these files are added.

If the loader is constructed with a stream, the size can be "unknown" as described for MasterLexer::getTotalSourceSize(). In this case this method always returns MasterLexer::SOURCE_SIZE_UNKNOWN.

If the loader is constructed with a zone file, this method initially returns 0. So until either load() or loadIncremental() is called, the value is meaningless.

Note that when the source includes separate files, this method cannot take into account the included files that the loader has not recognized at the time of call. So it's possible that this method returns different values at different times of call.

Exceptions
None

Definition at line 1063 of file master_loader.cc.

◆ load()

void isc::dns::MasterLoader::load ( )
inline

Load everything.

This simply calls loadIncremental until the loading is done.

Exceptions
isc::InvalidOperationwhen called after loading was done already.
MasterLoaderErrorwhen there's an error in the input master file and the MANY_ERRORS is not specified. It never throws this in case MANY_ERRORS is specified.

Definition at line 121 of file master_loader.h.

Referenced by isc::dns::RRsetCollection::addRRset().

◆ loadedSuccessfully()

bool isc::dns::MasterLoader::loadedSuccessfully ( ) const

Was the loading successful?

Returns
true if and only if the loading was complete (after a call of load or after loadIncremental returned true) and there was no error. In other cases, return false.
Note
While this method works even before the loading is complete (by returning false in that case), it is meant to be called only after finishing the load.

Definition at line 1058 of file master_loader.cc.

◆ loadIncremental()

bool isc::dns::MasterLoader::loadIncremental ( size_t  count_limit)

Load some RRs.

This method loads at most count_limit RRs and reports them. In case an error (either fatal or without MANY_ERRORS) or end of file is encountered, they may be less.

Parameters
count_limitUpper limit on the number of RRs loaded.
Returns
In case it stops because of the count limit, it returns false. It returns true if the loading is done.
Exceptions
isc::InvalidOperationwhen called after loading was done already.
MasterLoaderErrorwhen there's an error in the input master file and the MANY_ERRORS is not specified. It never throws this in case MANY_ERRORS is specified.

Definition at line 1051 of file master_loader.cc.


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