Kea 2.7.0
isc::dhcp::CfgOption Class Reference

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
 
bool empty () const
 Indicates the object is empty.
 
- Public Member Functions inherited from isc::data::CfgToElement
virtual ~CfgToElement ()
 Destructor.
 

Methods and operators used for comparing objects.

bool equals (const CfgOption &other) const
 Check if configuration is equal to other configuration.
 
bool operator== (const CfgOption &other) const
 Equality operator.
 
bool operator!= (const CfgOption &other) const
 Inequality operator.
 
void add (const OptionPtr &option, const bool persistent, const bool cancelled, const std::string &option_space, const uint64_t id=0)
 Adds instance of the option to the configuration.
 
void add (const OptionDescriptor &desc, const std::string &option_space)
 A variant of the CfgOption::add method which takes option descriptor as an argument.
 
void replace (const OptionDescriptor &desc, const std::string &option_space)
 Replaces the instance of an option within this collection.
 
void merge (CfgOptionDefPtr cfg_def, CfgOption &other)
 Merges another option configuration into this one.
 
void createOptions (CfgOptionDefPtr cfg_def)
 Re-create the option in each descriptor based on given definitions.
 
void mergeTo (CfgOption &other) const
 Merges this configuration to another configuration.
 
void copyTo (CfgOption &other) const
 Copies this configuration to another configuration.
 
void encapsulate ()
 Appends encapsulated options to top-level options.
 
bool isEncapsulated () const
 Checks if options have been encapsulated.
 
OptionContainerPtr getAll (const std::string &option_space) const
 Returns all options for the specified option space.
 
OptionContainerPtr getAll (const uint32_t vendor_id) const
 Returns vendor options for the specified vendor id.
 
OptionContainerPtr getAllCombined (const std::string &option_space) const
 Returns all non-vendor or vendor options for the specified option space.
 
template<typename Selector >
OptionDescriptor get (const Selector &key, const uint16_t option_code) const
 Returns option for the specified key and option code.
 
template<typename Selector >
OptionDescriptorList getList (const Selector &key, const uint16_t option_code) const
 Returns options for the specified key and option code.
 
size_t del (const std::string &option_space, const uint16_t option_code)
 Deletes option for the specified option space and option code.
 
size_t del (const uint32_t vendor_id, const uint16_t option_code)
 Deletes vendor option for the specified vendor id.
 
size_t del (const uint64_t id)
 Deletes all options having a given database id.
 
std::list< std::string > getOptionSpaceNames () const
 Returns a list of configured option space names.
 
std::list< uint32_t > getVendorIds () const
 Returns a list of all configured vendor identifiers.
 
std::list< std::string > getVendorIdsSpaceNames () const
 Returns a list of option space names for configured vendor ids.
 
virtual isc::data::ElementPtr toElement () const
 Unparse a configuration object.
 
isc::data::ElementPtr toElementWithMetadata (const bool include_metadata) const
 Unparse a configuration object with optionally including the metadata.
 
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.
 

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 352 of file cfg_option.h.

Constructor & Destructor Documentation

◆ CfgOption()

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

default constructor

Definition at line 54 of file cfg_option.cc.

Member Function Documentation

◆ add() [1/2]

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
descOption descriptor holding option instance and other parameters pertaining to the option.
option_spaceOption space name.
Exceptions
isc::BadValueif the option space is invalid.

Definition at line 83 of file cfg_option.cc.

References isc::dhcp::OptionSpaceContainer< ContainerType, ItemType, Selector >::addItem(), isc_throw, isc::dhcp::LibDHCP::optionSpaceToVendorId(), and isc::dhcp::OptionSpace::validateName().

+ Here is the call graph for this function:

◆ add() [2/2]

void isc::dhcp::CfgOption::add ( const OptionPtr & option,
const bool persistent,
const bool cancelled,
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
optionPointer to the option being added.
persistentBoolean value which specifies if the option should be sent to the client regardless if requested (true), or nor (false)
cancelledBoolean value which specifies if the option must never be sent to the client.
option_spaceOption space name.
idOptional database id to be associated with the option.
Exceptions
isc::BadValueif the option space is invalid.

Definition at line 70 of file cfg_option.cc.

References add().

Referenced by add().

+ Here is the call graph for this function:

◆ copyTo()

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

Copies this configuration to another configuration.

This method copies options configuration to another object.

Parameters
[out]otherAn object to copy the configuration to.

Definition at line 254 of file cfg_option.cc.

References mergeTo().

+ Here is the call graph for this function:

◆ createDescriptorOption()

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:

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

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

  1. If no definition is found but the descriptor conveys a non-empty formatted value, throw an error.
  2. If not definition is found and there is no formatted value, return This leaves intact the generic option in the descriptor.
  3. 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.
  4. 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_defthe user specified definitions to use
spacethe option space name of the option
opt_descOptionDescriptor describing the option.
Returns
True if the descriptor's option instance was replaced.
Exceptions
InvalidOperationif 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 176 of file cfg_option.cc.

References DHCP4_OPTION_SPACE, DHCP6_OPTION_SPACE, isc::dhcp::LibDHCP::getLastResortOptionDef(), isc::dhcp::LibDHCP::getOptionDef(), isc::dhcp::LibDHCP::getVendorOptionDef(), isc_throw, and isc::dhcp::LibDHCP::optionSpaceToVendorId().

Referenced by createOptions().

+ Here is the call graph for this function:

◆ createOptions()

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_defset of of user-defined option definitions to use when creating option instances.

Definition at line 161 of file cfg_option.cc.

References createDescriptorOption(), getAll(), getOptionSpaceNames(), and replace().

+ Here is the call graph for this function:

◆ del() [1/3]

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_spaceOption space name.
option_codeCode of the option to be returned.
Returns
Number of deleted options.

Definition at line 360 of file cfg_option.cc.

References DHCP4_OPTION_SPACE, DHCP6_OPTION_SPACE, getAll(), and getOptionSpaceNames().

+ Here is the call graph for this function:

◆ del() [2/3]

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_idVendor identifier.
option_codeOption code.
Returns
Number of deleted options.

Definition at line 395 of file cfg_option.cc.

References getAll().

+ Here is the call graph for this function:

◆ del() [3/3]

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
idIdentifier 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 408 of file cfg_option.cc.

References isc::dhcp::OptionSpaceContainer< ContainerType, ItemType, Selector >::deleteItems(), encapsulate(), getAll(), and getOptionSpaceNames().

+ Here is the call graph for this function:

◆ empty()

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

Indicates the object is empty.

Returns
true when the object is empty

Definition at line 59 of file cfg_option.cc.

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

+ Here is the call graph for this function:

◆ encapsulate()

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 262 of file cfg_option.cc.

References DHCP4_OPTION_SPACE, and DHCP6_OPTION_SPACE.

Referenced by del(), and merge().

◆ equals()

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

Check if configuration is equal to other configuration.

Parameters
otherAn object holding configuration to compare to.
Returns
true if configurations are equal, false otherwise.

Definition at line 64 of file cfg_option.cc.

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

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

+ Here is the call graph for this function:

◆ get()

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. So please use the next method when multiple instances of the option are expected.
Parameters
keyOption space name or vendor identifier.
option_codeCode of the option to be returned.
Template Parameters
Selectorone 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 605 of file cfg_option.h.

References getAll().

+ Here is the call graph for this function:

◆ getAll() [1/2]

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_spaceName 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 341 of file cfg_option.cc.

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

Referenced by createOptions(), del(), del(), del(), get(), getAllCombined(), getList(), replace(), and toElementWithMetadata().

+ Here is the call graph for this function:

◆ getAll() [2/2]

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

Returns vendor options for the specified vendor id.

Parameters
vendor_idVendor 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 346 of file cfg_option.cc.

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

+ Here is the call graph for this function:

◆ getAllCombined()

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

Returns all non-vendor or vendor options for the specified option space.

It combines the output of the getAll function variants. When option space has the format of "vendor-X", it retrieves the vendor options by vendor id, where X must be a 32-bit unsigned integer. Otherwise, it fetches non-vendor options.

Parameters
option_spaceName 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 351 of file cfg_option.cc.

References getAll(), and isc::dhcp::LibDHCP::optionSpaceToVendorId().

+ Here is the call graph for this function:

◆ getList()

template<typename Selector >
OptionDescriptorList isc::dhcp::CfgOption::getList ( const Selector & key,
const uint16_t option_code ) const
inline

Returns options 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.

Parameters
keyOption space name or vendor identifier.
option_codeCode of the option to be returned.
Template Parameters
Selectorone of: std::string or uint32_t
Returns
List of Descriptors of the option.

Definition at line 636 of file cfg_option.h.

References getAll().

+ Here is the call graph for this function:

◆ getOptionSpaceNames()

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 707 of file cfg_option.h.

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

Referenced by createOptions(), del(), and del().

+ Here is the call graph for this function:

◆ getVendorIds()

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

Returns a list of all configured vendor identifiers.

Definition at line 712 of file cfg_option.h.

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

Referenced by getVendorIdsSpaceNames().

+ Here is the call graph for this function:

◆ getVendorIdsSpaceNames()

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 126 of file cfg_option.cc.

References getVendorIds().

+ Here is the call graph for this function:

◆ isEncapsulated()

bool isc::dhcp::CfgOption::isEncapsulated ( ) const
inline

Checks if options have been encapsulated.

Returns
true if options have been encapsulated, false otherwise.

Definition at line 550 of file cfg_option.h.

◆ merge()

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_defset of of user-defined option definitions to use when merging.
otheroption configuration to merge in.

Definition at line 140 of file cfg_option.cc.

References encapsulate(), and mergeTo().

+ Here is the call graph for this function:

◆ mergeTo()

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]otherConfiguration object to merge to.

Definition at line 246 of file cfg_option.cc.

Referenced by copyTo(), and merge().

◆ operator!=()

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

Inequality operator.

Parameters
otherAn object holding configuration to compare to.
Returns
true if configurations are unequal, false otherwise.

Definition at line 387 of file cfg_option.h.

References equals().

+ Here is the call graph for this function:

◆ operator==()

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

Equality operator.

Parameters
otherAn object holding configuration to compare to.
Returns
true if configurations are equal, false otherwise.

Definition at line 378 of file cfg_option.h.

References equals().

+ Here is the call graph for this function:

◆ replace()

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
descOption descriptor holding option instance and other parameters pertaining to the option.
option_spaceOption space name.
Exceptions
isc::BadValueif 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 101 of file cfg_option.cc.

References getAll(), and isc_throw.

Referenced by createOptions().

+ Here is the call graph for this function:

◆ toElement()

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

Unparse a configuration object.

Returns
a pointer to unparsed configuration

Implements isc::data::CfgToElement.

Definition at line 442 of file cfg_option.cc.

References toElementWithMetadata().

+ Here is the call graph for this function:

◆ toElementWithMetadata()

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

Unparse a configuration object with optionally including the metadata.

Parameters
include_metadataboolean value indicating if the metadata should be included (if true) or not (if false).
Returns
A pointer to the unparsed configuration.

Definition at line 447 of file cfg_option.cc.

References isc::data::Element::create(), isc::data::Element::createList(), isc::data::Element::createMap(), isc::util::encode::encodeHex(), getAll(), isc::dhcp::LibDHCP::getLastResortOptionDef(), isc::dhcp::LibDHCP::getOptionDef(), isc::dhcp::OptionSpaceContainer< ContainerType, ItemType, Selector >::getOptionSpaceNames(), isc::dhcp::LibDHCP::getRuntimeOptionDef(), isc::dhcp::LibDHCP::getVendorOptionDef(), and isc::dhcp::OPT_EMPTY_TYPE.

Referenced by toElement().

+ Here is the call graph for this function:

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