Kea  2.1.7-git
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 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

◆ CfgOption()

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

default constructor

Definition at line 52 of file cfg_option.cc.

Member Function Documentation

◆ add() [1/2]

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
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)
option_spaceOption space name.
idOptional database id to be associated with the option.
Exceptions
isc::BadValueif 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:

◆ add() [2/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 78 of file cfg_option.cc.

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

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

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

Referenced by merge().

+ 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 165 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:

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

Referenced by merge().

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

References DHCP4_OPTION_SPACE, and DHCP6_OPTION_SPACE.

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

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

◆ empty()

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.

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

References DHCP4_OPTION_SPACE, and DHCP6_OPTION_SPACE.

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

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

References isc::dhcp::OptionDescriptor::OptionDescriptor().

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

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

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

◆ getVendorIds()

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::OptionDescriptor::OptionDescriptor(), and isc::data::UserContext::toElement().

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

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

References copyTo(), and createOptions().

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

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

References isc::dhcp::OptionDescriptor::equals(), and isc::data::merge().

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

References isc::dhcp::OptionDescriptor::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 96 of file cfg_option.cc.

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

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

◆ 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 423 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: