[svn] commit: r3039 - in /branches/trac351/src/lib/dns: ./ python/ python/tests/ tests/
BIND 10 source code commits
bind10-changes at lists.isc.org
Tue Sep 28 02:16:05 UTC 2010
Author: jinmei
Date: Tue Sep 28 02:16:01 2010
New Revision: 3039
Log:
provided documentation
Added:
branches/trac351/src/lib/dns/python/rcode_python.cc
branches/trac351/src/lib/dns/python/tests/rcode_python_test.py
branches/trac351/src/lib/dns/rcode.cc
branches/trac351/src/lib/dns/rcode.h
branches/trac351/src/lib/dns/tests/rcode_unittest.cc
Modified:
branches/trac351/src/lib/dns/opcode.cc
branches/trac351/src/lib/dns/opcode.h
branches/trac351/src/lib/dns/python/opcode_python.cc
branches/trac351/src/lib/dns/python/tests/opcode_python_test.py
branches/trac351/src/lib/dns/tests/opcode_unittest.cc
Modified: branches/trac351/src/lib/dns/opcode.cc
==============================================================================
--- branches/trac351/src/lib/dns/opcode.cc (original)
+++ branches/trac351/src/lib/dns/opcode.cc Tue Sep 28 02:16:01 2010
@@ -44,10 +44,13 @@
"RESERVED14",
"RESERVED15"
};
+
+// OPCODEs are 4-bit values. So 15 is the highest code.
+const uint8_t MAX_OPCODE = 15;
}
-Opcode::Opcode(const uint16_t code) : code_(static_cast<CodeValue>(code)) {
- if (code > MAX_CODE) {
+Opcode::Opcode(const uint8_t code) : code_(static_cast<CodeValue>(code)) {
+ if (code > MAX_OPCODE) {
isc_throw(OutOfRange,
"DNS Opcode is too large to construct: " << code);
}
Modified: branches/trac351/src/lib/dns/opcode.h
==============================================================================
--- branches/trac351/src/lib/dns/opcode.h (original)
+++ branches/trac351/src/lib/dns/opcode.h Tue Sep 28 02:16:01 2010
@@ -29,62 +29,148 @@
/// \brief The \c Opcode class objects represent standard OPCODEs
/// of the header section of DNS messages as defined in RFC1035.
///
-/// Note: since there are only 15 possible values, it may make more sense to
-/// simply define an enum type to represent these values.
-///
-/// Constant objects are defined for standard flags.
+/// This is a straightforward value class encapsulating the OPCODE code
+/// values. Since OPCODEs are 4-bit integers that are used in limited
+/// places and it's unlikely that new code values will be assigned, we could
+/// represent them as simple integers (via constant variables or enums).
+/// However, we define a separate class so that we can benefit from C++
+/// type safety as much as possible. For convenience we also provide
+/// an enum type for standard OPCDE values, but it is generally advisable
+/// to handle OPCODEs through this class. In fact, public interfaces of
+/// this library uses this class to pass or return OPCODEs instead of the
+/// bare code values.
class Opcode {
public:
+ /// Constants for standard OPCODE values.
enum CodeValue {
- QUERY_CODE = 0,
- IQUERY_CODE = 1,
- STATUS_CODE = 2,
- RESERVED3_CODE = 3,
- NOTIFY_CODE = 4,
- UPDATE_CODE = 5,
- RESERVED6_CODE = 6,
- RESERVED7_CODE = 7,
- RESERVED8_CODE = 8,
- RESERVED9_CODE = 9,
- RESERVED10_CODE = 10,
- RESERVED11_CODE = 11,
- RESERVED12_CODE = 12,
- RESERVED13_CODE = 13,
- RESERVED14_CODE = 14,
- RESERVED15_CODE = 15,
- MAX_CODE = 15
+ QUERY_CODE = 0, ///< 0: Standard query (RFC1035)
+ IQUERY_CODE = 1, ///< 1: Inverse query (RFC1035)
+ STATUS_CODE = 2, ///< 2: Server status request (RFC1035)
+ RESERVED3_CODE = 3, ///< 3: Reserved for future use (RFC1035)
+ NOTIFY_CODE = 4, ///< 4: Notify (RFC1996)
+ UPDATE_CODE = 5, ///< 5: Dynamic update (RFC2136)
+ RESERVED6_CODE = 6, ///< 6: Reserved for future use (RFC1035)
+ RESERVED7_CODE = 7, ///< 7: Reserved for future use (RFC1035)
+ RESERVED8_CODE = 8, ///< 8: Reserved for future use (RFC1035)
+ RESERVED9_CODE = 9, ///< 9: Reserved for future use (RFC1035)
+ RESERVED10_CODE = 10, ///< 10: Reserved for future use (RFC1035)
+ RESERVED11_CODE = 11, ///< 11: Reserved for future use (RFC1035)
+ RESERVED12_CODE = 12, ///< 12: Reserved for future use (RFC1035)
+ RESERVED13_CODE = 13, ///< 13: Reserved for future use (RFC1035)
+ RESERVED14_CODE = 14, ///< 14: Reserved for future use (RFC1035)
+ RESERVED15_CODE = 15 ///< 15: Reserved for future use (RFC1035)
};
- explicit Opcode(const uint16_t code);
+
+ /// \name Constructors and Destructor
+ ///
+ /// We use the default versions of destructor, copy constructor,
+ /// and assignment operator.
+ ///
+ /// The default constructor is hidden as a result of defining the other
+ /// constructors. This is intentional; we don't want to allow an
+ /// \c Opcode object to be constructed with an invalid state.
+ //@{
+ /// \brief Constructor from the code value.
+ ///
+ /// Since OPCODEs are 4-bit values, parameters larger than 15 are invalid.
+ /// If \c code is larger than 15 an exception of class \c isc::OutOfRange
+ /// will be thrown.
+ ///
+ /// \param code The underlying code value of the \c Opcode.
+ explicit Opcode(const uint8_t code);
+ //@}
+
+ /// \brief Returns the \c Opcode code value.
+ ///
+ /// This method never throws an exception.
+ ///
+ /// \return The underlying code value corresponding to the \c Opcode.
CodeValue getCode() const { return (code_); }
/// \brief Return true iff two Opcodes are equal.
+ ///
+ /// Two Opcodes are equal iff their type codes are equal.
+ ///
+ /// This method never throws an exception.
+ ///
+ /// \param other the \c Opcode object to compare against.
+ /// \return true if the two Opcodes are equal; otherwise false.
bool equals(const Opcode& other) const
{ return (code_ == other.code_); }
+ /// \brief Same as \c equals().
bool operator==(const Opcode& other) const { return (equals(other)); }
-
+
+ /// \brief Return true iff two Opcodes are not equal.
+ ///
+ /// This method never throws an exception.
+ ///
+ /// \param other the \c Opcode object to compare against.
+ /// \return true if the two Opcodes are not equal; otherwise false.
bool nequals(const Opcode& other) const
{ return (code_ != other.code_); }
+ /// \brief Same as \c nequals().
bool operator!=(const Opcode& other) const { return (nequals(other)); }
+ /// \brief Convert the \c Opcode to a string.
+ ///
+ /// This method returns a string representation of the "mnemonic' used
+ /// for the enum and constant objects. For example, the string for
+ /// code value 0 is "QUERY", etc.
+ ///
+ /// If resource allocation for the string fails, a corresponding standard
+ /// exception will be thrown.
+ ///
+ /// \return A string representation of the \c Opcode.
std::string toText() const;
+ /// A constant object for the QUERY Opcode.
static const Opcode& QUERY();
+
+ /// A constant object for the IQUERY Opcode.
static const Opcode& IQUERY();
+
+ /// A constant object for the STATUS Opcode.
static const Opcode& STATUS();
+
+ /// A constant object for a reserved (code 3) Opcode.
static const Opcode& RESERVED3();
+
+ /// A constant object for the NOTIFY Opcode.
static const Opcode& NOTIFY();
+
+ /// A constant object for the UPDATE Opcode.
static const Opcode& UPDATE();
+
+ /// A constant object for a reserved (code 6) Opcode.
static const Opcode& RESERVED6();
+
+ /// A constant object for a reserved (code 7) Opcode.
static const Opcode& RESERVED7();
+
+ /// A constant object for a reserved (code 8) Opcode.
static const Opcode& RESERVED8();
+
+ /// A constant object for a reserved (code 9) Opcode.
static const Opcode& RESERVED9();
+
+ /// A constant object for a reserved (code 10) Opcode.
static const Opcode& RESERVED10();
+
+ /// A constant object for a reserved (code 11) Opcode.
static const Opcode& RESERVED11();
+
+ /// A constant object for a reserved (code 12) Opcode.
static const Opcode& RESERVED12();
+
+ /// A constant object for a reserved (code 13) Opcode.
static const Opcode& RESERVED13();
+
+ /// A constant object for a reserved (code 14) Opcode.
static const Opcode& RESERVED14();
+
+ /// A constant object for a reserved (code 15) Opcode.
static const Opcode& RESERVED15();
private:
CodeValue code_;
Modified: branches/trac351/src/lib/dns/python/opcode_python.cc
==============================================================================
--- branches/trac351/src/lib/dns/python/opcode_python.cc (original)
+++ branches/trac351/src/lib/dns/python/opcode_python.cc Tue Sep 28 02:16:01 2010
@@ -160,7 +160,7 @@
int
Opcode_init(s_Opcode* const self, PyObject* args) {
uint16_t code = 0;
- if (PyArg_ParseTuple(args, "h", &code)) {
+ if (PyArg_ParseTuple(args, "b", &code)) {
try {
self->opcode = new Opcode(code);
self->static_code = false;
@@ -386,8 +386,6 @@
Py_BuildValue("h", Opcode::RESERVED14_CODE));
addClassVariable(opcode_type, "RESERVED15_CODE",
Py_BuildValue("h", Opcode::RESERVED15_CODE));
- addClassVariable(opcode_type, "MAX_CODE",
- Py_BuildValue("h", Opcode::MAX_CODE));
return (true);
}
Modified: branches/trac351/src/lib/dns/python/tests/opcode_python_test.py
==============================================================================
--- branches/trac351/src/lib/dns/python/tests/opcode_python_test.py (original)
+++ branches/trac351/src/lib/dns/python/tests/opcode_python_test.py Tue Sep 28 02:16:01 2010
@@ -24,7 +24,7 @@
def test_init(self):
self.assertRaises(TypeError, Opcode, "wrong")
self.assertEqual(Rcode(0).get_code(), 0)
- self.assertEqual(Rcode(Opcode.MAX_CODE).get_code(), 15)
+ self.assertEqual(Rcode(Opcode.RESERVED15_CODE).get_code(), 15)
self.assertRaises(OverflowError, Opcode, 16)
def test_constants(self):
Modified: branches/trac351/src/lib/dns/tests/opcode_unittest.cc
==============================================================================
--- branches/trac351/src/lib/dns/tests/opcode_unittest.cc (original)
+++ branches/trac351/src/lib/dns/tests/opcode_unittest.cc Tue Sep 28 02:16:01 2010
@@ -30,7 +30,7 @@
TEST(OpcodeTest, construct) {
// This test also tests getCode()
EXPECT_EQ(0, Opcode(0).getCode());
- EXPECT_EQ(15, Opcode(Opcode::MAX_CODE).getCode());
+ EXPECT_EQ(15, Opcode(Opcode::RESERVED15_CODE).getCode());
EXPECT_THROW(Opcode(16), isc::OutOfRange);
}
@@ -76,7 +76,7 @@
TEST(OpcodeTest, toText) {
vector<const char*> expects;
- expects.resize(Opcode::MAX_CODE);
+ expects.resize(Opcode::RESERVED15_CODE + 1);
expects[Opcode::QUERY_CODE] = "QUERY";
expects[Opcode::IQUERY_CODE] = "IQUERY";
expects[Opcode::STATUS_CODE] = "STATUS";
@@ -94,7 +94,7 @@
expects[Opcode::RESERVED14_CODE] = "RESERVED14";
expects[Opcode::RESERVED15_CODE] = "RESERVED15";
- for (unsigned int i = 0; i < Opcode::MAX_CODE; ++i) {
+ for (unsigned int i = 0; i <= Opcode::RESERVED15_CODE; ++i) {
EXPECT_EQ(expects.at(i), Opcode(i).toText());
}
}
More information about the bind10-changes
mailing list