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.