// Copyright (C) 2013  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
// copyright notice and this permission notice appear in all copies.
//
// THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
// REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
// AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
// INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
// LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
// OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
// PERFORMANCE OF THIS SOFTWARE.

/**
 @page dhcpv4Hooks The Hooks API for the DHCPv4 Server

 @section dhcpv4HooksIntroduction Introduction
 Kea features an API (the "Hooks" API) that allows user-written code to
 be integrated into Kea and called at specific points in its processing.
 An overview of the API and a tutorial for writing such code can be found in
 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
 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:

 - Name of the hook point.
 - Arguments for the callout.  As well as the argument name and data type, the
   information includes the direction, which can be one of:
   - @b in - the server passes values to the callout but ignored any data
     returned.
   - @b out - the callout is expected to set this value.
   - <b>in/out</b> - the server passes a value to the callout and uses whatever
     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 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.

@section dhcpv4HooksHookPoints Hooks in the DHCPv4 Server

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:
   - name: @b query4, type: isc::dhcp::Pkt4Ptr, direction: <b>in/out</b>

 - @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
   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.  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.)

 - <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
   will be logged if logging is set to the appropriate debug level.

@subsection dhcpv4HooksSubnet4Select subnet4_select

 - @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>

 - @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
   not be modified.

 - <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).

@subsection dhcpv4HooksLeaseSelect lease4_select

 - @b Arguments:
   - name: @b subnet4, type: isc::dhcp::Subnet4Ptr, direction: <b>in</b>
   - name: @b fake_allocation, type: bool, direction: <b>in</b>
   - 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
   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.

@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:
   - name: @b response4, type: isc::dhcp::Pkt4Ptr, direction: <b>in/out</b>
   - name: @b query4, type: isc::dhcp::Pkt4Ptr, direction: <b>in</b>

 - @b Description: this callout is executed when server's response
   is about to be sent back to the client. The argument response4
   contains a pointer to an 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.  All fields
   of the Pkt4 object can be modified at this time, except 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.)\n\n
   The argument query4 contains a pointer to the corresponding query packet
   (allowing to perform correlation between response and query). This object
   cannot be modified.

 - <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 sent back to the client. The sole argument - response4 -
   contains a pointer to an 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.

 - <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.


*/