BIND 10 trac3252, updated. 9eb97b9690414e01d4685500aa66a19067bb68c1 [3252] Created developer's guide section about error handlers in IfaceMgr.

[BIND 10 source code commits]

The branch, trac3252 has been updated
       via  9eb97b9690414e01d4685500aa66a19067bb68c1 (commit)
      from  53ca658337ee97c1f8bbe04d8eb8b87621c6a146 (commit)

Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.

- Log -----------------------------------------------------------------
commit 9eb97b9690414e01d4685500aa66a19067bb68c1
Author: Marcin Siodelski <marcin at isc.org>
Date:   Fri Jan 10 17:26:32 2014 +0100

    [3252] Created developer's guide section about error handlers in IfaceMgr.

-----------------------------------------------------------------------

Summary of changes:
 doc/devel/mainpage.dox     |    1 +
 src/lib/dhcp/libdhcp++.dox |   31 ++++++++++++++++++++++++++++++-
 2 files changed, 31 insertions(+), 1 deletion(-)

-----------------------------------------------------------------------
diff --git a/doc/devel/mainpage.dox b/doc/devel/mainpage.dox
index da5240b..c30ad35 100644
--- a/doc/devel/mainpage.dox
+++ b/doc/devel/mainpage.dox
@@ -74,6 +74,7 @@
  *   - @subpage libdhcpIfaceMgr
  *   - @subpage libdhcpPktFilter
  *   - @subpage libdhcpPktFilter6
+ *   - @subpage libdhcpErrorLogging
  * - @subpage libdhcpsrv
  *   - @subpage leasemgr
  *   - @subpage cfgmgr
diff --git a/src/lib/dhcp/libdhcp++.dox b/src/lib/dhcp/libdhcp++.dox
index e1d7920..373fdb0 100644
--- a/src/lib/dhcp/libdhcp++.dox
+++ b/src/lib/dhcp/libdhcp++.dox
@@ -1,4 +1,4 @@
-// Copyright (C) 2012-2013  Internet Systems Consortium, Inc. ("ISC")
+// Copyright (C) 2012-2014  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
@@ -231,4 +231,33 @@ functions.
 Use \ref isc::dhcp::IfaceMgr::setPacketFilter function to set the custom packet
 filter object to be used by Interface Manager.
 
+ at section libdhcpErrorLogging Logging non-fatal errors in IfaceMgr.
+
+The libdhcp++ is a common library, meant to be used by various components,
+such as DHCP servers, relays and clients. It is also used by a perfdhcp
+benchmarking application. It provides a basic capabilities for these
+applications to perform operations on DHCP messages such as encoding
+or decoding them. It also provides capabilities to perform low level
+operations on sockets. Since libdhcp++ is a common library, its dependency
+on other BINDX modules should be minimal. In particular, errors occurring
+in the libdhcp++ are reported using exceptions, not a BINDX logger. This
+works well in most cases, but there are some cases in which it is
+undesired for a function to throw an exception in case of non-fatal error.
+
+The typical case, when exception should not be thrown, is when the \ref
+isc::dhcp::IfaceMgr::openSockets4 or \ref isc::dhcp::IfaceMgr::openSockets6
+fails to open a socket on one of the interfaces. This should not preclude
+the function from attempting to open sockets on other interfaces, which
+would be the case if exception was thrown.
+
+In such cases the IfaceMgr makes use of error handler callback function
+which may be installed by a caller. This function must implement the
+isc::dhcp::IfaceMgrErrorMsgCallback. Note that it is allowed to pass a NULL
+value instead, which would result falling back to a default behavior and
+exception will be thrown. If non-NULL value is provided, the
+\ref isc::dhcp::IfaceMgr will call error handler function and pass an
+error string as an argument. The handler function may use its logging
+mechanism to log this error message. In particular, the DHCP server
+will use BINDX logger to log the error message.
+
 */