wiki:HooksConfiguration

Hooks Configuration

Current Situation

At present (Kea 0.9.2), the only configuration related to hook code is the specification of the libraries to load in the "hooks-libraries" element of the configuration file, e.g.

"Dhcp4": {
    :
    "hooks-libraries": [
       "/opt/charging.so",
       "/opt/local/notification.so"
    ]
    :
}

In the above example, two hooks libraries are specified and will be loaded by Kea. The libraries are loaded in the order specified, so for every hook point, a function in "charging.so" (if present) will be called before the corresponding function in "notification.so" (if present).

However, there is currently no way to specify additional library-specific information to the library in the configuration file. Should such information be required, the library must obtain it itself (e.g. by reading information from a file in a known location).

Proposed Solution

Following the discussion in a kea-dev mailing list thread, the following is proposed:

Configuration Syntax

The syntax for the specification of libraries is extended as follows:

{
  "Dhcp4": {
       :
    "hooks-libraries" : [
      {
        "library" : "/opt/charging.so",
        "parameters" : {
           "alpha": "beta",
           "foo": "bar"
        }
      },
      {
        "library" : "/opt/local/notification.so",
        "parameters" : {
            "param1" : true,
            "param2" : 1
            }
        }
      },
      :
    ],
    :
  }
}

As before, hook library configuration information is specified as an array, the order of the array defining the order in which the hooks libraries are loaded and in which the function are called. However, instead of the elements of the array being strings, they are maps: this is a change to the current syntax. The maps contain the following elements:

  • "library" - this is mandatory, and is the file specification of a hooks library.
  • "parameters" - this is an optional element, and if present its type is not constrained - it depends on what the library expects.

In the examples above, the "charging" library has two string parameters associated with it. The "notification" library also has two parameters, one of which is a boolean value and the other an integer.

In the first release of the code containing this feature, allowed types for parameters will be string, integer and boolean. A future release will support more complex types (e.g. arrays, maps) but this will depend on a rewrite of the Kea configuration system.

Parameter Access

Access to the parameters is through methods on the LibraryHandle object, passed to the library's "load" function and accessible to other functions by calling a method on the CalloutHandle argument. The current proposal is to add the following methods:

std::string getStringParameter(const std::string& name)
Returns the value of the named parameter as a string. An exception is thrown if the value is not a string.

long getIntegerParameter(const std::string& name)
Returns the value of the named parameter as an integer. An exception is thrown if the value is not an integer.

bool getBooleanParameter(const std::string& name)
Returns the value of the named parameter as a boolean value. An exception is thrown if the value is not boolean.

QUESTION: is this syntax better than void getParameter(const std::string& name, T& value)?

Last modified 2 years ago Last modified on Oct 7, 2015, 11:28:51 AM