[svn] commit: r2606 - /branches/trac232/src/lib/datasrc/data_source.h
BIND 10 source code commits
bind10-changes at lists.isc.org
Wed Jul 28 15:30:12 UTC 2010
Author: jelte
Date: Wed Jul 28 15:30:12 2010
New Revision: 2606
Log:
header file documentation for the writables functions in data_source.h
Modified:
branches/trac232/src/lib/datasrc/data_source.h
Modified: branches/trac232/src/lib/datasrc/data_source.h
==============================================================================
--- branches/trac232/src/lib/datasrc/data_source.h (original)
+++ branches/trac232/src/lib/datasrc/data_source.h Wed Jul 28 15:30:12 2010
@@ -354,39 +354,131 @@
//
// Writable data sources
//
- // This not the final API
// For datasource that support writing, overwrite these
// methods. By default they will return NOT_IMPLEMENTED.
+ ///
+ /// \name Low-level functions for writable data sources.
+ /// The default functions for these return T_NOT_IMPLEMENTED
+ /// A data source that supports writes MUST override these methods.
+ ///
+ //@{
+ /// \brief Start a transaction
+ /// The given transaction must be in state INIT.
+ /// On success, the transaction must be in state RUNNING.
+ /// The data source checks for the zone, starts a backend
+ /// transaction, and sets any data it will need later in the given
+ /// transaction object.
+ /// \param transaction, a transaction that has been initialized for
+ /// a zone held by this data source.
+ /// \return T_SUCCESS on success, error value otherwise
+ virtual TransactionResult startTransaction(DataSrcTransaction& transaction);
+
+ /// \brief Commit the changes made in the given transaction
+ /// The transaction object must be in state RUNNING.
+ /// On successs, the transaction will be in state DONE.
+ /// \param transaction to be committed.
+ /// \return T_SUCCESS on success, error value otherwise
+ virtual TransactionResult commitTransaction(DataSrcTransaction& transaction);
+
+ /// \brief Roll back the changes made in the given transaction
+ /// The transaction object must be in state RUNNING.
+ /// On successs, the transaction will be in state DONE.
+ /// \param transaction to be rolled back.
+ /// \return T_SUCCESS on success, error value otherwise
+ virtual TransactionResult rollbackTransaction(DataSrcTransaction& transaction);
+
+ /// \brief Add an RRset to the zone.
+ /// \param transaction The transaction in which this addition is
+ /// performed.
+ /// \param RRsetPtr The RRset to add
+ /// \param T_SUCCESS on success.
virtual TransactionResult addRRset(DataSrcTransaction& transaction,
isc::dns::ConstRRsetPtr rrset);
+
+ /// \brief Delete an RRset from the zone.
+ /// \param transaction The transaction in which this deletion is
+ /// performed.
+ /// \param RRsetPtr The RRset to delete
+ /// \param T_SUCCESS on success.
virtual TransactionResult delRRset(DataSrcTransaction& transaction,
isc::dns::ConstRRsetPtr rrset);
+
+ /// \brief Remove an entire zone from the data source
+ /// Removes all records for the zone, and the zone itself from
+ /// the datasource.
+ /// \param transaction The transaction in which this deletion is
+ /// performed.
+ /// \return T_SUCCESS on success
virtual TransactionResult delZone(DataSrcTransaction& transaction);
+
+ /// \brief Replace the contents of the zone by the given list of
+ /// rrsets.
+ /// This deletes *all* current RRsets in the zone.
+ /// \param transaction The transaction to perform the operations on
+ /// \return T_SUCCESS on success
virtual TransactionResult replaceZone(DataSrcTransaction& transaction,
const isc::dns::RRsetList& rrsets);
-
- // The following methods are used by the 'high-level' ones below
- //
- // You can overwrite these functions if there is a specific reason
- // In principle this should not be necessary
+ //@}
+
+ /// \name High-level functions for writable data sources
+ /// These functions have a default implementation, and do not
+ /// need to be overridden. They can be, if the data source can make
+ /// use of specific knowledge about the backend.
+
+ //@{
+ /// \brief Checks whether an RRset exists
+ /// If the given RRset is of class NONE or ANY, it will check if
+ /// there are rrs for class IN.
+ /// If the given rrset has 0 rdata records; any RR with the given
+ /// name, class and type will result in a positive result,
+ /// otherwise the rrset in the data source4 must be exactly the
+ /// same.
+ ///
+ /// \param transaction The transaction in which the check is
+ /// performed
+ /// \param rrset The rrset to check for
+ /// \return true if the given rrset is equal to the one in the
+ /// database, or if the given rrset has a 0 rdata count,
+ /// and there are records in the database with the same
+ /// name, class and type. False otherwise.
virtual bool haveRRset(DataSrcTransaction& transaction,
isc::dns::ConstRRsetPtr rrset);
+
+ /// \brief Checks a prerequisite as described in section 3.2 of
+ /// RFC2136
+ /// \param transaction The transaction to perform the check in
+ /// \param prereq the prerequisite RRset
+ /// \return The DNS Rcode as defined by the rules in RFC2136
virtual isc::dns::Rcode updateCheckPrerequisite(DataSrcTransaction& transaction,
isc::dns::RRsetPtr prereq);
+
+ /// \brief Handles a single update as described in section 3.4 of
+ /// RFC2136
+ /// \param transaction The transaction to perform the update
+ /// \param update the update RRset
+ /// \return The DNS Rcode as defined by the rules in RFC2136
virtual isc::dns::Rcode updateProcessUpdate(DataSrcTransaction& transaction,
isc::dns::RRsetPtr update);
- // General High-level functions. If your data source can make use
- // of backend-specific shortcuts, you can overwrite these methods
- virtual TransactionResult startTransaction(DataSrcTransaction& transaction);
- virtual TransactionResult commitTransaction(DataSrcTransaction& transaction);
- virtual TransactionResult rollbackTransaction(DataSrcTransaction& transaction);
+ /// \brief Perform an IXFR operation
+ /// The given RRset iterator should point to the section of the
+ /// IXFR answer, and is processed as described in RFC1995
+ /// \param transaction the transaction to perform the operation in
+ /// \param start The start of the rrset iterator to handle
+ /// \param end the end of the rrset iterator to handle
+ /// \return SUCCESS on success, ERROR on failure.
virtual Result doIXFR(DataSrcTransaction& transaction,
const isc::dns::RRsetIterator start,
const isc::dns::RRsetIterator end);
+
+ /// \brief Perform a DNS Dynamic update as desribed in RFC2136
+ /// \param transaction the transaction to perform the udpate in
+ /// \param msg the DNS UPDATE msg to handle
+ /// \return SUCCESS on success, ERROR on failure.
virtual Result doUpdate(DataSrcTransaction& transaction,
isc::dns::Message& msg);
+ //@}
private:
isc::dns::RRClass rrclass;
More information about the bind10-changes
mailing list