mirror of
https://gitlab.isc.org/isc-projects/kea
synced 2025-08-22 09:57:41 +00:00
121 lines
5.2 KiB
Plaintext
121 lines
5.2 KiB
Plaintext
// Copyright (C) 2018-2022 Internet Systems Consortium, Inc. ("ISC")
|
|
//
|
|
// This Source Code Form is subject to the terms of the Mozilla Public
|
|
// License, v. 2.0. If a copy of the MPL was not distributed with this
|
|
// file, You can obtain one at http://mozilla.org/MPL/2.0/.
|
|
|
|
/**
|
|
|
|
@mainpage Kea Class Commands Hooks Library
|
|
|
|
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 <a href="https://reports.kea.isc.org/dev_guide/">Kea
|
|
Developer's Guide</a> and in particular its section about hooks: <a
|
|
href="https://reports.kea.isc.org/dev_guide/df/d46/hooksdgDevelopersGuide.html">
|
|
Hooks Developer's Guide</a>.
|
|
|
|
@section class_cmds 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 @c isc::class_cmds::ClassCmds
|
|
class that contains handlers for specific operations: @c addClass for
|
|
adding new classes, @c getClass for retrieving existing class,
|
|
@c getClassList for retrieving names of existing classes, @c updateClass
|
|
for updating existing class and @c 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 @c 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 @ref load() and @ref 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 --with-gtest or --with-gtest-source to the
|
|
configure script. Once the code builds, you can run tests with make check. This
|
|
command can be run in top-level Kea directory (all tests will be run) or in more
|
|
specific directory (only a subset of tests will be run). For example, make check
|
|
issued in src/hooks/dhcp/class_cmds will run only tests for class_cmds
|
|
library.
|
|
|
|
@section class_cmdsMTCompatibility 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.
|
|
|
|
*/
|