From: Thomas Markwalder Date: Fri, 1 Aug 2014 14:24:33 +0000 (-0400) Subject: [3505] Documented JSON format of NameChangeRequest X-Git-Tag: trac3482_base~59^2~1 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=0fbb0c3e7453abdfe478d771ce8aa898c4e4a1fa;p=thirdparty%2Fkea.git [3505] Documented JSON format of NameChangeRequest Documented JSON "schema" for isc::dhcp_ddns::NameChangeRequests and added explanation of NCR members to D2 doxygen --- diff --git a/src/lib/dhcp_ddns/libdhcp_ddns.dox b/src/lib/dhcp_ddns/libdhcp_ddns.dox index af7c94342f..bdf5d2b291 100644 --- a/src/lib/dhcp_ddns/libdhcp_ddns.dox +++ b/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. */ diff --git a/src/lib/dhcp_ddns/ncr_msg.h b/src/lib/dhcp_ddns/ncr_msg.h index 7fd6f64744..79ff39e170 100644 --- a/src/lib/dhcp_ddns/ncr_msg.h +++ b/src/lib/dhcp_ddns/ncr_msg.h @@ -230,8 +230,9 @@ typedef std::map 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" : , + /// "forward_change" : , + /// "reverse_change" : , + /// "fqdn" : "" , + /// "ip_address" : "", + /// "dhcid" : "", + /// "lease_expires_on" : "", + /// "lease_length" : + /// } + /// @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 ///