[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