Commit 0fcceb6b authored by Marcin Siodelski's avatar Marcin Siodelski

[3484] Updated description of hooks for DHCPv4 and DHCPv6 server.

parent 0d9d7115
// Copyright (C) 2013 Internet Systems Consortium, Inc. ("ISC")
// Copyright (C) 2013-2015 Internet Systems Consortium, Inc. ("ISC")
//
// Permission to use, copy, modify, and/or distribute this software for any
// purpose with or without fee is hereby granted, provided that the above
......@@ -22,7 +22,7 @@
the @ref hooksdgDevelopersGuide. Information for Kea maintainers can be
found in the @ref hooksComponentDeveloperGuide.
This manual is more specialised and is aimed at developers of hook
This manual is more specialized and is aimed at developers of hook
code for the DHCPv4 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:
......@@ -54,23 +54,25 @@ packet processing. Hook points that are not specific to packet processing
- @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 Description: this callout is executed when the server has received a
buffer containing a DHCPv4 message, but the message hasn't been parsed
yet. The sole argument "query4" contains a pointer to the isc::dhcp::Pkt4
object, which contains the source and destination address of the
received packet, interface over which the packet has been received, and
a raw buffer, stored in the data_ field, containing the DHCPv4 message
in the wire format. None of the packet fields (op_, hlen_, chaddr_, etc.)
are set yet. Callouts installed on this hook point can modify the data
in the received 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.
the callout will parse options carried in the buffer, create
@c isc::dhcp::Option objects (or derived) and add them to the "query4"
object using the @c 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 message. 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
......@@ -79,15 +81,14 @@ packet processing. Hook points that are not specific to packet processing
- @b Description: this callout is executed when an incoming DHCPv4
packet is received and its content has been parsed. The sole
argument - query4 - contains a pointer to an isc::dhcp::Pkt4 object
argument "query4" contains a pointer to an isc::dhcp::Pkt4 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
received, a list of all options present within and the relay
information. All fields of the Pkt4 object can be modified at this
time, except data_. (By the time this hook is reached, the contents
of the data_ field has been already parsed and stored in other
fields. Therefore, the modification in the data_ field has no
effect.)
time. By the time this hook is reached, the contents of the data_
field has been already parsed and stored in other fields. Therefore,
the modification in the data_ field has no effect.
- <b>Skip flag action</b>: If any callout sets the skip flag, the server will
drop the packet and start processing the next one. The reason for the drop
......@@ -98,19 +99,19 @@ packet processing. Hook points that are not specific to packet processing
- @b Arguments:
- name: @b query4, type: isc::dhcp::Pkt4Ptr, direction: <b>in/out</b>
- name: @b subnet4, type: isc::dhcp::Subnet4Ptr, direction: <b>in/out</b>
- name: @b subnet4collection, type: const isc::dhcp::Subnet4Collection *, direction: <b>in</b>
- name: @b subnet4collection, type: const isc::dhcp::Subnet4Collection *,
direction: <b>in</b>
- @b Description: this callout is executed when a subnet is being
selected for the incoming packet. All parameters and addresses
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 'subnet4collection'. The list itself must
different subnet if it wishes so. The list of all subnets currently
configured are provided as "subnet4collection". The list itself must
not be modified.
- <b>Skip flag action</b>: If any callout installed on 'subnet4_select'
- <b>Skip flag action</b>: If any callout, installed on "subnet4_select",
sets the skip flag, the server will not select any subnet. Packet processing
will continue, but will be severely limited (i.e. only global options
will be assigned).
will continue, but will be severely limited.
@subsection dhcpv4HooksLeaseSelect lease4_select
......@@ -120,22 +121,24 @@ packet processing. Hook points that are not specific to packet processing
- name: @b lease4, type: isc::dhcp::Lease4Ptr, 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
has selected a lease for the client's request, but before the lease has
been inserted into the database. Any modifications made to the
isc::dhcp::Lease4 object will be stored in the lease's record in
the database. The callout should sanity check all modifications as
the server will use that data as is with no further checking.\n\n
The server processes lease requests for DISCOVER and REQUEST in a
very similar way. The only major difference is that for DISCOVER
the lease is just selected, but not inserted into the database. It
is possible to distinguish between DISCOVER and REQUEST by checking
value of the fake_allocation flag: a value of true indicates that the
lease won't be inserted into the database (DISCOVER), a value of
false indicates that it will (REQUEST).
- <b>Skip flag action</b>: If any callout installed on 'lease4_select'
sets the skip flag, the server will not assign any lease. Packet
processing will continue, but client will not get an address.
"lease4" object will affect the lease's record in the database.
The callout should sanity check all modifications as the server will
use that data as is, with no further checking.\n\n
The server processes lease requests for DHCPDISCOVER and DHCPREQUEST in a
very similar way. The only major difference is that for DHCPDISCOVER
the lease is only selected, but not inserted into the database. The callouts
may distinguish between DHCPDISCOVER and DHCPREQUEST by checking the
value of the "fake_allocation" flag: a value of true indicates that the
lease won't be inserted into the database (DHCPDISCOVER case), a value of
false indicates that it will (DHCPREQUEST case).
- <b>Skip flag action</b>: If any callout installed on "lease4_select"
sets the skip flag, the server will not assign any lease and the callouts
become responsible for the lease assignment. If the callouts fail to provide
a lease, the packet processing will continue, but client will not get
an address.
@subsection dhcpv4HooksLeaseRenew lease4_renew
......@@ -146,15 +149,15 @@ packet processing. Hook points that are not specific to packet processing
- 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.
is about to renew a lease, as a result of receiving DHCPREQUEST/Renewing
packet. The "lease4" argument points to @c isc::dhcp::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.
- <b>Skip flag action</b>: If any callout installed on "lease4_renew"
sets the skip flag, the server will not update the lease in the
database and continue using old values instead.
@subsection dhcpv4HooksLeaseRelease lease4_release
......@@ -163,11 +166,11 @@ packet processing. Hook points that are not specific to packet processing
- 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
is about to release a lease, as a result of receiving DHCPRELEASE packet.
The "lease4" argument points to @c 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'
- <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.
......@@ -178,17 +181,17 @@ packet processing. Hook points that are not specific to packet processing
- 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 sent back to the client. The sole argument - response4 -
contains a pointer to an isc::dhcp::Pkt4 object that contains the
is about to be sent back to the client. The sole argument "response4"
contains a pointer to an isc::dhcp::Pkt4 object carrying the
packet, with source and destination addresses set, interface over which
it will be sent, and a list of all options and relay information. All fields
of the Pkt4 object can be modified at this time, except buffer_out_.
of the @c Pkt4 object can be modified at this time, except @c buffer_out_.
(This is scratch space used for constructing the packet after all
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
will not construct the 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.
......@@ -198,17 +201,19 @@ packet processing. Hook points that are not specific to packet processing
- 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 sent back to the client. The sole argument - response4 -
contains a pointer to an isc::dhcp::Pkt4 object that contains the
is about to be sent back to the client. The sole argument "response4"
contains a pointer to an @c isc::dhcp::Pkt4 object that contains the
packet, with source and destination addresses set, interface over which
it will be sent, and a list of all options and relay information. The raw
on-wire form is already prepared in buffer_out_ (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.
on-wire form is already prepared in @c buffer_out_ (see
@c isc::dhcp::Pkt4::getBuffer())
Callouts should not modify the packet fields or options contents at this
time, because they were already used to construct on-wire buffer. Their
modification would have no effect.
- <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
from a client was processed, so server's state most likely has changed
(e.g. lease was allocated). Setting this flag merely stops the change
being communicated to the client.
......
......@@ -55,25 +55,25 @@ packet processing. Hook points that are not specific to packet processing
- name: @b query6, type: isc::dhcp::Pkt6Ptr, direction: <b>in/out</b>
- @b Description: This callout is executed when an incoming DHCPv6
packet is received and the data stored in a buffer. The sole argument -
query6 - contains a pointer to an isc::dhcp::Pkt6 object that contains
packet is received and the data stored in a buffer. The sole argument
"query6" contains a pointer to an @c isc::dhcp::Pkt6 object that contains
the received information stored in the data_ field. Basic information
like protocol, source/destination addresses and ports are set, but
the contents of the buffer have not yet been parsed. That means that
the options_ field (that will eventually contain a list of objects
the @c options_ field (that will eventually contain a list of objects
representing the received options) is empty, so none of the methods
that operate on it (e.g., getOption()) will work. The primary purpose
of this early call is to offer the ability to modify incoming packets
in their raw form. Unless you need to access to the raw data, it is
usually better to install your callout on the pkt6_receive hook point.
usually better to install your callout on the "pkt6_receive" hook point.
- <b>Skip flag action</b>: If any callout sets the skip flag, the
server will assume that the callout parsed the buffer and added then
necessary option objects to the options_ field; the server will not
server will assume that the callout parsed the buffer and added the
necessary option objects to the @c options_ field; the server will not
do any parsing. If the callout sets the skip flag but does not parse
the buffer, the server will most probably drop the packet due to
the absence of mandatory options. If you want to drop the packet,
see the description of the skip flag in the pkt6_receive hook point.
see the description of the skip flag in the "pkt6_receive" hook point.
@subsection dhcpv6HooksPkt6Receive pkt6_receive
......@@ -81,16 +81,16 @@ packet processing. Hook points that are not specific to packet processing
- name: @b query6, type: isc::dhcp::Pkt6Ptr, direction: <b>in/out</b>
- @b Description: This callout is executed when an incoming DHCPv6
packet is received and its content is parsed. The sole argument -
query6 - contains a pointer to an isc::dhcp::Pkt6 object that contains
packet is received and its content is parsed. The sole argument
"query6" contains a pointer to an @c isc::dhcp::Pkt6 object that contains
all information regarding incoming packet, including its source and
destination addresses, the interface over which it was received, a list
of all options present within and relay information. All fields of
the Pkt6 object can be modified at this time, except data_. (data_
the "query6" 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 been parsed and is available though
other fields in the Pkt6 object. For this reason, it doesn't make
sense to modify it.)
other fields in the Pkt6 object. For this reason, modification of the
@c data_ field would have no effect.)
- <b>Skip flag action</b>: If any callout sets the skip flag, the server will
drop the packet and start processing the next one. The reason for the drop
......@@ -107,13 +107,12 @@ packet processing. Hook points that are not specific to packet processing
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
configured being provided as "subnet6collection". The list itself must
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"
sets the skip flag, the server will not select any subnet. Packet processing
will continue, but will be severely limited (i.e. only global options
will be assigned).
will continue, but will be severely limited.
@subsection dhcpv6HooksLease6Select lease6_select
......@@ -125,18 +124,18 @@ packet processing. Hook points that are not specific to packet processing
- @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
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
"lease6" object will affect 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>: If any callout installed on 'lease6_select'
REQUEST in a very similar way. The major difference is that
for SOLICIT the lease is only selected; it is not inserted into
the database. The callouts can distinguish between the SOLICIT and
REQUEST by checking the value of the "fake_allocation" flag: a value
of true means that the lease won't be inserted into the database
(SOLICIT case), a value of false means that it will (REQUEST).
- <b>Skip flag action</b>: If any callout installed on "lease6_select"
sets the skip flag, the server will not assign that particular lease.
Packet processing will continue and the client may get other addresses
or prefixes if it requested more than one address and/or prefix.
......@@ -150,26 +149,26 @@ packet processing. Hook points that are not specific to packet processing
- @b Description: This callout is executed when the server engine is
about to renew an existing lease. The client's request is provided as
the query6 argument and the existing lease with the appropriate fields
already modified is given in the lease6 argument. The final argument,
the "query6" argument and the existing lease with the appropriate fields
already modified is given in the "lease6" argument. The final argument,
ia_na, is the IA_NA option that will be sent back to the client.
Callouts installed on the lease6_renew may modify the content of
the lease6 object. Care should be taken however, as that modified
Callouts installed on the "lease6_renew" may modify the content of
the "lease6" object. Care should be taken however, as that modified
information will be written to the database without any further
checking. \n\n Although the envisaged usage assumes modification of T1,
T2, preferred and valid lifetimes only, other parameters associated
with the lease may be modified as well. The only exception is the addr_
with the lease may be modified as well. The only exception is the @c addr_
field, which must not be modified as it is used by the database to
select the existing lease to be updated. Care should also be taken to
modify the ia_na argument to match any changes in the lease6 argument.
modify the "ia_na" argument to match any changes in the "lease6" argument.
If a client sends more than one IA_NA option, callouts will be called
separately for each IA_NA instance. The callout will be called only
when the update is valid, i.e. conditions such as an invalid addresses
or invalid iaid renewal attempts will not trigger this hook point.
- <b>Skip flag action</b>: If any callout installed on 'lease6_renew'
- <b>Skip flag action</b>: If any callout installed on "lease6_renew"
sets the skip flag, the server will not renew the lease. Under these
circumstances, the callout should modify the ia_na argument to reflect
circumstances, the callout should modify the "ia_na" argument to reflect
this fact; otherwise the client will think the lease was renewed and continue
to operate under this assumption.
......@@ -181,12 +180,12 @@ packet processing. Hook points that are not specific to packet processing
- @b Description: This callout is executed when the server engine is
about to release an existing lease. The client's request is provided
as the query6 argument and the existing lease is given in the lease6
argument. Although the lease6 structure may be modified, it doesn't
as the "query6" argument and the existing lease is given in the "lease6"
argument. Although the "lease6" structure may be modified, it doesn't
make sense to do so as it will be destroyed immediately the callouts
finish execution.
- <b>Skip flag action</b>: If any callout installed on 'lease6_release'
- <b>Skip flag action</b>: If any callout installed on "lease6_release"
sets the skip flag, the server will not delete the lease, which will
remain in the database until it expires. However, the server will send out
the response back to the client as if it did.
......@@ -197,22 +196,22 @@ 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 - response6 -
contains a pointer to an isc::dhcp::Pkt6 object that contains the
is about to be send back to the client. The sole argument "response6"
contains a pointer to an @c 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. It should be noted that
unless the callout sets the skip flag (see below), anything placed in the
bufferOut_ field will be overwritten when the callout returns.
(bufferOut_ is scratch space used for constructing the packet.)
of the "response6" object can be modified at this time. It should be
noted that unless the callout sets the skip flag (see below), anything
placed in the @c buffer_out_ field will be overwritten when the callout
returns. (buffer_out_ is scratch space used for constructing the packet.)
- <b>Skip flag action</b>: If any callout sets the skip flag, the server
will assume that the callout did pack the transaction-id, message type and
option objects into the bufferOut_ field and will skip packing part.
will assume that the callout did pack the "transaction-id", "message type"
and option objects into the @c buffer_out_ field and will skip packing part.
Note that if the callout sets skip flag, but did not prepare the
output buffer, the server will send a zero sized message that will be
ignored by the client. If you want to drop the packet, please see
skip flag in the buffer6_send hook point.
skip flag in the "buffer6_send" hook point.
@subsection dhcpv6HooksBuffer6Send buffer6_send
......@@ -221,14 +220,14 @@ packet processing. Hook points that are not specific to packet processing
- @b Description: This callout is executed when server's response is
assembled into binary form and 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
client. The sole argument "response6" contains a pointer to an
@c isc::dhcp::Pkt6 object that contains the packet, with set source and
destination addresses, interface over which it will be sent, list of
all options and relay information. All options are already encoded
in bufferOut_ field. It doesn't make sense to modify anything but the
contents of bufferOut_ at this time (although if it is a requirement
in @c buffer_out_ field. It doesn't make sense to modify anything but the
contents of buffer_out_ at this time (although if it is a requirement
to modify that data, it will probably be found easier to modify the
option objects in a callout attached to the pkt6_send hook).
option objects in a callout attached to the "pkt6_send" hook).
- <b>Skip flag action</b>: If any callout sets the skip flag, the server
will drop this response packet. However, the original request packet
......
......@@ -100,11 +100,11 @@ shared library and loaded by Kea into its address space.
To illustrate how to write code that integrates with Kea, we will
use the following (rather contrived) example:
The Kea DHCPv4 server is used to allocate IPv4 addresses to clients
<i>The Kea DHCPv4 server is used to allocate IPv4 addresses to clients
(as well as to pass them other information such as the address of DNS
servers). We will suppose that we need to classify clients requesting
IPv4 addresses according to their hardware address, and want to log both
the hardware address and allocated IP address for the clients of interest.
the hardware address and allocated IP address for the clients of interest.</i>
The following sections describe how to implement these requirements.
The code presented here is not efficient and there are better ways of
......@@ -282,11 +282,11 @@ int callout(CalloutHandle& handle);
@endcode
(As before, the callout is declared with "C" linkage.) Information is passed
between Kea and the callout through name/value pairs in the CalloutHandle
between Kea and the callout through name/value pairs in the @c CalloutHandle
object. The object is also used to pass information between callouts on a
per-request basis. (Both of these concepts are explained below.)
A callout returns an "int" as a status return. A value of 0 indicates
A callout returns an @c int as a status return. A value of 0 indicates
success, anything else signifies an error. The status return has no
effect on server processing; the only difference between a success
and error code is that if the latter is returned, the server will
......@@ -296,7 +296,7 @@ error information to the Kea logging system.
@subsubsection hooksdgArguments Callout Arguments
The CalloutHandle object provides two methods to get and set the
The @c CalloutHandle object provides two methods to get and set the
arguments passed to the callout. These methods are called (naturally
enough) getArgument and SetArgument. Their usage is illustrated by the
following code snippets.
......@@ -336,27 +336,27 @@ In the callout
handle.setArgument("data_count", number);
@endcode
As can be seen "getArgument" is used to retrieve data from the
CalloutHandle, and setArgument used to put data into it. If a callout
As can be seen @c getArgument is used to retrieve data from the
@c CalloutHandle, and @c setArgument used to put data into it. If a callout
wishes to alter data and pass it back to the server, it should retrieve
the data with getArgument, modify it, and call setArgument to send
the data with @c getArgument, modify it, and call @c setArgument to send
it back.
There are several points to be aware of:
- the data type of the variable in the call to getArgument must match
the data type of the variable passed to the corresponding setArgument
- the data type of the variable in the call to @c getArgument must match
the data type of the variable passed to the corresponding @c setArgument
<B>exactly</B>: using what would normally be considered to be a
"compatible" type is not enough. For example, if the server passed
an argument as an "int" and the callout attempted to retrieve it as a
"long", an exception would be thrown even though any value that can
be stored in an "int" will fit into a "long". This restriction also
an argument as an @c int and the callout attempted to retrieve it as a
@c long, an exception would be thrown even though any value that can
be stored in an @c int will fit into a @c long. This restriction also
applies the "const" attribute but only as applied to data pointed to by
pointers, e.g. if an argument is defined as a "char*", an exception will
pointers, e.g. if an argument is defined as a @c char*, an exception will
be thrown if an attempt is made to retrieve it into a variable of type
"const char*". (However, if an argument is set as a "const int", it can
be retrieved into an "int".) The documentation of each hook point will
detail the data type of each argument.
@c const @c char*. (However, if an argument is set as a @c const @c int,
it can be retrieved into an @c int.) The documentation of each hook
point will detail the data type of each argument.
- Although all arguments can be modified, some altered values may not
be read by the server. (These would be ones that the server considers
"read-only".) Consult the documentation of each hook to see whether an
......@@ -371,8 +371,8 @@ parameters can be modified. As a general rule:
- Do not alter arguments unless you mean the change to be reflected in
the server.
- If you alter an argument, call CalloutHandle::setArgument to update the
value in the CalloutHandle object.
- If you alter an argument, call @c CalloutHandle::setArgument to update the
value in the @c CalloutHandle object.
@subsubsection hooksdgSkipFlag The "Skip" Flag
......@@ -391,7 +391,7 @@ is a server where a callout inspects the hardware address of the client
sending the packet and compares it against a black list; if the address
is on it, the callout notifies the server to drop the packet.
To handle these common cases, the CalloutHandle has a "skip" flag.
To handle these common cases, the @c CalloutHandle has a "skip" flag.
This is set by a callout when it wishes the server to skip normal
processing. It is set false by the hooks framework before callouts on a
hook are called. If the flag is set on return, the server will take the
......@@ -427,7 +427,7 @@ Future developments may have the server processing multiple packets
simultaneously, or to suspend processing on a packet and resume it at
a later time after other packets have been processed.
As well as argument information, the CalloutHandle object can be used by
As well as argument information, the @c CalloutHandle object can be used by
callouts to attach information to a packet being handled by the server.
This information (known as "context") is not used by the server: its purpose
is to allow callouts to pass information between one another on a
......@@ -441,9 +441,9 @@ simultaneously: callouts can effectively attach data to a packet that
follows the packet around the system.
Context information is held as name/value pairs in the same way
as arguments, being accessed by the pair of methods setContext and
getContext. They have the same restrictions as the setArgument and
getArgument methods - the type of data retrieved from context must
as arguments, being accessed by the pair of methods @c setContext and
@c getContext. They have the same restrictions as the @c setArgument and
@c getArgument methods - the type of data retrieved from context must
<B>exactly</B> match the type of the data set.
The example in the next section illustrates their use.
......@@ -457,8 +457,9 @@ do this in one callout, for this example we'll use two:
- pkt4_receive - a callout on this hook is invoked when a packet has been
received and has been parsed. It is passed a single argument, "query4"
which is an isc::dhcp::Pkt4 object (representing a DHCP v4 packet).
We will do the classification here.
which is an isc::dhcp::Pkt4Ptr object, holding a pointer to the
isc::dhcp::Pkt4 object (representing a DHCPv4 packet). We will do the
classification here.
- pkt4_send - called when a response is just about to be sent back to
the client. It is passed a single argument "response4". This is the
......@@ -521,7 +522,7 @@ int pkt4_receive(CalloutHandle& handle) {
}
@endcode
The pkt4_receive callout placed the hardware address of an interesting client in
The "pkt4_receive" callout placed the hardware address of an interesting client in
the "hwaddr" context for the packet. Turning now to the callout that will
write this information to the log file:
......@@ -757,12 +758,12 @@ to initialize per-request context. The second is called after all
server-defined hooks have been processed, and is to allow a library to
tidy up.
As an example, the pkt4_send example above required that the code
As an example, the "pkt4_send" example above required that the code
check for an exception being thrown when accessing the "hwaddr" context
item in case it was not set. An alternative strategy would have been to
provide a callout for the "context_create" hook and set the context item
"hwaddr" to an empty string. Instead of needing to handle an exception,
pkt4_send would be guaranteed to get something when looking for
"pkt4_send" would be guaranteed to get something when looking for
the hwaddr item and so could write or not write the output depending on
the value.
......@@ -771,7 +772,7 @@ automatically deletes context. An example where it could be required
is where memory has been allocated by a callout during the processing
of a request and a raw pointer to it stored in the context object. On
destruction of the context, that memory will not be automatically
released. Freeing in the memory in the "context_destroy callout will solve
released. Freeing in the memory in the "context_destroy" callout will solve
that problem.
Actually, when the context is destroyed, the destructor
......@@ -786,8 +787,8 @@ Here it is assumed that the hooks library is performing some form of
security checking on the packet and needs to maintain information in
a user-specified "SecurityInformation" object. (The details of this
fictitious object are of no concern here.) The object is created in
the context_create callout and used in both the pkt4_receive and the
pkt4_send callouts.
the "context_create" callout and used in both the "pkt4_receive" and the
"pkt4_send" callouts.
@code
// Storing information in a "raw" pointer. Assume that the
......@@ -831,7 +832,7 @@ int pkt4_send(CalloutHandle& handle) {
}
// Context destruction. We need to delete the pointed-to SecurityInformation
// object because we will lose the pointer to it when the CalloutHandle is
// object because we will lose the pointer to it when the @c CalloutHandle is
// destroyed.
int context_destroy(CalloutHandle& handle) {
// Retrieve the pointer to the SecurityInformation object
......@@ -843,7 +844,7 @@ int context_destroy(CalloutHandle& handle) {
}
@endcode
The requirement for the context_destroy callout can be eliminated if
The requirement for the "context_destroy" callout can be eliminated if
a Boost shared ptr is used to point to the allocated memory:
@code
......@@ -865,7 +866,7 @@ int context_create(CalloutHandle& handle) {
}
// Other than the data type, a shared pointer has similar semantics to a "raw"
// pointer. Only the code from pkt4_receive is shown here.
// pointer. Only the code from "pkt4_receive" is shown here.
int pkt4_receive(CalloutHandle& handle) {
// Retrieve the pointer to the SecurityInformation object
......@@ -881,7 +882,7 @@ int pkt4_receive(CalloutHandle& handle) {
}
// No context_destroy callout is needed to delete the allocated
// SecurityInformation object. When the CalloutHandle is destroyed, the shared
// SecurityInformation object. When the @c CalloutHandle is destroyed, the shared
// pointer object will be destroyed. If that is the last shared pointer to the
// allocated memory, then it too will be deleted.
@endcode
......@@ -915,13 +916,13 @@ registration is through the LibraryHandle object. This was briefly
introduced in the discussion of the framework functions, in that
an object of this type is pass to the "load" function. A LibraryHandle
can also be obtained from within a callout by calling the CalloutHandle's
getLibraryHandle() method.
@c getLibraryHandle() method.
The LibraryHandle provides three methods to manipulate callouts:
- registerCallout - register a callout on a hook.
- deregisterCallout - deregister a callout from a hook.
- deregisterAllCallouts - deregister all callouts on a hook.
- @c registerCallout - register a callout on a hook.
- @c deregisterCallout - deregister a callout from a hook.
- @c deregisterAllCallouts - deregister all callouts on a hook.
The following sections cover some of the ways in which these can be used.
......@@ -960,7 +961,7 @@ a hook point. Although it is likely to be rare for user code to need to
do this, there may be instances where it make sense.
To register multiple callouts on a hook, just call
LibraryHandle::registerCallout multiple times on the same hook, e.g.
@c LibraryHandle::registerCallout multiple times on the same hook, e.g.
@code
libhandle.registerCallout("pkt4_receive", classify);
......@@ -968,7 +969,7 @@ LibraryHandle::registerCallout multiple times on the same hook, e.g.
@endcode
The hooks framework will call the callouts in the order they are
registered. The same CalloutHandle is passed between them, so any
registered. The same @c CalloutHandle is passed between them, so any
change made to the CalloutHandle's arguments, "skip" flag, or per-request
context by the first is visible to the second.
......@@ -1036,7 +1037,7 @@ int write_data(CalloutHandle& handle) {
flush(interesting);
// We've logged the data, so deregister ourself. This callout will not
// be called again until it is registered by pkt4_receive.
// be called again until it is registered by "pkt4_receive".
handle.getLibraryHandle().deregisterCallout("pkt4_send", write_data);
......@@ -1093,7 +1094,7 @@ request.
The vertical blue lines represent callout context. Context is
per-packet but also per-library. When the server calls "authorize",
the CalloutHandle's getContext and setContext methods access a context
the CalloutHandle's @c getContext and @c setContext methods access a context
created purely for library 1. The next callout on the hook will access