Represents option data configuration for the DHCP server. More...

#include <cfg_option.h>

Inheritance diagram for isc::dhcp::CfgOption:

Public Member Functions
	CfgOption ()
	default constructor More...

void	add (const OptionPtr &option, const bool persistent, const std::string &option_space, const uint64_t id=0)
	Adds instance of the option to the configuration. More...

void	add (const OptionDescriptor &desc, const std::string &option_space)
	A variant of the CfgOption::add method which takes option descriptor as an argument. More...

void	copyTo (CfgOption &other) const
	Copies this configuration to another configuration. More...

void	createOptions (CfgOptionDefPtr cfg_def)
	Re-create the option in each descriptor based on given definitions. More...

size_t	del (const std::string &option_space, const uint16_t option_code)
	Deletes option for the specified option space and option code. More...

size_t	del (const uint32_t vendor_id, const uint16_t option_code)
	Deletes vendor option for the specified vendor id. More...

size_t	del (const uint64_t id)
	Deletes all options having a given database id. More...

bool	empty () const
	Indicates the object is empty. More...

void	encapsulate ()
	Appends encapsulated options to top-level options. More...

template<typename Selector >
OptionDescriptor	get (const Selector &key, const uint16_t option_code) const
	Returns option for the specified key and option code. More...

OptionContainerPtr	getAll (const std::string &option_space) const
	Returns all options for the specified option space. More...

OptionContainerPtr	getAll (const uint32_t vendor_id) const
	Returns vendor options for the specified vendor id. More...

std::list< std::string >	getOptionSpaceNames () const
	Returns a list of configured option space names. More...

std::list< uint32_t >	getVendorIds () const
	Returns a list of all configured vendor identifiers. More...

std::list< std::string >	getVendorIdsSpaceNames () const
	Returns a list of option space names for configured vendor ids. More...

void	merge (CfgOptionDefPtr cfg_def, CfgOption &other)
	Merges another option configuration into this one. More...

void	mergeTo (CfgOption &other) const
	Merges this configuration to another configuration. More...

void	replace (const OptionDescriptor &desc, const std::string &option_space)
	Replaces the instance of an option within this collection. More...

virtual isc::data::ElementPtr	toElement () const
	Unparse a configuration object. More...

isc::data::ElementPtr	toElementWithMetadata (const bool include_metadata) const
	Unparse a configuration object with optionally including the metadata. More...

Methods and operators used for comparing objects.
bool	equals (const CfgOption &other) const
	Check if configuration is equal to other configuration. More...

bool	operator== (const CfgOption &other) const
	Equality operator. More...

bool	operator!= (const CfgOption &other) const
	Inequality operator. More...

Public Member Functions inherited from isc::data::CfgToElement
virtual	~CfgToElement ()
	Destructor. More...

Static Public Member Functions
static bool	createDescriptorOption (CfgOptionDefPtr cfg_def, const std::string &space, OptionDescriptor &opt_desc)
	Creates an option descriptor's option based on a set of option defs. More...

Detailed Description

Represents option data configuration for the DHCP server.

This class holds a collection of options to be sent to a DHCP client. Options are grouped by the option space or vendor identifier (for vendor options).

The server configuration allows for specifying two distinct collections of options: global options and per-subnet options in which some options may overlap.

The collection of global options specify options being sent to the client belonging to any subnets, i.e. global options are "inherited" by all subnets.

The per-subnet options are configured for a particular subnet and are sent to clients which belong to this subnet. The values of the options specified for a particular subnet override the values of the global options.

This class represents a single collection of options (either global or per-subnet). Each subnet holds its own object of the CfgOption type. The CfgMgr holds a CfgOption object representing global options.

Note that having a separate copy of the CfgOption to represent global options is useful when the client requests stateless configuration from the DHCP server and no subnet is selected for this client. This client will only receive global options.

Definition at line 314 of file cfg_option.h.

Constructor & Destructor Documentation

isc::dhcp::CfgOption::CfgOption ( )

default constructor

Definition at line 52 of file cfg_option.cc.

Member Function Documentation

void isc::dhcp::CfgOption::add	(	const OptionPtr &	option,
		const bool	persistent,
		const std::string &	option_space,
		const uint64_t	id = `0`
	)

