// Copyright (C) 2013-2020 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_ddns libkea-dhcp_ddns - DHCP_DDNS Request I/O Library

@section libdhcp_ddnsIntro Introduction

This is a library of classes (in the isc::dhcp_ddns namespace) for sending
and receiving requests used by ISC's DHCP-DDNS (aka D2) service to carry
out DHCP-driven DNS updates.  Each request contains the following information:

    - change-type -  indicates if this is a request to add or remove DNS entries
    - forward-change - indicates if the forward DNS zone (the one that
      contains name to address mappings) should be updated
    - reverse-change - indicates if reverse DNS zone (which contains the
      address to name mappings) should be updated
    - fqdn - the fully qualified domain name whose DNS entries should be updated
    - ip-address - IP address (v4 or v6) leased to the client with the
      given FQDN
    - dhcid - DHCID (a form of identification) of the client to whom the IP
      address is leased
    - lease-expires-on - timestamp containing the date/time the lease expires
    - lease-length - duration in seconds for which the lease is valid.

These requests are implemented in this library by the class,
isc::dhcp_ddns::NameChangeRequest.  This class provides services for
constructing the requests as well as marshalling them to and from various
transport formats.  Currently, the only format supported is JSON, however the
design of the classes in this library is such that supporting additional
formats will be easy to add.  The JSON "schema" is documented here:
isc::dhcp_ddns::NameChangeRequest::fromJSON().

For sending and receiving NameChangeRequests, this library supplies an abstract
pair of classes, isc::dhcp_ddns::NameChangeSender and
isc::dhcp_ddns::NameChangeListener.  NameChangeSender defines the public
interface that DHCP_DDNS clients, such as DHCP servers, use for sending
requests to DHCP_DDNS.   NameChangeListener is used by request consumers,
primarily the DHCP_DDNS service, for receiving the requests.

By providing abstract interfaces, the implementation isolates the senders and
listeners from any underlying details of request transportation.  This was done
to allow support for a variety of transportation mechanisms.  Currently, the
only transport supported is via UDP Sockets.

The UDP implementation is provided by isc::dhcp_ddns::NameChangeUDPSender
and isc::dhcp_ddns::NameChangeUDPListener.  The implementation is strictly
unidirectional: there is no explicit acknowledgment of receipt of a
request so, as it is UDP, no guarantee of delivery.

@section libdhcp_ddnsMTConsiderations Multi-Threading Consideration for DHCP_DDNS Request I/O Library

By default this library is not thread safe (it uses asynchronous I/O) at
the exception of the Name Change Request sender class (@c
isc::dhcp_ddns::NameChangeSender) which is Kea thread safe (i.e. it is
thread safe when the multi-threading mode is true).

*/