Kea: isc::hooks::LibraryHandle Class Reference

| Kea 3.0.2-git

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.
int | getLibraryIndex () const
| Get library index.
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.
void | setLibraryIndex (int library_index)
| Set library index.

## 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);
}
isc::hooks::LibraryHandle::registerCommandCallout
void registerCommandCallout(const std::string &command_name, CalloutPtr callout)
Register control command handler.
Definition library_handle.cc:36
isc::hooks::LibraryHandle::LibraryHandle
LibraryHandle(CalloutManager &manager, int index=-1)
Constructor.
Definition library_handle.h:77
load
int load(LibraryHandle &handle)
This function is called when the library is loaded.
Definition gss_tsig_callouts.cc:146

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.

## ◆ 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.

## ◆ getLibraryIndex()

int isc::hooks::LibraryHandle::getLibraryIndex | ( |  | ) | const
| inline

Get library index.

Returns
  Current library index.

Definition at line 214 of file library_handle.h.

Referenced by load().

## ◆ 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:

- isc::data::IntElement
- isc::data::DoubleElement
- isc::data::BoolElement
- isc::data::StringElement
- isc::data::ListElement
- isc::data::MapElement

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 isc::run_script::RunScriptImpl::configure(), and 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::HooksManager::getLibraryInfo().

Referenced by getParameter(), getParameterNames(), isc::limits::load(), 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.

Referenced by registerCommandCallout().

## ◆ 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(), and registerCallout().

Referenced by load().

Here is the call graph for this function:

## ◆ setLibraryIndex()

void isc::hooks::LibraryHandle::setLibraryIndex | ( | int | library_index | ) |
| inline

Set library index.

Sets the current library index. This has the following valid values:

- -1: invalidate current index.
- 0: pre-user library callout.
- 1 - numlib: user-library callout (where "numlib" is the number of libraries loaded in the system, this figure being passed to this object at construction time).
- INT_MAX: post-user library callout.

Parameters

  library_index | New library index.

Definition at line 230 of file library_handle.h.

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

- library_handle.h
- library_handle.cc