// Copyright (C) 2021 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 d2Hooks The Hooks API for the Kea DHCP DDNS (D2)

 @section d2HooksIntroduction Introduction
 Kea features an API (the "Hooks" API) that allows user-written code to
 be integrated into Kea and called at specific points in its processing.
 An overview of the API and a tutorial for writing such code can be found in
 the @ref hooksdgDevelopersGuide. It also includes information how hooks
 framework can be used to implement additional control commands for
 Kea DHCP DDNS. Information for Kea maintainers can be found in the
 @ref hooksComponentDeveloperGuide.

 This manual is more specialized and is aimed at developers of hook
 code for Kea DHCP DDNS. It describes each hook point, what the callouts
 attached to the hook are able to do, and the arguments passed to the
 callouts.  Each entry in this manual has the following information:

 - Name of the hook point.
 - Arguments for the callout.  As well as the argument name and data type, the
   information includes the direction, which can be one of:
   - @b in - the server passes values to the callout but ignored any data
     returned.
   - @b out - the callout is expected to set this value.
   - <b>in/out</b> - the server passes a value to the callout and uses whatever
     value the callout sends back.  Note that the callout may choose not to
     do any modification, in which case the server will use whatever value
     it sent to the callout.
 - Description of the hook. This explains where in the processing the hook
   is located, the possible actions a callout attached to this hook could take,
   and a description of the data passed to the callouts.
 - Next step status: the action taken by the server when a callout chooses to set
    status to specified value. Actions not listed explicitly are not supported.
   If a callout sets status to unsupported value, this specific value will be
   ignored and treated as if the status was CONTINUE.

@section d2HooksHookPoints Hooks in Kea DHCP DDNS

The following list is roughly ordered by appearance of specific hook points during
packet processing, but the exact order depends on the actual processing. Hook points
that are not specific to packet processing (e.g. lease expiration) will be added
to the end of this list.

 @subsection d2HooksD2SrvConfigured d2_srv_configured
 - @b Arguments:
   - name: @b io_context, type: isc::asiolink::IOServicePtr, direction: <b>in</b>
   - name: @b json_config, type: isc::data::ConstElementPtr, direction: <b>in</b>
   - name: @b server_config, type: isc::d2::D2CfgContextPtr, direction: <b>in</b>
   - name: @b error, type: std::string, direction: <b>out</b>

 - @b Description: this callout is executed when the server has completed
   its (re)configuration. The server provides received and parsed configuration
   structures to the hook library. It also provides a pointer to the IOService
   object which is used by the server to run asynchronous operations. The hooks
   libraries can use this IOService object to schedule asynchronous tasks which
   are triggered by the Kea DHCP DDNS's main loop. The hook library should hold
   the provided pointer until the library is unloaded. The D2CfgContext
   object provides access to the D2 running configuration.

 - <b>Next step status</b>: If any callout sets the status to DROP, the server
   considers the configuration is incorrect and rejects it using the error
   string as an error message.

 @subsection d2HooksSelectKey select_key
 - @b Arguments:
   - name: @b current_server, type: isc::d2::DnsServerInfoPtr, direction: <b>in</b>
   - name: @b tsig_key, type: isc::d2::D2TsigKeyPtr, direction: <b>in/out</b>

 - @b Description: this callout is executed when the D2 is selecting for
   a TSIG key to protect the next DNS update to the already chosen DNS
   server. Pointers to the current DNS server and TSIG key are provided.
   If a hook library wants to use another TSIG key the pointer must be updated.

 - <b>Next step status</b>: If any callout sets the status to a different
   value than CONTINUE the current server is skipped.
*/