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

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

◆ 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(), and pack().

◆ 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 getTotalLength(), pack(), 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(), and isc::dhcp::OptionVendorClass::toText().

◆ getLengthFieldType()

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

inline

Returns tuple length data field type.

Definition at line 155 of file opaque_data_tuple.h.

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

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

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(), and isc_throw.

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

Here is the call graph for this function:

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

Public Types

Public Member Functions

Assignment and comparison operators.

Detailed Description

Member Typedef Documentation

◆ Buffer

◆ InputIterator

Member Enumeration Documentation

◆ LengthFieldType

Constructor & Destructor Documentation

◆ OpaqueDataTuple() [1/2]

◆ OpaqueDataTuple() [2/2]

Member Function Documentation

◆ append() [1/4]

◆ append() [2/4]

◆ append() [3/4]

◆ append() [4/4]

◆ assign() [1/3]

◆ assign() [2/3]

◆ assign() [3/3]

◆ clear()

◆ equals()

◆ getData()

◆ getDataFieldSize()

◆ getLength()

◆ getLengthFieldType()

◆ getText()

◆ getTotalLength()

◆ operator!=()

◆ operator=()

◆ operator==()

◆ pack()

◆ unpack()