labelsequence.h 16 KB
 Jelte Jansen committed Mar 01, 2012 1 ``````// Copyright (C) 2012 Internet Systems Consortium, Inc. ("ISC") `````` Jelte Jansen committed Feb 20, 2012 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 ``````// // Permission to use, copy, modify, and/or distribute this software for any // purpose with or without fee is hereby granted, provided that the above // copyright notice and this permission notice appear in all copies. // // THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH // REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY // AND FITNESS. IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT, // INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM // LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE // OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR // PERFORMANCE OF THIS SOFTWARE. #ifndef __LABELSEQUENCE_H #define __LABELSEQUENCE_H 1 #include #include namespace isc { namespace dns { `````` JINMEI Tatuya committed Jul 20, 2012 24 ``````/// \brief Light-weight Accessor to Name data. `````` Jelte Jansen committed Feb 28, 2012 25 26 ``````/// /// The purpose of this class is to easily match Names and parts of Names, `````` Jelte Jansen committed Mar 02, 2012 27 ``````/// without needing to copy the underlying data on each label strip. `````` Jelte Jansen committed Feb 28, 2012 28 ``````/// `````` Jelte Jansen committed Jul 12, 2012 29 30 ``````/// It can only work on existing Name objects, or data as provided by the /// Name object or another LabelSequence, and the data or Name MUST `````` Jelte Jansen committed Feb 28, 2012 31 32 33 34 ``````/// remain in scope during the entire lifetime of its associated /// LabelSequence(s). /// /// Upon creation of a LabelSequence, it records the offsets of the `````` Jelte Jansen committed Mar 02, 2012 35 36 ``````/// labels in the wireformat data of the Name. When stripLeft() or /// stripRight() is called on the LabelSequence, no changes in the `````` Jelte Jansen committed Jul 12, 2012 37 ``````/// original data occur, but the internal pointers of the `````` Jelte Jansen committed Mar 02, 2012 38 ``````/// LabelSequence are modified. `````` Jelte Jansen committed Feb 28, 2012 39 40 41 ``````/// /// LabelSequences can be compared to other LabelSequences, and their /// data can be requested (which then points to part of the original `````` Jelte Jansen committed Jul 12, 2012 42 ``````/// data of the original Name object). `````` Jelte Jansen committed Feb 20, 2012 43 ``````class LabelSequence { `````` Mukund Sivaraman committed Jul 04, 2012 44 45 46 `````` // Name calls the private toText(bool) method of LabelSequence. friend std::string Name::toText(bool) const; `````` Jelte Jansen committed Feb 20, 2012 47 ``````public: `````` Jelte Jansen committed Jul 25, 2012 48 49 50 51 52 53 54 55 `````` /// \brief Max possible size of serialized image generated by \c serialize /// /// A fixed length buffer of this size can be always passed to /// \c serialize() safely. (But the application shouldn't use the /// specific size value; it must use this constant variable). static const size_t MAX_SERIALIZED_LENGTH = Name::MAX_WIRE + Name::MAX_LABELS + 1; `````` Jelte Jansen committed Feb 28, 2012 56 57 58 59 60 61 62 63 `````` /// \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 `````` Jelte Jansen committed Jul 09, 2012 64 `````` explicit LabelSequence(const Name& name): `````` JINMEI Tatuya committed Jul 20, 2012 65 66 67 68 `````` data_(&name.ndata_[0]), offsets_(&name.offsets_[0]), first_label_(0), last_label_(name.getLabelCount() - 1) `````` Jelte Jansen committed Mar 01, 2012 69 `````` {} `````` Jelte Jansen committed Feb 28, 2012 70 `````` `````` JINMEI Tatuya committed Jul 20, 2012 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 `````` /// \brief Constructor from serialized image. /// /// This constructor restores a \c LabelSequence object from a serialized /// binary image previously generated by \c serialize(). Any other input /// to this constructor will result in undefined behavior. /// /// The binary data passed to this constructor MUST remain in scope and /// MUST NOT be modified during the lifetime of this LabelSequence. /// /// As long as the data were previously generated by a call to /// \c serialize() on a valid \c LabelSequence object, this constructor /// should succeed. While any other case is undefined, this constructor /// may perform some validity checks internally for safety. Nevertheless, /// applications must not rely on such checks. /// /// \param buf Pointer to the serialized image generated by \c serialize(). explicit LabelSequence(const void* buf); `````` Jelte Jansen committed Jul 25, 2012 89 90 91 92 93 94 `````` /// \brief Construct 'extendable' LabelSequence /// /// This form of LabelSequence copies the data from the given /// labelsequence into the given external buffer, which is subsequently /// extendable by calling extend() /// `````` Jelte Jansen committed Jul 25, 2012 95 96 97 98 99 100 101 102 103 104 105 `````` /// The data is placed into the given buffer as follows: /// - binary sequence of name data, starting at position 0, /// length determined by source LabelSequence /// - offsets, starting at position Name::MAX_WIRE, length /// determined by source LabelSequence /// The offsets are updated to be correct for the potentially partial /// name data (as stripLeft() and stripRight may have been called on /// the source LabelSequence). /// /// \note The given buf MUST remain in scope during the lifetime of /// the LabelSequence created here. `````` Jelte Jansen committed Jul 25, 2012 106 107 108 109 110 `````` /// \note The buffer should never be modified except through /// calls to extend(). /// \note Also, only associate the buffer with at most one /// LabelSequence. Behaviour is undefined if two LabelSequences are /// using the same buffer. `````` Jelte Jansen committed Jul 25, 2012 111 `````` /// `````` Jelte Jansen committed Jul 25, 2012 112 113 114 115 `````` /// \param src LabelSequence to copy the initial data from /// \param buf external buffer to store this labelsequence's data in LabelSequence(const LabelSequence& src, uint8_t buf[MAX_SERIALIZED_LENGTH]); `````` JINMEI Tatuya committed Jul 20, 2012 116 117 118 119 120 121 122 123 124 125 `````` /// \brief Copy constructor. /// /// \note The associated data MUST remain in scope during the lifetime /// of this LabelSequence, since only the pointers are copied. /// /// \note No validation is done on the given data upon construction; /// use with care. /// /// \param ls The LabelSequence to construct a LabelSequence from LabelSequence(const LabelSequence& ls): `````` JINMEI Tatuya committed Jul 20, 2012 126 127 128 129 `````` data_(ls.data_), offsets_(ls.offsets_), first_label_(ls.first_label_), last_label_(ls.last_label_) `````` JINMEI Tatuya committed Jul 20, 2012 130 131 `````` {} `````` Jelte Jansen committed Feb 28, 2012 132 133 `````` /// \brief Return the wire-format data for this LabelSequence /// `````` Jelte Jansen committed Jul 12, 2012 134 135 136 `````` /// The data is returned as a pointer to (the part of) the original /// wireformat data, from either the original Name object, or the /// raw data given in the constructor, and the given len value is `````` Jelte Jansen committed Feb 28, 2012 137 138 139 `````` /// set to the number of octets that match this labelsequence. /// /// \note The data pointed to is only valid if the original Name `````` Jelte Jansen committed Jul 12, 2012 140 `````` /// object or data is still in scope `````` Jelte Jansen committed Feb 28, 2012 141 142 `````` /// /// \param len Pointer to a size_t where the length of the data `````` Jelte Jansen committed Feb 28, 2012 143 `````` /// will be stored (in number of octets) `````` Jelte Jansen committed Feb 28, 2012 144 `````` /// \return Pointer to the wire-format data of this label sequence `````` Mukund Sivaraman committed Jun 24, 2012 145 `````` const uint8_t* getData(size_t* len) const; `````` Jelte Jansen committed Feb 20, 2012 146 `````` `````` JINMEI Tatuya committed Mar 05, 2012 147 148 149 150 151 152 153 154 155 156 157 `````` /// \brief Return the length of the wire-format data of this LabelSequence /// /// This method returns the number of octets for the data that would /// be returned by the \c getData() method. /// /// Note that the return value of this method is always positive. /// Note also that if the return value of this method is 1, it means the /// sequence consists of the null label, i.e., a single "dot", and vice /// versa. /// /// \note The data pointed to is only valid if the original Name `````` Jelte Jansen committed Jul 12, 2012 158 `````` /// object or data is still in scope `````` JINMEI Tatuya committed Mar 05, 2012 159 160 161 162 `````` /// /// \return The length of the data of the label sequence in octets. size_t getDataLength() const; `````` JINMEI Tatuya committed Jul 20, 2012 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 `````` /// \brief Return the size of serialized image of the \c LabelSequence. /// /// This method calculates the size of necessary storage to store /// serialized image of this \c LabelSequence (which would be dumped by /// \c serialize()) and returns it. The size is in bytes. /// /// \throw none. /// /// \return The size of serialized image of the \c LabelSequence. size_t getSerializedLength() const; /// \brief Serialize the \c LabelSequence object in to a buffer. /// /// This method dumps a serialized image of this \c LabelSequence /// that would be restored by the corresponding constructor into the /// given buffer. The buffer size must be at least equal to /// the value returned by getSerializedLength() (it can be larger than /// that). /// /// The serialized image would be as follows: /// - olen: number of offsets (1 byte) /// - binary sequence of offsets (olen bytes, verbatim copy of offsets_ /// of this size) /// - binary sequence of name data (length determined by itself, verbatim /// copy of data_ of the corresponding size) /// /// Applications must use the resulting image opaque value and must not /// use it for other purposes than input to the corresponding constructor /// to restore it. Application behavior that assumes the specific /// organization of the image is not guaranteed. /// /// \throw isc::BadValue buf_len is too short (this method never throws /// otherwise) /// /// \param buf Pointer to the placeholder to dump the serialized image /// \param buf_len The size of available region in \c buf void serialize(void* buf, size_t buf_len) const; `````` Mukund Sivaraman committed Jun 25, 2012 201 `````` /// \brief Compares two label sequences for equality. `````` Jelte Jansen committed Feb 28, 2012 202 203 `````` /// /// Performs a (optionally case-insensitive) comparison between this `````` Mukund Sivaraman committed Jun 25, 2012 204 `````` /// LabelSequence and another LabelSequence for equality. `````` Jelte Jansen committed Feb 28, 2012 205 206 207 208 209 `````` /// /// \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. `````` Jelte Jansen committed Feb 20, 2012 210 211 `````` bool equals(const LabelSequence& other, bool case_sensitive = false) const; `````` Mukund Sivaraman committed Jun 25, 2012 212 213 214 215 216 217 218 219 220 221 222 223 `````` /// \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 a NameComparisonResult object representing the /// comparison result. NameComparisonResult compare(const LabelSequence& other, bool case_sensitive = false) const; `````` Jelte Jansen committed Mar 01, 2012 224 `````` /// \brief Remove labels from the front of this LabelSequence `````` Jelte Jansen committed Feb 28, 2012 225 `````` /// `````` Jelte Jansen committed Mar 01, 2012 226 227 228 `````` /// \note No actual memory is changed, this operation merely updates the /// internal pointers based on the offsets in the Name object. /// `````` Tomek Mrugalski committed Jun 01, 2012 229 `````` /// \exception OutOfRange if i is greater than or equal to the number `````` Jelte Jansen committed Mar 01, 2012 230 231 232 `````` /// of labels currently pointed to by this LabelSequence /// /// \param i The number of labels to remove. `````` Jelte Jansen committed Mar 02, 2012 233 `````` void stripLeft(size_t i); `````` Jelte Jansen committed Mar 01, 2012 234 235 `````` /// \brief Remove labels from the end of this LabelSequence `````` Jelte Jansen committed Feb 28, 2012 236 237 `````` /// /// \note No actual memory is changed, this operation merely updates the `````` Jelte Jansen committed Jul 12, 2012 238 `````` /// internal pointers based on the offsets originally provided. `````` Jelte Jansen committed Feb 28, 2012 239 `````` /// `````` Tomek Mrugalski committed Jun 01, 2012 240 `````` /// \exception OutOfRange if i is greater than or equal to the number `````` Jelte Jansen committed Mar 01, 2012 241 `````` /// of labels currently pointed to by this LabelSequence `````` Jelte Jansen committed Feb 28, 2012 242 `````` /// `````` Jelte Jansen committed Mar 01, 2012 243 `````` /// \param i The number of labels to remove. `````` Jelte Jansen committed Mar 02, 2012 244 `````` void stripRight(size_t i); `````` Jelte Jansen committed Feb 20, 2012 245 `````` `````` Jelte Jansen committed Feb 28, 2012 246 247 248 `````` /// \brief Returns the current number of labels for this LabelSequence /// /// \return The number of labels `````` JINMEI Tatuya committed Jul 20, 2012 249 250 251 `````` size_t getLabelCount() const { return (last_label_ - first_label_ + 1); } `````` Jelte Jansen committed Feb 21, 2012 252 `````` `````` Mukund Sivaraman committed Jul 02, 2012 253 254 255 256 `````` /// \brief Convert the LabelSequence to a string. /// /// This method returns a std::string object representing the /// LabelSequence as a string. The returned string ends with a dot `````` Mukund Sivaraman committed Jul 04, 2012 257 `````` /// '.' if the label sequence is absolute. `````` Mukund Sivaraman committed Jul 02, 2012 258 `````` /// `````` Jelte Jansen committed Jul 12, 2012 259 `````` /// This function assumes the underlying data is in proper `````` Mukund Sivaraman committed Jul 02, 2012 260 261 262 263 264 `````` /// uncompressed wire format. If it finds an unexpected label /// character including compression pointer, an exception of class /// \c BadLabelType will be thrown. In addition, if resource /// allocation for the result string fails, a corresponding standard /// exception will be thrown. `````` Jelte Jansen committed Jul 12, 2012 265 `````` /// `````` Mukund Sivaraman committed Jul 02, 2012 266 `````` /// \return a string representation of the LabelSequence. `````` Mukund Sivaraman committed Jul 04, 2012 267 `````` std::string toText() const; `````` Mukund Sivaraman committed Jul 02, 2012 268 `````` `````` Jelte Jansen committed Jul 25, 2012 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 `````` /// \brief Extend this LabelSequence with the given labelsequence /// /// The given labels are added to the name data, and internal data /// is updated accordingly. /// The data from the given LabelSequence is copied into the buffer /// associated with this LabelSequence; the appended LabelSequence /// can be released if it is not needed for other operations anymore. /// /// Some minimal checking is done on the data, but internal integrity /// is not assumed. Do NOT modify the given buffer except through calls /// to this method, and do NOT call this method if the buffer is /// associated to another LabelSequence (behaviour of the other /// LabelSequence is undefined in that scenario). /// /// \exception BadValue If the buffer does not appear to be associated /// with this LabelSequence, or if the maximum wire length or maximum /// number of labels would be exceeded by this operation /// /// \param labels The labels to append to this LabelSequence /// \param buf The buffer associated with this LabelSequence void extend(const LabelSequence& labels, uint8_t buf[MAX_SERIALIZED_LENGTH]); `````` Mukund Sivaraman committed Jul 04, 2012 292 ``````private: `````` Mukund Sivaraman committed Jun 29, 2012 293 294 `````` /// \brief Convert the LabelSequence to a string. /// `````` Mukund Sivaraman committed Jul 04, 2012 295 296 297 298 `````` /// This method is a version of the zero-argument toText() method, /// that accepts a omit_final_dot argument. The /// returned string ends with a dot '.' if /// omit_final_dot is false. `````` Mukund Sivaraman committed Jun 29, 2012 299 `````` /// `````` Mukund Sivaraman committed Jul 05, 2012 300 301 302 `````` /// This method is used as a helper for Name::toText() /// only. /// `````` Mukund Sivaraman committed Jul 04, 2012 303 `````` /// \param omit_final_dot whether to omit the trailing dot in the output. `````` Mukund Sivaraman committed Jun 29, 2012 304 `````` /// \return a string representation of the LabelSequence. `````` Mukund Sivaraman committed Jul 04, 2012 305 `````` std::string toText(bool omit_final_dot) const; `````` Mukund Sivaraman committed Jun 29, 2012 306 `````` `````` Mukund Sivaraman committed Jul 04, 2012 307 ``````public: `````` JINMEI Tatuya committed Mar 06, 2012 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 `````` /// \brief Calculate a simple hash for the label sequence. /// /// This method calculates a hash value for the label sequence as binary /// data. If \c case_sensitive is false, it ignores the case stored in /// the labels; specifically, it normalizes the labels by converting all /// upper case characters to lower case ones and calculates the hash value /// for the result. /// /// This method is intended to provide a lightweight way to store a /// relatively small number of label sequences in a hash table. /// For this reason it only takes into account data up to 16 octets /// (16 was derived from BIND 9's implementation). Also, the function does /// not provide any unpredictability; a specific sequence will always have /// the same hash value. It should therefore not be used in the context /// where an untrusted third party can mount a denial of service attack by /// forcing the application to create a very large number of label /// sequences that have the same hash value and expected to be stored in /// a hash table. /// /// \exception None /// /// \param case_sensitive /// \return A hash value for this label sequence. size_t getHash(bool case_sensitive) const; `````` Jelte Jansen committed Feb 28, 2012 333 334 335 336 337 `````` /// \brief Checks whether the label sequence is absolute /// /// \return true if the last label is the root label bool isAbsolute() const; `````` Jelte Jansen committed Feb 20, 2012 338 ``````private: `````` JINMEI Tatuya committed Jul 20, 2012 339 340 341 342 343 344 `````` const uint8_t* data_; // wire-format name data const uint8_t* offsets_; // an array of offsets in data_ for the labels size_t first_label_; // index of offsets_ for the first label size_t last_label_; // index of offsets_ for the last label. // can be equal to first_label_, but must not // be smaller (the class ensures that) `````` Jelte Jansen committed Feb 20, 2012 345 346 347 ``````}; `````` Mukund Sivaraman committed Jun 29, 2012 348 349 350 351 352 353 354 355 356 357 358 ``````/// /// \brief Insert the label sequence as a string into stream. /// /// This method convert the \c label_sequence into a string and inserts /// it into the output stream \c os. /// /// This function overloads the global operator<< to behave as described in /// ostream::operator<< but applied to \c LabelSequence objects. /// /// \param os A \c std::ostream object on which the insertion operation is /// performed. `````` Jelte Jansen committed Jul 12, 2012 359 ``````/// \param label_sequence The \c LabelSequence object output by the operation. `````` Mukund Sivaraman committed Jun 29, 2012 360 361 362 363 364 ``````/// \return A reference to the same \c std::ostream object referenced by /// parameter \c os after the insertion operation. std::ostream& operator<<(std::ostream& os, const LabelSequence& label_sequence); `````` Jelte Jansen committed Feb 20, 2012 365 366 367 368 ``````} // end namespace dns } // end namespace isc #endif `````` JINMEI Tatuya committed Jul 20, 2012 369 370 371 372 `````` // Local Variables: // mode: c++ // End:``````