Adds instance of the option to the configuration.

There are two types of options which may be passed to this method:

vendor options
non-vendor options

The non-vendor options are grouped by the name of the option space (specified in textual format). The vendor options are grouped by the vendor identifier, which is a 32-bit unsigned integer value.

In order to add new vendor option to the list the option space name (last argument of this method) should be specified as "vendor-X" where "X" is a 32-bit unsigned integer, e.g. "vendor-1234". Options for which the option_space argument doesn't follow this format are added as non-vendor options.

Parameters

option	Pointer to the option being added.
persistent	Boolean value which specifies if the option should be sent to the client regardless if requested (true), or nor (false)
option_space	Option space name.
id	Optional database id to be associated with the option.

Exceptions

isc::BadValue if the option space is invalid.

Definition at line 67 of file cfg_option.cc.

References isc::data::BaseStampedElement::setId().

Here is the call graph for this function:

void isc::dhcp::CfgOption::add	(	const OptionDescriptor &	desc,
		const std::string &	option_space
	)

A variant of the CfgOption::add method which takes option descriptor as an argument.

Parameters

desc	Option descriptor holding option instance and other parameters pertaining to the option.
option_space	Option space name.

Exceptions

isc::BadValue if the option space is invalid.

Definition at line 78 of file cfg_option.cc.

References isc_throw, and isc::dhcp::OptionDescriptor::option_.

void isc::dhcp::CfgOption::copyTo ( CfgOption & other ) const

Copies this configuration to another configuration.

This method copies options configuration to another object.

Parameters

[out] other An object to copy the configuration to.

Definition at line 240 of file cfg_option.cc.

References isc::dhcp::OptionSpaceContainer< ContainerType, ItemType, Selector >::clearItems().

Referenced by merge().

Here is the call graph for this function:

bool isc::dhcp::CfgOption::createDescriptorOption	(	CfgOptionDefPtr	cfg_def,
		const std::string &	space,
		OptionDescriptor &	opt_desc
	)

static

Creates an option descriptor's option based on a set of option defs.

This function's primary use is to create definition specific options for option descriptors fetched from a configuration backend, as part of a configuration merge.

Given an OptionDescriptor whose option_ member contains a generic option (i.e has a code and/or data), this function will attempt to find a matching definition and then use that definition's factory to create an option instance specific to that definition. It will then replace the descriptor's generic option with the specific option.

Three sources of definitions are searched, in the following order:

Standard option definitions (LIBDHCP::getOptionDef))
Vendor option definitions (LIBDHCP::getVendorOptionDef))
User specified definitions passed in via cfg_def parameter.

The code will use the first matching definition found. It then applies the following rules:

If no definition is found but the descriptor conveys a non-empty formatted value, throw an error.
If not definition is found and there is no formatted value, return This leaves intact the generic option in the descriptor.
If a definition is found and there is no formatted value, pass the descriptor's generic option's data into the definition's factory. Replace the descriptor's option with the newly created option.
If a definition is found and there is a formatted value, split the value into vector of values and pass that into the definition's factory. Replace the descriptor's option with the newly created option.

Parameters

cfg_def	the user specified definitions to use
space	the option space name of the option
opt_desc	OptionDescriptor describing the option.

Returns: True if the descriptor's option instance was replaced.

Exceptions

InvalidOperation if the descriptor conveys a formatted value and there is no definition matching the option code in the given space, or if the definition factory invocation fails.

Definition at line 167 of file cfg_option.cc.

References DHCP4_OPTION_SPACE, DHCP6_OPTION_SPACE, isc::dhcp::OptionDescriptor::formatted_value_, isc_throw, isc::dhcp::OptionDescriptor::option_, and isc::Exception::what().

Here is the call graph for this function:

void isc::dhcp::CfgOption::createOptions ( CfgOptionDefPtr cfg_def )

Re-create the option in each descriptor based on given definitions.

Invokes createDescriptorOption() on each option descriptor in each option space, passing in the given dictionary of option definitions. If the descriptor's option is re-created, then the descriptor is updated by calling replace().

Parameters

cfg_def set of of user-defined option definitions to use when creating option instances.

Definition at line 152 of file cfg_option.cc.

