[svn] commit: r115 - in /branches/jinmei-doxygentrial: doc/ doc/html/ doc/html/api/ src/lib/dns/
BIND 10 source code commits
bind10-changes at lists.isc.org
Thu Oct 22 23:13:49 UTC 2009
Author: jinmei
Date: Thu Oct 22 23:13:49 2009
New Revision: 115
Log:
experimental header file with doxygen markups and generated files
Added:
branches/jinmei-doxygentrial/doc/Doxyfile
branches/jinmei-doxygentrial/doc/html/
branches/jinmei-doxygentrial/doc/html/api/
branches/jinmei-doxygentrial/doc/html/api/annotated.html
branches/jinmei-doxygentrial/doc/html/api/class_d_n_s_bad_escape.gif (with props)
branches/jinmei-doxygentrial/doc/html/api/class_d_n_s_bad_escape.html
branches/jinmei-doxygentrial/doc/html/api/class_d_n_s_bad_label_type.gif (with props)
branches/jinmei-doxygentrial/doc/html/api/class_d_n_s_bad_label_type.html
branches/jinmei-doxygentrial/doc/html/api/class_d_n_s_empty_label.gif (with props)
branches/jinmei-doxygentrial/doc/html/api/class_d_n_s_empty_label.html
branches/jinmei-doxygentrial/doc/html/api/class_d_n_s_exception.gif (with props)
branches/jinmei-doxygentrial/doc/html/api/class_d_n_s_exception.html
branches/jinmei-doxygentrial/doc/html/api/class_d_n_s_label_too_long.gif (with props)
branches/jinmei-doxygentrial/doc/html/api/class_d_n_s_label_too_long.html
branches/jinmei-doxygentrial/doc/html/api/class_i_s_c_1_1_d_n_s_1_1_name-members.html
branches/jinmei-doxygentrial/doc/html/api/class_i_s_c_1_1_d_n_s_1_1_name.html
branches/jinmei-doxygentrial/doc/html/api/class_i_s_c_1_1_d_n_s_1_1_name_comparison_result-members.html
branches/jinmei-doxygentrial/doc/html/api/class_i_s_c_1_1_d_n_s_1_1_name_comparison_result.html
branches/jinmei-doxygentrial/doc/html/api/class_i_s_c_exception.gif (with props)
branches/jinmei-doxygentrial/doc/html/api/class_i_s_c_exception.html
branches/jinmei-doxygentrial/doc/html/api/class_i_s_c_no_space.gif (with props)
branches/jinmei-doxygentrial/doc/html/api/class_i_s_c_no_space.html
branches/jinmei-doxygentrial/doc/html/api/class_i_s_c_unexpected.gif (with props)
branches/jinmei-doxygentrial/doc/html/api/class_i_s_c_unexpected.html
branches/jinmei-doxygentrial/doc/html/api/classes.html
branches/jinmei-doxygentrial/doc/html/api/doxygen.css
branches/jinmei-doxygentrial/doc/html/api/doxygen.png (with props)
branches/jinmei-doxygentrial/doc/html/api/files.html
branches/jinmei-doxygentrial/doc/html/api/functions.html
branches/jinmei-doxygentrial/doc/html/api/functions_enum.html
branches/jinmei-doxygentrial/doc/html/api/functions_eval.html
branches/jinmei-doxygentrial/doc/html/api/functions_func.html
branches/jinmei-doxygentrial/doc/html/api/globals.html
branches/jinmei-doxygentrial/doc/html/api/globals_defs.html
branches/jinmei-doxygentrial/doc/html/api/globals_enum.html
branches/jinmei-doxygentrial/doc/html/api/globals_eval.html
branches/jinmei-doxygentrial/doc/html/api/globals_func.html
branches/jinmei-doxygentrial/doc/html/api/hierarchy.html
branches/jinmei-doxygentrial/doc/html/api/index.html
branches/jinmei-doxygentrial/doc/html/api/name_8cc.html
branches/jinmei-doxygentrial/doc/html/api/name_8h.html
branches/jinmei-doxygentrial/doc/html/api/name_8h_source.html
branches/jinmei-doxygentrial/doc/html/api/name__unittest_8cc.html
branches/jinmei-doxygentrial/doc/html/api/namespace_i_s_c.html
branches/jinmei-doxygentrial/doc/html/api/namespace_i_s_c_1_1_d_n_s.html
branches/jinmei-doxygentrial/doc/html/api/namespacemembers.html
branches/jinmei-doxygentrial/doc/html/api/namespacemembers_func.html
branches/jinmei-doxygentrial/doc/html/api/namespaces.html
branches/jinmei-doxygentrial/doc/html/api/run__unittests_8cc.html
branches/jinmei-doxygentrial/doc/html/api/tab_b.gif (with props)
branches/jinmei-doxygentrial/doc/html/api/tab_l.gif (with props)
branches/jinmei-doxygentrial/doc/html/api/tab_r.gif (with props)
branches/jinmei-doxygentrial/doc/html/api/tabs.css
Modified:
branches/jinmei-doxygentrial/src/lib/dns/name.h
Modified: branches/jinmei-doxygentrial/src/lib/dns/name.h
==============================================================================
--- branches/jinmei-doxygentrial/src/lib/dns/name.h (original)
+++ branches/jinmei-doxygentrial/src/lib/dns/name.h Thu Oct 22 23:13:49 2009
@@ -26,8 +26,27 @@
class NameCompressor;
class NameDecompressor;
+///
+/// This is a supplemental class used only as a return value of Name::compare().
+/// It encapsulate a tuple of the comparison: ordering, number of common labels,
+/// and relationship as follows:
+/// - ordering: relative ordering under the DNSSEC order relation
+/// - labels: the number of common significant labels of the two names being
+/// compared
+/// - relationship: see NameComparisonResult::NameRelation
+///
class NameComparisonResult {
public:
+ /// The relation of two names under comparison.
+ /// Its semantics for the case of
+ /// <code>name1->compare(name2)</code> (where name1 and name2 are instances
+ /// of the Name class) is as follows:
+ /// - none: there's no hierarchical relationship between the two names
+ /// - contains: name1 properly contains name2; name2 is a proper
+ /// subdomain of name1
+ /// - subdomain: name1 is a proper subdomain of name2
+ /// - equal: name1 and name2 are equal
+ /// - commonancestor: name1 and name2 share a common ancestor
enum NameRelation {
none = 0,
contains = 1,
@@ -36,49 +55,237 @@
commonancestor = 4
};
+ ///
+ /// \name Constructors and Destructor
+ ///
+ //@{
+ /// \brief Constructor from a comparison tuple
+ ///
+ /// This constructor simply initializes the object in the straightforward
+ /// way.
explicit NameComparisonResult(int order, int nlabels,
NameRelation relation) :
order_(order), nlabels_(nlabels), relation_(relation) {}
+ //@}
+
+ ///
+ /// \name Getter Methods
+ ///
+ //@{
+ /// Returns the ordering of the comparison result
int get_order() const { return (order_); }
+ /// Returns the number of common labels of the comparison result
int get_common_labels() const { return (nlabels_); }
+ /// Returns the NameRelation of the comparison result
NameRelation get_relation() const { return (relation_); }
+ //@}
private:
int order_;
int nlabels_;
NameRelation relation_;
};
+///
+/// The <code>Name</code> class encapsulates DNS names. It provides interfaces
+/// to construct a name from string or wire-format data, transform a name into
+/// a string or wire-format data, compare two names, get access to attributes.
+///
+/// Note that while many other DNS APIs introduce an "absolute or relative"
+/// attribute of names as defined in RFC1035, names are always "absolute" in
+/// the initial design of this API.
+/// In fact, separating absolute and relative would confuse API users
+/// unnecessarily. For example, it's not so intuitive to consider the
+/// comparison result of an absolute name with a relative name.
+/// We've looked into how the concept of absolute names is used in BIND9,
+/// and found that in many cases names are generally absolute.
+/// The only reasonable case of separating absolute and relative is in a master
+/// file parser, where a relative name must be a complete name with an "origin"
+/// name, which must be absolute. So, in this initial design, we chose a
+/// simpler approach: the API generally handles names as absolute; when we
+/// introduce a parser of master files, we'll introduce the notion of relative
+/// names as a special case.
+///
class Name {
public:
+ ///
+ /// \name Constructors and Destructor
+ ///
+ //@{
+ /// The default constructor
Name() : length_(0), labels_(0) {}
+ /// Constructor from a string
explicit Name(const std::string& namestr) : length_(0), labels_(0)
{ from_string(namestr); }
+ /// Constructor from wire-format data
explicit Name(NameDecompressor& decompressor, Buffer& buffer);
- // copy constructor (default cp-ctor should work fine)
- //Name(const Name& orig);
- // destructor (default dtor should work fine)
- //~Name();
-
+ /// The destructor
+ ~Name() {}
+ //@}
+
+ ///
+ /// \name Getter Methods
+ ///
+ //@{
+ /// \brief Gets the length of the <code>Name</code> in its wire format.
+ ///
+ /// @return the length of the <code>Name</code>
+ size_t get_length() const { return (length_); }
+
+ /// \brief Returns the number of labels contained in the <code>Name</code>.
+ ///
+ /// Note that an empty label (corresponding to a trailing '.') is counted
+ /// as a single label, so the return value of this method must be >0.
+ ///
+ /// @return the number of labels
+ unsigned int get_labels() const { return (labels_); }
+ //@}
+
+ ///
+ /// \name Converter methods
+ ///
+ //@{
+ /// \brief Convert the Name to a string.
+ ///
+ /// This method returns a <code>std::string</code> object representing the
+ /// Name as a string. Unless <code>omit_final_dot</code> is
+ /// <code>true</code>, the returned string ends with a dot '.'; the default
+ /// is <code>false</code>.
+ ///
+ /// @param omit_final_dot whether to omit the trailing dot in the output.
+ /// @return a string representation of the <code>Name</code>.
std::string to_text(bool omit_final_dot = false) const;
+
+ /// \brief Render the <code>Name</code> in the wire format
+ ///
+ /// This method dumps the Name in the DNS wire format in <code>b</code>.
+ /// When the Name should be compressed, <code>c</code> contains the
+ /// compression context.
+ ///
+ /// Note: This interface may not be a good one and may be revisited.
void to_wire(Buffer& buffer, NameCompressor& compressor) const;
- size_t get_length() const { return (length_); }
- unsigned int get_labels() const { return (labels_); }
+ //@}
+
+ ///
+ /// \name Comparison methods
+ ///
+ //@{
+ /// \brief Compare two <code>Name</code>s.
+ ///
+ /// This method compares the <code>Name</code> and <code>other</code> and
+ /// returns the result in the form of a <code>NameComparisonResult</code>
+ /// object.
+ ///
+ /// Note that this is a case-insensitive comparison.
+ ///
+ /// @param other the right-hand operand to compare against.
+ /// @returns a <code>NameComparisonResult</code> object representing the
+ /// comparison result.
NameComparisonResult compare(const Name& other) const;
+
+ /// \brief Return true iff two names are equal.
+ ///
+ /// The comparison is based on the result of the compare() method.
+ /// @param other the <code>Name</code> object to compare against.
+ /// @return true if <code>compare(other).get_order()</code> is 0;
+ /// otherwise false.
+ bool equals(const Name& other) const;
+
+ /// Same as equals()
+ bool operator==(const Name& other) const;
+
+ /// \brief Return true iff two names are not equal.
+ ///
+ /// The comparison is based on the result of the compare() method.
+ /// @param other the <code>Name</code> object to compare against.
+ /// @return true if <code>compare(other).get_order()</code> is non 0;
+ /// otherwise false.
+ bool nequals(const Name& other) const;
+
+ /// Same as nequals()
+ bool operator!=(const Name& other) const { return (!(*this == other)); }
+
+ /// \brief Less-than or equal comparison for Name against <code>other</code>
+ ///
+ /// The comparison is based on the result of the compare() method.
+ /// @param other the <code>Name</code> object to compare against.
+ /// @return true if <code>compare(other).get_order() <= 0</code>;
+ /// otherwise false.
+ bool leq(const Name& other) const;
+
+ /// Same as leq()
+ bool operator<=(const Name& other) const;
+
+ /// \brief Greater-than or equal comparison for Name against
+ /// <code>other</code>
+ ///
+ /// The comparison is based on the result of the compare() method.
+ /// @param other the <code>Name</code> object to compare against.
+ /// @return true if <code>compare(other).get_order() >= 0</code>;
+ /// otherwise false.
+ bool geq(const Name& other) const;
+
+ /// Same as geq()
+ bool operator>=(const Name& other) const;
+
+ /// \brief Less-than comparison for Name against <code>other</code>
+ ///
+ /// The comparison is based on the result of the compare() method.
+ /// @param other the <code>Name</code> object to compare against.
+ /// @return true if <code>compare(other).get_order() < 0</code>;
+ /// otherwise false.
+ bool lthan(const Name& other) const;
+
+ /// Same as lthan()
+ bool operator<(const Name& other) const;
+
+ /// \brief Greater-than comparison for Name against <code>other</code>
+ ///
+ /// The comparison is based on the result of the compare() method.
+ /// @param other the <code>Name</code> object to compare against.
+ /// @return true if <code>compare(other).get_order() > 0</code>;
+ /// otherwise false.
+ bool gthan(const Name& other) const;
+
+ /// Same as gthan()
+ bool operator>(const Name& other) const;
+ //@}
+
+ ///
+ /// \name Transformer methods
+ ///
+ //@{
+ /// \brief Extract a specified sub part of Name
+ ///
+ /// Note: we may want to have different versions (signatures) of this
+ /// method. For example, we want to split the Name based on a given suffix
+ /// name.
+ ///
+ /// @param first the start position of the extracted name
+ /// @param n number of labels of the extracted name
+ /// @return a new Name object based on the Name containing <code>n</code>
+ /// labels including and following the <code>first</code> label.
Name split(unsigned int first, unsigned int n) const;
+
+ /// \brief Concatenate two names
+ ///
+ /// This method appends <code>suffix</code> to <code>this</code> Name.
+ ///
+ /// @param suffix a Name object to be appended to the Name.
+ /// @return a new Name object concatenating <code>suffix</code> to
+ /// <code>this</code> Name.
Name concatenate(const Name& suffix) const;
+ //@}
+
+ ///
+ /// \name Testing methods
+ ///
+ //@{
+ /// \brief Test if this is a wildcard name.
+ ///
+ /// @return true if the least significant label of this Name is
+ /// <code>'*'</code>; otherwise returns false.
bool is_wildcard() const;
- bool operator==(const Name& other) const;
- bool equals(const Name& other) const; // alias of ==
- bool operator!=(const Name& other) const { return (!(*this == other)); }
- bool nequals(const Name& other) const; // alias of !=
- bool operator<=(const Name& other) const;
- bool leq(const Name& other) const; // alias of <=
- bool operator>=(const Name& other) const;
- bool geq(const Name& other) const; // alias of >=
- bool operator<(const Name& other) const;
- bool lthan(const Name& other) const; // alias of <
- bool operator>(const Name& other) const;
- bool gthan(const Name& other) const; // alias of >
+ //@}
private:
static const unsigned int MAXWIRE = 255;
More information about the bind10-changes
mailing list