Kea  2.3.5-git
isc::dns::LabelSequence Class Reference

Light-weight Accessor to Name data. More...

#include <labelsequence.h>

Public Member Functions

 LabelSequence (const Name &name)
 Constructs a LabelSequence for the given name. More...
 
 LabelSequence (const void *buf)
 Constructor from serialized image. More...
 
 LabelSequence (const LabelSequence &src, uint8_t buf[MAX_SERIALIZED_LENGTH])
 Construct 'extendable' LabelSequence. More...
 
 LabelSequence (const LabelSequence &ls)
 Copy constructor. More...
 
NameComparisonResult compare (const LabelSequence &other, bool case_sensitive=false) const
 Compares two label sequences. More...
 
bool equals (const LabelSequence &other, bool case_sensitive=false) const
 Compares two label sequences for equality. More...
 
void extend (const LabelSequence &labels, uint8_t buf[MAX_SERIALIZED_LENGTH])
 Extend this LabelSequence with the given labelsequence. More...
 
const uint8_t * getData (size_t *len) const
 Return the wire-format data for this LabelSequence. More...
 
size_t getDataLength () const
 Return the length of the wire-format data of this LabelSequence. More...
 
size_t getHash (bool case_sensitive) const
 Calculate a simple hash for the label sequence. More...
 
size_t getLabelCount () const
 Returns the current number of labels for this LabelSequence. More...
 
size_t getSerializedLength () const
 Return the size of serialized image of the LabelSequence. More...
 
bool isAbsolute () const
 Checks whether the label sequence is absolute. More...
 
LabelSequenceoperator= (const LabelSequence &other)
 Assignment operator. More...
 
bool operator== (const LabelSequence &other) const
 Compares two label sequences for equality (case ignored). More...
 
void serialize (void *buf, size_t buf_len) const
 Serialize the LabelSequence object in to a buffer. More...
 
void stripLeft (size_t i)
 Remove labels from the front of this LabelSequence. More...
 
void stripRight (size_t i)
 Remove labels from the end of this LabelSequence. More...
 
std::string toRawText (bool omit_final_dot) const
 Convert the LabelSequence to a string without escape sequences. More...
 
std::string toText () const
 Convert the LabelSequence to a string. More...
 

Static Public Member Functions

Well-known LabelSequence constants
static const LabelSequenceWILDCARD ()
 Wildcard label ("*") More...
 

Static Public Attributes

static const size_t MAX_SERIALIZED_LENGTH
 Max possible size of serialized image generated by serialize. More...
 

Friends

std::string Name::toText (bool) const
 

Detailed Description

Light-weight Accessor to Name data.

The purpose of this class is to easily match Names and parts of Names, without needing to copy the underlying data on each label strip.

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 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 stripLeft() or stripRight() is called on the LabelSequence, no changes in the original 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 original Name object).

Definition at line 35 of file labelsequence.h.

Constructor & Destructor Documentation

◆ LabelSequence() [1/4]

isc::dns::LabelSequence::LabelSequence ( const Name name)
inlineexplicit

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).
Parameters
nameThe Name to construct a LabelSequence for

Definition at line 64 of file labelsequence.h.

◆ LabelSequence() [2/4]

isc::dns::LabelSequence::LabelSequence ( const void *  buf)
explicit

Constructor from serialized image.

This constructor restores a LabelSequence object from a serialized binary image previously generated by 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 serialize() on a valid 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.

Parameters
bufPointer to the serialized image generated by serialize().

Definition at line 21 of file labelsequence.cc.

References isc_throw, isc::dns::Name::MAX_LABELLEN, and isc::dns::Name::MAX_LABELS.

◆ LabelSequence() [3/4]

isc::dns::LabelSequence::LabelSequence ( const LabelSequence src,
uint8_t  buf[MAX_SERIALIZED_LENGTH] 
)

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()

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.
The buffer should never be modified except through calls to extend().
Also, only associate the buffer with at most one LabelSequence. Behaviour is undefined if two LabelSequences are using the same buffer.
Parameters
srcLabelSequence to copy the initial data from
bufexternal buffer to store this labelsequence's data in

Definition at line 63 of file labelsequence.cc.

