// Copyright (C) 2018-2025 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/.

/**

@page libdhcp_class_cmds 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 -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".

@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.

*/
