Kea: isc::dhcp::CfgOption Class Reference

| Kea 3.0.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:
[legend]

## 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.
template<typename Selector>
OptionDescriptor | allowedForClientClasses (const Selector &key, const uint16_t option_code, const ClientClasses &cclasses) const
| Fetches an option for a given code if it is allowed for the given list of client classes.
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.
virtual isc::data::ElementPtr | toElement (CfgOptionDefPtr cfg_option_def) const
| Unparse a configuration object.
isc::data::ElementPtr | toElementWithMetadata (const bool include_metadata, CfgOptionDefPtr cfg_option_def=CfgOptionDefPtr()) 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 372 of file cfg_option.h.

## Constructor & Destructor Documentation

## ◆ CfgOption()

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

default constructor

Definition at line 71 of file cfg_option.cc.

Referenced by copyTo(), equals(), merge(), mergeTo(), operator!=(), and operator==().

## 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

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

References isc_throw, isc::dhcp::OptionDescriptor::option_, 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

  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)
  cancelled | Boolean value which specifies if the option must never be sent to the client.
  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 87 of file cfg_option.cc.

References add(), and isc::data::BaseStampedElement::setId().

Referenced by add().

Here is the call graph for this function:

## ◆ allowedForClientClasses()

template<typename Selector>

OptionDescriptor isc::dhcp::CfgOption::allowedForClientClasses | ( | const Selector & | key,
|  | const uint16_t | option_code,
|  | const ClientClasses & | cclasses ) const
| inline

Fetches an option for a given code if it is allowed for the given list of client classes.

Parameters

  key | Option space name or vendor identifier.
  option_code | Code of the option to be returned.
  cclasses | list of ClientClasses to validate against

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

References getAll().

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] | other | An object to copy the configuration to.

Definition at line 271 of file cfg_option.cc.

References CfgOption(), isc::dhcp::OptionSpaceContainer< ContainerType, ItemType, Selector >::clearItems(), isEncapsulated(), and mergeTo().

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

References DHCP4_OPTION_SPACE, DHCP6_OPTION_SPACE, isc::dhcp::OptionDescriptor::formatted_value_, isc::dhcp::LibDHCP::getLastResortOptionDef(), isc::dhcp::LibDHCP::getOptionDef(), isc::dhcp::LibDHCP::getVendorOptionDef(), isc_throw, isc::dhcp::OptionDescriptor::option_, 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_def | set of of user-defined option definitions to use when creating option instances.

Definition at line 178 of file cfg_option.cc.

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

Referenced by merge().

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_space | Option space name.
  option_code | Code of the option to be returned.

Returns
  Number of deleted options.

Definition at line 378 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_id | Vendor identifier.
  option_code | Option code.

Returns
  Number of deleted options.

Definition at line 413 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

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

References 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 76 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 280 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

  other | An object holding configuration to compare to.

Returns
  true if configurations are equal, false otherwise.

Definition at line 81 of file cfg_option.cc.

References CfgOption().

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

  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 625 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_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 359 of file cfg_option.cc.

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

## ◆ getAll() [2/2]

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

## ◆ 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_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 369 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

  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
  List of Descriptors of the option.

Definition at line 656 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 787 of file cfg_option.h.

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

## ◆ getVendorIds()

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

Returns a list of all configured vendor identifiers.

Definition at line 792 of file cfg_option.h.

Referenced by getVendorIdsSpaceNames().

## ◆ 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 143 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 570 of file cfg_option.h.

Referenced by copyTo().

## ◆ 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_def | set of of user-defined option definitions to use when merging.
  other | option configuration to merge in.

Definition at line 157 of file cfg_option.cc.

References CfgOption(), copyTo(), createOptions(), 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] | other | Configuration object to merge to.

Definition at line 263 of file cfg_option.cc.

References CfgOption().

Referenced by copyTo(), and merge().

Here is the call graph for this function:

## ◆ operator!=()

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

References CfgOption(), and equals().

Here is the call graph for this function:

## ◆ operator==()

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

References CfgOption(), and 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

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

References getAll(), isc_throw, and isc::dhcp::OptionDescriptor::option_.

Referenced by createOptions().

Here is the call graph for this function:

## ◆ toElement() [1/2]

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

Unparse a configuration object.

Returns
  a pointer to unparsed configuration

Implements isc::data::CfgToElement.

Definition at line 460 of file cfg_option.cc.

References toElementWithMetadata().

Here is the call graph for this function:

## ◆ toElement() [2/2]

ElementPtr isc::dhcp::CfgOption::toElement | ( | CfgOptionDefPtr | cfg_option_def | ) | const
| virtual

Unparse a configuration object.

Parameters

  cfg_option_def | config option definitions

Returns
  a pointer to unparsed configuration

Definition at line 465 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,
|  | CfgOptionDefPtr | cfg_option_def = CfgOptionDefPtr() ) 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).
  cfg_option_def | config option definitions (optional).

Returns
  A pointer to the unparsed configuration.

Definition at line 470 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::LibDHCP::getRuntimeOptionDef(), isc::dhcp::LibDHCP::getVendorOptionDef(), and isc::dhcp::OPT_EMPTY_TYPE.

Referenced by toElement(), and toElement().

Here is the call graph for this function:

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

- cfg_option.h
- cfg_option.cc