From: Marcin Siodelski <marcin@isc.org>
Date: Mon, 9 Nov 2015 13:43:21 +0000 (+0100)
Subject: [4106] Improved documentation of the base IPC class.
X-Git-Tag: trac4296_base~2^2~8
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=0ceff3ccadae83a920d938831e7d0c8ef521855e;p=thirdparty%2Fkea.git

[4106] Improved documentation of the base IPC class.
---

diff --git a/src/lib/dhcpsrv/dhcp4o6_ipc.h b/src/lib/dhcpsrv/dhcp4o6_ipc.h
index 8a6e7f48ee..40b2b5fde0 100644
--- a/src/lib/dhcpsrv/dhcp4o6_ipc.h
+++ b/src/lib/dhcpsrv/dhcp4o6_ipc.h
@@ -35,8 +35,36 @@ public:
         isc::Exception(file, line, what) { };
 };
 
-/// @brief 
+/// @brief Base class implementing transmission of the DHCPv4 over
+/// DHCPv6 messages (RFC 7341) between the Kea servers.
 ///
+/// When the DHCPv6 server receives the DHCPv4 query message it needs
+/// to forward it to the DHCPv4 server for processing. The DHCPv4
+/// server processes the message and responds with the DHCPv4 response
+/// message to the DHCPv6 server. The server forwards it back to the
+/// client. This class implements the communication between the DHCPv4
+/// and DHCPv6 servers to allow for transmission of the DHCPv4 query
+/// and DHCPv6 response messages.
+///
+/// This class creates a socket (when @c open is called) and binds it
+/// to a port, depending on the configuration. The port number is
+/// explicitly specified in the server configuration. This explicit
+/// port value is used directly on the DHCPv6 server side. The DHCPv4
+/// server uses the port specified + 1.
+///
+/// The DHCPv4 and DHCPv6 servers use distict instances of classes derived
+/// from this base class. Each of these instances is used to send and
+/// receive messages sent by the other server.
+///
+/// In order to make address allocation decisions, the DHCPv4 server
+/// requires information about the interface and the source address of
+/// the original DHCPv4 query message sent by the client. This
+/// information is known by the DHCPv6 server and needs to be conveyed
+/// to the DHCPv4 server. The IPC conveys it in the
+/// @c ISC_V6_4O6_INTERFACE and @c ISC_V6_4O6_SRC_ADDRESS options
+/// within the Vendor Specific Information option, with ISC
+/// enterprise id. These options are added by the IPC sender and removed
+/// by the IPC receiver.
 class Dhcp4o6IpcBase : public boost::noncopyable {
 protected:
     /// @brief Constructor
@@ -47,38 +75,48 @@ protected:
     /// @brief Destructor.
     virtual ~Dhcp4o6IpcBase();
 
-    /// @brief Open communication socket (from base class)
+    /// @brief Open communication socket (from base class).
     ///
-    /// @param port port number to use (0 for disabled)
-    /// @param side side of the server (4 or 6)
+    /// @param port Port number to use. The socket is bound to this port
+    /// if the endpoint type is DHCPv6 server, otherwise the port + 1
+    /// value is used.
+    /// @param side Endpoint type (DHCPv4 or DHCPv6 server).
     ///
-    /// @return new socket descriptor
+    /// @return New socket descriptor.
     int open(const uint16_t port, const int side);
 
 public:
-    /// @brief Open communication socket (for derived classes)
+
+    /// @brief Open communication socket (for derived classes).
     virtual void open() = 0;
 
-    /// @brief Close communication socket
+    /// @brief Close communication socket.
     void close();
 
-    /// @brief Receive IPC message
+    /// @brief Receive message over IPC.
     ///
     /// @return a pointer to a DHCPv6 message with interface and remote
     /// address set from the IPC message
     Pkt6Ptr receive();
 
-    /// @brief Send IPC message
+    /// @brief Send message over IPC.
+    ///
+    /// The IPC uses @c ISC_V6_4O6_INTERFACE and @c ISC_V6_4O6_SRC_ADDRESS
+    /// options conveyed within the Vendor Specific Information option, with
+    /// ISC enterprise id, to communicate the client remote address and the
+    /// interface on which the DHCPv4 query was received. These options will
+    /// be removed by the receiver.
     ///
-    /// @param a pointer to a DHCPv6 message with interface and remote
-    /// address set for the IPC message
+    /// @param pkt Pointer to a DHCPv6 message with interface and remote
+    /// address.
     void send(const Pkt6Ptr& pkt);
 
 protected:
-    /// @brief Port number
+
+    /// @brief Port number configured for IPC communication.
     uint16_t port_;
 
-    /// @brief Socket descriptor
+    /// @brief Socket descriptor.
     int socket_fd_;
 };