Kea: isc::dhcp::OpaqueDataTuple Class Reference

| Kea 3.2.0-git

isc::dhcp::OpaqueDataTuple Class Reference

Represents a single instance of the opaque data preceded by length. More...

`#include <opaque_data_tuple.h>`

## Public Types
using | Buffer = std::vector<uint8_t>
| Defines a type of the data buffer used to hold the opaque data.
using | InputIterator = Buffer::const_iterator
enum | LengthFieldType { LENGTH_EMPTY = -1 , LENGTH_1_BYTE , LENGTH_2_BYTES }
| Size of the length field in the tuple. More...

## Public Member Functions
| OpaqueDataTuple (LengthFieldType length_field_type)
| Default constructor.
| OpaqueDataTuple (LengthFieldType length_field_type, InputIterator begin, InputIterator end)
| Constructor.
void | append (const char *data, const size_t len)
| Appends data to the tuple.
void | append (const std::string &text)
| Appends string to the tuple.
void | append (const uint8_t *data, const size_t len)
void | append (InputIterator data, const size_t len)
void | assign (const char *data, const size_t len)
| Assigns data to the tuple.
void | assign (const std::string &text)
| Assigns string data to the tuple.
void | assign (InputIterator data, const size_t len)
void | clear ()
| Removes the contents of the tuple.
bool | equals (const std::string &other) const
| Checks if the data carried in the tuple match the string.
const Buffer & | getData () const
| Returns a reference to the buffer holding tuple data.
size_t | getLength () const
| Returns the length of the data in the tuple.
LengthFieldType | getLengthFieldType () const
| Returns tuple length data field type.
std::string | getText () const
| Return the tuple data in the textual format.
size_t | getTotalLength () const
| Returns a total size of the tuple, including length field.
void | pack (isc::util::OutputBuffer &buf) const
| Renders the tuple to a buffer in the wire format.
void | unpack (InputIterator begin, InputIterator end)
| Parses wire data and creates a tuple from it.

## Assignment and comparison operators.
OpaqueDataTuple & | operator= (const std::string &other)
| Assignment operator.
bool | operator== (const std::string &other) const
| Equality operator.
bool | operator!= (const std::string &other)
| Inequality operator.
int | getDataFieldSize () const
| Returns the size of the tuple length field.

## Detailed Description

Represents a single instance of the opaque data preceded by length.

Some of the DHCP options, such as Vendor Class option (16) in DHCPv6 or V-I Vendor Class option (124) in DHCPv4 may carry multiple pairs of opaque-data preceded by its length. Such pairs are called tuples. This class represents a single instance of the tuple in the DHCPv4 or DHCPv6 option.

Although, the primary purpose of this class is to represent data tuples in Vendor Class options, there may be other options defined in the future that may have similar structure and this class can be used to represent the data tuples in these new options too.

This class exposes a set of convenience methods to assign and retrieve the opaque data from the tuple. It also implements a method to render the tuple data into a wire format, as well as a method to create an instance of the tuple from the wire format.

Definition at line 46 of file opaque_data_tuple.h.

## Member Typedef Documentation

## ◆ Buffer

using isc::dhcp::OpaqueDataTuple::Buffer = std::vector<uint8_t>

Defines a type of the data buffer used to hold the opaque data.

Definition at line 63 of file opaque_data_tuple.h.

## ◆ InputIterator

using isc::dhcp::OpaqueDataTuple::InputIterator = Buffer::const_iterator

Definition at line 64 of file opaque_data_tuple.h.

## Member Enumeration Documentation

## ◆ LengthFieldType

enum isc::dhcp::OpaqueDataTuple::LengthFieldType

Size of the length field in the tuple.

In the wire format, the tuple consists of the two fields: one holding a length of the opaque data size, second holding opaque data. The first field's size may be equal to 1 or 2 bytes. Usually, the tuples carried in the DHCPv6 options have 2 byte long length fields, the tuples carried in DHCPv4 options have 1 byte long length fields.

Enumerator
LENGTH_EMPTY |
LENGTH_1_BYTE |
LENGTH_2_BYTES |

Definition at line 56 of file opaque_data_tuple.h.

## Constructor & Destructor Documentation

## ◆ OpaqueDataTuple() [1/2]

isc::dhcp::OpaqueDataTuple::OpaqueDataTuple | ( | LengthFieldType | length_field_type | ) |

Default constructor.

Parameters

  length_field_type | Indicates a length of the field which holds the size of the tuple.

Definition at line 15 of file opaque_data_tuple.cc.

## ◆ OpaqueDataTuple() [2/2]

isc::dhcp::OpaqueDataTuple::OpaqueDataTuple | ( | LengthFieldType | length_field_type,
|  | InputIterator | begin,
|  | InputIterator | end )
| inline

Constructor.

Creates a tuple from on-wire data. It calls `OpaqueDataTuple::unpack` internally.

Parameters

  length_field_type | Indicates the length of the field holding the opaque data size.
  begin | Iterator pointing to the beginning of the buffer holding wire data.
  end | Iterator pointing to the end of the buffer holding wire data.

Exceptions

  It | may throw an exception if the `unpack` throws.

Definition at line 83 of file opaque_data_tuple.h.

References unpack().

Here is the call graph for this function:

## Member Function Documentation

## ◆ append() [1/4]

void isc::dhcp::OpaqueDataTuple::append | ( | const char * | data,
|  | const size_t | len )
| inline

Appends data to the tuple.

This function appends the data of the specified length to the tuple. If the specified buffer length is greater than the size of the buffer, the behavior of this function is undefined.

Parameters

  data | Iterator pointing to the beginning of the buffer being appended. The source buffer may be an STL object or an array of characters. In the latter case, the pointer to the beginning of this array should be passed.
  len | Length of the source buffer.

Template Parameters

  InputIterator | Type of the iterator pointing to the beginning of the source buffer.

Definition at line 103 of file opaque_data_tuple.h.

Referenced by append(), and isc::dhcp::operator>>().

## ◆ append() [2/4]

void isc::dhcp::OpaqueDataTuple::append | ( | const std::string & | text | ) |

Appends string to the tuple.

In most cases, the tuple will carry a string. This function appends the string to the tuple.

Parameters

  text | String to be appended in the tuple.

Definition at line 20 of file opaque_data_tuple.cc.

References append().

Here is the call graph for this function:

## ◆ append() [3/4]

void isc::dhcp::OpaqueDataTuple::append | ( | const uint8_t * | data,
|  | const size_t | len )
| inline

Definition at line 106 of file opaque_data_tuple.h.

## ◆ append() [4/4]

void isc::dhcp::OpaqueDataTuple::append | ( | InputIterator | data,
|  | const size_t | len )
| inline

Definition at line 109 of file opaque_data_tuple.h.

## ◆ assign() [1/3]

void isc::dhcp::OpaqueDataTuple::assign | ( | const char * | data,
|  | const size_t | len )
| inline

Assigns data to the tuple.

This function replaces existing data in the tuple with the new data. If the specified buffer length is greater than the size of the buffer, the behavior of this function is undefined.

Parameters

  data | Iterator pointing to the beginning of the buffer being assigned. The source buffer may be an STL object or an array of characters. In the latter case, the pointer to the beginning of this array should be passed.
  len | Length of the source buffer.

Definition at line 131 of file opaque_data_tuple.h.

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

## ◆ assign() [2/3]

void isc::dhcp::OpaqueDataTuple::assign | ( | const std::string & | text | ) |

Assigns string data to the tuple.

In most cases, the tuple will carry a string. This function sets the string to the tuple.

Parameters

  text | String to be assigned to the tuple.

Definition at line 28 of file opaque_data_tuple.cc.

References assign(), and clear().

Here is the call graph for this function:

## ◆ assign() [3/3]

void isc::dhcp::OpaqueDataTuple::assign | ( | InputIterator | data,
|  | const size_t | len )
| inline

Definition at line 134 of file opaque_data_tuple.h.

## ◆ clear()

void isc::dhcp::OpaqueDataTuple::clear | ( |  | ) |

Removes the contents of the tuple.

Definition at line 38 of file opaque_data_tuple.cc.

Referenced by assign(), and isc::dhcp::operator>>().

## ◆ equals()

bool isc::dhcp::OpaqueDataTuple::equals | ( | const std::string & | other | ) | const

Checks if the data carried in the tuple match the string.

Parameters

  other | String to compare tuple data against.

Definition at line 43 of file opaque_data_tuple.cc.

References getText().

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

Here is the call graph for this function:

## ◆ getData()

const Buffer & isc::dhcp::OpaqueDataTuple::getData | ( |  | ) | const
| inline

Returns a reference to the buffer holding tuple data.

Warning
  The returned reference is valid only within the lifetime of the object which returned it. The use of the returned reference after the object has been destroyed yelds undefined behavior.

Definition at line 174 of file opaque_data_tuple.h.

Referenced by isc::dhcp::TokenVendorClass::evaluate(), pack(), isc::dhcp::DnrInstance::unpackAdn(), and isc::dhcp::OptionDataTypeUtil::writeTuple().

## ◆ getDataFieldSize()

int isc::dhcp::OpaqueDataTuple::getDataFieldSize | ( |  | ) | const

Returns the size of the tuple length field.

The returned value depends on the `LengthFieldType` set for the tuple.

Definition at line 74 of file opaque_data_tuple.cc.

References LENGTH_1_BYTE.

Referenced by isc::dhcp::OptionOpaqueDataTuples::addTuple(), isc::dhcp::OptionVendorClass::addTuple(), getTotalLength(), pack(), isc::dhcp::OptionOpaqueDataTuples::setTuple(), isc::dhcp::OptionVendorClass::setTuple(), and unpack().

## ◆ getLength()

size_t isc::dhcp::OpaqueDataTuple::getLength | ( |  | ) | const
| inline

Returns the length of the data in the tuple.

Definition at line 160 of file opaque_data_tuple.h.

Referenced by getTotalLength(), pack(), isc::dhcp::OptionOpaqueDataTuples::toText(), isc::dhcp::OptionVendorClass::toText(), isc::dhcp::DnrInstance::unpackAddresses(), isc::dhcp::DnrInstance::unpackAdn(), and isc::dhcp::OptionDataTypeUtil::writeTuple().

## ◆ getLengthFieldType()

LengthFieldType isc::dhcp::OpaqueDataTuple::getLengthFieldType | ( |  | ) | const
| inline

Returns tuple length data field type.

Definition at line 155 of file opaque_data_tuple.h.

Referenced by isc::dhcp::OptionOpaqueDataTuples::addTuple(), isc::dhcp::OptionVendorClass::addTuple(), isc::dhcp::OptionOpaqueDataTuples::setTuple(), isc::dhcp::OptionVendorClass::setTuple(), and isc::dhcp::OptionDataTypeUtil::writeTuple().

## ◆ getText()

std::string isc::dhcp::OpaqueDataTuple::getText | ( |  | ) | const

Return the tuple data in the textual format.

Definition at line 48 of file opaque_data_tuple.cc.

Referenced by equals(), and isc::dhcp::operator<<().

## ◆ getTotalLength()

size_t isc::dhcp::OpaqueDataTuple::getTotalLength | ( |  | ) | const
| inline

Returns a total size of the tuple, including length field.

Definition at line 165 of file opaque_data_tuple.h.

References getDataFieldSize(), and getLength().

Referenced by isc::dhcp::OptionOpaqueDataTuples::unpack(), isc::dhcp::OptionVendorClass::unpack(), and isc::dhcp::DnrInstance::unpackSvcParams().

