// Copyright (C) 2012  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 dhcp4 DHCPv4 Server Component

BIND10 offers DHCPv4 server implementation. It is implemented as
b10-dhcp4 component.  Its primary code is located in
isc::dhcp::Dhcpv4Srv class. It uses \ref libdhcp extensively,
especially isc::dhcp::Pkt4, isc::dhcp::Option and
isc::dhcp::IfaceMgr classes. Currently this code offers skeleton
functionality, i.e. it is able to receive and process incoming
requests and trasmit responses. However, it does not have database
management, so it returns only one, hardcoded lease to whoever asks
for it.

DHCPv4 server component does not support direct traffic (relayed
only), as support for transmission to hosts without IPv4 address
assigned is not implemented in IfaceMgr yet.

@section dhcpv4Session BIND10 message queue integration

DHCPv4 server component is now integrated with BIND10 message queue.
The integration is performed by establishSession() and disconnectSession()
functions in isc::dhcp::ControlledDhcpv4Srv class. main() method deifined
in the src/bin/dhcp4/main.cc file instantiates isc::dhcp::ControlledDhcpv4Srv
class that establishes connection with msgq and install necessary handlers
for receiving commands and configuration updates. It is derived from
a base isc::dhcp::Dhcpv4Srv class that implements DHCPv4 server functionality,
without any controlling mechanisms.

ControlledDhcpv4Srv instantiates several components to make management
session possible. In particular, isc::cc::Session cc_session
object uses ASIO for establishing connection. It registers its socket
in isc::asiolink::IOService io_service object. Typically, other components
(e.g. auth or resolver) that use ASIO for their communication, register their
other sockets in the
same io_service and then just call io_service.run() method that does
not return, until one of the callback decides that it is time to shut down
the whole component cal calls io_service.stop(). DHCPv4 works in a
different way. It does receive messages using select()
(see isc::dhcp::IfaceMgr::receive4()), which is incompatible with ASIO.
To solve this problem, socket descriptor is extracted from cc_session
object and is passed to IfaceMgr by using isc::dhcp::IfaceMgr::set_session_socket().
IfaceMgr then uses this socket in its select() call. If there is some
data to be read, it calls registered callback that is supposed to
read and process incoming data.

This somewhat complicated approach is needed for a simple reason. In
embedded deployments there will be no message queue. Not referring directly
to anything related to message queue in isc::dhcp::Dhcpv4Srv and
isc::dhcp::IfaceMgr classes brings in two benefits. First, the can
be used with and without message queue. Second benefit is related to the
first one: \ref libdhcp is supposed to be simple and robust and not require
many dependencies. One notable example of a use case that benefits from
this approach is a perfdhcp tool. Finally, the idea is that it should be
possible to instantiate Dhcpv4Srv object directly, thus getting a server
that does not support msgq. That is useful for embedded environments.
It may also be useful in validation.

@section dhcpv4ConfigParser Configuration Parser in DHCPv4

This parser follows exactly the same logic as its DHCPv6 counterpart.
See \ref dhcpv6ConfigParser.

@section dhcpv4ConfigInherit DHCPv4 configuration inheritance

Configuration inheritance in DHCPv4 follows exactly the same logic as its DHCPv6
counterpart. See \ref dhcpv6ConfigInherit.

*/