Kea 2.5.6
isc::config::BaseCommandMgr Class Reference

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

#include <base_command_mgr.h>

+ Inheritance diagram for isc::config::BaseCommandMgr:

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, HandlersPairHandlerContainer
 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
namename of the commands
paramsparameters 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
namename of the commands
paramsparameters specific to the command
originaloriginal 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().

+ 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)

◆ 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
configtypically 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::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_nameCommand name.
paramsCommand arguments.
original_cmdPointer 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::agent::CtrlAgentCommandMgr, and 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
cmdPointer to the data element representing command in JSON format.

Reimplemented in isc::agent::CtrlAgentCommandMgr.

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().

+ Here is the call graph for this function:

◆ registerCommand()

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

◆ 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
cmdName of the command to be handled.
handlerPointer 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: