[3505] Documented JSON format of NameChangeRequest

Documented JSON "schema" for isc::dhcp_ddns::NameChangeRequests
and added explanation of NCR members to D2 doxygen

src/lib/dhcp_ddns/libdhcp_ddns.dox

@@ -1,4 +1,4 @@
-// Copyright (C) 2013  Internet Systems Consortium, Inc. ("ISC")
+// 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
@@ -17,19 +17,32 @@
 
 @section libdhcp_ddnsIntro Libdhcp_ddns Library Introduction
 
-libdhcp_ddns is a library of classes for sending and receiving requests used
-by ISC's  DHCP-DDNS service for carrying out DHCP-driven DDNS.  These requests
-are implemented in this library by the class, 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.
+This is a library of classes (isc::dhcp_ddns) for sending and receiving
+requests used by ISC's DHCP-DDNS (aka D2) service for carrying 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 forward DNS should be updates
+    - reverse_change - indicates if reverse DNS should be updated
+    - fqdn - fully qualified domain name whose DNS entries should be updated
+    - ip_address - IP address (v4 or v6) leased to the given FQDN
+    - dhcid - DHCID 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 (TTL)
+
+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, NameChangeSender and 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.
+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
@@ -38,10 +51,11 @@ only transport supported is via UDP Sockets, though support for TCP/IP sockets
 is forthcoming.  There may eventually be an implementation which is driven
 through an RDBMS.
 
-The UDP implementation is provided by NameChangeUDPSender and NameChangeUPDListener.
-The implementation is strictly unidirectional.  This means that there is no explicit
-acknowledgement of receipt of a request, and as it is UDP there is no guarantee of
-delivery.  Once provided, transport via TCP/IP sockets will provide a more reliable
+The UDP implementation is provided by isc::dhcp_ddns::NameChangeUDPSender and
+isc::dhcp_ddns::NameChangeUPDListener.  The implementation is strictly
+unidirectional.  This means that there is no explicit acknowledgement of
+receipt of a request, and as it is UDP there is no guarantee of delivery.
+Once provided, transport via TCP/IP sockets will provide a more reliable
 mechanism.
 
 */

src/lib/dhcp_ddns/ncr_msg.h

@@ -230,8 +230,9 @@ typedef std::map<std::string, isc::data::ConstElementPtr> ElementMap;
 /// request DNS updates.  Each message contains a single DNS change (either an
 /// add/update or a remove) for a single FQDN.  It provides marshalling services
 /// for moving instances to and from the wire.  Currently, the only format
-/// supported is JSON, however the class provides an interface such that other
-/// formats can be readily supported.
+/// supported is JSON detailed here isc::dhcp_ddns::NameChangeRequest::fromJSON
+/// The class provides an interface such that other formats can be readily
+/// supported.
 class NameChangeRequest {
 public:
     /// @brief Default Constructor.
@@ -295,13 +296,15 @@ public:
     /// @brief Instance method for marshalling the contents of the request
     /// into the given buffer in the given format.
     ///
-    /// When the format is:
+    /// Whe the format is:
     ///
     /// JSON: Upon completion, the buffer will contain a two byte unsigned
     /// integer which specifies the length of the JSON text; followed by the
     /// JSON text itself. The JSON text contains the names and values for all
     /// the request data needed to reassemble the request on the receiving
-    /// end. The JSON text in the buffer is NOT null-terminated.
+    /// end. The JSON text in the buffer is NOT null-terminated.  The format
+    /// is identical that described under
+    /// isc::dhcp_ddns::NameChangeRequest::fromJSON
     ///
     /// (NOTE currently only JSON is supported.)
     ///
@@ -312,7 +315,75 @@ public:
                   isc::util::OutputBuffer& buffer) const;
 
     /// @brief Static method for creating a NameChangeRequest from a
-    /// string containing a JSON rendition of a request.
+    /// string containing a JSON rendition of a request.  The JSON content
+    /// expected is described below:
+    ///
+    /// A request must be enclosed within curly brackets "{..}" (Whitespace
+    /// is optional but used here for clarity).
+    ///
+    /// @code
+    ///     {
+    ///      "change_type" : <type>,
+    ///      "forward_change" : <boolean>,
+    ///      "reverse_change" : <boolean>,
+    ///      "fqdn" : "<fqdn>" ,
+    ///      "ip_address" : "<ip>",
+    ///      "dhcid" : "<hex_string>",
+    ///      "lease_expires_on" : "<yyyymmddHHMMSS>",
+    ///      "lease_length" : <secs>
+    ///     }
+    /// @endcode
+    ///
+    /// - type - integer 0 or 1: 0 to add/update DNS entries, 1 to remove DNS
+    ///   entries
+    /// - boolean - case insensitve "true" or "false"
+    /// - ip - IPv4 or IPv6 address: "192.168.0.1" or "2001:db8:1::2"
+    /// - fqdn - Fully qualified domain name such as "myhost.example.com.".
+    /// - (Note that a trailing dot will be appended if not supplied)
+    /// - hex_string - a string containing an even number of hexadecimal
+    ///   digits without delimiters such as "2C010203040A7F8E3D" (case
+    ///   insensitive)
+    /// - yyyymmddHHMMSS date and time:
+    ///     - yyyy - four digit year
+    ///     - mm - month of year (1-12),
+    ///     - dd - day of the month (1-31),
+    ///     - HH - hour of the day (0-23)
+    ///     - MM - minutes of the hour (0-59)
+    ///     - SS - seconds of the minute (0-59)
+    /// - secs - duration of the lease in seconds between 1 and 4294967295
+    /// (2^32 - 1), inclusive
+    ///
+    ///  Examples:
+    ///
+    ///  Valid Remove with an IPv4 address, foward DNS only:
+    ///
+    /// @code
+    ///  {
+    ///     "change_type" : 1,
+    ///     "forward_change" : true,
+    ///     "reverse_change" : false,
+    ///     "fqdn" : "myhost.example.com.",
+    ///     "ip_address" : "192.168.2.1" ,
+    ///     "dhcid" : "010203040A7F8E3D" ,
+    ///     "lease_expires_on" : "20130121132405",
+    ///     "lease_length" : 1300
+    ///  }
+    /// @endcode
+    ///
+    ///  Valid Add with an IPv6 address, both forward and reverse DNS:
+    ///
+    /// @code
+    ///  {
+    ///     "change_type" : 0,
+    ///     "forward_change" : true,
+    ///     "reverse_change" : true,
+    ///     "fqdn" : "someother.example.com.",
+    ///     "ip_address" : "2001::db8:1::2",
+    ///     "dhcid" : "010203040A7F8E3D" , "
+    ///     "lease_expires_on" : "20130121132405",
+    ///     "lease_length" : 27400
+    ///   }
+    /// @endcode
     ///
     /// @param json is a string containing the JSON text
     ///