Commit 0fbb0c3e authored by Thomas Markwalder's avatar Thomas Markwalder

[3505] Documented JSON format of NameChangeRequest

Documented JSON "schema" for isc::dhcp_ddns::NameChangeRequests
and added explanation of NCR members to D2 doxygen
parent 35860175
// 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.
*/
......@@ -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
///
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment