Browse Source

[2995] Editorial changes to the DHCPv6 hooks documentation.

Stephen Morris 12 years ago
parent
commit
78fdf6daaf
1 changed files with 49 additions and 46 deletions
  1. 49 46
      src/bin/dhcp6/dhcp6_hooks.dox

+ 49 - 46
src/bin/dhcp6/dhcp6_hooks.dox

@@ -18,13 +18,14 @@
  @section dhcpv6HooksIntroduction Introduction
  @section dhcpv6HooksIntroduction Introduction
  BIND10 features an API (the "Hooks" API) that allows user-written code to
  BIND10 features an API (the "Hooks" API) that allows user-written code to
  be integrated into BIND 10 and called at specific points in its processing.
  be integrated into BIND 10 and called at specific points in its processing.
- An overview of the API and a tutorial for writing generalised hook code can
- API can be found in @ref hooksDevelopersGuide and @ref hooksComponentDeveloperGuide.
+ An overview of the API and a tutorial for writing such code can be found in
+ the @ref hooksDevelopersGuide.  Information for BIND 10 maintainers can be
+ found in the @ref hooksComponentDeveloperGuide.
 
 
  This manual is more specialised and is aimed at developers of hook
  This manual is more specialised and is aimed at developers of hook
- code for the DHCPv6 server. It describes each hook point, the callouts
- attached to the hook are able to do, and the arguments passed  to them.
- Each entry in this manual has the following information:
+ code for the DHCPv6 server. It describes each hook point, what the callouts
+ attached to the hook are able to do, and the arguments passed to the
+ callouts.  Each entry in this manual has the following information:
 
 
  - Name of the hook point.
  - Name of the hook point.
  - Arguments for the callout.  As well as the argument name and data type, the
  - Arguments for the callout.  As well as the argument name and data type, the
@@ -36,9 +37,9 @@
      value the callout sends back.  Note that the callout may choose not to
      value the callout sends back.  Note that the callout may choose not to
      do any modification, in which case the server will use whatever value
      do any modification, in which case the server will use whatever value
      it sent to the callout.
      it sent to the callout.
- - Description: a description of the hook, including where in the processing
-   it is called, a description of the data available, and the possible
-   actions a callout attached to this hook could take.
+ - Description of the hook. This explains where in the processing the hook
+   is located, the possible actions a callout attached to this hook could take,
+   and a description of the data passed to the callouts.
  - Skip flag action: the action taken by the server if a callout chooses to set
  - Skip flag action: the action taken by the server if a callout chooses to set
     the "skip" flag.
     the "skip" flag.
 
 
@@ -55,18 +56,19 @@ packet processing. Hook points that are not specific to packet processing
 
 
  - @b Description: this callout is executed when an incoming DHCPv6
  - @b Description: this callout is executed when an incoming DHCPv6
    packet is received and its content is parsed. The sole argument -
    packet is received and its content is parsed. The sole argument -
-   pkt6 - contains a pointer to an isc::dhcp::Pkt6 object that contains all
-   information regarding incoming packet, including its source and
+   query6 - contains a pointer to an isc::dhcp::Pkt6 object that contains
+   all information regarding incoming packet, including its source and
    destination addresses, interface over which it was received, a list
    destination addresses, interface over which it was received, a list
-   of all options present within and relay information. See Pkt6 class
-   definition for details. All fields of the Pkt6 class can be
-   modified at this time, except data_ (which contains incoming packet
-   as raw buffer, but that information was already parsed, so it
-   doesn't make sense to modify it at this time).
+   of all options present within and relay information.  All fields of
+   the Pkt6 object can be modified at this time, except data_. (data_
+   contains the incoming packet as raw buffer. By the time this hook is
+   reached, that information has already parsed and is available though
+   other fields in the Pkt6 object.  For this reason, it doesn't make
+   sense to modify it.)
 
 
  - <b>Skip flag action</b>: If any callout sets the skip flag, the server will
  - <b>Skip flag action</b>: If any callout sets the skip flag, the server will
-   drop the packet and will not do anything with it except logging a drop
-   reason if debugging is enabled.
+   drop the packet and start processing the next one.  The reason for the drop
+   will be logged if logging is set to the appropriate debug level.
 
 
 @subsection dhcpv6HooksSubnet6Select subnet6_select
 @subsection dhcpv6HooksSubnet6Select subnet6_select
 
 
@@ -76,10 +78,10 @@ packet processing. Hook points that are not specific to packet processing
    - name: @b subnet6collection, type: const isc::dhcp::Subnet6Collection&, direction: <b>in</b>
    - name: @b subnet6collection, type: const isc::dhcp::Subnet6Collection&, direction: <b>in</b>
 
 
  - @b Description: this callout is executed when a subnet is being
  - @b Description: this callout is executed when a subnet is being
-   selected for incoming packet. All parameters, addresses and
-   prefixes will be assigned from that subnet. Callout can select a
-   different subnet if it wishes so. The list of all subnets currently
-   configured is provided as 'subnet6collection'. The list itself must
+   selected for the incoming packet. All parameters, addresses and
+   prefixes will be assigned from that subnet. A callout can select a
+   different subnet if it wishes so, the list of all subnets currently
+   configured being provided as 'subnet6collection'. The list itself must
    not be modified.
    not be modified.
 
 
  - <b>Skip flag action</b>: If any callout installed on 'subnet6_select'
  - <b>Skip flag action</b>: If any callout installed on 'subnet6_select'
@@ -95,17 +97,18 @@ packet processing. Hook points that are not specific to packet processing
    - name: @b lease6, type: isc::dhcp::Lease6Ptr, direction: <b>in/out</b>
    - name: @b lease6, type: isc::dhcp::Lease6Ptr, direction: <b>in/out</b>
 
 
  - @b Description: this callout is executed after the server engine
  - @b Description: this callout is executed after the server engine
-   has selected a lease for client's request but before the lease has
-   been inserted into the database. Any modifications made to the
-   Lease6 object will be directly inserted into database. The callout should
-   make sure that any modifications are sanity checked as the
-   server will use that data as is with no further checking.\n\n
-   The server processes lease requests for SOLICIT and REQUEST in a very
-   similar way. The only major difference is that for SOLICIT the
-   lease is just selected but it is not inserted into database.  It is
-   possible to distinguish between SOLICIT and REQUEST by checking value
-   of fake_allocation flag: true means that the lease won't be interested
-   into database (SOLICIT), false means that it will (REQUEST).
+   has selected a lease for client's request but before the lease
+   has been inserted into the database. Any modifications made to the
+   isc::dhcp::Lease6 object will be stored in the lease's record in the
+   database. The callout should make sure that any modifications are
+   sanity checked as the server will use that data as is with no further
+   checking.\n\n The server processes lease requests for SOLICIT and
+   REQUEST in a very similar way. The only major difference is that
+   for SOLICIT the lease is just selected; it is not inserted into
+   the database.  It is possible to distinguish between SOLICIT and
+   REQUEST by checking value of the fake_allocation flag: a value of true
+   means that the lease won't be inserted into the database (SOLICIT),
+   a value of false means that it will (REQUEST).
 
 
  - <b>Skip flag action</b>: the "skip" flag is ignored by the server on this
  - <b>Skip flag action</b>: the "skip" flag is ignored by the server on this
    hook.
    hook.
@@ -116,19 +119,19 @@ packet processing. Hook points that are not specific to packet processing
    - name: @b response6, type: isc::dhcp::Pkt6Ptr, direction: <b>in/out</b>
    - name: @b response6, type: isc::dhcp::Pkt6Ptr, direction: <b>in/out</b>
 
 
  - @b Description: this callout is executed when server's response
  - @b Description: this callout is executed when server's response
-   is about to be send back to the client. The sole argument - pkt6 -
-   contains a pointer to Pkt6 class that contains packet, with set
-   source and destination addresses, interface over which it will be
-   send, list of all options and relay information. (See the isc::dhcp::Pkt6
-   class definition for details.) All fields of the Pkt6 class can be
-   modified at this time, except bufferOut_.  (This is scratch space used for
-   constructing the packet after all pkt6_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 drop this response packet. However, the original
-   request packet from a client was processed, so server's state was likely
-   changed (e.g. lease was allocated). This flag will merely stop the
-   change to be communicated to the client.
+   is about to be send back to the client. The sole argument - response6 -
+   contains a pointer to an isc::dhcp::Pkt6 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.  All fields
+   of the Pkt6 object can be modified at this time, except bufferOut_.
+   (This is scratch space used for constructing the packet after all
+   pkt6_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 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.
 
 
 */
 */