Kea: isc::config::BaseCommandMgr Class Reference

| Kea 3.2.0-git

isc::config::BaseCommandMgr Class Reference

Commands Manager, responsible for processing external commands. More...

`#include <base_command_mgr.h>`

Inheritance diagram for isc::config::BaseCommandMgr:
[legend]

## Classes
struct | HandlersPair

## Public Types
typedef std::function< isc::data::ConstElementPtr(const std::string &name, const isc::data::ConstElementPtr &params)> | CommandHandler
| Defines command handler type.
typedef std::function< isc::data::ConstElementPtr(const std::string &name, const isc::data::ConstElementPtr &params, const isc::data::ConstElementPtr &original)> | ExtendedCommandHandler
| Defines extended command handler type.

## Public Member Functions
| BaseCommandMgr ()
| Constructor.
virtual | ~BaseCommandMgr ()
| Destructor.
void | deregisterAll ()
| Auxiliary method that removes all installed commands.
void | deregisterCommand (const std::string &cmd)
| Deregisters specified command handler.
virtual isc::data::ConstElementPtr | processCommand (const isc::data::ConstElementPtr &cmd)
| Triggers command processing.
void | registerCommand (const std::string &cmd, CommandHandler handler)
| Registers specified command handler for a given command.
void | registerExtendedCommand (const std::string &cmd, ExtendedCommandHandler handler)
| Registers specified command handler for a given command.

## Static Public Member Functions
static std::string | getHash (const isc::data::ConstElementPtr &config)
| returns a hash of a given Element structure

## Protected Types
typedef std::map< std::string, HandlersPair > | HandlerContainer
| Type of the container for command handlers.

## Protected Member Functions
virtual isc::data::ConstElementPtr | handleCommand (const std::string &cmd_name, const isc::data::ConstElementPtr &params, const isc::data::ConstElementPtr &original_cmd)
| Handles the command having a given name and arguments.

## Protected Attributes
HandlerContainer | handlers_
| Container for command handlers.

## Detailed Description

Commands Manager, responsible for processing external commands.

Commands Manager is a generic interface for handling external commands. Commands are received over control sockets. Derivations of this class provide implementations of the control socket layers, e.g. unix domain sockets, TCP sockets etc. This base class merely provides methods to manage command handling functions, i.e. register commands, deregister commands. It also includes a BaseCommandMgr::processCommand method which uses the command as an input and invokes appropriate handlers.

The commands and responses are formatted using JSON. See https://gitlab.isc.org/isc-projects/kea/-/wikis/Designs/Stats-design for details.

Below is an example of the command using JSON format:

{
"command": "statistic-get",
"arguments": {
"name": "received-packets"
}
}

And the response is:

{
"result": 0,
"arguments": {
"received-packets": [ [ 1234, "2015-04-15 12:34:45.123" ] ]
}
}

BaseCommandsMgr does not implement the commands (except one, "list-commands") itself, but rather provides an interface (see registerCommand, deregisterCommand, processCommand) for other components to use it.

Definition at line 72 of file base_command_mgr.h.

## Member Typedef Documentation

## ◆ CommandHandler

typedef std::function<isc::data::ConstElementPtr (const std::string& name, const isc::data::ConstElementPtr& params)> isc::config::BaseCommandMgr::CommandHandler

Defines command handler type.

Command handlers are expected to use this format.

Parameters

  name | name of the commands
  params | parameters specific to the command

Returns
  response (created with createAnswer())

Definition at line 83 of file base_command_mgr.h.

## ◆ ExtendedCommandHandler

typedef std::function<isc::data::ConstElementPtr (const std::string& name, const isc::data::ConstElementPtr& params, const isc::data::ConstElementPtr& original)> isc::config::BaseCommandMgr::ExtendedCommandHandler

Defines extended command handler type.

This command handler includes third parameter which holds the entire command control message. The handler can retrieve additional information from this parameter, e.g. 'service'.

Parameters

  name | name of the commands
  params | parameters specific to the command
  original | original control command.

Returns
  response (created with createAnswer())

Definition at line 97 of file base_command_mgr.h.

## ◆ HandlerContainer

typedef std::map<std::string, HandlersPair> isc::config::BaseCommandMgr::HandlerContainer
| protected

Type of the container for command handlers.

Definition at line 193 of file base_command_mgr.h.

## Constructor & Destructor Documentation

## ◆ BaseCommandMgr()

isc::config::BaseCommandMgr::BaseCommandMgr | ( |  | ) |

Constructor.

Registers hookpoint "command-processed" Registers "list-commands" command.

Definition at line 47 of file base_command_mgr.cc.

References registerCommand().

Referenced by isc::config::HookedCommandMgr::HookedCommandMgr().

Here is the call graph for this function:

## ◆ ~BaseCommandMgr()

virtual isc::config::BaseCommandMgr::~BaseCommandMgr | ( |  | ) |
| inlinevirtual

Destructor.

Definition at line 106 of file base_command_mgr.h.

## Member Function Documentation

## ◆ deregisterAll()

void isc::config::BaseCommandMgr::deregisterAll | ( |  | ) |

Auxiliary method that removes all installed commands.

The only unwipeable method is list-commands, which is internally handled at all times.

Definition at line 109 of file base_command_mgr.cc.

References handlers_, and registerCommand().

Here is the call graph for this function:

## ◆ deregisterCommand()

void isc::config::BaseCommandMgr::deregisterCommand | ( | const std::string & | cmd | ) |

Deregisters specified command handler.

Parameters

  cmd | Name of the command that's no longer handled.

Definition at line 92 of file base_command_mgr.cc.

References isc::config::COMMAND_DEREGISTERED, isc::config::command_logger, isc::config::DBG_COMMAND, handlers_, isc_throw, and LOG_DEBUG.

Referenced by isc::dhcp::ControlledDhcpv4Srv::~ControlledDhcpv4Srv(), isc::dhcp::ControlledDhcpv6Srv::~ControlledDhcpv6Srv(), and isc::d2::D2Controller::deregisterCommands().

## ◆ getHash()

std::string isc::config::BaseCommandMgr::getHash | ( | const isc::data::ConstElementPtr & | config | ) |
| static

returns a hash of a given Element structure

The hash is currently implemented as SHA256 on the string

Parameters

  config | typically full config, but hash can be calculated on any structure

Returns
  hash of string representation

Definition at line 193 of file base_command_mgr.cc.

References isc::cryptolink::digest(), isc::util::encode::encodeHex(), isc::util::OutputBuffer::getData(), isc::util::OutputBuffer::getLength(), isc_throw, and isc::cryptolink::SHA256.

Referenced by isc::dhcp::ControlledDhcpv4Srv::commandConfigGetHandler(), isc::dhcp::ControlledDhcpv6Srv::commandConfigGetHandler(), isc::dhcp::ControlledDhcpv4Srv::commandConfigHashGetHandler(), isc::dhcp::ControlledDhcpv6Srv::commandConfigHashGetHandler(), isc::process::DControllerBase::configGetHandler(), isc::process::DControllerBase::configHashGetHandler(), isc::dhcp::configureDhcp4Server(), isc::dhcp::configureDhcp6Server(), and isc::d2::D2CfgMgr::parse().

Here is the call graph for this function:

## ◆ handleCommand()

ConstElementPtr isc::config::BaseCommandMgr::handleCommand | ( | const std::string & | cmd_name,
|  | const isc::data::ConstElementPtr & | params,
|  | const isc::data::ConstElementPtr & | original_cmd )
| protectedvirtual

Handles the command having a given name and arguments.

This method can be overridden in the derived classes to provide custom logic for processing commands. For example, the HookedCommandMgr extends this method to delegate commands processing to a hook library.

Parameters

  cmd_name | Command name.
  params | Command arguments.
  original_cmd | Pointer to the entire command received. It may be sometimes useful to retrieve additional parameters from this command.

Returns
  Pointer to the const data element representing response to a command.

Reimplemented in isc::config::HookedCommandMgr.

Definition at line 164 of file base_command_mgr.cc.

References isc::config::CONTROL_RESULT_COMMAND_UNSUPPORTED, isc::config::createAnswer(), and handlers_.

Referenced by isc::config::HookedCommandMgr::handleCommand(), and processCommand().

Here is the call graph for this function:

## ◆ processCommand()

isc::data::ConstElementPtr isc::config::BaseCommandMgr::processCommand | ( | const isc::data::ConstElementPtr & | cmd | ) |
| virtual

Triggers command processing.

This method processes specified command. The command is specified using a single Element. See BaseCommandMgr for description of its syntax. After the command has been handled, callouts for the hook point, "command-processed" will be invoked.

This method is virtual so it can be overridden in derived classes to pre-process command and post-process response if necessary.

This method is an entry point for dealing with a command. Internally it calls `BaseCommandMgr::handleCommand`.

Parameters

  cmd | Pointer to the data element representing command in JSON format.

Definition at line 119 of file base_command_mgr.cc.

References isc::hooks::HooksManager::callCallouts(), isc::hooks::HooksManager::calloutsPresent(), isc::config::command_logger, isc::config::COMMAND_PROCESS_ERROR2, isc::config::COMMAND_RECEIVED, isc::config::CONTROL_RESULT_ERROR, isc::config::createAnswer(), isc::hooks::HooksManager::createCalloutHandle(), handleCommand(), Hooks, LOG_INFO, LOG_WARN, isc::config::parseCommand(), and isc::Exception::what().

Referenced by isc::dhcp::ControlledDhcpv4Srv::loadConfigFile(), and isc::dhcp::ControlledDhcpv6Srv::loadConfigFile().

Here is the call graph for this function:

## ◆ registerCommand()

void isc::config::BaseCommandMgr::registerCommand | ( | const std::string & | cmd,
|  | CommandHandler | handler )

Registers specified command handler for a given command.

Parameters

  cmd | Name of the command to be handled.
  handler | Pointer to the method that will handle the command.

Definition at line 53 of file base_command_mgr.cc.

References isc::config::command_logger, isc::config::COMMAND_REGISTERED, isc::config::DBG_COMMAND, isc::config::BaseCommandMgr::HandlersPair::handler, handlers_, isc_throw, and LOG_DEBUG.

Referenced by BaseCommandMgr(), isc::dhcp::ControlledDhcpv4Srv::ControlledDhcpv4Srv(), isc::dhcp::ControlledDhcpv6Srv::ControlledDhcpv6Srv(), deregisterAll(), and isc::d2::D2Controller::registerCommands().

## ◆ registerExtendedCommand()

void isc::config::BaseCommandMgr::registerExtendedCommand | ( | const std::string & | cmd,
|  | ExtendedCommandHandler | handler )

Registers specified command handler for a given command.

This variant of the method uses extended command handler which, besides command name and arguments, also has a third parameter 'original_cmd' in its signature. Such handlers can retrieve additional parameters from the command, e.g. 'service' indicating where the command should be routed.

Parameters

  cmd | Name of the command to be handled.
  handler | Pointer to the method that will handle the command.

Definition at line 72 of file base_command_mgr.cc.

References isc::config::COMMAND_EXTENDED_REGISTERED, isc::config::command_logger, isc::config::DBG_COMMAND, isc::config::BaseCommandMgr::HandlersPair::extended_handler, handlers_, isc_throw, and LOG_DEBUG.

## Member Data Documentation

## ◆ handlers_

HandlerContainer isc::config::BaseCommandMgr::handlers_
| protected

Container for command handlers.

Definition at line 196 of file base_command_mgr.h.

Referenced by deregisterAll(), deregisterCommand(), handleCommand(), registerCommand(), and registerExtendedCommand().

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

- base_command_mgr.h
- base_command_mgr.cc