[2983] Developer's Guide updated, ChangeLog proposal added.

diff --git a/ChangeLog b/ChangeLog
index 1ce395900f0a5a7c50c7a61e155e587571acd74d..d775692a65499124c66fd3ceb35cb9318f11bb0b 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+6XX.   [func]          tomek
+       Additional hooks (buffer4_receive, lease4_renew,
+       lease4_release, buffer4_send) added to the DHCPv4 server.
+       (Trac #2983, git ABCD)
+
 659.   [func]          stephen
        Added capability to configure the hooks libraries for the b10-dhcp4 and
        b10-dhcp6 servers through the BIND 10 configuration mechanism.

diff --git a/src/bin/dhcp4/dhcp4_hooks.dox b/src/bin/dhcp4/dhcp4_hooks.dox
index 85fcfc46e74f60c0e958a7a17d2dd073048f08cd..10d05f3abbc2a7d13953fea99d2ac6549ea167d3 100644 (file)
--- a/src/bin/dhcp4/dhcp4_hooks.dox
+++ b/src/bin/dhcp4/dhcp4_hooks.dox
@@ -49,6 +49,29 @@ The following list is ordered by appearance of specific hook points during
 packet processing. Hook points that are not specific to packet processing
 (e.g. lease expiration) will be added to the end of this list.
 
+ @subsection dhcpv4HooksBuffer4Receive buffer4_receive
+
+ - @b Arguments:
+   - name: @b query4, type: isc::dhcp::Pkt4Ptr, direction: <b>in/out</b>
+
+ - @b Description: this callout is executed when an incoming DHCPv4
+   buffer is received, before its content is parsed. The sole argument
+   - query4 - contains a pointer to an isc::dhcp::Pkt4 object that
+   contains raw information regarding incoming packet, including its
+   source and destination addresses, interface over which it was
+   received, and a raw buffer stored in data_ field. None of the
+   packet fields (op_, hlen_, chaddr_, etc.) are set yet. Callouts
+   installed on this hook point can modify the incoming buffer. The
+   server will parse the buffer afterwards.
+
+ - <b>Skip flag action</b>: If any callout sets the skip flag, the server will
+   skip the buffer parsing. In such case there is an expectation that
+   the callout will parse the buffer and create option objects (see
+   isc::dhcp::Pkt4::addOption()). Otherwise the server will find out
+   that some mandatory options are missing (e.g. DHCP Message Type) and
+   will drop the packet. If you want to have the capability to drop
+   a message, it is better to use skip flag in pkt4_receive callout.
+
  @subsection dhcpv4HooksPkt4Receive pkt4_receive
 
  - @b Arguments:
@@ -114,6 +137,41 @@ packet processing. Hook points that are not specific to packet processing
    sets the skip flag, the server will not assign any lease. Packet
    processing will continue, but client will not get an address.
 
+@subsection dhcpv4HooksLeaseRenew lease4_renew
+
+ - @b Arguments:
+   - name: @b subnet4, type: isc::dhcp::Subnet4Ptr, direction: <b>in</b>
+   - name: @b clientid, type: isc::dhcp::ClientId, direction: <b>in</b>
+   - name: @b hwaddr, type: isc::dhcp::HWAddr, direction: <b>in</b>
+   - name: @b lease4, type: isc::dhcp::Lease4Ptr, direction: <b>in/out</b>
+
+ - @b Description: this callout is executed when the server engine
+   is about to renew a lease, as a result of receiving REQUEST/Renewing
+   packet. The lease4 argument points to Lease4 object that contains
+   the updated values. Callout can modify those values. Care should be taken
+   as the server will attempt to update the lease in the database without
+   any additional checks.
+
+ - <b>Skip flag action</b>: If any callout installed on 'lease4_renew'
+   sets the skip flag, the server will not update the lease and will
+   use old values instead.
+
+@subsection dhcpv4HooksLeaseRelease lease4_release
+
+ - @b Arguments:
+   - name: @b query4, type: isc::dhcp::Pkt4Ptr, direction: <b>in</b>
+   - name: @b lease4, type: isc::dhcp::Lease4Ptr, direction: <b>in</b>
+
+ - @b Description: this callout is executed when the server engine
+   is about to release a lease, as a result of receiving RELEASE packet.
+   The lease4 argument points to Lease4 object that contains the lease to
+   be released. It doesn't make sense to modify it at this time.
+
+ - <b>Skip flag action</b>: If any callout installed on 'lease4_release'
+   sets the skip flag, the server will not delete the lease. It will be
+   kept in the database and will go through the regular expiration/reuse
+   process.
+
 @subsection dhcpv4HooksPkt4Send pkt4_send
 
  - @b Arguments:
@@ -129,10 +187,30 @@ packet processing. Hook points that are not specific to packet processing
    pkt4_send callouts are complete, so any changes to that field will
    be overwritten.)
 
+ - <b>Skip flag action</b>: if any callout sets the skip flag, the server
+   will not construct raw buffer. The expectation is that if the callout
+   set skip flag, it is responsible for constructing raw form on its own.
+   Otherwise the output packet will be sent with zero length.
+
+@subsection dhcpv4HooksBuffer4Send buffer4_send
+
+ - @b Arguments:
+   - name: @b response4, type: isc::dhcp::Pkt4Ptr, direction: <b>in/out</b>
+
+ - @b Description: this callout is executed when server's response
+   is about to be send back to the client. The sole argument - response4 -
+   contains a pointer to an isc::dhcp::Pkt4 object that contains the
+   packet, with set source and destination addresses, interface over which
+   it will be send, list of all options and relay information. The raw
+   on-wire form is already prepared in bufferOut_ (see isc::dhcp::Pkt4::getBuffer())
+   It doesn't make any sense to modify packet fields or options content
+   at this time, because they were already used to construct on-wire buffer.
+
  - <b>Skip flag action</b>: if any callout sets the skip flag, the server
    will drop this response packet. However, the original request packet
    from a client was processed, so server's state was most likely changed
    (e.g. lease was allocated). Setting this flag merely stops the change
    being communicated to the client.
 
+
 */