Welcome to Kea Class Commands Hooks Library. This documentation is addressed at developers who are interested in internal operation of the Class Commands library. This file provides information needed to understand and perhaps extend this library.

This documentation is stand-alone: you should have read and understood Kea Developer's Guide and in particular its section about hooks: Hooks Developer's Guide.

Overview

Introduction

libdhcp_class_cmds is a hooks library which provides additional commands for manipulating client classes. The currently supported commands are:

class-get - which attempts to retrieve client class with specified name. Details of the client class, if present, will be returned.
class-list - which attempts to retrieve the list of all client class names.
class-add - inserts a new client class. This allows you to dynamically (while the server is running) insert a new client class with test expressions, options, several DHCPv4 message fields, ...
class-update - updates a configured client class. This allows you to dynamically (while the server is running) update existing client class with new test expression, options, several DHCPv4 message fields, ...
class-del - deletes existing client class. This allows you to remove an existing class while the server is running.

Internal structure

Almost all the code is enclosed within isc::class_cmds namespace.

The core library consists of several files:

class_cmds.h - This file contains definition of a isc::class_cmds::ClassCmds class that contains handlers for specific operations: addClass for adding new classes, getClass for retrieving existing class, getClassList for retrieving names of existing classes, updateClass for updating existing class and delClass for deleting a client class. This class uses pimpl design pattern, which means that the actual implementation is hidden in an internal object. The advantage of this approach is mostly hermetization, i.e. the internals are not exposed and the whole library provides small, clean interface. There is a pointer to internal class called ClassCmdsImpl. That class is defined in class_cmds.cc.
class_cmds.cc - This file contains the most important piece: code that performs the operations on classes.
class_cmds_callouts.cc - This is a very simple file that provides wrappers for hook points. Due to the way how hooks interface is defined in Kea, these are plain C-style functions (note extern "C" clause and lack of namespaces). This file also contains load() and unload() functions. The load function registers new commands (class-add, class-get, class-list, class-update and class-del).
version.cc - This file contains a single function that returns Kea hooks version. This is part of the mandatory hooks library interface and is used by Kea to check if the library is not compiled against too old or too new version.
class_cmds_messages.cc - This file is autogenerated and should never be modified. If you want to introduce any changes, please modify class_cmds_messages.mes instead.
class_cmds_messages.h - This file is autogenerated and should never be modified. If you want to introduce any changes, please modify class_cmds_messages.mes instead.
class_cmds_messages.mes - This file contains list of all message the library could print, with a short description of what specific message means.
class_cmds_log.h - This file contains declaration of a logger that is used in class_cmds library.
class_cmds_log.cc - This file contains definition of a logger that is used in class_cmds library.
class_cmds.dox - This doxygen documentation contains main part of the Developer's Guide text.

Regenerating this documentation

To regenerate this documentation, type: make devel in the main directory of the class_cmds library. Make sure you have at least doxygen software installed, but it is useful to also have graphviz. The generated documentation will be stored in html/ directory.

Testing

Similar to all other code in Kea, also this library comes with unit-tests that use googletest framework. Those tests are stored in tests/ directory. To build and run them, you need to pass -D tests=enabled to the "meson setup" command line. Once the code builds, you can run tests with "meson compile". This command can be run in top-level build directory (all tests will be run) or by running tests on this library only "meson test -C build dhcp-class-cmds-tests".

Multi-Threading Compatibility

The libdhcp_class_cmds hooks library is compatible with multi-threading. All commands are executed inside a critical section, i.e. with threads stopped.