From: Jelte Jansen Date: Tue, 28 Feb 2012 10:43:08 +0000 (+0100) Subject: [1602] update doxygen X-Git-Tag: trac2351_base~226^2~116^2~136^2~2^2~5 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=afa40133222b39078a914b0bf5780be013b8b992;p=thirdparty%2Fkea.git [1602] update doxygen --- diff --git a/src/lib/dns/labelsequence.cc b/src/lib/dns/labelsequence.cc index b43d8e4d61..bf80c360f4 100644 --- a/src/lib/dns/labelsequence.cc +++ b/src/lib/dns/labelsequence.cc @@ -15,34 +15,9 @@ #include #include -/// Light-weight Accessor to Name object -/// -/// The purpose of this class is to easily match Names and parts of Names, -/// without needing to copy the underlying data on each split. -/// -/// It can only work on existing Name objects, and the Name object MUST -/// remain in scope during the entire lifetime of its associated -/// LabelSequence(s) -/// -/// Upon creation of a LabelSequence, it records the offsets of the -/// labels in the wireformat data of the Name. When split() is called on -/// the LabelSequence, no changes in the Name's data occur, but the -/// internal pointers of the LabelSequence are modified. -/// -/// LabelSequences can be compared to other LabelSequences, and their -/// data can be requested (which then points to part of the original -/// data of the associated Name object). -/// - namespace isc { namespace dns { -/// \brief Constructs a LabelSequence for the given name -/// -/// The associated Name MUST remain in scope during the lifetime of -/// this LabelSequence, since getData() refers to data from the -/// Name object (the only data the LabelSequence stores are pointers -/// to the labels in the Name object). LabelSequence::LabelSequence(const Name& name) : name_(name), first_label_(0) { size_t label_count_ = name.getLabelCount(); diff --git a/src/lib/dns/labelsequence.h b/src/lib/dns/labelsequence.h index 686442f146..45af27471f 100644 --- a/src/lib/dns/labelsequence.h +++ b/src/lib/dns/labelsequence.h @@ -21,19 +21,107 @@ namespace isc { namespace dns { +/// \brief Light-weight Accessor to Name object +/// +/// The purpose of this class is to easily match Names and parts of Names, +/// without needing to copy the underlying data on each split. +/// +/// It can only work on existing Name objects, and the Name object MUST +/// remain in scope during the entire lifetime of its associated +/// LabelSequence(s). +/// +/// Upon creation of a LabelSequence, it records the offsets of the +/// labels in the wireformat data of the Name. When split() is called on +/// the LabelSequence, no changes in the Name's data occur, but the +/// internal pointers of the LabelSequence are modified. +/// +/// \note For consistency reasons, when talking about labels and label +/// counts, LabelSequence objects never include the root label in their +/// calculations or return values. Wireformat data resulting from +/// getData() is never absolute, and the result of a labelCount(), +/// even if split() has never been called on the LabelSequence, is +/// always smaller than the labelCount of the original Name object. +/// +/// LabelSequences can be compared to other LabelSequences, and their +/// data can be requested (which then points to part of the original +/// data of the associated Name object). +/// class LabelSequence { public: + /// \brief Constructs a LabelSequence for the given name + /// + /// \note The associated Name MUST remain in scope during the lifetime + /// of this LabelSequence, since getData() refers to data from the + /// Name object (the only data the LabelSequence stores are pointers + /// to the labels in the Name object). + /// + /// \param name The Name to construct a LabelSequence for LabelSequence(const Name& name); + + /// \brief Destructor ~LabelSequence(); + /// \brief Return the wire-format data for this LabelSequence + /// + /// The data, is returned as a pointer to the original wireformat + /// data of the original Name object, and the given len value is + /// set to the number of octets that match this labelsequence. + /// + /// \note The data pointed to here is never absolute (i.e. it does + /// not include the root label), so if this data is used anywhere + /// you probably need to add an empty label (one octet with value + /// zero). + /// + /// \note The data pointed to is only valid if the original Name + /// object is still in scope + /// + /// \param len Pointer to a size_t where the length of the data + /// is stored + /// \return Pointer to the wire-format data of this label sequence const char* getData(size_t* len) const; + /// \brief Compares two label sequences. + /// + /// Performs a (optionally case-insensitive) comparison between this + /// LabelSequence and another LabelSequence. + /// + /// \param other The LabelSequence to compare with + /// \param case_sensitive If true, comparison is case-insensitive + /// \return true if The label sequences consist are the same length, + /// and contain the same data. bool equals(const LabelSequence& other, bool case_sensitive = false) const; + /// \brief Remove one or more labels from this LabelSequence + /// + /// Removes labels from either the front or the back of the LabelSequence + /// + /// \note No actual memory is changed, this operation merely updates the + /// internal pointers based on the offsets at creation time. + /// + /// \exeption OutOfRange if abs(i) is greater than the number of labels + /// currently pointed to by this LabelSequence + /// + /// \param i When positive, removes i labels from the front of the + /// LabelSequence. When negative, removes i labels from the + /// end of it. void split(int i); + /// \brief Returns the current number of labels for this LabelSequence + /// + /// \note This count does NOT include the root label + /// + /// \return The number of labels size_t getLabelCount() const { return last_label_ - first_label_; } + /// \brief Returns the original Name object associated with this + /// LabelSequence + /// + /// While the Name should still be in scope during the lifetime of + /// the LabelSequence, it can still be useful to have access to it, + /// for instance in helper functions that are only passed the + /// LabelSequence itself. + /// + /// \return Reference to the original Name object const Name& getName() const { return name_; } private: