name.h 29.1 KB
Newer Older
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22
// Copyright (C) 2009  Internet Systems Consortium, Inc. ("ISC")
//
// 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 __NAME_H
#define __NAME_H 1

#include <stdint.h>

#include <string>
#include <vector>

23
#include <exceptions/exceptions.h>
24 25

namespace isc {
26
namespace util {
27 28
class InputBuffer;
class OutputBuffer;
29 30 31
}

namespace dns {
32
class AbstractMessageRenderer;
33

34 35 36 37 38 39 40 41 42
///
/// \brief Base class for name parser exceptions.
///
class NameParserException : public Exception {
public:
    NameParserException(const char* file, size_t line, const char* what) :
        isc::Exception(file, line, what) {}
};

43 44 45 46
///
/// \brief A standard DNS module exception that is thrown if the name parser
/// encounters an empty label in the middle of a name.
///
47
class EmptyLabel : public NameParserException {
48 49
public:
    EmptyLabel(const char* file, size_t line, const char* what) :
50
        NameParserException(file, line, what) {}
51 52 53 54 55 56
};

///
/// \brief A standard DNS module exception that is thrown if the name parser
/// encounters too long a name.
///
57
class TooLongName : public NameParserException {
58 59
public:
    TooLongName(const char* file, size_t line, const char* what) :
60
        NameParserException(file, line, what) {}
61 62 63 64 65 66
};

///
/// \brief A standard DNS module exception that is thrown if the name parser
/// encounters too long a label.
///
67
class TooLongLabel : public NameParserException {
68 69
public:
    TooLongLabel(const char* file, size_t line, const char* what) :
70
        NameParserException(file, line, what) {}
71 72 73 74 75 76 77 78
};

///
/// \brief A standard DNS module exception that is thrown if the name parser
/// encounters an obsolete or incomplete label type.  In effect "obsolete" only
/// applies to bitstring labels, which would begin with "\[".  Incomplete cases
/// include an incomplete escaped sequence such as "\12".
///
79
class BadLabelType : public NameParserException {
80 81
public:
    BadLabelType(const char* file, size_t line, const char* what) :
82
        NameParserException(file, line, what) {}
83 84 85 86 87 88
};

///
/// \brief A standard DNS module exception that is thrown if the name parser
/// fails to decode a "\"-escaped sequence.
///
89
class BadEscape : public NameParserException {
90 91
public:
    BadEscape(const char* file, size_t line, const char* what) :
92
        NameParserException(file, line, what) {}
93 94 95 96
};

///
/// \brief A standard DNS module exception that is thrown if the name parser
97
/// finds the input (string or wire-format %data) is incomplete.
98 99 100 101
///
/// An attempt of constructing a name from an empty string will trigger this
/// exception.
///
102
class IncompleteName : public NameParserException {
103 104
public:
    IncompleteName(const char* file, size_t line, const char* what) :
105
        NameParserException(file, line, what) {}
106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155
};

///
/// 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:
    ///    - SUPERDOMAIN: 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
    ///
    /// Note that in our implementation there's always a hierarchical
    /// relationship between any two names since all names are absolute and
    /// they at least share the trailing empty label.
    /// So, for example, the relationship between "com." and "net." is
    /// "commonancestor".  This may be counter intuitive and inconvenient, but
    /// we'll keep this design at the moment until we decide whether and how to
    /// handle "non absolute" names (see the description of the \c Name class).
    /// If we want to (re)introduce the notion of non absolute names, we'll
    /// want to distinguish "com" and "com.", and the current definition would
    /// be more compatible for that purpose.
    /// If, on the other hand, we finally decide we really don't need that
    /// notion, we'll probably reconsider the design here, too. 
    enum NameRelation {
        SUPERDOMAIN = 0,
        SUBDOMAIN = 1,
        EQUAL = 2,
        COMMONANCESTOR = 3
    };

    ///
    /// \name Constructors and Destructor
    ///
    //@{
    /// \brief Constructor from a comparison tuple
    ///
    /// This constructor simply initializes the object in the straightforward
    /// way.
156 157
    NameComparisonResult(int order, unsigned int nlabels,
                         NameRelation relation) :
158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180
        order_(order), nlabels_(nlabels), relation_(relation) {}
    //@}

    ///
    /// \name Getter Methods
    ///
    //@{
    /// Returns the ordering of the comparison result
    int getOrder() const { return (order_); }
    /// Returns the number of common labels of the comparison result
    unsigned int getCommonLabels() const { return (nlabels_); }
    /// Returns the NameRelation of the comparison result
    NameRelation getRelation() const { return (relation_); }
    //@}
private:
    int order_;
    unsigned int nlabels_;
    NameRelation relation_;
};

///
/// The \c Name class encapsulates DNS names.
///
181 182
/// 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
183 184
/// access to various properties of a name, etc.
///
185
/// Notes to developers: Internally, a name object maintains the name %data
186
/// in wire format as an instance of \c std::string.  Since many string
187
/// implementations adopt copy-on-write %data sharing, we expect this approach
188 189 190 191 192 193 194 195 196 197 198 199
/// 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.
///
/// A name object also maintains a vector of offsets (\c offsets_ member),
/// each of which is the offset to a label of the name: The n-th element of
/// the vector specifies the offset to the n-th label.  For example, if the
/// object represents "www.example.com", the elements of the offsets vector
/// are 0, 4, 12, and 16.  Note that the offset to the trailing dot (16) is
/// 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
200
/// %data, and in that sense are redundant).  In our implementation, however,
201
/// we always build and maintain the offsets.  We believe we need more low
202
/// level, specialized %data structure and interface where we really need to
203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221
/// pursue performance, and would rather keep this generic API and
/// implementation simpler.
///
/// 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 {
Jelte Jansen's avatar
Jelte Jansen committed
222 223 224 225 226
    // LabelSequences use knowledge about the internal data structure
    // of this class for efficiency (they use the offsets_ vector and
    // the ndata_ string)
    friend class LabelSequence;

227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250
    ///
    /// \name Constructors and Destructor
    ///
    //@{
private:
    /// The default constructor
    ///
    /// This is used internally in the class implementation, but at least at
    /// the moment defined as private because it will construct an incomplete
    /// object in that it doesn't have any labels.  We may reconsider this
    /// design choice as we see more applications of the class.
    Name() : length_(0), labelcount_(0) {}
public:
    /// Constructor from a string
    ///
    /// If the given string does not represent a valid DNS name, an exception
    /// of class \c EmptyLabel, \c TooLongLabel, \c BadLabelType, \c BadEscape,
    /// \c TooLongName, or \c IncompleteName will be thrown.
    /// In addition, if resource allocation for the new name fails, a
    /// corresponding standard exception will be thrown.
    ///
    /// \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);
251
    /// Constructor from wire-format %data.
252 253 254 255 256
    ///
    /// 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.
    ///
257
    /// The input %data may or may not be compressed; if it's compressed, this
258 259
    /// method will automatically decompress it.
    ///
260
    /// If the given %data does not represent a valid DNS name, an exception
261
    /// of class \c DNSMessageFORMERR will be thrown.
262 263 264
    /// In addition, if resource allocation for the new name fails, a
    /// corresponding standard exception will be thrown.
    ///
265
    /// \param buffer A buffer storing the wire format %data.
266
    /// \param downcase Whether to convert upper case alphabets to lower case.
267
    explicit Name(isc::util::InputBuffer& buffer, bool downcase = false);
268 269
    ///
    /// We use the default copy constructor intentionally.
270
    //@}
271 272
    /// We use the default copy assignment operator intentionally.
    ///
273 274 275 276 277

    ///
    /// \name Getter Methods
    ///
    //@{
278
    /// \brief Provides one-byte name %data in wire format at the specified
279 280 281
    /// position.
    ///
    /// This method returns the unsigned 8-bit value of wire-format \c Name
282
    /// %data at the given position from the head.
283 284 285 286
    ///
    /// 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
287
    /// "example", instead of \c 'e', because it returns a %data portion
288 289 290 291
    /// 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
292 293
    /// wire-format name %data without dumping the %data into a buffer,
    /// which would involve %data copies and would be less efficient.
294 295 296 297 298 299
    /// 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
    ///
300
    /// Parameter \c pos must be in the valid range of the name %data, that is,
301 302 303 304
    /// 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.
    ///
305 306
    /// \param pos The position in the wire format name %data to be returned.
    /// \return An unsigned 8-bit integer corresponding to the name %data
307
    /// at the position of \c pos.
308
    uint8_t at(size_t pos) const
309 310
    {
        if (pos >= length_) {
JINMEI Tatuya's avatar
JINMEI Tatuya committed
311
            isc_throw(OutOfRange, "Out of range access in Name::at()");
312 313 314
        }
        return (ndata_[pos]);
    }
Jelte Jansen's avatar
Jelte Jansen committed
315

316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367
    /// \brief Gets the length of the <code>Name</code> in its wire format.
    ///
    /// This method never throws an exception.
    ///
    /// \return the length (the number of octets in wire format) of the
    /// <code>Name</code>
    size_t getLength() 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.
    ///
    /// This method never throws an exception.
    ///
    /// \return the number of labels
    unsigned int getLabelCount() const { return (labelcount_); }
    //@}

    ///
    /// \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>.  The default value of this parameter is
    /// <code>true</code>; converted names will have a trailing dot by default.
    ///
    /// This function assumes the name is in proper 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.
    //
    /// \param omit_final_dot whether to omit the trailing dot in the output.
    /// \return a string representation of the <code>Name</code>.
    std::string toText(bool omit_final_dot = false) const;

    /// \brief Render the <code>Name</code> in the wire format with compression.
    ///
    /// This method dumps the Name in wire format with help of \c renderer,
    /// which encapsulates output buffer and name compression algorithm to
    /// render the name.
    ///
    /// If resource allocation in rendering process fails, a corresponding
    /// standard exception will be thrown.
    ///
    /// \param renderer DNS message rendering context that encapsulates the
    /// output buffer and name compression information.
368
    void toWire(AbstractMessageRenderer& renderer) const;
369 370 371 372 373 374 375 376 377 378

    /// \brief Render the <code>Name</code> in the wire format without
    /// compression.
    ///
    /// If resource allocation in rendering process fails, a corresponding
    /// standard exception will be thrown.  This can be avoided by preallocating
    /// a sufficient size of \c buffer.  Specifically, if
    /// <code>buffer.getCapacity() - buffer.getLength() >= Name::MAX_WIRE</code>
    /// then this method should not throw an exception.
    ///
379
    /// \param buffer An output buffer to store the wire %data.
380
    void toWire(isc::util::OutputBuffer& buffer) const;
381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424
    //@}

    ///
    /// \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 case-insensitive comparison.
    ///
    /// This method never throws an exception.
    ///
    /// \param other the right-hand operand to compare against.
    /// \return a <code>NameComparisonResult</code> object representing the
    /// comparison result.
    NameComparisonResult compare(const Name& other) const;

    /// \brief Return true iff two names are equal.
    ///
    /// Semantically this could be implemented based on the result of the
    /// \c compare() method, but the actual implementation uses different code
    /// that simply performs character-by-character comparison (case
    /// insensitive for the name label parts) on the two names.  This is because
    /// it would be much faster and the simple equality check would be pretty
    /// common.
    ///
    /// This method never throws an exception.
    ///
    /// \param other the <code>Name</code> object to compare against.
    /// \return true if the two names are equal; otherwise false.
    bool equals(const Name& other) const;

    /// Same as equals()
    bool operator==(const Name& other) const { return (equals(other)); }

    /// \brief Return true iff two names are not equal.
    ///
    /// This method simply negates the result of \c equal() method, and in that
    /// sense it's redundant.  The separate method is provided just for
    /// convenience.
JINMEI Tatuya's avatar
JINMEI Tatuya committed
425
    bool nequals(const Name& other) const { return (!(equals(other))); }
426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520

    /// Same as nequals()
    bool operator!=(const Name& other) const { return (nequals(other)); }

    /// \brief Less-than or equal comparison for Name against <code>other</code>
    ///
    /// The comparison is based on the result of the \c compare() method.
    ///
    /// This method never throws an exception.
    ///
    /// \param other the <code>Name</code> object to compare against.
    /// \return true if <code>compare(other).getOrder() <= 0</code>;
    /// otherwise false.
    bool leq(const Name& other) const;

    /// Same as leq()
    bool operator<=(const Name& other) const { return (leq(other)); }

    /// \brief Greater-than or equal comparison for Name against
    /// <code>other</code>
    ///
    /// The comparison is based on the result of the \c compare() method.
    ///
    /// This method never throws an exception.
    ///
    /// \param other the <code>Name</code> object to compare against.
    /// \return true if <code>compare(other).getOrder() >= 0</code>;
    /// otherwise false.
    bool geq(const Name& other) const;

    /// Same as geq()
    bool operator>=(const Name& other) const { return (geq(other)); }

    /// \brief Less-than comparison for Name against <code>other</code>
    ///
    /// The comparison is based on the result of the \c compare() method.
    ///
    /// This method never throws an exception.
    ///
    /// \param other the <code>Name</code> object to compare against.
    /// \return true if <code>compare(other).getOrder() < 0</code>;
    /// otherwise false.
    bool lthan(const Name& other) const;

    /// Same as lthan()
    bool operator<(const Name& other) const { return (lthan(other)); }

    /// \brief Greater-than comparison for Name against <code>other</code>
    ///
    /// The comparison is based on the result of the \c compare() method.
    ////
    /// This method never throws an exception.
    ///
    /// \param other the <code>Name</code> object to compare against.
    /// \return true if <code>compare(other).getOrder() > 0</code>;
    /// otherwise false.
    bool gthan(const Name& other) const;

    /// Same as gthan()
    bool operator>(const Name& other) const { return (gthan(other)); }
    //@}

    ///
    /// \name Transformer methods
    ///
    //@{
    /// \brief Extract a specified subpart of Name.
    ///
    /// <code>name.split(first, n)</code> constructs a new name starting from
    /// the <code>first</code>-th label of the \c name, and subsequent \c n
    /// labels including the \c first one.  Since names in this current
    /// implementation are always "absolute", if the specified range doesn't
    /// contain the trailing dot of the original \c name, then a dot will be
    /// appended to the resulting name.  As a result, the number of labels
    /// will be <code>n + 1</code>, rather than \c n.  For example,
    /// when \c n is <code>Name("www.example.com")</code>,
    /// both <code>n.split(1, 2)</code> and <code>n.split(1, 3)</code>
    /// will produce a name corresponding to "example.com.", which has 3 labels.
    /// Note also that labels are counted from 0, and so <code>first = 1</code>
    /// in this example specified the label "example", not "www".
    ///
    /// Parameter \c n must be larger than 0, and the range specified by
    /// \c first and \c n must not exceed the valid range of the original name;
    /// otherwise, an exception of class \c OutOfRange will be thrown.
    ///
    /// Note to developers: 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 (in labels) 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;

521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586
    /// \brief Extract a specified super domain name of Name.
    ///
    /// This function constructs a new \c Name object that is a super domain
    /// of \c this name.
    /// The new name is \c level labels upper than \c this name.
    /// For example, when \c name is www.example.com,
    /// <code>name.split(1)</code> will return a \c Name object for example.com.
    /// \c level can be 0, in which case this method returns a copy of
    /// \c this name.
    /// The possible maximum value for \c level is
    /// <code>this->getLabelCount()-1</code>, in which case this method
    /// returns a root name.
    ///
    /// One common expected usage of this method 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(name.split(i));
    ///     // upper_name'll be www.example.com., example.com., com., and then .
    /// }
    /// \endcode
    ///
    /// \c level must be smaller than the number of labels of \c this name;
    /// 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 method is a
    /// simple wrapper to one usage of the other
    /// <code>split(unsigned int, unsigned int) const</code> method and is
    /// redundant in some sense.
    /// We provide the "redundant" method for convenience, however, because
    /// the expected usage shown above seems to be common, and the parameters
    /// to the other \c split(unsigned int, unsigned int) const to implement
    /// it may not be very intuitive.
    ///
    /// We are also aware that it is generally discouraged to add a public
    /// member function that could be implemented using other member functions.
    /// We considered making it a non member function, but we could not come
    /// up with an intuitive function name to represent the specific service.
    /// Some other BIND 10 developers argued, probably partly because of the
    /// counter intuitive function name, a different signature of \c split
    /// would be better to improve code readability.
    /// While that may be a matter of personal preference, we accepted the
    /// argument.  One major goal of public APIs like this is wider acceptance
    /// from internal/external developers, so unless there is a clear advantage
    /// it would be better to respect the preference of the API users.
    ///
    /// Since this method doesn't have to be a member function in other way,
    /// it is intentionally implemented only using public interfaces of the
    /// \c Name class; it doesn't refer to private members of the class even if
    /// it could.
    /// This way we hope we can avoid damaging the class encapsulation,
    /// which is a major drawback of public member functions.
    /// As such if and when this "method" has to be extended, it should be
    /// implemented without the privilege of being a member function unless
    /// there is a very strong reason to do so.  In particular a minor
    /// performance advantage shouldn't justify that approach.
    ///
    /// \param level The number of labels to be removed from \c this name to
    /// create the super domain name.
    /// (0 <= \c level < <code>this->getLabelCount()</code>)
    /// \return A new \c Name object to be created.
    Name split(unsigned int level) const;

587 588 589 590 591 592 593 594
    /// \brief Reverse the labels of a name
    ///
    /// This method reverses the labels of a name.  For example, if
    /// \c this is "www.example.com.", this method will return 
    /// "com.example.www."  (This is useful because DNSSEC sort order
    /// is equivalent to a lexical sort of label-reversed names.)
    Name reverse() const;

595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672
    /// \brief Concatenate two names.
    ///
    /// This method appends \c suffix to \c this Name.  The trailing dot of
    /// \c this Name will be removed.  For example, if \c this is "www."
    /// and \c suffix is "example.com.", a successful return of this method
    /// will be a name of "www.example.com."
    ///
    ///The resulting length of the concatenated name must not exceed
    /// \c Name::MAX_WIRE; otherwise an exception of class
    /// \c TooLongName will be thrown.
    ///
    /// \param suffix a Name object to be appended to the Name.
    /// \return a new Name object concatenating \c suffix to \c this Name.
    Name concatenate(const Name& suffix) const;

    /// \brief Downcase all upper case alphabet characters in the name.
    ///
    /// This method modifies the calling object so that it can perform the
    /// conversion as fast as possible and can be exception free.
    ///
    /// The return value of this version of \c downcase() is a reference to
    /// the calling object (i.e., \c *this) so that the caller can use the
    /// result of downcasing in a single line.  For example, if variable
    /// \c n is a \c Name class object possibly containing upper case
    /// characters, and \c b is an \c OutputBuffer class object, then the
    /// following code will dump the name in wire format to \c b with
    /// downcasing upper case characters:
    ///
    /// \code n.downcase().toWire(b); \endcode
    ///
    /// Since this method modifies the calling object, a \c const name object
    /// cannot call it.  If \c n is a \c const Name class object, it must first
    /// be copied to a different object and the latter must be used for the
    /// downcase modification.
    ///
    /// \return A reference to the calling object with being downcased.
    Name& downcase();
    //@}

    ///
    /// \name Testing methods
    ///
    //@{
    /// \brief Test if this is a wildcard name.
    ///
    /// \return \c true if the least significant label of this Name is
    /// <code>'*'</code>; otherwise \c false.
    bool isWildcard() const;
    //@}

    ///
    /// \name Protocol constants
    ///
    //@{
    /// \brief Max allowable length of domain names.
    static const size_t MAX_WIRE = 255;

    /// \brief Max allowable labels of domain names.
    ///
    /// This is <code>ceil(MAX_WIRE / 2)</code>, and is equal to the number of
    /// labels of name "a.a.a.a....a." (127 "a"'s and trailing dot).
    static const size_t MAX_LABELS = 128;

    /// \brief Max allowable length of labels of a domain name.
    static const size_t MAX_LABELLEN = 63;

    /// \brief Max possible pointer value for name compression.
    ///
    /// This is the highest number of 14-bit unsigned integer.  Name compression
    /// pointers are identified as a 2-byte value starting with the upper two
    /// bit being 11.
    static const uint16_t MAX_COMPRESS_POINTER = 0x3fff;
    /// \brief A 8-bit masked value indicating a start of compression pointer.
    static const uint16_t COMPRESS_POINTER_MARK8 = 0xc0;
    /// \brief A 16-bit masked value indicating a start of compression pointer.
    static const uint16_t COMPRESS_POINTER_MARK16 = 0xc000;
    //@}

673 674 675 676 677 678 679 680
    ///
    /// \name Well-known name constants
    ///
    //@{
    /// \brief Root name (i.e. ".").
    static const Name& ROOT_NAME();
    //@}

681 682 683 684 685 686 687
private:
    std::string ndata_;
    std::vector<unsigned char> offsets_;
    unsigned int length_;
    unsigned int labelcount_;
};

688
inline const Name&
689
Name::ROOT_NAME() {
690 691 692 693
    static Name root_name(".");
    return (root_name);
}

694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716
///
/// \brief Insert the name as a string into stream.
///
/// This method convert the \c name 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 Name objects.
///
/// \param os A \c std::ostream object on which the insertion operation is
/// performed.
/// \param name The \c Name object output by the operation.
/// \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 Name& name);
}
}
#endif // __NAME_H

// Local Variables: 
// mode: c++
// End: