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

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(), isc::agent::CtrlAgentController::deregisterCommands(), 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::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::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

cmd	Pointer 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
	)

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(), isc::agent::CtrlAgentController::registerCommands(), 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:

Classes

Public Types

Public Member Functions

Static Public Member Functions

Protected Types

Protected Member Functions

Protected Attributes

Detailed Description

Member Typedef Documentation

◆ CommandHandler

◆ ExtendedCommandHandler

◆ HandlerContainer

Constructor & Destructor Documentation

◆ BaseCommandMgr()

◆ ~BaseCommandMgr()

Member Function Documentation

◆ deregisterAll()

◆ deregisterCommand()

◆ getHash()

◆ handleCommand()

◆ processCommand()

◆ registerCommand()

◆ registerExtendedCommand()

Member Data Documentation

◆ handlers_