References getData(), getLabelCount(), and isc::dns::Name::MAX_WIRE.

+ Here is the call graph for this function:

◆ LabelSequence() [4/4]

isc::dns::LabelSequence::LabelSequence ( const LabelSequence ls)
inline

Copy constructor.

Note
The associated data MUST remain in scope during the lifetime of this LabelSequence, since only the pointers are copied.
No validation is done on the given data upon construction; use with care.
Parameters
lsThe LabelSequence to construct a LabelSequence from

Definition at line 125 of file labelsequence.h.

Member Function Documentation

◆ compare()

NameComparisonResult isc::dns::LabelSequence::compare ( const LabelSequence other,
bool  case_sensitive = false 
) const

Compares two label sequences.

Performs a (optionally case-insensitive) comparison between this LabelSequence and another LabelSequence.

Parameters
otherThe LabelSequence to compare with
case_sensitiveIf true, comparison is case-insensitive
Returns
a NameComparisonResult object representing the comparison result.

Definition at line 169 of file labelsequence.cc.

References isc::dns::NameComparisonResult::COMMONANCESTOR, isc::dns::NameComparisonResult::EQUAL, getLabelCount(), isc_throw_assert, isc::dns::name::internal::maptolower, isc::dns::Name::MAX_LABELLEN, isc::dns::NameComparisonResult::NONE, isc::dns::NameComparisonResult::SUBDOMAIN, and isc::dns::NameComparisonResult::SUPERDOMAIN.

Referenced by isc::dns::Name::compare(), and operator==().

+ Here is the call graph for this function:

◆ equals()

bool isc::dns::LabelSequence::equals ( const LabelSequence other,
bool  case_sensitive = false 
) const

Compares two label sequences for equality.

Performs a (optionally case-sensitive) comparison between this LabelSequence and another LabelSequence for equality.

Parameters
otherThe LabelSequence to compare with
case_sensitiveIf true, comparison is case-sensitive
Returns
true if The label sequences consist are the same length, and contain the same data.

Definition at line 142 of file labelsequence.cc.

References getData(), and isc::dns::name::internal::maptolower.

Referenced by operator=(), and operator==().

+ Here is the call graph for this function:

◆ extend()

void isc::dns::LabelSequence::extend ( const LabelSequence labels,
uint8_t  buf[MAX_SERIALIZED_LENGTH] 
)

Extend this LabelSequence with the given labelsequence.

The given labels are appended to the name data, and internal offset data is updated accordingly.

The data from the given LabelSequence is copied into the buffer associated with this LabelSequence; the appended LabelSequence (the 'labels' argument) can be released if it is not needed for other operations anymore.

If this LabelSequence is absolute, its root label will be stripped before the given LabelSequence is appended; after extend(), this LabelSequence will be absolute if, and only if, the appended LabelSequence was. A side-effect of this property is that adding the root label to an absolute LabelSequence has no effect (the root label is stripped, then added again).

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).

Exceptions
BadValueIf 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
Parameters
labelsThe labels to append to this LabelSequence
bufThe buffer associated with this LabelSequence

Definition at line 420 of file labelsequence.cc.

References getData(), getLabelCount(), isAbsolute(), isc_throw, isc::dns::Name::MAX_LABELS, and isc::dns::Name::MAX_WIRE.

Referenced by getLabelCount().

+ Here is the call graph for this function:

◆ getData()

const uint8_t * isc::dns::LabelSequence::getData ( size_t *  len) const

Return the wire-format data for this LabelSequence.

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 set to the number of octets that match this labelsequence.

Note
The data pointed to is only valid if the original Name object or data is still in scope
Parameters
lenPointer to a size_t where the length of the data will be stored (in number of octets)
Returns
Pointer to the wire-format data of this label sequence

Definition at line 83 of file labelsequence.cc.

References getDataLength().

Referenced by equals(), extend(), isc::dhcp::OptionDefinition::factoryOpaqueDataTuples(), getHash(), LabelSequence(), operator=(), isc::dhcp::Option6ClientFqdn::packDomainName(), isc::dhcp::Option4ClientFqdn::packDomainName(), isc::dhcp::OptionDataTypeUtil::writeFqdn(), and isc::dns::MessageRenderer::writeName().

+ Here is the call graph for this function:

◆ getDataLength()

size_t isc::dns::LabelSequence::getDataLength ( ) const

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 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 object or data is still in scope
Returns
The length of the data of the label sequence in octets.

Definition at line 89 of file labelsequence.cc.

Referenced by isc::dhcp::OptionDefinition::factoryOpaqueDataTuples(), getData(), getSerializedLength(), operator=(), isc::dhcp::Option6ClientFqdn::packDomainName(), isc::dhcp::Option4ClientFqdn::packDomainName(), serialize(), toRawText(), isc::dhcp::OptionDataTypeUtil::writeFqdn(), and isc::dns::MessageRenderer::writeName().

◆ getHash()

size_t isc::dns::LabelSequence::getHash ( bool  case_sensitive) const

Calculate a simple hash for the label sequence.

This method calculates a hash value for the label sequence as binary data. If 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.

Exceptions
None
Parameters
case_sensitive
Returns
A hash value for this label sequence.

Definition at line 266 of file labelsequence.cc.

References getData(), and isc::dns::name::internal::maptolower.

Referenced by getLabelCount(), and isc::dns::MessageRenderer::writeName().

+ Here is the call graph for this function:

◆ getLabelCount()

size_t isc::dns::LabelSequence::getLabelCount ( ) const
inline

Returns the current number of labels for this LabelSequence.

Returns
The number of labels

Definition at line 308 of file labelsequence.h.

References extend(), getHash(), isAbsolute(), isc::dns::operator<<(), toRawText(), and toText().

Referenced by compare(), extend(), getSerializedLength(), LabelSequence(), serialize(), stripLeft(), stripRight(), toRawText(), and isc::dns::MessageRenderer::writeName().

+ Here is the call graph for this function:

◆ getSerializedLength()

size_t isc::dns::LabelSequence::getSerializedLength ( ) const

Return the size of serialized image of the LabelSequence.

This method calculates the size of necessary storage to store serialized image of this LabelSequence (which would be dumped by serialize()) and returns it. The size is in bytes.

Exceptions
none.
Returns
The size of serialized image of the LabelSequence.

Definition at line 95 of file labelsequence.cc.

References getDataLength(), and getLabelCount().

Referenced by operator=(), and serialize().

+ Here is the call graph for this function:

◆ isAbsolute()

bool isc::dns::LabelSequence::isAbsolute ( ) const

Checks whether the label sequence is absolute.

Returns
true if the last label is the root label

Definition at line 261 of file labelsequence.cc.

Referenced by extend(), getLabelCount(), and toText().

◆ operator=()

LabelSequence& isc::dns::LabelSequence::operator= ( const LabelSequence other)
inline

Assignment operator.

Note
The associated data MUST remain in scope during the lifetime of this LabelSequence, since only the pointers are copied.
No validation is done on the given data upon construction; use with care.
Parameters
otherThe LabelSequence to assign a LabelSequence from

Definition at line 141 of file labelsequence.h.

References equals(), getData(), getDataLength(), getSerializedLength(), and serialize().

+ Here is the call graph for this function:

◆ operator==()

bool isc::dns::LabelSequence::operator== ( const LabelSequence other) const
inline

Compares two label sequences for equality (case ignored).

This is equivalent to this->equals(other).

The operator version is convenient some specific cases such as in unit tests.

Definition at line 267 of file labelsequence.h.

References compare(), equals(), stripLeft(), and stripRight().

+ Here is the call graph for this function:

◆ serialize()

void isc::dns::LabelSequence::serialize ( void *  buf,
size_t  buf_len 
) const

Serialize the LabelSequence object in to a buffer.

This method dumps a serialized image of this 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).

Be careful about where the buffer is located; due to the nature of the buffer, it's quite possible that the memory region is being used to construct another active LabelSequence. In such a case the serialization would silently break that sequence object, and it will be very difficult to identify the cause. This method has minimal level checks to avoid such disruption: If the serialization would break "this" LabelSequence object, it doesn't write anything to the given buffer and throw a isc::BadValue exception.

