Commit 0ea00066 authored by Stephen Morris's avatar Stephen Morris

[3505] Documentation edits made during review

parent 0fbb0c3e
......@@ -89,13 +89,13 @@
* - @subpage leasemgr
* - @subpage cfgmgr
* - @subpage allocengine
* - @subpage libdhcp_ddns
* - @subpage dhcpDatabaseBackends
* - @subpage configBackend
* - @subpage configBackendMotivation
* - @subpage configBackendJSONDesign
* - @subpage configBackendAdding
* - @subpage perfdhcpInternals
* - @subpage libdhcp_ddns
*
* @section miscellaneousTopics Miscellaneous Topics
* - @subpage logKeaLogging
......
......@@ -13,21 +13,26 @@
// PERFORMANCE OF THIS SOFTWARE.
/**
@page libdhcp_ddns DHCP_DDNS Request IO Library
@page libdhcp_ddns libdhcp_ddns - DHCP_DDNS Request I/O Library
@section libdhcp_ddnsIntro Libdhcp_ddns Library Introduction
@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:
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
- 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 (TTL)
- 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
......@@ -40,22 +45,18 @@ 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
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, 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 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.
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.
*/
......@@ -315,47 +315,61 @@ public:
isc::util::OutputBuffer& buffer) const;
/// @brief Static method for creating a NameChangeRequest from a
/// string containing a JSON rendition of a request. The JSON content
/// expected is described below:
/// string containing a JSON rendition of a request.
///
/// A request must be enclosed within curly brackets "{..}" (Whitespace
/// is optional but used here for clarity).
/// The JSON expected is described below. Note that a request must be
/// enclosed within curly brackets "{..}" and that whitespace is optional
/// (it is used in the following examples for clarity).
///
/// @code
/// {
/// "change_type" : <type>,
/// "change_type" : <integer>,
/// "forward_change" : <boolean>,
/// "reverse_change" : <boolean>,
/// "fqdn" : "<fqdn>" ,
/// "ip_address" : "<ip>",
/// "fqdn" : "<fqdn>",
/// "ip_address" : "<address>",
/// "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:
/// - change_type - indicates whether this request is to add or update
/// DNS entries or to remove them. The value is an integer and is
/// 0 for add/update and 1 for remove.
/// - forward_change - indicates whether the the forward (name to
/// address) DNS zone should be updated. The value is a string
/// representing a boolean. It is "true" if the zone should be updated
/// and "false" if not. (Unlike the keyword, the boolean value is
/// case-insensitive.)
/// - reverse_change - indicates whether the the reverse (address to
/// name) DNS zone should be updated. The value is a string
/// representing a boolean. It is "true" if the zone should be updated
/// and "false" if not. (Unlike the keyword, the boolean value is
/// case-insensitive.)
/// - fqdn - fully qualified domain name such as "myhost.example.com.".
/// (Note that a trailing dot will be appended if not supplied.)
/// - ip_address - the IPv4 or IPv6 address of the client. The value
/// is a string representing the IP address (e.g. "192.168.0.1" or
/// "2001:db8:1::2").
/// - dhcid - identification of the DHCP client to whom the IP address has
/// been leased. The value is a string containing an even number of
/// hexadecimal digits without delimiters such as "2C010203040A7F8E3D"
/// (case insensitive).
/// - lease_expires_on - the date and time on which the lease expires.
/// The value is a string of the form "yyyymmddHHMMSS" where:
/// - 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
/// - lease_length - the length of the lease in seconds. This is an
/// integer and may range between 1 and 4294967295 (2^32 - 1) inclusive.
///
/// Examples:
/// Examples:
///
/// Valid Remove with an IPv4 address, foward DNS only:
/// Removal of an IPv4 address from the forward DNS zone only:
///
/// @code
/// {
......@@ -370,7 +384,7 @@ public:
/// }
/// @endcode
///
/// Valid Add with an IPv6 address, both forward and reverse DNS:
/// Addition of an IPv6 address to both forward and reverse DNS zones:
///
/// @code
/// {
......
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