Here is the call graph for this function:

## ◆ operator!=()

bool isc::dhcp::OpaqueDataTuple::operator!= | ( | const std::string & | other | ) |

Inequality operator.

This operator compares the string given as an argument to the data carried in the tuple for inequality.

Parameters

  other | String to compare the tuple against.

Returns
  true if the data carried in the tuple is unequal the given string.

Definition at line 91 of file opaque_data_tuple.cc.

References equals().

Here is the call graph for this function:

## ◆ operator=()

OpaqueDataTuple & isc::dhcp::OpaqueDataTuple::operator= | ( | const std::string & | other | ) |

Assignment operator.

This operator assigns the string data to the tuple.

Parameters

  other | string to be assigned to the tuple.

Returns
  Tuple object after assignment.

Definition at line 79 of file opaque_data_tuple.cc.

References assign().

Here is the call graph for this function:

## ◆ operator==()

bool isc::dhcp::OpaqueDataTuple::operator== | ( | const std::string & | other | ) | const

Equality operator.

This operator compares the string given as an argument to the data carried in the tuple in the textual format.

Parameters

  other | String to compare the tuple against.

Returns
  true if data carried in the tuple is equal to the string.

Definition at line 86 of file opaque_data_tuple.cc.

References equals().

Here is the call graph for this function:

## ◆ pack()

void isc::dhcp::OpaqueDataTuple::pack | ( | isc::util::OutputBuffer & | buf | ) | const

Renders the tuple to a buffer in the wire format.

This function creates the following wire representation of the tuple:

- 1 or 2 bytes holding a length of the data.
- variable number of bytes holding data. and writes it to the specified buffer. The new are appended to the buffer, so as data existing in the buffer is preserved.

The tuple is considered malformed if one of the following occurs:

- the size of the data is 0 (tuple is empty),
- the size of the data is greater than 255 and the size of the length field is 1 byte (see `LengthFieldType`).
- the size of the data is greater than 65535 and the size of the length field is 2 bytes (see `LengthFieldType`).

Function will throw an exception if trying to render malformed tuple.

Parameters

  [out] | buf | Buffer to which the data is rendered.

Exceptions

  OpaqueDataTupleError | if failed to render the data to the buffer because the tuple is malformed.

Definition at line 54 of file opaque_data_tuple.cc.

References getData(), getDataFieldSize(), getLength(), isc_throw, isc::util::OutputBuffer::writeData(), isc::util::OutputBuffer::writeUint16(), and isc::util::OutputBuffer::writeUint8().

Here is the call graph for this function:

## ◆ unpack()

void isc::dhcp::OpaqueDataTuple::unpack | ( | OpaqueDataTuple::InputIterator | begin,
|  | OpaqueDataTuple::InputIterator | end )

Parses wire data and creates a tuple from it.

This function parses on-wire data stored in the provided buffer and stores it in the tuple object. The wire data must include at least the data field of the length matching the specified `LengthFieldType`. The remaining buffer length (excluding the length field) must be equal or greater than the length carried in the length field. If any of these two conditions is not met, an exception is thrown.

This function allows opaque data with the length of 0.

Parameters

  begin | Iterator pointing to the beginning of the buffer holding wire data.
  end | Iterator pointing to the end of the buffer holding wire data.

Template Parameters

  InputIterator | Type of the iterators passed to this function.

Definition at line 117 of file opaque_data_tuple.cc.

References assign(), getDataFieldSize(), isc_throw, isc::dhcp::Option::lenient_parsing_, and isc::util::readUint16().

Referenced by OpaqueDataTuple(), isc::dhcp::OptionDataTypeUtil::readTuple(), isc::dhcp::DnrInstance::unpackAddresses(), isc::dhcp::DnrInstance::unpackAdn(), and isc::dhcp::DnrInstance::unpackSvcParams().

Here is the call graph for this function:

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

- opaque_data_tuple.h
- opaque_data_tuple.cc