Referenced by merge().

size_t isc::dhcp::CfgOption::del	(	const std::string &	option_space,
		const uint16_t	option_code
	)

Deletes option for the specified option space and option code.

If the option is encapsulated within some non top level option space, it is also deleted from all option instances encapsulating this option space.

Parameters

option_space	Option space name.
option_code	Code of the option to be returned.

Returns: Number of deleted options.

Definition at line 340 of file cfg_option.cc.

References DHCP4_OPTION_SPACE, and DHCP6_OPTION_SPACE.

size_t isc::dhcp::CfgOption::del	(	const uint32_t	vendor_id,
		const uint16_t	option_code
	)

Deletes vendor option for the specified vendor id.

Parameters

vendor_id	Vendor identifier.
option_code	Option code.

Returns: Number of deleted options.

Definition at line 377 of file cfg_option.cc.

size_t isc::dhcp::CfgOption::del ( const uint64_t id )

Deletes all options having a given database id.

Note that there are cases when there will be multiple options having the same id (typically id of 0). When configuration backend is in use it sets the unique ids from the database. In cases when the configuration backend is not used, the ids default to 0. Passing the id of 0 would result in deleting all options that were not added via the database.

Both regular and vendor specific options are deleted with this method.

This method internally calls encapsulate() after deleting options having the given id.

Parameters

id	Identifier of the options to be deleted.

Returns: Number of deleted options. Note that if a single option instance is encapsulated by multiple options it adds 1 to the number of deleted options even though the same instance is deleted from multiple higher level options.

Definition at line 390 of file cfg_option.cc.

bool isc::dhcp::CfgOption::empty ( ) const

Indicates the object is empty.

Returns: true when the object is empty

Definition at line 56 of file cfg_option.cc.

void isc::dhcp::CfgOption::encapsulate ( )

Appends encapsulated options to top-level options.

This method iterates over the top-level options (from "dhcp4" and "dhcp6" option space) and checks which option spaces these options encapsulate. For each encapsulated option space, the options from this option space are appended to top-level options.

Definition at line 248 of file cfg_option.cc.

References DHCP4_OPTION_SPACE, and DHCP6_OPTION_SPACE.

bool isc::dhcp::CfgOption::equals ( const CfgOption & other ) const

Check if configuration is equal to other configuration.

Parameters

other An object holding configuration to compare to.

Returns: true if configurations are equal, false otherwise.

Definition at line 61 of file cfg_option.cc.

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

template<typename Selector >

OptionDescriptor isc::dhcp::CfgOption::get	(	const Selector &	key,
		const uint16_t	option_code
	)		const

inline

Returns option for the specified key and option code.

The key should be a string, in which case it specifies an option space name, or an uint32_t value, in which case it specifies a vendor identifier.

Note: If there are multiple options with the same key, only one will be returned. No indication will be given of the presence of others, and the instance returned is not determinable.

Parameters

key	Option space name or vendor identifier.
option_code	Code of the option to be returned.

Template Parameters

Selector one of: std::string or uint32_t

Returns: Descriptor of the option. If option hasn't been found, the descriptor holds NULL option.

Definition at line 544 of file cfg_option.h.

References getAll().

Here is the call graph for this function:

OptionContainerPtr isc::dhcp::CfgOption::getAll ( const std::string & option_space ) const

Returns all options for the specified option space.

This method will not return vendor options, i.e. having option space name in the format of "vendor-X" where X is 32-bit unsigned integer. See getAll(uint32_t) for vendor options.

Parameters

option_space Name of the option space.

Returns: Pointer to the container holding returned options. This container is empty if no options have been found.

Definition at line 330 of file cfg_option.cc.

Referenced by get().

OptionContainerPtr isc::dhcp::CfgOption::getAll ( const uint32_t vendor_id ) const

Returns vendor options for the specified vendor id.

Parameters

vendor_id Vendor id for which options are to be returned.

Returns: Pointer to the container holding returned options. This container is empty if no options have been found.

Definition at line 335 of file cfg_option.cc.

std::list<std::string> isc::dhcp::CfgOption::getOptionSpaceNames ( ) const

inline

Returns a list of configured option space names.

The returned option space names exclude vendor option spaces, such as "vendor-1234". These are returned by the getVendorIdsSpaceNames.

Returns: List comprising option space names.

Definition at line 613 of file cfg_option.h.

References isc::dhcp::OptionSpaceContainer< ContainerType, ItemType, Selector >::getOptionSpaceNames().

Here is the call graph for this function:

std::list<uint32_t> isc::dhcp::CfgOption::getVendorIds ( ) const

inline

Returns a list of all configured vendor identifiers.

Definition at line 618 of file cfg_option.h.

References isc::dhcp::OptionSpaceContainer< ContainerType, ItemType, Selector >::getOptionSpaceNames().

Here is the call graph for this function:

std::list< std::string > isc::dhcp::CfgOption::getVendorIdsSpaceNames ( ) const

Returns a list of option space names for configured vendor ids.

For each vendor-id the option space name returned is constructed as "vendor-XYZ" where XYZ is a uint32_t value without leading zeros.

Returns: List comprising option space names for vendor options.

Definition at line 122 of file cfg_option.cc.

void isc::dhcp::CfgOption::merge	(	CfgOptionDefPtr	cfg_def,
		CfgOption &	other
	)

Merges another option configuration into this one.

This method calls mergeTo() to add this configuration's options into other (skipping any duplicates). Next it calls createDescriptorOption() for each option descriptor in the merged set. This (re)-creates each descriptor's option based on the merged set of opt definitions. Finally, it calls copyTo() to overwrite this configuration's options with the merged set in other.

Warning: The merge operation will affect the other configuration. Therefore, the caller must not rely on the data held in the other object after the call to merge. Also, the data held in other must not be modified after the call to merge because it may affect the merged configuration.

Parameters

cfg_def	set of of user-defined option definitions to use when merging.
other	option configuration to merge in.

Definition at line 137 of file cfg_option.cc.

References copyTo(), and createOptions().

Here is the call graph for this function:

void isc::dhcp::CfgOption::mergeTo ( CfgOption & other ) const

Merges this configuration to another configuration.

This method iterates over the configuration items held in this configuration and copies them to the configuration specified as a parameter. If an item exists in the destination it is not copied.

Parameters

[out] other Configuration object to merge to.

Definition at line 232 of file cfg_option.cc.

bool isc::dhcp::CfgOption::operator!= ( const CfgOption & other ) const

inline

Inequality operator.

Parameters

other An object holding configuration to compare to.

Returns: true if configurations are unequal, false otherwise.

Definition at line 349 of file cfg_option.h.

References equals().

Here is the call graph for this function:

bool isc::dhcp::CfgOption::operator== ( const CfgOption & other ) const

inline

Equality operator.

Parameters

other An object holding configuration to compare to.

Returns: true if configurations are equal, false otherwise.

Definition at line 340 of file cfg_option.h.

References equals().

Here is the call graph for this function:

void isc::dhcp::CfgOption::replace	(	const OptionDescriptor &	desc,
		const std::string &	option_space
	)

Replaces the instance of an option within this collection.

This method locates the option within the given space and replaces it with a copy of the given descriptor. This effectively updates the contents without altering the container indexing.

Parameters

desc	Option descriptor holding option instance and other parameters pertaining to the option.
option_space	Option space name.

Exceptions

isc::BadValue if the descriptor's option instance is null, if space is invalid, or if the option does not already exist in the given space.

Definition at line 96 of file cfg_option.cc.

References isc_throw, and isc::dhcp::OptionDescriptor::option_.

ElementPtr isc::dhcp::CfgOption::toElement ( ) const

virtual

Unparse a configuration object.

Returns: a pointer to unparsed configuration

Implements isc::data::CfgToElement.

Definition at line 426 of file cfg_option.cc.

ElementPtr isc::dhcp::CfgOption::toElementWithMetadata ( const bool include_metadata ) const

Unparse a configuration object with optionally including the metadata.

Parameters

include_metadata boolean value indicating if the metadata should be included (if true) or not (if false).

Returns: A pointer to the unparsed configuration.

Definition at line 431 of file cfg_option.cc.

References isc::data::Element::create(), isc::data::Element::createList(), isc::data::Element::createMap(), and isc::util::encode::encodeHex().

Here is the call graph for this function:

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

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation