#include <libdhcp++.h>

Public Types
typedef std::map< unsigned short, Option::Factory * >	FactoryMap
	Map of factory functions. More...

Static Public Member Functions
static void	clearRuntimeOptionDefs ()
	Removes runtime option definitions. More...

static void	commitRuntimeOptionDefs ()
	Commits runtime option definitions. More...

static void	extendVendorOptions4 (isc::dhcp::OptionCollection &options)
	Extend vendor options from fused options in multiple OptionVendor or OptionVendorClass options and add respective suboptions or values. More...

static bool	fuseOptions4 (isc::dhcp::OptionCollection &options)
	Fuse multiple options with the same option code in long options (RFC3396). More...

static OptionDefinitionPtr	getLastResortOptionDef (const std::string &space, const std::string &name)
	Returns last resort option definition by space and option name. More...

static OptionDefinitionPtr	getLastResortOptionDef (const std::string &space, const uint16_t code)
	Returns last resort option definition by space and option code. More...

static OptionDefContainerPtr	getLastResortOptionDefs (const std::string &space)
	Returns last resort option definitions for specified option space name. More...

static OptionDefinitionPtr	getOptionDef (const std::string &space, const std::string &name)
	Return the definition of option having a specified name. More...

static OptionDefinitionPtr	getOptionDef (const std::string &space, const uint16_t code)
	Return the first option definition matching a particular option code. More...

static const OptionDefContainerPtr	getOptionDefs (const std::string &space)
	Returns collection of option definitions. More...

static OptionDefinitionPtr	getRuntimeOptionDef (const std::string &space, const std::string &name)
	Returns runtime (non-standard) option definition by space and option name. More...

static OptionDefinitionPtr	getRuntimeOptionDef (const std::string &space, const uint16_t code)
	Returns runtime (non-standard) option definition by space and option code. More...

static OptionDefContainerPtr	getRuntimeOptionDefs (const std::string &space)
	Returns runtime (non-standard) option definitions for specified option space name. More...

static OptionDefinitionPtr	getVendorOptionDef (const Option::Universe u, const uint32_t vendor_id, const std::string &name)
	Returns vendor option definition for a given vendor-id and option name. More...

static OptionDefinitionPtr	getVendorOptionDef (const Option::Universe u, const uint32_t vendor_id, const uint16_t code)
	Returns vendor option definition for a given vendor-id and code. More...

static const OptionDefContainerPtr	getVendorOptionDefs (Option::Universe u, const uint32_t vendor_id)
	Returns option definitions for given universe and vendor. More...

static isc::dhcp::OptionPtr	optionFactory (isc::dhcp::Option::Universe u, uint16_t type, const OptionBuffer &buf)
	Factory function to create instance of option. More...

static void	OptionFactoryRegister (Option::Universe u, uint16_t type, Option::Factory *factory)
	Registers factory method that produces options of specific option types. More...

static uint32_t	optionSpaceToVendorId (const std::string &option_space)
	Converts option space name to vendor id. More...

static void	packOptions4 (isc::util::OutputBuffer &buf, const isc::dhcp::OptionCollection &options, bool top=false, bool check=true)
	Stores DHCPv4 options in a buffer. More...

static void	packOptions6 (isc::util::OutputBuffer &buf, const isc::dhcp::OptionCollection &options)
	Stores DHCPv6 options in a buffer. More...

static void	revertRuntimeOptionDefs ()
	Reverts uncommitted changes to runtime option definitions. More...

static void	setRuntimeOptionDefs (const OptionDefSpaceContainer &defs)
	Copies option definitions created at runtime. More...

static bool	shouldDeferOptionUnpack (const std::string &space, const uint16_t code)
	Checks if an option unpacking has to be deferred. More...

static bool	splitOptions4 (isc::dhcp::OptionCollection &options, ScopedOptionsCopyContainer &scopedOptions, uint32_t used=0)
	Split long options in multiple options with the same option code (RFC3396). More...

static size_t	unpackOptions4 (const OptionBuffer &buf, const std::string &option_space, isc::dhcp::OptionCollection &options, std::list< uint16_t > &deferred, bool flexible_pad_end=false)
	Parses provided buffer as DHCPv4 options and creates Option objects. More...

static size_t	unpackOptions6 (const OptionBuffer &buf, const std::string &option_space, isc::dhcp::OptionCollection &options, size_t relay_msg_offset=0, size_t relay_msg_len=0)
	Parses provided buffer as DHCPv6 options and creates Option objects. More...

static size_t	unpackVendorOptions4 (const uint32_t vendor_id, const OptionBuffer &buf, isc::dhcp::OptionCollection &options)
	Parses provided buffer as DHCPv4 vendor options and creates Option objects. More...

static size_t	unpackVendorOptions6 (const uint32_t vendor_id, const OptionBuffer &buf, isc::dhcp::OptionCollection &options)
	Parses provided buffer as DHCPv6 vendor options and creates Option objects. More...

Detailed Description

Definition at line 52 of file libdhcp++.h.

Member Typedef Documentation

◆ FactoryMap

typedef std::map<unsigned short, Option::Factory*> isc::dhcp::LibDHCP::FactoryMap

Map of factory functions.

Definition at line 57 of file libdhcp++.h.

Member Function Documentation

◆ clearRuntimeOptionDefs()

void LibDHCP::clearRuntimeOptionDefs ( )

static

Removes runtime option definitions.

Definition at line 230 of file libdhcp++.cc.

◆ commitRuntimeOptionDefs()

void LibDHCP::commitRuntimeOptionDefs ( )

static

Commits runtime option definitions.

Definition at line 240 of file libdhcp++.cc.

◆ extendVendorOptions4()

void LibDHCP::extendVendorOptions4 ( isc::dhcp::OptionCollection & options )

static

Extend vendor options from fused options in multiple OptionVendor or OptionVendorClass options and add respective suboptions or values.

Parameters

options The option container which needs to be updated with extended vendor options.

Definition at line 802 of file libdhcp++.cc.

Referenced by isc::dhcp::Pkt4::unpack().

◆ fuseOptions4()

bool LibDHCP::fuseOptions4 ( isc::dhcp::OptionCollection & options )

static

Fuse multiple options with the same option code in long options (RFC3396).

Parameters

options The option container which needs to be updated with fused options.

Returns: True if any option has been fused, false otherwise.

Definition at line 623 of file libdhcp++.cc.

References isc::data::copy().

Referenced by isc::dhcp::Pkt4::unpack().

Here is the call graph for this function:

◆ getLastResortOptionDef() [1/2]

OptionDefinitionPtr LibDHCP::getLastResortOptionDef	(	const std::string &	space,
		const std::string &	name
	)

static

Returns last resort option definition by space and option name.

Parameters

space	Option space name.
name	Option name.

Returns: Pointer to option definition or NULL if it doesn't exist.

Definition at line 257 of file libdhcp++.cc.

◆ getLastResortOptionDef() [2/2]

OptionDefinitionPtr LibDHCP::getLastResortOptionDef	(	const std::string &	space,
		const uint16_t	code
	)

static

Returns last resort option definition by space and option code.

Parameters

space	Option space name.
code	Option code.

Returns: Pointer to option definition or NULL if it doesn't exist.

Definition at line 245 of file libdhcp++.cc.

Referenced by isc::dhcp::CfgOption::createDescriptorOption(), isc::dhcp::Dhcpv4Srv::deferredUnpack(), isc::dhcp::OptionDataParser::findOptionDefinition(), and isc::dhcp::CfgOption::toElementWithMetadata().

◆ getLastResortOptionDefs()

OptionDefContainerPtr LibDHCP::getLastResortOptionDefs ( const std::string & space )

static

Returns last resort option definitions for specified option space name.

Parameters

space Option space name.

Returns: Pointer to the container holding option definitions or NULL.

Definition at line 269 of file libdhcp++.cc.

References DHCP4_OPTION_SPACE, LAST_RESORT_V4_OPTION_SPACE, and null_option_def_container_().

Here is the call graph for this function:

◆ getOptionDef() [1/2]

OptionDefinitionPtr LibDHCP::getOptionDef	(	const std::string &	space,
		const std::string &	name
	)

static

Return the definition of option having a specified name.

Parameters

space	option space.
name	Option name.

Returns: Pointer to the option definition or NULL pointer if option definition has not been found.

Definition at line 136 of file libdhcp++.cc.

◆ getOptionDef() [2/2]

OptionDefinitionPtr LibDHCP::getOptionDef	(	const std::string &	space,
		const uint16_t	code
	)

static

Return the first option definition matching a particular option code.

Parameters

space	option space.
code	option code.

Returns: reference to an option definition being requested or NULL pointer if option definition has not been found.

Definition at line 124 of file libdhcp++.cc.

Referenced by isc::dhcp::CfgOption::createDescriptorOption(), isc::dhcp::Dhcpv4Srv::deferredUnpack(), isc::dhcp::OptionDataParser::findOptionDefinition(), isc::dhcp::CfgOption::toElementWithMetadata(), and isc::dhcp::LeaseMgr::upgradeLease4ExtendedInfo().

◆ getOptionDefs()

const OptionDefContainerPtr LibDHCP::getOptionDefs ( const std::string & space )

static

Returns collection of option definitions.

This method returns a collection of option definitions for a specified option space.

Parameters

space Option space.

Returns: Pointer to a collection of option definitions.

Definition at line 97 of file libdhcp++.cc.

References null_option_def_container_().

Here is the call graph for this function:

◆ getRuntimeOptionDef() [1/2]

OptionDefinitionPtr LibDHCP::getRuntimeOptionDef	(	const std::string &	space,
		const std::string &	name
	)

static

Returns runtime (non-standard) option definition by space and option name.

Parameters

space	Option space name.
name	Option name.

Returns: Pointer to option definition or NULL if it doesn't exist.

Definition at line 199 of file libdhcp++.cc.

◆ getRuntimeOptionDef() [2/2]

OptionDefinitionPtr LibDHCP::getRuntimeOptionDef	(	const std::string &	space,
		const uint16_t	code
	)

static

Returns runtime (non-standard) option definition by space and option code.

Parameters

space	Option space name.
code	Option code.

Returns: Pointer to option definition or NULL if it doesn't exist.

Definition at line 187 of file libdhcp++.cc.

Referenced by isc::dhcp::Dhcpv4Srv::deferredUnpack(), isc::dhcp::OptionDataParser::findOptionDefinition(), and isc::dhcp::CfgOption::toElementWithMetadata().

◆ getRuntimeOptionDefs()

OptionDefContainerPtr LibDHCP::getRuntimeOptionDefs ( const std::string & space )

static

Returns runtime (non-standard) option definitions for specified option space name.

Parameters

space Option space name.

Returns: Pointer to the container holding option definitions or NULL.

Definition at line 211 of file libdhcp++.cc.

◆ getVendorOptionDef() [1/2]

OptionDefinitionPtr LibDHCP::getVendorOptionDef	(	const Option::Universe	u,
		const uint32_t	vendor_id,
		const std::string &	name
	)

static

Returns vendor option definition for a given vendor-id and option name.

Parameters

u	Universe (V4 or V6)
vendor_id	Enterprise-id for a given vendor
name	Option name.

Returns: A pointer to an option definition or NULL pointer if no option definition found.

Definition at line 148 of file libdhcp++.cc.

◆ getVendorOptionDef() [2/2]

OptionDefinitionPtr LibDHCP::getVendorOptionDef	(	const Option::Universe	u,
		const uint32_t	vendor_id,
		const uint16_t	code
	)

static

Returns vendor option definition for a given vendor-id and code.

Parameters

u	universe (V4 or V6)
vendor_id	enterprise-id for a given vendor
code	option code

Returns: reference to an option definition being requested or NULL pointer if option definition has not been found.

Definition at line 166 of file libdhcp++.cc.

Referenced by isc::dhcp::CfgOption::createDescriptorOption(), isc::dhcp::OptionDataParser::findOptionDefinition(), and isc::dhcp::CfgOption::toElementWithMetadata().

◆ getVendorOptionDefs()

const OptionDefContainerPtr LibDHCP::getVendorOptionDefs	(	Option::Universe	u,
		const uint32_t	vendor_id
	)

static

Returns option definitions for given universe and vendor.

Parameters

u	option universe
vendor_id	enterprise-id of a given vendor

Returns: a container for a given vendor (or NULL if no option definitions are defined)

Definition at line 107 of file libdhcp++.cc.

References DOCSIS3_V4_OPTION_SPACE, DOCSIS3_V6_OPTION_SPACE, and VENDOR_ID_CABLE_LABS.

◆ optionFactory()

OptionPtr LibDHCP::optionFactory	(	isc::dhcp::Option::Universe	u,
		uint16_t	type,
		const OptionBuffer &	buf
	)

static

Factory function to create instance of option.

Factory method creates instance of specified option. The option to be created has to have corresponding factory function registered with LibDHCP::OptionFactoryRegister.

Parameters

u	universe of the option (V4 or V6)
type	option-type
buf	option-buffer

Returns: instance of option.

Exceptions

isc::InvalidOperation if there is no factory function registered for the specified option type.

Definition at line 285 of file libdhcp++.cc.

References isc_throw.

◆ OptionFactoryRegister()

void LibDHCP::OptionFactoryRegister	(	Option::Universe	u,
		uint16_t	type,
		Option::Factory *	factory
	)

static

Registers factory method that produces options of specific option types.

Exceptions

isc::BadValue if provided the type is already registered, has too large a value or an invalid universe is specified.

Parameters

u	universe of the option (V4 or V6)
type	option-type
factory	function pointer

Definition at line 1243 of file libdhcp++.cc.

References isc_throw.

◆ optionSpaceToVendorId()

uint32_t LibDHCP::optionSpaceToVendorId ( const std::string & option_space )

static

Converts option space name to vendor id.

If the option space name is specified in the following format: "vendor-X" where X is an uint32_t number, it is assumed to be a vendor space and the uint32_t number is returned by this function. If the option space name is invalid this method will return 0, which is not a valid vendor-id, to signal an error.

Todo:: remove this function once when the conversion is dealt by the appropriate functions returning options by option space names.

Parameters

option_space Option space name.

Returns: vendor id.

Definition at line 1296 of file libdhcp++.cc.

Referenced by isc::dhcp::CfgOption::add(), isc::dhcp::CfgOption::createDescriptorOption(), isc::dhcp::OptionDataParser::findOptionDefinition(), and isc::dhcp::CfgOption::getAllCombined().

◆ packOptions4()

void LibDHCP::packOptions4	(	isc::util::OutputBuffer &	buf,
		const isc::dhcp::OptionCollection &	options,
		bool	top = `false`,
		bool	check = `true`
	)

static

Stores DHCPv4 options in a buffer.

Stores all options defined in options containers in a on-wire format in output buffer specified by buf.

May throw different exceptions if option assembly fails. There may be different reasons (option too large, option malformed, too many options etc.)

This is v4 specific version, which stores DHCP message type first, and the Relay Agent Information option and END options last. This function is initially called to pack the options for a packet in Pkt4::pack(). That call leads to it being called recursively in Option::packOptions(). Thus the logic used to output the message type should only be executed by the top-most. This is governed by the parameter top, below.

Parameters

buf	output buffer (assembled options will be stored here)
options	collection of options to store to
top	indicates if this is the first call to pack the options. When true logic to emit the message type first is executed. It defaults to false.
check	indicates if the code should be more flexible with PAD and END options. If true, PAD and END options will not be parsed. This is useful for partial parsing and slightly broken packets.

Definition at line 1010 of file libdhcp++.cc.

References isc::dhcp::DHO_DHCP_AGENT_OPTIONS, isc::dhcp::DHO_DHCP_MESSAGE_TYPE, and isc::dhcp::DHO_END.

Referenced by isc::dhcp::Pkt4::pack(), and isc::dhcp::Option::packOptions().

◆ packOptions6()

void LibDHCP::packOptions6	(	isc::util::OutputBuffer &	buf,
		const isc::dhcp::OptionCollection &	options
	)

static

Stores DHCPv6 options in a buffer.

Stores all options defined in options containers in a on-wire format in output buffer specified by buf.

May throw different exceptions if option assembly fails. There may be different reasons (option too large, option malformed, too many options etc.)

Currently there's no special logic in it. Options are stored in the order of their option codes.

Parameters

buf	output buffer (assembled options will be stored here)
options	collection of options to store to

Definition at line 1236 of file libdhcp++.cc.

Referenced by isc::dhcp::Option::packOptions(), isc::dhcp::Pkt6::packUDP(), and isc::dhcp::AllocEngine::updateLease6ExtendedInfo().

◆ revertRuntimeOptionDefs()

void LibDHCP::revertRuntimeOptionDefs ( )

