kea/src/lib/dhcp_ddns/libdhcp_ddns.dox

// Copyright (C) 2013-2014  Internet Systems Consortium, Inc. ("ISC")
//
// Permission to use, copy, modify, and/or distribute this software for any
// purpose with or without fee is hereby granted, provided that the above
// copyright notice and this permission notice appear in all copies.
//
// THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
// REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
// AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
// INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
// LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
// OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
// PERFORMANCE OF THIS SOFTWARE.

/**
@page libdhcp_ddns libdhcp_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 acknowledgement of receipt of a
request so, as it is UDP, no guarantee of delivery.

*/