In general, it should be safe to call this method on a LabelSequence object constructed from a Name object or a copy of such LabelSequence. When you construct LabelSequence from pre-serialized data, calling this method on it can be unsafe. One safe (but a bit less efficient) way in such a case is to make the source LabelSequence temporary and immediately create a local copy using an explicit buffer, and call this method on the latter:

// don't do this, it's not safe (and would result in exception):
// LabelSequence(buf).serialize(buf, buf_len);
// The following are the safe way:
LabelSequence seq(LabelSequence(buf), ext_buf);
... (strip the labels, etc)
seq.serialize(buf, buf_len); // it's safe to override buf here

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 as 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.

Exceptions
isc::BadValuebuf_len is too short (this method never throws otherwise) or the serialization would override internal data of of the source LabelSequence.
Parameters
bufPointer to the placeholder to dump the serialized image
buf_lenThe size of available region in buf

Definition at line 113 of file labelsequence.cc.

References getDataLength(), getLabelCount(), getSerializedLength(), isc_throw, and isc_throw_assert.

Referenced by operator=().

+ Here is the call graph for this function:

◆ stripLeft()

void isc::dns::LabelSequence::stripLeft ( size_t  i)

Remove labels from the front of this LabelSequence.

Note
No actual memory is changed, this operation merely updates the internal pointers based on the offsets in the Name object.
Exceptions
OutOfRangeif i is greater than or equal to the number of labels currently pointed to by this LabelSequence
Parameters
iThe number of labels to remove.

Definition at line 243 of file labelsequence.cc.

References getLabelCount(), and isc_throw.

Referenced by operator==(), and isc::dns::MessageRenderer::writeName().

+ Here is the call graph for this function:

◆ stripRight()

void isc::dns::LabelSequence::stripRight ( size_t  i)

Remove labels from the end of this LabelSequence.

Note
No actual memory is changed, this operation merely updates the internal pointers based on the offsets originally provided.
Exceptions
OutOfRangeif i is greater than or equal to the number of labels currently pointed to by this LabelSequence
Parameters
iThe number of labels to remove.

Definition at line 252 of file labelsequence.cc.

References getLabelCount(), and isc_throw.

Referenced by operator==(), and isc::dns::MessageRenderer::writeName().

+ Here is the call graph for this function:

◆ toRawText()

std::string isc::dns::LabelSequence::toRawText ( bool  omit_final_dot) const

Convert the LabelSequence to a string without escape sequences.

The string returned will contain a single character value for any escape sequences in the label(s).

Parameters
omit_final_dotwhether to omit the trailing dot in the output.
Returns
a string representation of the LabelSequence that does not contain escape sequences.

Definition at line 284 of file labelsequence.cc.

References getDataLength(), getLabelCount(), isc_throw, isc_throw_assert, isc::dns::Name::MAX_LABELLEN, and toText().

Referenced by getLabelCount(), and isc::dns::Name::toRawText().

+ Here is the call graph for this function:

◆ toText()

std::string isc::dns::LabelSequence::toText ( ) const

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 '.' if the label sequence is absolute.

This function assumes the underlying data is in proper uncompressed wire format. If it finds an unexpected label character including compression pointer, an exception of class BadLabelType will be thrown. In addition, if resource allocation for the result string fails, a corresponding standard exception will be thrown.

Returns
a string representation of the LabelSequence.

Definition at line 415 of file labelsequence.cc.

References isAbsolute().

Referenced by getLabelCount(), isc::dns::operator<<(), toRawText(), and isc::dns::Name::toText().

+ Here is the call graph for this function:

◆ WILDCARD()

const LabelSequence & isc::dns::LabelSequence::WILDCARD ( )
inlinestatic

Wildcard label ("*")

Definition at line 443 of file labelsequence.h.

Friends And Related Function Documentation

◆ Name::toText

std::string Name::toText ( bool  ) const
friend

Member Data Documentation

◆ MAX_SERIALIZED_LENGTH

const size_t isc::dns::LabelSequence::MAX_SERIALIZED_LENGTH
static
Initial value:

Max possible size of serialized image generated by serialize.

A fixed length buffer of this size can be always passed to serialize() safely. (But the application shouldn't use the specific size value; it must use this constant variable).

Definition at line 45 of file labelsequence.h.


The documentation for this class was generated from the following files: