[5100] Documented control_command_receive hook.

diff --git a/src/bin/dhcp4/dhcp4_hooks.dox b/src/bin/dhcp4/dhcp4_hooks.dox
index 1fa6d07ebe0e3382c8050089fbe094656a317eba..5217d1c7bd8e39c9003d8d465bc1c2f4177aacec 100644 (file)
--- a/src/bin/dhcp4/dhcp4_hooks.dox
+++ b/src/bin/dhcp4/dhcp4_hooks.dox
@@ -1,4 +1,4 @@
-// Copyright (C) 2013-2016 Internet Systems Consortium, Inc. ("ISC")
+// Copyright (C) 2013-2017 Internet Systems Consortium, Inc. ("ISC")
 //
 // This Source Code Form is subject to the terms of the Mozilla Public
 // License, v. 2.0. If a copy of the MPL was not distributed with this
@@ -292,6 +292,35 @@ to the end of this list.
   expired leases will remain in the database and their recovery will
   be attempted during the next reclaim cycle.
 
+@subsection dhcpv4HooksControlCommandReceive control_command_receive
+
+ - @b Arguments:
+   - name: @b command, type: isc::data::ConstElementPtr, direction: <b>in</b>
+   - name: @b response, type: isc::data::ConstElementPtr, direction: <b>in/out</b>
+
+ - @b Description: this callout is executed when DHCPv4 server receives a
+   control command over the command channel (typically unix domain socket).
+   The "command" argument is a pointer to the parsed JSON structure
+   including command name and command arguments. If the callout implements
+   the specified command, it handles the command and creates appropriate
+   response. The response should be returned in the "response" argument.
+   In most cases, the callout which handles the command will set the next
+   step action to SKIP, to prevent the server from trying to handle the
+   command on its own and overriding the response created by the callouts.
+   A notable exception is the 'list-commands' command for which the callouts
+   should not set the next step action to SKIP. The server has a special
+   code path for this command which combines the list of commands returned
+   by the callouts with the list of commands supported by the server. If
+   the callout sets the next step action to SKIP in this case, the server
+   will only return the list of commands supported by the hook library.
+
+ - <b>Next step status</b>: if any callout sets the next step action to SKIP,
+   the server will assume that the command has been handled by the callouts
+   and will expect that the response is provided in the "response" argument.
+   The server will not handle the command in this case but simply return the
+   response returned by the callout to the caller.
+
+
 @section dhcpv4HooksOptionsAccess Accessing DHCPv4 Options within a Packet
 When the server constructs a response message to a client it includes
 DHCP options configured for this client in a response message. Apart

diff --git a/src/bin/dhcp6/dhcp6_hooks.dox b/src/bin/dhcp6/dhcp6_hooks.dox
index 5b3142f538a2684fbaa6401c9b0051f936f2f280..44b07779ea6334ede667e9cebab59ffe03f61034 100644 (file)
--- a/src/bin/dhcp6/dhcp6_hooks.dox
+++ b/src/bin/dhcp6/dhcp6_hooks.dox
@@ -1,4 +1,4 @@
-// Copyright (C) 2013-2016 Internet Systems Consortium, Inc. ("ISC")
+// Copyright (C) 2013-2017 Internet Systems Consortium, Inc. ("ISC")
 //
 // This Source Code Form is subject to the terms of the Mozilla Public
 // License, v. 2.0. If a copy of the MPL was not distributed with this
@@ -334,6 +334,35 @@ to the end of this list.
   expired leases will remain in the database and their recovery will
   be attempted during the next reclaim cycle.
 
+@subsection dhcpv6HooksControlCommandReceive control_command_receive
+
+ - @b Arguments:
+   - name: @b command, type: ConstElementPtr, direction: <b>in</b>
+   - name: @b response, type: ConstElementPtr, direction: <b>in/out</b>
+
+ - @b Description: this callout is executed when DHCPv4 server receives a
+   control command over the command channel (typically unix domain socket).
+   The "command" argument is a pointer to the parsed JSON structure
+   including command name and command arguments. If the callout implements
+   the specified command, it handles the command and creates appropriate
+   response. The response should be returned in the "response" argument.
+   In most cases, the callout which handles the command will set the next
+   step action to SKIP, to prevent the server from trying to handle the
+   command on its own and overriding the response created by the callouts.
+   A notable exception is the 'list-commands' command for which the callouts
+   should not set the next step action to SKIP. The server has a special
+   code path for this command which combines the list of commands returned
+   by the callouts with the list of commands supported by the server. If
+   the callout sets the next step action to SKIP in this case, the server
+   will only return the list of commands supported by the hook library.
+
+ - <b>Next step status</b>: if any callout sets the next step action to SKIP,
+   the server will assume that the command has been handled by the callouts
+   and will expect that the response is provided in the "response" argument.
+   The server will not handle the command in this case but simply return the
+   response returned by the callout to the caller.
+
+
 @section dhcpv6HooksOptionsAccess Accessing DHCPv6 Options within a Packet
 When the server constructs a response message to a client it includes
 DHCP options configured for this client in a response message. Apart