static

Reverts uncommitted changes to runtime option definitions.

Definition at line 235 of file libdhcp++.cc.

◆ setRuntimeOptionDefs()

void LibDHCP::setRuntimeOptionDefs ( const OptionDefSpaceContainer & defs )

static

Copies option definitions created at runtime.

Copied option definitions will be used as "runtime" option definitions. A typical use case is to set option definitions specified by the user in the server configuration. These option definitions should be removed or replaced with new option definitions upon reconfiguration.

Parameters

defs	Const reference to a container holding option definitions grouped by option spaces.

Definition at line 216 of file libdhcp++.cc.

References isc::dhcp::OptionDefSpaceContainer::addItem(), isc::dhcp::OptionSpaceContainer< ContainerType, ItemType, Selector >::getItems(), and isc::dhcp::OptionSpaceContainer< ContainerType, ItemType, Selector >::getOptionSpaceNames().

Referenced by isc::dhcp::OptionDefListParser::parse().

Here is the call graph for this function:

◆ shouldDeferOptionUnpack()

bool LibDHCP::shouldDeferOptionUnpack	(	const std::string &	space,
		const uint16_t	code
	)

static

Checks if an option unpacking has to be deferred.

DHCPv4 option 43 and 224-254 unpacking is done after classification.

Parameters

space	Option space name.
code	Option code.

Returns: True if option processing should be deferred.

Definition at line 278 of file libdhcp++.cc.

References DHCP4_OPTION_SPACE, and isc::dhcp::DHO_VENDOR_ENCAPSULATED_OPTIONS.

◆ splitOptions4()

bool LibDHCP::splitOptions4	(	isc::dhcp::OptionCollection &	options,
		ScopedOptionsCopyContainer &	scopedOptions,
		uint32_t	used = `0`
	)

static

Split long options in multiple options with the same option code (RFC3396).

Parameters

options	The option container which needs to be updated with split options.
scopedOptions	temporary storage for options that are going to be split. See ScopedPktOptionsCopy for explanation.
used	The size of the buffer that has already been used by the parent option effectively shrinking the maximum supported length for each options in the container.

Returns: True if any option has been split, false otherwise.

Definition at line 1055 of file libdhcp++.cc.

References isc::data::copy(), isc::util::OutputBuffer::getData(), isc::util::OutputBuffer::getLength(), and isc_throw.

Referenced by isc::dhcp::Pkt4::pack().

Here is the call graph for this function:

◆ unpackOptions4()

size_t LibDHCP::unpackOptions4	(	const OptionBuffer &	buf,
		const std::string &	option_space,
		isc::dhcp::OptionCollection &	options,
		std::list< uint16_t > &	deferred,
		bool	flexible_pad_end = `false`
	)

static

Parses provided buffer as DHCPv4 options and creates Option objects.

Parses provided buffer and stores created Option objects in options container.

Parameters

buf	Buffer to be parsed.
option_space	A name of the option space which holds definitions to be used to parse options in the packets.
options	Reference to option container. Options will be put here.
deferred	Reference to an option code list. Options which processing is deferred will be put here.
flexible_pad_end	Parse options 0 and 255 as PAD and END when they are not defined in the option space.

Returns: offset to the first byte after the last successfully parsed option or the offset of the DHO_END option type.

The unpackOptions6 note applies too.

Definition at line 457 of file libdhcp++.cc.

References DHCP4_OPTION_SPACE, isc::dhcp::DHO_END, isc::dhcp::DHO_HOST_NAME, isc::dhcp::DHO_PAD, isc::dhcp::DHO_VIVCO_SUBOPTIONS, isc::dhcp::DHO_VIVSO_SUBOPTIONS, isc_throw, and isc_throw_assert.

Referenced by isc::dhcp::Pkt4::unpack(), and isc::dhcp::Option::unpackOptions().

◆ unpackOptions6()

size_t LibDHCP::unpackOptions6	(	const OptionBuffer &	buf,
		const std::string &	option_space,
		isc::dhcp::OptionCollection &	options,
		size_t *	relay_msg_offset = `0`,
		size_t *	relay_msg_len = `0`
	)

static

Parses provided buffer as DHCPv6 options and creates Option objects.

Parses provided buffer and stores created Option objects in options container. The last two parameters are optional and are used in relay parsing. If they are specified, relay-msg option is not created, but rather those two parameters are specified to point out where the relay-msg option resides and what is its length. This is a performance optimization that avoids unnecessary copying of potentially large relay-msg option. It is not used for anything, except in the next iteration its content will be treated as buffer to be parsed.

Parameters

buf	Buffer to be parsed.
option_space	A name of the option space which holds definitions to be used to parse options in the packets.
options	Reference to option container. Options will be put here.
relay_msg_offset	reference to a size_t structure. If specified, offset to beginning of relay_msg option will be stored in it.
relay_msg_len	reference to a size_t structure. If specified, length of the relay_msg option will be stored in it.

Returns: offset to the first byte after the last successfully parsed option

Note: This function throws when an option type is defined more than once, and it calls option building routines which can throw. Partial parsing does not throw: it is the responsibility of the caller to handle this condition.

Definition at line 309 of file libdhcp++.cc.

References D6O_RELAY_MSG, D6O_VENDOR_OPTS, isc_throw, isc_throw_assert, and isc::util::readUint16().

Referenced by isc::dhcp::Pkt6::unpackMsg(), isc::dhcp::Option::unpackOptions(), isc::dhcp::Pkt6::unpackRelayMsg(), and isc::dhcp::LeaseMgr::upgradeLease6ExtendedInfo().

Here is the call graph for this function:

◆ unpackVendorOptions4()

size_t LibDHCP::unpackVendorOptions4	(	const uint32_t	vendor_id,
		const OptionBuffer &	buf,
		isc::dhcp::OptionCollection &	options
	)

static

Parses provided buffer as DHCPv4 vendor options and creates Option objects.

Parses provided buffer and stores created Option objects in options container.

Parameters

vendor_id	enterprise-id of the vendor
buf	Buffer to be parsed.
options	Reference to option container. Suboptions will be put here.

Returns: offset to the first byte after the last successfully parsed suboption

The unpackVendorOptions6 note applies

Definition at line 904 of file libdhcp++.cc.

References isc_throw, and isc_throw_assert.

Referenced by isc::dhcp::OptionVendor::unpack().

◆ unpackVendorOptions6()

size_t LibDHCP::unpackVendorOptions6	(	const uint32_t	vendor_id,
		const OptionBuffer &	buf,
		isc::dhcp::OptionCollection &	options
	)

static

Parses provided buffer as DHCPv6 vendor options and creates Option objects.

Parses provided buffer and stores created Option objects in options container.

Parameters

vendor_id	enterprise-id of the vendor
buf	Buffer to be parsed.
options	Reference to option container. Suboptions will be put here.

Returns: offset to the first byte after the last successfully parsed suboption

Note: unpackVendorOptions6 throws when it fails to parse a suboption so the return value is currently always the buffer length.

Definition at line 808 of file libdhcp++.cc.

References isc_throw, isc_throw_assert, and isc::util::readUint16().

Referenced by isc::dhcp::OptionVendor::unpack().

Here is the call graph for this function:

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

Public Types

Static Public Member Functions

Detailed Description

Member Typedef Documentation

◆ FactoryMap

Member Function Documentation

◆ clearRuntimeOptionDefs()

◆ commitRuntimeOptionDefs()

◆ extendVendorOptions4()

◆ fuseOptions4()

◆ getLastResortOptionDef() [1/2]

◆ getLastResortOptionDef() [2/2]

◆ getLastResortOptionDefs()

◆ getOptionDef() [1/2]

◆ getOptionDef() [2/2]

◆ getOptionDefs()

◆ getRuntimeOptionDef() [1/2]

◆ getRuntimeOptionDef() [2/2]

◆ getRuntimeOptionDefs()

◆ getVendorOptionDef() [1/2]

◆ getVendorOptionDef() [2/2]

◆ getVendorOptionDefs()

◆ optionFactory()

◆ OptionFactoryRegister()

◆ optionSpaceToVendorId()

◆ packOptions4()

◆ packOptions6()

◆ revertRuntimeOptionDefs()

◆ setRuntimeOptionDefs()

◆ shouldDeferOptionUnpack()

◆ splitOptions4()

◆ unpackOptions4()

◆ unpackOptions6()

◆ unpackVendorOptions4()

◆ unpackVendorOptions6()