From be9562a0d38bdb2ba5d3e8456dd13a0cbc19b48e Mon Sep 17 00:00:00 2001 From: JINMEI Tatuya Date: Fri, 13 Apr 2012 23:25:44 -0700 Subject: [PATCH] [1781] overall documentation update --- src/lib/datasrc/database.h | 72 ++++++++++++++++++++++++++++++++++++-- 1 file changed, 70 insertions(+), 2 deletions(-) diff --git a/src/lib/datasrc/database.h b/src/lib/datasrc/database.h index b760f04948..b77ab3ea0b 100644 --- a/src/lib/datasrc/database.h +++ b/src/lib/datasrc/database.h @@ -95,23 +95,36 @@ public: ADD_COLUMN_COUNT = 6 ///< Number of columns }; + /// \brief Definitions of the fields to be passed to addRecordToNSEC3Zone() + /// + /// Each derived implementation of addRecordToNSEC3Zone() should expect + /// the "columns" array to be filled with the values as described in this + /// enumeration, in this order. + /// + /// Note that there is no "reversed name" column. Since the conceptual + /// separate namespace for NSEC3 is very simplified and essentially only + /// consists of a single-label names, there is no need for using reversed + /// names to identify the "previous hash". enum AddNSEC3RecordColumns { - ADD_NSEC3_HASH = 0, ///< The owner name of the record (a domain name) + ADD_NSEC3_HASH = 0, ///< The hash (1st) label of the owner name, + ///< excluding the dot character ADD_NSEC3_TTL = 1, ///< The TTL of the record (in numeric form) ADD_NSEC3_TYPE = 2, ///< The RRType of the record (either NSEC3 or - ///< RRSIG) + ///< RRSIG for NSEC3) ADD_NSEC3_RDATA = 3, ///< Full text representation of the record's ///< RDATA ADD_NSEC3_COLUMN_COUNT = 4 ///< Number of columns }; /// \brief Definitions of the fields to be passed to deleteRecordInZone() + /// and deleteRecordInNSEC3Zone() /// /// Each derived implementation of deleteRecordInZone() should expect /// the "params" array to be filled with the values as described in this /// enumeration, in this order. enum DeleteRecordParams { DEL_NAME = 0, ///< The owner name of the record (a domain name) + ///< or the hash label for deleteRecordInNSEC3Zone() DEL_TYPE = 1, ///< The RRType of the record (A/NS/TXT etc.) DEL_RDATA = 2, ///< Full text representation of the record's RDATA DEL_PARAM_COUNT = 3 ///< Number of parameters @@ -442,6 +455,41 @@ public: virtual void addRecordToZone( const std::string (&columns)[ADD_COLUMN_COUNT]) = 0; + /// \brief Add a single NSEC3-related record to the zone to be updated. + /// + /// This method is similar to \c addRecordToZone(), but is expected to + /// be only used for NSEC3 RRs or RRSIG RRs that cover NSEC3. In terms + /// of the DNS protocol, these types of RRs reside in a separate space + /// of the zone. While this interface does not mandate a specific way + /// of implementing the separate namespaces in the underlying database, + /// it would be more convenient for the underlying implementation if the + /// interfaces are separated; for example, the implementation does not + /// have to examine the given data to identify the appropriate namespace. + /// + /// An implementation may choose to skip providing this interface if the + /// zones managed by that data source are known to not support NSEC3. + /// In that case the implementation should throw the + /// \c isc::NotImplemented exception. + /// + /// Note that the \c ADD_NSEC3_HASH column of \c columns is expected to + /// store only the hash label, not the entire owner name. This is similar + /// to the \c hash parameter of \c getNSEC3Records(). + /// + /// The RRs to be added using this method are expected to be limited to + /// NSEC3 or RRSIG RRs that cover NSEC3, but it's generally assumed to + /// be the caller's responsibility to ensure that; the implementation + /// is not required to check that condition. The result of adding + /// unexpected type of RRs (and the result of subsequent lookups) is + /// undefined. + /// + /// Other general notes for \c addRecordToZone() also applies to this + /// method. + /// + /// \exception isc::NotImplemented in case the database does not support + /// NSEC3 + /// + /// \param columns An array of strings that defines a record to be added + /// to the NSEC3 namespace of the zone. virtual void addRecordToNSEC3Zone( const std::string (&columns)[ADD_NSEC3_COLUMN_COUNT]) = 0; @@ -482,6 +530,26 @@ public: virtual void deleteRecordInZone( const std::string (¶ms)[DEL_PARAM_COUNT]) = 0; + /// \brief Delete a single NSEC3-related record from the zone to be + /// updated. + /// + /// This method is similar to \c deleteRecordInZone(), but is expected to + /// be only used for NSEC3 RRs or RRSIG RRs that cover NSEC3. The + /// relationship between these two methods is similar to that between + /// \c addRecordToZone() and \c addRecordToNSEC3Zone(), and the same + /// notes apply to this method. + /// + /// This method uses the same set of parameters to specify the record + /// to be deleted as \c deleteRecordInZone(), but the \c DEL_NAME column + /// is expected to only store the hash label of the owner name. + /// This is the same as \c ADD_NSEC3_HASH column for + /// \c addRecordToNSEC3Zone(). + /// + /// \exception isc::NotImplemented in case the database does not support + /// NSEC3 + /// + /// \param params An array of strings that defines a record to be deleted + /// from the NSEC3 namespace of the zone. virtual void deleteRecordInNSEC3Zone( const std::string (¶ms)[DEL_PARAM_COUNT]) = 0;