Commit 78fdf6da authored by Stephen Morris's avatar Stephen Morris
Browse files

[2995] Editorial changes to the DHCPv6 hooks documentation.

parent 72b06693
......@@ -18,13 +18,14 @@
@section dhcpv6HooksIntroduction Introduction
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.
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
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.
- 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
do any modification, in which case the server will use whatever value
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
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
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
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
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
......@@ -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>
- @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.
- <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>
- @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
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>
- @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.
*/
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