[svn] commit: r3123 - in /branches/trac358/src/lib/dns: message.cc message.h

BIND 10 source code commits bind10-changes at lists.isc.org
Wed Oct 6 13:03:28 UTC 2010


Author: jinmei
Date: Wed Oct  6 13:03:27 2010
New Revision: 3123

Log:
added more documentation
with one minor cleanup (removed an unused constant)

Modified:
    branches/trac358/src/lib/dns/message.cc
    branches/trac358/src/lib/dns/message.h

Modified: branches/trac358/src/lib/dns/message.cc
==============================================================================
--- branches/trac358/src/lib/dns/message.cc (original)
+++ branches/trac358/src/lib/dns/message.cc Wed Oct  6 13:03:27 2010
@@ -883,6 +883,5 @@
 operator<<(ostream& os, const Message& message) {
     return (os << message.toText());
 }
-
 } // end of namespace dns
 } // end of namespace isc

Modified: branches/trac358/src/lib/dns/message.h
==============================================================================
--- branches/trac358/src/lib/dns/message.h (original)
+++ branches/trac358/src/lib/dns/message.h Wed Oct  6 13:03:27 2010
@@ -87,18 +87,6 @@
 
 template <typename T>
 struct SectionIteratorImpl;
-
-/// \brief The \c Section class objects represent DNS message sections such
-/// as the header, question, or answer.
-///
-/// Note: this class doesn't seem to be very useful.  We should probably
-/// revisit this design.
-///
-/// Note: whether or not it's represented as a class, we'll need a way
-/// to represent more advanced sections such as those used in dynamic updates.
-/// This is a TODO item.
-///
-/// Constant objects are defined for standard flags.
 
 /// \c SectionIterator is a templated class to provide standard-compatible
 /// iterators for Questions and RRsets for a given DNS message section.
@@ -159,36 +147,99 @@
 ///   of RR in the message.
 class Message {
 public:
+    /// Constants to specify the operation mode of the \c Message.
     enum Mode {
-        PARSE = 0,
-        RENDER = 1
+        PARSE = 0,              ///< Parse mode (handling an incoming message)
+        RENDER = 1              ///< Render mode (building an outgoing message)
     };
 
-    /// notes:
-    /// - won't prohibit ugly casting and bit-wise operation at the code
-    ///   level:
-    /// \code uint16_t combined_flags = static_cast<uint16_t>(HEADERFLAG_AA) |
-    /// static_cast<uint16_t>(HEADERFLAG_CD);
-    /// message->setHeaderFlag(static_cast<HeaderFlag>(combined_flags), true);
+    /// \brief Constants for flag bit fields of a DNS message header.
+    ///
+    /// Only the defined constants are valid where a header flag is required
+    /// in this library (e.g., in \c Message::setHeaderFlag()).
+    /// Since these are enum constants, however, invalid value could be passed
+    /// via casting without an error at compilation time.
+    /// It is generally the callee's responsibility to check and reject invalid
+    /// values.
+    /// Of course, applications shouldn't pass invalid values even if the
+    /// callee does not perform proper validation; the result in such usage
+    /// is undefined.
+    ///
+    /// In the current implementation, the defined values happen to be
+    /// a 16-bit integer with one bit being set corresponding to the
+    /// specified flag in the second 16 bits of the DNS Header section
+    /// in order to make the internal implementation simpler.
+    /// For example, \c HEADERFLAG_QR is defined to be 0x8000 as the QR
+    /// bit is the most significant bit of the 2nd 16 bits of the header.
+    /// However, applications should not assume this coincidence and
+    /// must solely use the enum representations.
+    /// Any usage based on the assumption of the underlying values is invalid
+    /// and the result is undefined.
+    ///
+    /// Likewise, bit wise operations such as AND or OR on the flag values
+    /// are invalid and are not guaranteed to work, even if it could compile
+    /// with casting.
+    /// For example, the following code will compile:
+    /// \code const uint16_t combined_flags =
+    ///           static_cast<uint16_t>(Message::HEADERFLAG_AA) |
+    ///           static_cast<uint16_t>(Message::HEADERFLAG_CD);
+    /// message->setHeaderFlag(static_cast<Message::HeaderFlag>(combined_flags));
     /// \endcode
-    /// but it's highly discouraged, and hopefully the cast notation is
-    /// sufficiently ugly to prevent proliferation of the usage.
+    /// and (with the current definition) happens to work as if it were
+    /// validly written as follows:
+    /// \code message->setHeaderFlag(Message::HEADERFLAG_AA);
+    /// message->setHeaderFlag(Message::HEADERFLAG_CD);
+    /// \endcode
+    /// But the former notation is invalid and may not work in future versions.
+    /// We did not try to prohibit such usage at compilation time, e.g., by
+    /// introducing a separately defined class considering the balance
+    /// between the complexity and advantage, but hopefully the cast notation
+    /// is sufficiently ugly to prevent proliferation of the usage.
     enum HeaderFlag {
-        HEADERFLAG_QR = 0x8000,
-        HEADERFLAG_AA = 0x0400,
-        HEADERFLAG_TC = 0x0200,
-        HEADERFLAG_RD = 0x0100,
-        HEADERFLAG_RA = 0x0080,
-        HEADERFLAG_AD = 0x0020,
-        HEADERFLAG_CD = 0x0010
+        HEADERFLAG_QR = 0x8000, ///< Query (if cleared) or response (if set)
+        HEADERFLAG_AA = 0x0400, ///< Authoritative answer
+        HEADERFLAG_TC = 0x0200, ///< Truncation
+        HEADERFLAG_RD = 0x0100, ///< Recursion desired
+        HEADERFLAG_RA = 0x0080, ///< Recursion available
+        HEADERFLAG_AD = 0x0020, ///< DNSSEC checking disabled (RFC4035)
+        HEADERFLAG_CD = 0x0010  ///< Authentic %data (RFC4035)
     };
 
-    /// This happens to be the index, but apps should not assume that.
+    /// \brief Constants to specify sections of a DNS message.
+    ///
+    /// The sections are those defined in RFC 1035 excluding the Header
+    /// section; the fields of the Header section are accessed via specific
+    /// methods of the \c Message class (e.g., \c getQid()).
+    ///
+    /// <b>Open Design Issue:</b>
+    /// In the current implementation the values for the constants are
+    /// sorted in the order of appearance in DNS messages, i.e.,
+    /// from %Question to Additional.
+    /// So, for example,
+    /// code <code>section >= Message::SECTION_AUTHORITY</code> can be
+    /// used to do something in or after the Authority section.
+    /// This would be convenient, but it is not clear if it's really a good
+    /// idea to rely on relationship between the underlying values of enum
+    /// constants.  At the moment, applications are discouraged to rely on
+    /// this implementation detail.  We will see if such usage is sufficiently
+    /// common to officially support it.
+    ///
+    /// Note also that since we don't define \c operator++ for this enum,
+    /// the following code intending to iterate over all sections will
+    /// \b not compile:
+    /// \code for (Section s; s <= SECTION_ADDITIONAL; ++s) { // ++s undefined
+    ///     // do something
+    /// } \endcode
+    /// This is intentional at this moment, and we'll see if we need to allow
+    /// that as we have more experiences with this library.
+    ///
+    /// <b>Future Extension:</b> We'll probably also define constants for
+    /// the section names used in dynamic updates in future versions.
     enum Section {
-        SECTION_QUESTION = 0,
-        SECTION_ANSWER = 1,
-        SECTION_AUTHORITY = 2,
-        SECTION_ADDITIONAL = 3
+        SECTION_QUESTION = 0,   ///< %Question section
+        SECTION_ANSWER = 1,     ///< Answer section
+        SECTION_AUTHORITY = 2,  ///< Authority section
+        SECTION_ADDITIONAL = 3  ///< Additional section
     };
 
     ///
@@ -218,7 +269,9 @@
     /// \brief Set or clear the specified header flag bit in the header
     /// section.
     ///
-    /// Only allowed in the \c RENDER mode.
+    /// This method is only allowed in the \c RENDER mode;
+    /// if the \c Message is in other mode, an exception of class
+    /// InvalidMessageOperation will be thrown.
     void setHeaderFlag(const HeaderFlag flag, const bool on = true);
 
     /// \brief Return the query ID given in the header section of the message.
@@ -226,7 +279,9 @@
 
     /// \brief Set the query ID of the header section of the message.
     ///
-    /// Only allowed in the \c RENDER mode.
+    /// This method is only allowed in the \c RENDER mode;
+    /// if the \c Message is in other mode, an exception of class
+    /// InvalidMessageOperation will be thrown.
     void setQid(qid_t qid);
 
     /// \brief Return the Response Code of the message.
@@ -244,7 +299,9 @@
 
     /// \brief Set the Response Code of the message.
     ///
-    /// Only allowed in the \c RENDER mode.
+    /// This method is only allowed in the \c RENDER mode;
+    /// if the \c Message is in other mode, an exception of class
+    /// InvalidMessageOperation will be thrown.
     ///
     /// If the specified code is an EDNS extended RCODE, an EDNS OPT RR will be
     /// included in the message.
@@ -260,7 +317,9 @@
 
     /// \brief Set the OPCODE of the header section of the message.
     ///
-    /// Only allowed in the \c RENDER mode.
+    /// This method is only allowed in the \c RENDER mode;
+    /// if the \c Message is in other mode, an exception of class
+    /// InvalidMessageOperation will be thrown.
     void setOpcode(const Opcode& opcode);
 
     /// \brief Return, if any, the EDNS associated with the message.
@@ -273,14 +332,37 @@
 
     /// \brief Set EDNS for the message.
     ///
-    /// Only allowed in the \c RENDER mode; otherwise an exception of class
-    /// \c InvalidMessageOperation will be thrown.
+    /// This method is only allowed in the \c RENDER mode;
+    /// if the \c Message is in other mode, an exception of class
+    /// InvalidMessageOperation will be thrown.
     ///
     /// \param edns A shared pointer to an \c EDNS object to be set in
     /// \c Message.
     void setEDNS(ConstEDNSPtr edns);
 
     /// \brief Returns the number of RRs contained in the given section.
+    ///
+    /// In the \c PARSE mode, the returned value may not be identical to
+    /// the actual number of RRs of the incoming message that is parsed.
+    /// The \c Message class handles some "meta" RRs such as EDNS OPT RR
+    /// separately.  This method doesn't include such RRs.
+    /// Also, a future version of the parser will detect and unify duplicate
+    /// RRs (which should be rare in practice though), in which case
+    /// the stored RRs in the \c Message object will be fewer than the RRs
+    /// originally contained in the incoming message.
+    ///
+    /// Likewise, in the \c RENDER mode, even if \c EDNS is set in the
+    /// \c Message, this method doesn't count the corresponding OPT RR
+    /// in the Additional section.
+    ///
+    /// This method is basically exception free, but if
+    /// \c section is not a valid constant of the \c Section type,
+    /// an exception of class \c OutOfRange will be thrown.
+    ///
+    /// \param section The section in the message where RRs should be
+    /// counted.
+    /// \return The number of RRs stored in the specified section of the
+    /// message.
     unsigned int getRRCount(const Section section) const;
 
     /// \brief Return an iterator corresponding to the beginning of the
@@ -293,15 +375,23 @@
 
     /// \brief Return an iterator corresponding to the beginning of the
     /// given section (other than Question) of the message.
+    ///
+    /// \c section must be a valid constant of the \c Section type;
+    /// otherwise, an exception of class \c OutOfRange will be thrown.
     const RRsetIterator beginSection(const Section section) const;
 
     /// \brief Return an iterator corresponding to the end of the
     /// given section (other than Question) of the message.
+    ///
+    /// \c section must be a valid constant of the \c Section type;
+    /// otherwise, an exception of class \c OutOfRange will be thrown.
     const RRsetIterator endSection(const Section section) const;
 
     /// \brief Add a (pointer like object of) Question to the message.
     ///
-    /// Only allowed in the \c RENDER mode.
+    /// This method is only allowed in the \c RENDER mode;
+    /// if the \c Message is in other mode, an exception of class
+    /// InvalidMessageOperation will be thrown.
     void addQuestion(QuestionPtr question);
 
     /// \brief Add a (pointer like object of) Question to the message.
@@ -312,7 +402,9 @@
     /// form may be more intuitive and may make more sense for performance
     /// insensitive applications.
     ///
-    /// Only allowed in the \c RENDER mode.
+    /// This method is only allowed in the \c RENDER mode;
+    /// if the \c Message is in other mode, an exception of class
+    /// InvalidMessageOperation will be thrown.
     void addQuestion(const Question& question);
 
     /// \brief Add a (pointer like object of) RRset to the given section
@@ -321,15 +413,22 @@
     /// This interface takes into account the RRSIG possibly attached to
     /// \c rrset.  This interface design needs to be revisited later.
     ///
-    /// Only allowed in the \c RENDER mode.
-    ///
-    /// Note that addRRset() does not currently check for duplicate
+    /// This method is only allowed in the \c RENDER mode;
+    /// if the \c Message is in other mode, an exception of class
+    /// InvalidMessageOperation will be thrown.
+    /// \c section must be a valid constant of the \c Section type;
+    /// otherwise, an exception of class \c OutOfRange will be thrown.
+    ///
+    /// Note that \c addRRset() does not currently check for duplicate
     /// data before inserting RRsets.  The caller is responsible for
-    /// checking for these (see hasRRset() below).
+    /// checking for these (see \c hasRRset() below).
     void addRRset(const Section section, RRsetPtr rrset, bool sign = false);
 
     /// \brief Determine whether the given section already has an RRset
     /// matching the given name, RR class and RR type.
+    ///
+    /// \c section must be a valid constant of the \c Section type;
+    /// otherwise, an exception of class \c OutOfRange will be thrown.
     ///
     /// This should probably be extended to be a "find" method that returns
     /// a matching RRset if found.
@@ -385,9 +484,6 @@
     ///
     /// With EDNS the maximum size can be increased per message.
     static const uint16_t DEFAULT_MAX_UDPSIZE = 512;
-
-    /// \brief The highest EDNS version this implementation supports.
-    static const uint8_t EDNS_SUPPORTED_VERSION = 0;
     //@}
 
 private:




More information about the bind10-changes mailing list