Library handle. More...

#include <library_handle.h>

Public Member Functions
	LibraryHandle (CalloutManager &manager, int index=-1)
	Constructor.

bool	deregisterAllCallouts (const std::string &name)
	Removes all callouts on a hook.

bool	deregisterCallout (const std::string &name, CalloutPtr callout)
	De-Register a callout on a hook.

isc::data::ConstElementPtr	getParameter (const std::string &name)
	Returns configuration parameter for the library.

std::vector< std::string >	getParameterNames ()
	Returns names of configuration parameters for the library.

isc::data::ConstElementPtr	getParameters ()
	Get configuration parameter common code.

void	registerCallout (const std::string &name, CalloutPtr callout)
	Register a callout on a hook.

void	registerCommandCallout (const std::string &command_name, CalloutPtr callout)
	Register control command handler.

Detailed Description

Library handle.

This class is accessed by the user library when registering callouts, either by the library's load() function, or by one of the callouts themselves.

It is really little more than a shell around the CalloutManager. By presenting this object to the user-library callouts, callouts can manage the callout list for their own library, but cannot affect the callouts registered by other libraries.

(This restriction is achieved by the CalloutManager maintaining the concept of the "current library". When a callout is registered - either by the library's load() function, or by a callout in the library - the registration information includes the library active at the time. When that callout is called, the CalloutManager uses that information to set the "current library": the registration functions only operator on data whose associated library is equal to the "current library".)

As of Kea 1.3.0 release, the LibraryHandle can be used by the hook libraries to install control command handlers and dynamically register hook points with which the handlers are associated. For example, if the hook library supports control-command 'foo-bar' it should register its handler similarly to this:

int load(LibraryHandle& libhandle) {
    libhandle.registerCommandCallout("foo-bar", foo_bar_handler);
    return (0);
}

which will result in automatic creation of the hook point for the command (if one doesn't exist) and associating the callout 'foo_bar_handler' with this hook point as a handler for the command.

Definition at line 60 of file library_handle.h.

Constructor & Destructor Documentation

◆ LibraryHandle()

isc::hooks::LibraryHandle::LibraryHandle	(	CalloutManager &	manager,
		int	index = -1 )

inline

Constructor.

Parameters

manager	Back reference to the containing CalloutManager. This reference is used to access appropriate methods in that object. Note that the reference is safe - the only instance of the LibraryHandle in the system is as a member of the CalloutManager to which it points.
index	Index of the library to which the LibraryHandle applies. If negative, the library index as set in the CalloutManager is used. Note: although -1 is a valid argument value for isc::hooks::CalloutManager::setLibraryIndex(), in this class it is used as a sentinel to indicate that the library index in isc::hooks::CalloutManager should not be set or reset.

Definition at line 77 of file library_handle.h.

Member Function Documentation

◆ deregisterAllCallouts()

bool isc::hooks::LibraryHandle::deregisterAllCallouts ( const std::string & name )

Removes all callouts on a hook.

Removes all callouts associated with a given hook that were registered. by the current library. It does not affect callouts that were registered by other libraries.

Parameters

name	Name of the hook from which the callouts are removed.

Returns: true if one or more callouts were deregistered.

Exceptions

NoSuchHook Thrown if the hook name is unrecognized.

Definition at line 60 of file library_handle.cc.

References isc::hooks::CalloutManager::deregisterAllCallouts(), and isc::hooks::CalloutManager::getLibraryIndex().

Here is the call graph for this function:

◆ deregisterCallout()

bool isc::hooks::LibraryHandle::deregisterCallout	(	const std::string &	name,
		CalloutPtr	callout )

De-Register a callout on a hook.

Searches through the functions registered by the current library with the named hook and removes all entries matching the callout. It does not affect callouts registered by other libraries.

Parameters

name	Name of the hook from which the callout is removed.
callout	Pointer to the callout function to be removed.

Returns: true if a one or more callouts were deregistered.

Exceptions

NoSuchHook	The hook name is unrecognized.
Unexpected	The hook name is valid but an internal data structure is of the wrong size.

Definition at line 46 of file library_handle.cc.

References isc::hooks::CalloutManager::deregisterCallout(), and isc::hooks::CalloutManager::getLibraryIndex().

Here is the call graph for this function:

◆ getParameter()

isc::data::ConstElementPtr isc::hooks::LibraryHandle::getParameter ( const std::string & name )

Returns configuration parameter for the library.

This method returns configuration parameters specified in the configuration file. Here's the example. Let's assume that there are two hook libraries configured:

"hooks-libraries": [ { "library": "/opt/charging.so", "parameters": {} }, { "library": "/opt/local/notification.so", "parameters": { "mail": "alarm@example.com", "floor": 42, "debug": false, "users": [ "alice", "bob", "charlie" ], "header": { "french": "bonjour", "klingon": "yl'el" } } } ]

The first library has no parameters, so regardless of the name specified, for that library getParameter will always return NULL.

For the second parameter, depending the following calls will return:

x = getParameter("mail") will return instance of isc::data::StringElement. The content can be accessed with x->stringValue() and will return std::string.
x = getParameter("floor") will return an instance of isc::data::IntElement. The content can be accessed with x->intValue() and will return int.
x = getParameter("debug") will return an instance of isc::data::BoolElement. Its value can be accessed with x->boolValue() and will return bool.
x = getParameter("users") will return an instance of ListElement. Its content can be accessed with the following methods: x->size(), x->get(index)
x = getParameter("header") will return an instance of isc::data::MapElement. Its content can be accessed with the following methods: x->find("klingon"), x->contains("french"), x->size()

For more examples and complete API, see documentation for isc::data::Element class and its derivatives:

Another good way to learn how to use Element interface is to look at the unittests in data_unittests.cc.

Parameters

name	text name of the parameter.

Returns: ElementPtr representing requested parameter (may be null, if there is no such parameter.)

Definition at line 101 of file library_handle.cc.

References getParameters(), and isc::data::Element::map.

Referenced by load().

Here is the call graph for this function:

◆ getParameterNames()

std::vector< std::string > isc::hooks::LibraryHandle::getParameterNames ( )

Returns names of configuration parameters for the library.

This method returns a vector of strings reflecting names of configuration parameters specified in the configuration file.

Note: : kept for backward compatibility.

Returns: a vector with parameter entry names.

Definition at line 113 of file library_handle.cc.

References getParameters(), and isc::data::Element::map.

Here is the call graph for this function:

◆ getParameters()

isc::data::ConstElementPtr isc::hooks::LibraryHandle::getParameters ( )

Get configuration parameter common code.

Returns: configuration parameters.

Definition at line 74 of file library_handle.cc.

References isc::hooks::CalloutManager::getLibraryIndex(), and isc::hooks::HooksManager::getLibraryInfo().

Referenced by getParameter(), getParameterNames(), and load().

Here is the call graph for this function:

◆ registerCallout()

void isc::hooks::LibraryHandle::registerCallout	(	const std::string &	name,
		CalloutPtr	callout )

Register a callout on a hook.

Registers a callout function with a given hook. The callout is added to the end of the callouts for the current library that are associated with that hook.

Parameters

name	Name of the hook to which the callout is added.
callout	Pointer to the callout function to be registered.

Exceptions

NoSuchHook	The hook name is unrecognized.
Unexpected	The hook name is valid but an internal data structure is of the wrong size.

Definition at line 21 of file library_handle.cc.

References isc::hooks::CalloutManager::getLibraryIndex(), and isc::hooks::CalloutManager::registerCallout().

Referenced by registerCommandCallout().

Here is the call graph for this function:

◆ registerCommandCallout()

void isc::hooks::LibraryHandle::registerCommandCallout	(	const std::string &	command_name,
		CalloutPtr	callout )

Register control command handler.

Registers control command handler by creating a hook point for this command (if it doesn't exist) and associating the callout as a command handler. It is possible to register multiple command handlers for the same control command because command handlers are implemented as callouts.

Parameters

command_name	Command name for which handler should be installed.
callout	Pointer to the command handler implemented as a callout.

Definition at line 36 of file library_handle.cc.

References isc::hooks::ServerHooks::commandToHookName(), registerCallout(), and isc::hooks::CalloutManager::registerCommandHook().

Referenced by load().

Here is the call graph for this function:

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

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ LibraryHandle()

Member Function Documentation

◆ deregisterAllCallouts()

◆ deregisterCallout()

◆ getParameter()

◆ getParameterNames()

◆ getParameters()

◆ registerCallout()

◆ registerCommandCallout()