Commit 5ec0945e authored by Michal 'vorner' Vaner's avatar Michal 'vorner' Vaner
Browse files

[2377] Documentation for MasterLoader

parent 11ed5b5c
......@@ -17,29 +17,81 @@
#include <dns/master_loader_callbacks.h>
#include <boost/noncopyable.hpp>
namespace isc {
namespace dns {
class Name;
class RRClass;
class MasterLoader {
/// \brief 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.
class MasterLoader : boost::noncopyable {
public:
/// \brief Options how the parsing should work.
enum Options {
DEFAULT = 0,
MANY_ERRORS ///< Lenient mode
DEFAULT = 0, ///< Nothing special.
MANY_ERRORS = 1 ///< Lenient mode.
};
/// \brief 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().
///
/// \param master_file Path to the file to load.
/// \param zone_origin The origin of zone to be expected inside
/// the master file. Currently unused, but it is expected to
/// be used for some validation.
/// \param zone_class The class of zone to be expected inside the
/// master file.
/// \param callbacks The callbacks by which it should report problems.
/// \param add_callback The callback which would be called with each
/// loaded RR.
/// \param options Options 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.
/// \throw std::bad_alloc when there's not enough memory.
/// \throw isc::InvalidParameter if add_callback is empty.
MasterLoader(const char* master_file,
const Name& zone_origin,
const RRClass& zone_class,
const MasterLoaderCallbacks& callbacks,
const AddRRCallback& add_callback,
Options options = DEFAULT);
/// \brief Destructor
~MasterLoader();
/// \brief 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.
///
/// \param count_limit Upper limit on the number of RRs loaded.
/// \return In case it stops because of the count limit, it returns false.
/// It returns true if the loading is done.
/// \throw isc::InvalidOperation when called after loading was done
/// already.
bool loadIncremental(size_t count_limit);
/// \brief Load everything
///
/// This simply calls loadIncremental until the loading is done.
/// \throw isc::InvalidOperation when called after loading was done
/// already.
void load() {
while (!loadIncremental(1000)) {
while (!loadIncremental(1000)) { // 1000 = arbitrary largish number
// Body intentionally left blank
}
}
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment