Kea  2.1.7-git
isc::dhcp::LibDHCP Class Reference

#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 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 uint16_t code)
 Returns last resort option definition by space and option code. More...
 
static OptionDefinitionPtr getLastResortOptionDef (const std::string &space, const std::string &name)
 Returns last resort option definition by space and option name. 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 uint16_t code)
 Return the first option definition matching a particular option code. More...
 
static OptionDefinitionPtr getOptionDef (const std::string &space, const std::string &name)
 Return the definition of option having a specified name. More...
 
static const OptionDefContainerPtr getOptionDefs (const std::string &space)
 Returns collection of option definitions. 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 OptionDefinitionPtr getRuntimeOptionDef (const std::string &space, const std::string &name)
 Returns runtime (non-standard) option definition by space and option name. 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 uint16_t code)
 Returns vendor option definition for a given vendor-id and code. 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 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 228 of file libdhcp++.cc.

◆ commitRuntimeOptionDefs()

void LibDHCP::commitRuntimeOptionDefs ( )
static

Commits runtime option definitions.

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

◆ fuseOptions4()

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

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

Parameters
optionsThe option container which needs to be updated with fused options.
Returns
True if any option has been fused, false otherwise.

Definition at line 619 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 uint16_t  code 
)
static

Returns last resort option definition by space and option code.

Parameters
spaceOption space name.
codeOption code.
Returns
Pointer to option definition or NULL if it doesn't exist.

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

Referenced by isc::flex_option::FlexOptionImpl::configure(), isc::dhcp::Dhcpv4Srv::deferredUnpack(), and isc::dhcp::OptionDataParser::findOptionDefinition().

◆ getLastResortOptionDef() [2/2]

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

Returns last resort option definition by space and option name.

Parameters
spaceOption space name.
nameOption name.
Returns
Pointer to option definition or NULL if it doesn't exist.

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

◆ getLastResortOptionDefs()

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

Returns last resort option definitions for specified option space name.

Parameters
spaceOption space name.
Returns
Pointer to the container holding option definitions or NULL.

Definition at line 267 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 uint16_t  code 
)
static

Return the first option definition matching a particular option code.

Parameters
spaceoption space.
codeoption code.
Returns
reference to an option definition being requested or NULL pointer if option definition has not been found.

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

Referenced by isc::flex_option::FlexOptionImpl::configure(), isc::dhcp::Dhcpv4Srv::deferredUnpack(), and isc::dhcp::OptionDataParser::findOptionDefinition().

◆ getOptionDef() [2/2]

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

Return the definition of option having a specified name.

Parameters
spaceoption space.
nameOption name.
Returns
Pointer to the option definition or NULL pointer if option definition has not been found.

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

◆ 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
spaceOption space.
Returns
Pointer to a collection of option definitions.

Definition at line 95 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 uint16_t  code 
)
static

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

Parameters
spaceOption space name.
codeOption code.
Returns
Pointer to option definition or NULL if it doesn't exist.

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

Referenced by isc::flex_option::FlexOptionImpl::configure(), isc::dhcp::Dhcpv4Srv::deferredUnpack(), and isc::dhcp::OptionDataParser::findOptionDefinition().

◆ getRuntimeOptionDef() [2/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
spaceOption space name.
nameOption name.
Returns
Pointer to option definition or NULL if it doesn't exist.

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

◆ getRuntimeOptionDefs()

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

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

Parameters
spaceOption space name.
Returns
Pointer to the container holding option definitions or NULL.

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

◆ getVendorOptionDef() [1/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
uuniverse (V4 or V6)
vendor_identerprise-id for a given vendor
codeoption code
Returns
reference to an option definition being requested or NULL pointer if option definition has not been found.

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

Referenced by isc::dhcp::OptionDataParser::findOptionDefinition().

◆ getVendorOptionDef() [2/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
uUniverse (V4 or V6)
vendor_idEnterprise-id for a given vendor
nameOption name.
Returns
A pointer to an option definition or NULL pointer if no option definition found.

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

◆ getVendorOptionDefs()

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

Returns option definitions for given universe and vendor.

Parameters
uoption universe
vendor_identerprise-id of a given vendor
Returns
a container for a given vendor (or NULL if no option definitions are defined)

Definition at line 105 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
uuniverse of the option (V4 or V6)
typeoption-type
bufoption-buffer
Returns
instance of option.
Exceptions
isc::InvalidOperationif there is no factory function registered for the specified option type.

Definition at line 283 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::BadValueif provided the type is already registered, has too large a value or an invalid universe is specified.
Parameters
uuniverse of the option (V4 or V6)
typeoption-type
factoryfunction pointer

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

References initOptionSpace(), and isc_throw.

+ Here is the call graph for this function:

◆ 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_spaceOption space name.
Returns
vendor id.

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

Referenced by isc::dhcp::OptionDataParser::findOptionDefinition().

◆ 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
bufoutput buffer (assembled options will be stored here)
optionscollection of options to store to
topindicates 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.

Definition at line 888 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
bufoutput buffer (assembled options will be stored here)
optionscollection of options to store to

Definition at line 1069 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 233 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
defsConst reference to a container holding option definitions grouped by option spaces.

Definition at line 214 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
spaceOption space name.
codeOption code.
Returns
True if option processing should be deferred.

Definition at line 276 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
optionsThe option container which needs to be updated with split options.
usedThe 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 934 of file libdhcp++.cc.

References isc::data::copy(), 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
bufBuffer to be parsed.
option_spaceA name of the option space which holds definitions to be used to parse options in the packets.
optionsReference to option container. Options will be put here.
deferredReference to an option code list. Options which processing is deferred will be put here.
flexible_pad_endParse 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_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
bufBuffer to be parsed.
option_spaceA name of the option space which holds definitions to be used to parse options in the packets.
optionsReference to option container. Options will be put here.
relay_msg_offsetreference to a size_t structure. If specified, offset to beginning of relay_msg option will be stored in it.
relay_msg_lenreference 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 308 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(), and isc::dhcp::Pkt6::unpackRelayMsg().

+ 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_identerprise-id of the vendor
bufBuffer to be parsed.
optionsReference 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 782 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_identerprise-id of the vendor
bufBuffer to be parsed.
optionsReference 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 685 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: