Kea 2.5.8
isc::hooks::LibraryHandle Class Reference

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);
}
int load(LibraryHandle &)
This function is called when the library is loaded.
void registerCommandCallout(const std::string &command_name, CalloutPtr callout)
Register control command handler.

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
managerBack 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.
indexIndex 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
nameName of the hook from which the callouts are removed.
Returns
true if one or more callouts were deregistered.
Exceptions
NoSuchHookThrown 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
nameName of the hook from which the callout is removed.
calloutPointer to the callout function to be removed.
Returns
true if a one or more callouts were deregistered.
Exceptions
NoSuchHookThe hook name is unrecognized.
UnexpectedThe 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
nametext 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
nameName of the hook to which the callout is added.
calloutPointer to the callout function to be registered.
Exceptions
NoSuchHookThe hook name is unrecognized.
UnexpectedThe 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_nameCommand name for which handler should be installed.
calloutPointer 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: