Kea  2.1.7-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. More...
 
using InputIterator = Buffer::const_iterator
 
enum  LengthFieldType { 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. More...
 
 OpaqueDataTuple (LengthFieldType length_field_type, InputIterator begin, InputIterator end)
 Constructor. More...
 
void append (const char *data, const size_t len)
 Appends data to the tuple. More...
 
void append (InputIterator data, const size_t len)
 
void append (const std::string &text)
 Appends string to the tuple. More...
 
void assign (const char *data, const size_t len)
 Assigns data to the tuple. More...
 
void assign (InputIterator data, const size_t len)
 
void assign (const std::string &text)
 Assigns string data to the tuple. More...
 
void clear ()
 Removes the contents of the tuple. More...
 
bool equals (const std::string &other) const
 Checks if the data carried in the tuple match the string. More...
 
const BuffergetData () const
 Returns a reference to the buffer holding tuple data. More...
 
int getDataFieldSize () const
 Returns the size of the tuple length field. More...
 
size_t getLength () const
 Returns the length of the data in the tuple. More...
 
LengthFieldType getLengthFieldType () const
 Returns tuple length data field type. More...
 
std::string getText () const
 Return the tuple data in the textual format. More...
 
size_t getTotalLength () const
 Returns a total size of the tuple, including length field. More...
 
void pack (isc::util::OutputBuffer &buf) const
 Renders the tuple to a buffer in the wire format. More...
 
void unpack (InputIterator begin, InputIterator end)
 Parses wire data and creates a tuple from it. More...
 
Assignment and comparison operators.
OpaqueDataTupleoperator= (const std::string &other)
 Assignment operator. More...
 
bool operator== (const std::string &other) const
 Equality operator. More...
 
bool operator!= (const std::string &other)
 Inequality operator. More...
 

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 47 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

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_1_BYTE 
LENGTH_2_BYTES 

Definition at line 57 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_typeIndicates a length of the field which holds the size of the tuple.

Definition at line 14 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_typeIndicates the length of the field holding the opaque data size.
beginIterator pointing to the beginning of the buffer holding wire data.
endIterator pointing to the end of the buffer holding wire data.
Exceptions
Itmay throw an exception if the unpack throws.

Definition at line 83 of file opaque_data_tuple.h.

Member Function Documentation

◆ append() [1/3]

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
dataIterator 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.
lenLength of the source buffer.
Template Parameters
InputIteratorType 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/3]

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

Definition at line 106 of file opaque_data_tuple.h.

◆ append() [3/3]

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
textString to be appended in the tuple.

Definition at line 19 of file opaque_data_tuple.cc.

References append().

+ Here is the call graph for this function:

◆ 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
dataIterator 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.
lenLength of the source buffer.

Definition at line 128 of file opaque_data_tuple.h.

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

◆ assign() [2/3]

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

Definition at line 131 of file opaque_data_tuple.h.

◆ assign() [3/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
textString to be assigned to the tuple.

Definition at line 27 of file opaque_data_tuple.cc.

References assign(), and clear().

+ Here is the call graph for this function:

◆ clear()

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

Removes the contents of the tuple.

Definition at line 37 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
otherString to compare tuple data against.

Definition at line 42 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 171 of file opaque_data_tuple.h.

References isc::data::operator!=(), and isc::data::operator==().

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

+ Here is the call graph for this function:

◆ 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 73 of file opaque_data_tuple.cc.

References LENGTH_1_BYTE.

Referenced by isc::dhcp::OptionOpaqueDataTuples::addTuple(), isc::dhcp::OptionVendorClass::addTuple(), 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 157 of file opaque_data_tuple.h.

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

◆ getLengthFieldType()

◆ getText()

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

Return the tuple data in the textual format.

Definition at line 47 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 162 of file opaque_data_tuple.h.

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

◆ 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
otherString to compare the tuple against.
Returns
true if the data carried in the tuple is unequal the given string.

Definition at line 90 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
otherstring to be assigned to the tuple.
Returns
Tuple object after assignment.

Definition at line 78 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
otherString to compare the tuple against.
Returns
true if data carried in the tuple is equal to the string.

Definition at line 85 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]bufBuffer to which the data is rendered.
Exceptions
OpaqueDataTupleErrorif failed to render the data to the buffer because the tuple is malformed.

Definition at line 53 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
beginIterator pointing to the beginning of the buffer holding wire data.
endIterator pointing to the end of the buffer holding wire data.
Template Parameters
InputIteratorType of the iterators passed to this function.

Definition at line 116 of file opaque_data_tuple.cc.

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

Referenced by isc::dhcp::OptionDataTypeUtil::readTuple().

+ Here is the call graph for this function:

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