[svn] commit: r1812 - /branches/trac49/src/lib/dns/name.h
BIND 10 source code commits
bind10-changes at lists.isc.org
Wed May 12 04:20:41 UTC 2010
Author: jinmei
Date: Wed May 12 04:20:41 2010
New Revision: 1812
Log:
added documentation
Modified:
branches/trac49/src/lib/dns/name.h
Modified: branches/trac49/src/lib/dns/name.h
==============================================================================
--- branches/trac49/src/lib/dns/name.h (original)
+++ branches/trac49/src/lib/dns/name.h Wed May 12 04:20:41 2010
@@ -84,7 +84,7 @@
///
/// \brief A standard DNS module exception that is thrown if the name parser
-/// finds the input (string or wire-format data) is incomplete.
+/// finds the input (string or wire-format %data) is incomplete.
///
/// An attempt of constructing a name from an empty string will trigger this
/// exception.
@@ -168,13 +168,13 @@
///
/// The \c Name 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
+/// 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 various properties of a name, etc.
///
-/// Notes to developers: Internally, a name object maintains the name data
+/// Notes to developers: Internally, a name object maintains the name %data
/// in wire format as an instance of \c std::string. Since many string
-/// implementations adopt copy-on-write data sharing, we expect this approach
+/// implementations adopt copy-on-write %data sharing, we expect this approach
/// will make copying a name less expensive in typical cases. If this is
/// found to be a significant performance bottleneck later, we may reconsider
/// the internal representation or perhaps the API.
@@ -187,9 +187,9 @@
/// included. In the BIND9 DNS library from which this implementation is
/// derived, the offsets are optional, probably due to performance
/// considerations (in fact, offsets can always be calculated from the name
-/// data, and in that sense are redundant). In our implementation, however,
+/// %data, and in that sense are redundant). In our implementation, however,
/// we always build and maintain the offsets. We believe we need more low
-/// level, specialized data structure and interface where we really need to
+/// level, specialized %data structure and interface where we really need to
/// pursue performance, and would rather keep this generic API and
/// implementation simpler.
///
@@ -233,21 +233,21 @@
/// \param namestr A string representation of the name to be constructed.
/// \param downcase Whether to convert upper case alphabets to lower case.
explicit Name(const std::string& namestr, bool downcase = false);
- /// Constructor from wire-format data.
+ /// Constructor from wire-format %data.
///
/// The \c buffer parameter normally stores a complete DNS message
/// containing the name to be constructed. The current read position of
/// the buffer points to the head of the name.
///
- /// The input data may or may not be compressed; if it's compressed, this
+ /// The input %data may or may not be compressed; if it's compressed, this
/// method will automatically decompress it.
///
- /// If the given data does not represent a valid DNS name, an exception
+ /// If the given %data does not represent a valid DNS name, an exception
/// of class \c DNSMessageFORMERR will be thrown.
/// In addition, if resource allocation for the new name fails, a
/// corresponding standard exception will be thrown.
///
- /// \param buffer A buffer storing the wire format data.
+ /// \param buffer A buffer storing the wire format %data.
/// \param downcase Whether to convert upper case alphabets to lower case.
explicit Name(InputBuffer& buffer, bool downcase = false);
///
@@ -260,35 +260,35 @@
/// \name Getter Methods
///
//@{
- /// \brief Provides one-byte name data in wire format at the specified
+ /// \brief Provides one-byte name %data in wire format at the specified
/// position.
///
/// This method returns the unsigned 8-bit value of wire-format \c Name
- /// data at the given position from the head.
+ /// %data at the given position from the head.
///
/// For example, if \c n is a \c Name object for "example.com",
/// \c n.at(3) would return \c 'a', and \c n.at(7) would return \c 'e'.
/// Note that \c n.at(0) would be 7 (decimal), the label length of
- /// "example", instead of \c 'e', because it returns a data portion
+ /// "example", instead of \c 'e', because it returns a %data portion
/// in wire-format. Likewise, \c n.at(8) would return 3 (decimal)
/// instead of <code>'.'</code>
///
/// This method would be useful for an application to examine the
- /// wire-format name data without dumping the data into a buffer,
- /// which would involve data copies and would be less efficient.
+ /// wire-format name %data without dumping the %data into a buffer,
+ /// which would involve %data copies and would be less efficient.
/// One common usage of this method would be something like this:
/// \code for (size_t i = 0; i < name.getLength(); ++i) {
/// uint8_t c = name.at(i);
/// // do something with c
/// } \endcode
///
- /// Parameter \c pos must be in the valid range of the name data, that is,
+ /// Parameter \c pos must be in the valid range of the name %data, that is,
/// must be less than \c Name.getLength(). Otherwise, an exception of
/// class \c OutOfRange will be thrown.
/// This method never throws an exception in other ways.
///
- /// \param pos The position in the wire format name data to be returned.
- /// \return An unsigned 8-bit integer corresponding to the name data
+ /// \param pos The position in the wire format name %data to be returned.
+ /// \return An unsigned 8-bit integer corresponding to the name %data
/// at the position of \c pos.
uint8_t at(size_t pos) const
{
@@ -360,7 +360,7 @@
/// <code>buffer.getCapacity() - buffer.getLength() >= Name::MAX_WIRE</code>
/// then this method should not throw an exception.
///
- /// \param buffer An output buffer to store the wire data.
+ /// \param buffer An output buffer to store the wire %data.
void toWire(OutputBuffer& buffer) const;
//@}
@@ -609,11 +609,108 @@
return (root_name);
}
+///
+/// \name Utility functions manipulating names.
+///
+//@{
+/// \brief Create an ancestor name of a given \c Name.
+///
+/// This function creates a new \c Name object that is an ancestor of
+/// \c source. The new name is \c level labels upper than \c source.
+/// For example, when \c source is www.example.com,
+/// <code>createAncestorNameOf(source, 1)</code> will return a \c Name object
+/// for example.com.
+/// \c level can be 0, in which case this function returns a copy of the
+/// \c source name.
+/// The possible maximum value for \c level is
+/// <code>source.getLabelCount()-1</code>, in which case this function
+/// returns a root name.
+///
+/// One common expected usage of this function is to iterate over super
+/// domains of a given name, label by label, as shown in the following
+/// sample code:
+/// \code // if name is www.example.com...
+/// for (int i = 0; i < name.getLabelCount(); ++i) {
+/// Name upper_name(createAncestorNameOf(name, i));
+/// // upper_name will be www.example.com., example.com., com., and then .
+/// }
+/// \endcode
+///
+/// \c level must be smaller than the number of labels of \c source;
+/// otherwise an exception of class \c OutOfRange will be thrown.
+/// In addition, if resource allocation for the new name fails, a
+/// corresponding standard exception will be thrown.
+///
+/// Note to developers: probably as easily imagined, this function is a
+/// simple wrapper to one usage of the \c Name::split() method and is
+/// redundant in some sense.
+/// We provide this as a public function for convenience, however, because
+/// the expected usage shown above seems to be common, and the parameters
+/// to \c Name::split() to implement it may not be very intuitive.
+/// Another possible question about this function might be why this is not
+/// implemented as a public member function of the \c Name class.
+/// This is because we wanted to keep the class definition as simple as
+/// possible by limiting public members to something primitive to the class
+/// (being a wrapper of another member, this function is clearly not
+/// primitive).
+/// And, in fact, this is generally considered a better practice in C++;
+/// if we implemented this function as a member function, it might exploit
+/// its ability to access private class members for, e.g., performance
+/// reasons, which would make it harder to change the internal implementation
+/// of the class in future.
+/// One possible disadvantage of non member function approach is that
+/// it might be less efficient than a member function providing the same
+/// service. At the moment we have no evidence that the performance overhead
+/// is a real issue, so we follow the common practice of the language.
+/// If, through performance benchmark in future, it turns out to be a
+/// significant bottleneck in critical operations, we may change the decision
+/// and may consider implementing it as a member function of the \c Name class.
+///
+/// \param source A \c Name for which the ancestor name is to be created.
+/// \param level The number of labels to be removed from \c source to create
+/// the ancestor name. (0 <= \c level < <code>source.getLabelCount()</code>)
+/// \return A new \c Name object to be created.
Name
createAncestorNameOf(const Name& source, unsigned int level);
+/// \brief Create a suffix name of a give \c Name.
+///
+/// This function creates a new \c Name object that shares the specified
+/// number (\c labels) of trailing labels of a given name (\c source).
+/// The trailing dot of \c source is counted as a single label.
+/// For example, when \c source is www.example.com,
+/// <code>createSuffixNameOf(source, 2)</code> will return a \c Name object
+/// for com. (including a trailing dot).
+///
+/// One common expected usage of this function is to iterate over super
+/// domains of a given name, label by label from the root to the given name,
+/// as shown in the following sample code:
+/// \code // if name is www.example.com...
+/// for (int i = 1; i <= name.getLabelCount(); ++i) {
+/// Name suffix_name(createSuffixNameOf(name, i));
+/// // suffix_name will be ., com., example.com., then www.example.com.
+/// }
+/// \endcode
+///
+/// \c labels must be a non-0 integer and must not exceed the number of
+/// labels of \c source;
+/// otherwise an exception of class \c OutOfRange will be thrown.
+/// In addition, if resource allocation for the new name fails, a
+/// corresponding standard exception will be thrown.
+///
+/// Note to developers: the same implementation decision as that for
+/// \c createAncestorNameOf applies to this function.
+/// See the description of that function for more details.
+///
+/// \param source A \c Name for which the suffix name is to be created.
+/// \param labels The number of trailing labels that the suffix name should
+/// share with \c source.
+/// (1 <= \c labels <= <code>source.getLabelCount()</code>)
+///
+/// \return A new \c Name object to be created.
Name
createSuffixNameOf(const Name& source, unsigned int labels);
+//@}
///
/// \brief Insert the name as a string into stream.
More information about the bind10-changes
mailing list