Kea: isc::dhcp_ddns::NameChangeListener Class Reference

| Kea 3.2.0-git

isc::dhcp_ddns::NameChangeListener Class Referenceabstract

Abstract interface for receiving NameChangeRequests. More...

`#include <ncr_io.h>`

Inheritance diagram for isc::dhcp_ddns::NameChangeListener:
[legend]

## Classes
class | RequestReceiveHandler
| Abstract class for defining application layer receive callbacks. More...

## Public Types
typedef boost::shared_ptr< RequestReceiveHandler > | RequestReceiveHandlerPtr
| Defines a smart pointer to an instance of a request receive handler.
enum | Result { SUCCESS , TIME_OUT , STOPPED , ERROR }
| Defines the outcome of an asynchronous NCR receive. More...

## Public Member Functions
| NameChangeListener (RequestReceiveHandlerPtr recv_handler)
| Constructor.
virtual | ~NameChangeListener ()
| Destructor.
bool | amListening () const
| Returns true if the listener is listening, false otherwise.
bool | isIoPending () const
| Returns true if the listener has an IO call in progress.
void | startListening (const isc::asiolink::IOServicePtr &io_service)
| Prepares the IO for reception and initiates the first receive.
void | stopListening ()
| Closes the IO source and stops listen logic.

## Protected Member Functions
virtual void | close ()=0
| Abstract method which closes the IO source.
virtual void | doReceive ()=0
| Initiates an IO layer asynchronous read.
void | invokeRecvHandler (const Result result, NameChangeRequestPtr &ncr)
| Calls the NCR receive handler registered with the listener.
virtual void | open (const isc::asiolink::IOServicePtr &io_service)=0
| Abstract method which opens the IO source for reception.
void | receiveNext ()
| Initiates an asynchronous receive.

## Detailed Description

Abstract interface for receiving NameChangeRequests.

NameChangeListener provides the means to:

- Supply a callback to invoke upon receipt of an NCR or a listening error
- Start listening using a given IOService instance to process events
- Stop listening

It implements the high level logic flow to listen until a request arrives, invoke the implementation's handler and return to listening for the next request.

It provides virtual methods that allow derivations supply implementations to open the appropriate IO source, perform a listen, and close the IO source.

The overall design is based on a callback chain. The listener's caller (the application) supplies an "application" layer callback through which it will receive inbound NameChangeRequests. The listener derivation will supply its own callback to the IO layer to process receive events from its IO source. This is referred to as the NameChangeRequest completion handler. It is through this handler that the NameChangeRequest layer gains access to the low level IO read service results. It is expected to assemble NameChangeRequests from the inbound data and forward them to the application layer by invoking the application layer callback registered with the listener.

The application layer callback is structured around a nested class, RequestReceiveHandler. It consists of single, abstract operator() which accepts a result code and a pointer to a NameChangeRequest as parameters. In order to receive inbound NCRs, a caller implements a derivation of the RequestReceiveHandler and supplies an instance of this derivation to the NameChangeListener constructor. This "registers" the handler with the listener.

To begin listening, the caller invokes the listener's startListener() method, passing in an IOService instance. This in turn will pass the IOService into the virtual method, open(). The open method is where the listener derivation performs the steps necessary to prepare its IO source for reception (e.g. opening a socket, connecting to a database).

Assuming the open is successful, startListener will call receiveNext, to initiate an asynchronous receive. This method calls the virtual method, doReceive(). The listener derivation uses doReceive to instigate an IO layer asynchronous receive passing in its IO layer callback to handle receive events from the IO source.

As stated earlier, the derivation's NameChangeRequest completion handler MUST invoke the application layer handler registered with the listener. This is done by passing in either a success status and a populated NameChangeRequest or an error status and an empty request into the listener's invokeRecvHandler method. This is the mechanism by which the listener's caller is handed inbound NCRs.

Definition at line 167 of file ncr_io.h.

## Member Typedef Documentation

## ◆ RequestReceiveHandlerPtr

typedef boost::shared_ptr<RequestReceiveHandler> isc::dhcp_ddns::NameChangeListener::RequestReceiveHandlerPtr

Defines a smart pointer to an instance of a request receive handler.

Definition at line 206 of file ncr_io.h.

## Member Enumeration Documentation

## ◆ Result

enum isc::dhcp_ddns::NameChangeListener::Result

Defines the outcome of an asynchronous NCR receive.

Enumerator
SUCCESS |
TIME_OUT |
STOPPED |
ERROR |

Definition at line 171 of file ncr_io.h.

## Constructor & Destructor Documentation

## ◆ NameChangeListener()

isc::dhcp_ddns::NameChangeListener::NameChangeListener | ( | RequestReceiveHandlerPtr | recv_handler | ) |

Constructor.

Parameters

  recv_handler | is a pointer the application layer handler to be invoked each time a NCR is received or a receive error occurs.

Definition at line 53 of file ncr_io.cc.

Referenced by isc::dhcp_ddns::NameChangeUDPListener::NameChangeUDPListener().

## ◆ ~NameChangeListener()

virtual isc::dhcp_ddns::NameChangeListener::~NameChangeListener | ( |  | ) |
| inlinevirtual

Destructor.

Definition at line 215 of file ncr_io.h.

## Member Function Documentation

## ◆ amListening()

bool isc::dhcp_ddns::NameChangeListener::amListening | ( |  | ) | const
| inline

Returns true if the listener is listening, false otherwise.

A true value indicates that the IO source has been opened successfully, and that receive loop logic is active. This implies that closing the IO source will interrupt that operation, resulting in a callback invocation.

Returns
  The listening mode.

Definition at line 316 of file ncr_io.h.

Referenced by invokeRecvHandler(), and startListening().

## ◆ close()

virtual void isc::dhcp_ddns::NameChangeListener::close | ( |  | ) |
| protectedpure virtual

Abstract method which closes the IO source.

The derivation uses this method to perform the steps needed to "close" the IO source.

Exceptions

  If | the implementation encounters an error it MUST throw it as an isc::Exception or derivative.

Implemented in isc::dhcp_ddns::NameChangeUDPListener.

Referenced by stopListening().

## ◆ doReceive()

virtual void isc::dhcp_ddns::NameChangeListener::doReceive | ( |  | ) |
| protectedpure virtual

Initiates an IO layer asynchronous read.

The derivation uses this method to perform the steps needed to initiate an asynchronous read of the IO source with the derivation's IO layer handler as the IO completion callback.

Exceptions

  If | the implementation encounters an error it MUST throw it as an isc::Exception or derivative.

Implemented in isc::dhcp_ddns::NameChangeUDPListener.

Referenced by receiveNext().

## ◆ invokeRecvHandler()

void isc::dhcp_ddns::NameChangeListener::invokeRecvHandler | ( | const Result | result,
|  | NameChangeRequestPtr & | ncr )
| protected

Calls the NCR receive handler registered with the listener.

This is the hook by which the listener's caller's NCR receive handler is called. This method MUST be invoked by the derivation's implementation of doReceive.

NOTE: The handler invoked by this method MUST NOT THROW. The handler is at application level and should trap and handle any errors at that level, rather than throw exceptions. If an error has occurred prior to invoking the handler, it will be expressed in terms a failed result being passed to the handler, not a throw. Therefore any exceptions at the handler level are application issues and should be dealt with at that level.

This method does wrap the handler invocation within a try-catch block as a fail-safe. The exception will be logged but the receive logic will continue. What this implies is that continued operation may or may not succeed as the application has violated the interface contract.

Parameters

  result | contains that receive outcome status.
  ncr | is a pointer to the newly received NameChangeRequest if result is NameChangeListener::SUCCESS. It is indeterminate other wise.

Definition at line 108 of file ncr_io.cc.

References amListening(), isc::dhcp_ddns::dhcp_ddns_logger, isc::dhcp_ddns::DHCP_DDNS_NCR_RECV_NEXT_ERROR, isc::dhcp_ddns::DHCP_DDNS_UNCAUGHT_NCR_RECV_HANDLER_ERROR, ERROR, LOG_ERROR, receiveNext(), and isc::Exception::what().

Referenced by isc::dhcp_ddns::NameChangeUDPListener::receiveCompletionHandler().

Here is the call graph for this function:

## ◆ isIoPending()

bool isc::dhcp_ddns::NameChangeListener::isIoPending | ( |  | ) | const
| inline

Returns true if the listener has an IO call in progress.

A true value indicates that the listener has an asynchronous IO in progress which will complete at some point in the future. Completion of the call will invoke the registered callback. It is important to understand that the listener and its related objects should not be deleted while there is an IO call pending. This can result in the IO service attempting to invoke methods on objects that are no longer valid.

Returns
  The IO pending flag.

Definition at line 331 of file ncr_io.h.

## ◆ open()

virtual void isc::dhcp_ddns::NameChangeListener::open | ( | const isc::asiolink::IOServicePtr & | io_service | ) |
| protectedpure virtual

Abstract method which opens the IO source for reception.

The derivation uses this method to perform the steps needed to prepare the IO source to receive requests.

Parameters

  io_service | is the IOService that process IO events.

Exceptions

  If | the implementation encounters an error it MUST throw it as an isc::Exception or derivative.

Implemented in isc::dhcp_ddns::NameChangeUDPListener.

Referenced by startListening().

## ◆ receiveNext()

void isc::dhcp_ddns::NameChangeListener::receiveNext | ( |  | ) |
| protected

Initiates an asynchronous receive.

Sets context information to indicate that IO is in progress and invokes the derivation's asynchronous receive method, doReceive. Note doReceive should not be called outside this method to ensure context information integrity.

Exceptions

  Derivation's | doReceive method may throw isc::Exception upon error.

Definition at line 85 of file ncr_io.cc.

References doReceive().

Referenced by invokeRecvHandler(), isc::dhcp_ddns::NameChangeUDPListener::receiveCompletionHandler(), and startListening().

Here is the call graph for this function:

## ◆ startListening()

void isc::dhcp_ddns::NameChangeListener::startListening | ( | const isc::asiolink::IOServicePtr & | io_service | ) |

Prepares the IO for reception and initiates the first receive.

Calls the derivation's open implementation to initialize the IO layer source for receiving inbound requests. If successful, it starts the first asynchronous read by receiveNext.

Parameters

  io_service | is the IOService that will handle IO event processing.

Exceptions

  NcrListenError | if the listener is already "listening" or in the event the open or doReceive methods fail.

Definition at line 58 of file ncr_io.cc.

References amListening(), isc_throw, open(), receiveNext(), stopListening(), and isc::Exception::what().

Here is the call graph for this function:

## ◆ stopListening()

void isc::dhcp_ddns::NameChangeListener::stopListening | ( |  | ) |

Closes the IO source and stops listen logic.

Calls the derivation's implementation of close and marks the state as not listening.

Definition at line 91 of file ncr_io.cc.

References close(), isc::dhcp_ddns::dhcp_ddns_logger, isc::dhcp_ddns::DHCP_DDNS_NCR_LISTEN_CLOSE_ERROR, LOG_ERROR, and isc::Exception::what().

Referenced by isc::dhcp_ddns::NameChangeUDPListener::~NameChangeUDPListener(), and startListening().

Here is the call graph for this function:

The documentation for this class was generated from the following files:

- ncr_io.h
- ncr_io.cc