Kea: isc::hooks::CalloutHandle Class Reference

| Kea 3.2.0-git

isc::hooks::CalloutHandle Class Reference

Per-packet callout handle. More...

`#include <callout_handle.h>`

## Public Types
enum | CalloutNextStep { NEXT_STEP_CONTINUE = 0 , NEXT_STEP_SKIP = 1 , NEXT_STEP_DROP = 2 , NEXT_STEP_PARK = 3 }
| Specifies allowed next steps. More...
typedef std::map< int, ElementCollection > | ContextCollection
| Typedef to allow abbreviations in specifications when accessing context.
typedef std::map< std::string, boost::any > | ElementCollection
| Typedef to allow abbreviation of iterator specification in methods.

## Public Member Functions
| CalloutHandle (const boost::shared_ptr< CalloutManager > &manager, const boost::shared_ptr< LibraryManagerCollection > &lmcoll=boost::shared_ptr< LibraryManagerCollection >())
| Constructor.
| ~CalloutHandle ()
| Destructor.
void | deleteAllArguments ()
| Delete all arguments.
void | deleteAllContext ()
| Delete all context items.
void | deleteArgument (const std::string &name)
| Delete argument.
void | deleteContext (const std::string &name)
| Delete context element.
template<typename T>
void | getArgument (const std::string &name, T &value) const
| Get argument.
std::vector< std::string > | getArgumentNames () const
| Get argument names.
template<typename T>
void | getContext (const std::string &name, T &value) const
| Get context.
std::vector< std::string > | getContextNames () const
| Get context names.
int | getCurrentHook () const
| Get current hook index.
int | getCurrentLibrary () const
| Get current library index.
std::string | getHookName () const
| Get hook name.
template<typename T>
bool | getOptionalContext (const std::string &name, T &value) const
| Fetch an optional named element from the current library context.
ParkingLotHandlePtr | getParkingLotHandlePtr () const
| Returns pointer to the parking lot handle for this hook point.
CalloutNextStep | getStatus () const
| Returns the next processing step.
template<typename T>
void | setArgument (const std::string &name, T value)
| Set argument.
template<typename T>
void | setContext (const std::string &name, T value)
| Set context.
void | setCurrentHook (int hook_index)
| Set current hook index.
void | setCurrentLibrary (int library_index)
| Set current library index.
void | setStatus (const CalloutNextStep next)
| Sets the next processing step.

## Detailed Description

Per-packet callout handle.

An object of this class is associated with every packet (or request) processed by the server. It forms the principle means of passing data between the server and the user-library callouts.

The class allows access to the following information:

- Arguments. When the callouts associated with a hook are called, they are passed information by the server (and can return information to it) through name/value pairs. Each of these pairs is an argument and the information is accessed through the {get,set}Argument() methods.
- Per-packet context. Each packet has a context associated with it, this context being on a per-library basis. In other words, As a packet passes through the callouts associated with a given library, the callouts can associate and retrieve information with the packet. The per-library nature of the context means that the callouts within a given library can pass packet-specific information between one another, but they cannot pass information to callous within another library. Typically such context is created in the "context_create" callout and destroyed in the "context_destroy" callout. The information is accessed through the {get,set}Context() methods.

Definition at line 78 of file callout_handle.h.

## Member Typedef Documentation

## ◆ ContextCollection

typedef std::map<int, ElementCollection> isc::hooks::CalloutHandle::ContextCollection

Typedef to allow abbreviations in specifications when accessing context.

The ElementCollection is the name/value collection for a particular context. The "int" corresponds to the index of an associated library - there is a 1:1 correspondence between libraries and a name.value collection.

The collection of contexts is stored in a map, as not every library will require creation of a context associated with each packet. In addition, the structure is more flexible in that the size does not need to be set when the CalloutHandle is constructed.

Definition at line 109 of file callout_handle.h.

## ◆ ElementCollection

typedef std::map<std::string, boost::any> isc::hooks::CalloutHandle::ElementCollection

Typedef to allow abbreviation of iterator specification in methods.

The std::string is the argument name and the "boost::any" is the corresponding value associated with it.

Definition at line 97 of file callout_handle.h.

## Member Enumeration Documentation

## ◆ CalloutNextStep

enum isc::hooks::CalloutHandle::CalloutNextStep

Specifies allowed next steps.

Those values are used to designate the next step in packet processing. They are set by hook callouts and read by the Kea server. See setStatus for detailed description of each value.

Enumerator
NEXT_STEP_CONTINUE | continue normally
NEXT_STEP_SKIP | skip the next processing step
NEXT_STEP_DROP | drop the packet
NEXT_STEP_PARK | park the packet

Definition at line 86 of file callout_handle.h.

## Constructor & Destructor Documentation

## ◆ CalloutHandle()

isc::hooks::CalloutHandle::CalloutHandle | ( | const boost::shared_ptr< CalloutManager > & | manager,
|  | const boost::shared_ptr< LibraryManagerCollection > & | lmcoll = boost::shared_ptr<LibraryManagerCollection>() )

Constructor.

Creates the object and calls the callouts on the "context_create" hook.

Of the two arguments passed, only the pointer to the callout manager is actively used. The second argument, the pointer to the library manager collection, is used for lifetime control: after use, the callout handle may contain pointers to memory allocated by the loaded libraries. The used of a shared pointer to the collection of library managers means that the libraries that could have allocated memory in a callout handle will not be unloaded until all such handles have been destroyed. This issue is discussed in more detail in the documentation for isc::hooks::LibraryManager.

Parameters

  manager | Pointer to the callout manager object.
  lmcoll | Pointer to the library manager collection. This has a null default for testing purposes.

Definition at line 24 of file callout_handle.cc.

References isc::hooks::ServerHooks::CONTEXT_CREATE, and NEXT_STEP_CONTINUE.

## ◆ ~CalloutHandle()

isc::hooks::CalloutHandle::~CalloutHandle | ( |  | ) |

Destructor.

Calls the context_destroy callback to release any per-packet context. It also clears stored data to avoid problems during member destruction.

Definition at line 37 of file callout_handle.cc.

References isc::hooks::ServerHooks::CONTEXT_DESTROY.

## Member Function Documentation

## ◆ deleteAllArguments()

void isc::hooks::CalloutHandle::deleteAllArguments | ( |  | ) |
| inline

Delete all arguments.

Deletes all arguments associated with this context.

N.B. If any elements are raw pointers, the pointed-to data is NOT deleted by this method.

Definition at line 201 of file callout_handle.h.

## ◆ deleteAllContext()

void isc::hooks::CalloutHandle::deleteAllContext | ( |  | ) |
| inline

Delete all context items.

Deletes all items from the context associated with the current library.

N.B. If any elements are raw pointers, the pointed-to data is NOT deleted by this.

Definition at line 346 of file callout_handle.h.

## ◆ deleteArgument()

void isc::hooks::CalloutHandle::deleteArgument | ( | const std::string & | name | ) |
| inline

Delete argument.

Deletes an argument of the given name. If an argument of that name does not exist, the method is a no-op.

N.B. If the element is a raw pointer, the pointed-to data is NOT deleted by this method.

Parameters

  name | Name of the element in the argument list to set.

Definition at line 191 of file callout_handle.h.

## ◆ deleteContext()

void isc::hooks::CalloutHandle::deleteContext | ( | const std::string & | name | ) |
| inline

Delete context element.

Deletes an item of the given name from the context associated with the current library. If an item of that name does not exist, the method is a no-op.

N.B. If the element is a raw pointer, the pointed-to data is NOT deleted by this.

Parameters

  name | Name of the context item to delete.

Definition at line 336 of file callout_handle.h.

## ◆ getArgument()

template<typename T>

void isc::hooks::CalloutHandle::getArgument | ( | const std::string & | name,
|  | T & | value ) const
| inline

Get argument.

Gets the value of an argument.

Parameters

  name | Name of the element in the argument list to get.
  value | [out] Value to set. The type of "value" is important: it must match the type of the value set.

Exceptions

  NoSuchArgument | No argument with the given name is present.
  boost::bad_any_cast | An argument with the given name is present, but the data type of the value is not the same as the type of the variable provided to receive the value.

Definition at line 164 of file callout_handle.h.

References isc_throw.

Referenced by addr6_register(), buffer4_receive(), isc::ha::HAImpl::buffer4Receive(), buffer6_receive(), isc::ha::HAImpl::buffer6Receive(), cb4_updated(), cb6_updated(), isc::limits::LimitManager::cb_updated(), command_processed(), isc::gss_tsig::GssTsigImpl::commandProcessed(), isc::ha::HAImpl::commandProcessed(), isc::ha::HAImpl::continueHandler(), d2_srv_configured(), ddns4_update(), ddns6_update(), dhcp4_srv_configured(), dhcp6_srv_configured(), isc::config::CmdsImpl::extractCommand(), isc::gss_tsig::GssTsigImpl::getHandler(), isc::ha::HAImpl::haResetHandler(), isc::ha::HAImpl::heartbeatHandler(), host4_identifier(), host6_identifier(), isc::gss_tsig::GssTsigImpl::keyDelHandler(), isc::gss_tsig::GssTsigImpl::keyExpireHandler(), isc::gss_tsig::GssTsigImpl::keyGetHandler(), lease4_decline(), lease4_expire(), lease4_offer(), lease4_recover(), lease4_release(), lease4_renew(), lease4_select(), isc::ha::HAImpl::lease4Expire(), isc::lease_cmds::LeaseCmdsImpl::lease4Offer(), isc::ha::HAImpl::lease4ServerDecline(), lease6_decline(), lease6_expire(), lease6_rebind(), lease6_recover(), lease6_release(), lease6_renew(), lease6_select(), isc::ha::HAImpl::lease6Expire(), isc::limits::LimitManager::lease_callout(), leases4_committed(), isc::ha::HAImpl::leases4Committed(), isc::lease_cmds::LeaseCmdsImpl::leases4Committed(), leases6_committed(), isc::ha::HAImpl::leases6Committed(), isc::lease_cmds::LeaseCmdsImpl::leases6Committed(), legalLog4Handler(), legalLog6Handler(), isc::ha::HAImpl::maintenanceNotifyHandler(), network4_add(), network4_del(), network4_get(), network4_subnet_add(), network4_subnet_del(), network6_add(), network6_del(), network6_get(), network6_subnet_add(), network6_subnet_del(), pkt4_receive(), pkt4_send(), pkt6_receive(), pkt6_send(), isc::limits::LimitManager::pkt_receive(), isc::gss_tsig::GssTsigImpl::purgeHandler(), isc::gss_tsig::GssTsigImpl::rekeyHandler(), isc::ha::HAImpl::scopesHandler(), select_key(), subnet4_add(), subnet4_del(), subnet4_delta_add(), subnet4_delta_del(), subnet4_get(), subnet4_select(), subnet4_update(), isc::ha::HAImpl::subnet4Select(), subnet6_add(), subnet6_del(), subnet6_delta_add(), subnet6_delta_del(), subnet6_get(), subnet6_select(), subnet6_update(), isc::ha::HAImpl::subnet6Select(), isc::limits::LimitManager::subnet_select(), isc::ha::HAImpl::syncCompleteNotifyHandler(), and isc::ha::HAImpl::synchronizeHandler().

## ◆ getArgumentNames()

vector< string > isc::hooks::CalloutHandle::getArgumentNames | ( |  | ) | const

Get argument names.

Returns a vector holding the names of arguments in the argument vector.

Returns
  Vector of strings reflecting argument names.

Definition at line 65 of file callout_handle.cc.

## ◆ getContext()

template<typename T>

void isc::hooks::CalloutHandle::getContext | ( | const std::string & | name,
|  | T & | value ) const
| inline

Get context.

Gets an element from the context associated with the current library.

Parameters

  name | Name of the element in the context to get.
  value | [out] Value to set. The type of "value" is important: it must match the type of the value set.

Exceptions

  NoSuchCalloutContext | Thrown if no context element with the name "name" is present.
  boost::bad_any_cast | Thrown if the context element is present but the type of the data is not the same as the type of the variable provided to receive its value.

Definition at line 271 of file callout_handle.h.

References isc_throw.

Referenced by isc::ha::HAImpl::leases4Committed(), isc::ha::HAImpl::leases6Committed(), legalLog4Handler(), legalLog6Handler(), pkt4_send(), pkt6_send(), isc::flex_id::retrieveFlexId(), subnet4_select(), and subnet6_select().

## ◆ getContextNames()

vector< string > isc::hooks::CalloutHandle::getContextNames | ( |  | ) | const

Get context names.

Returns a vector holding the names of items in the context associated with the current library.

Returns
  Vector of strings reflecting the names of items in the callout context associated with the current library.

Definition at line 110 of file callout_handle.cc.

## ◆ getCurrentHook()

int isc::hooks::CalloutHandle::getCurrentHook | ( |  | ) | const
| inline

Get current hook index.

Returns
  The current hook index

Definition at line 381 of file callout_handle.h.

Referenced by isc::hooks::CalloutManager::callCallouts().

## ◆ getCurrentLibrary()

int isc::hooks::CalloutHandle::getCurrentLibrary | ( |  | ) | const
| inline

Get current library index.

Returns
  The current library index

Definition at line 367 of file callout_handle.h.

Referenced by addDuration(), isc::hooks::CalloutManager::callCallouts(), command_processed(), getCustomEntry(), getCustomEntry(), handleLease4Cmds(), handleLease6Cmds(), legalLog4Handler(), and legalLog6Handler().

## ◆ getHookName()

string isc::hooks::CalloutHandle::getHookName | ( |  | ) | const

Get hook name.

Get the name of the hook to which the current callout is attached. This can be the null string if the CalloutHandle is being accessed outside of the CalloutManager's "callCallouts" method.

Returns
  Name of the current hook or the empty string if none.

Definition at line 125 of file callout_handle.cc.

## ◆ getOptionalContext()

template<typename T>

bool isc::hooks::CalloutHandle::getOptionalContext | ( | const std::string & | name,
|  | T & | value ) const
| inline

Fetch an optional named element from the current library context.

Gets an element from the context associated with the current library. If either context or the named element do not exist, the function returns false.

Parameters

  name | Name of the element in the context to get.
  value | [out] Value to set. The type of "value" is important: it must match the type of the value set.

Exceptions

  boost::bad_any_cast | Thrown if the context element is present but the type of the data is not the same as the type of the variable provided to receive its value.

Returns
  true if the named element exists, false otherwise.

Definition at line 300 of file callout_handle.h.

## ◆ getParkingLotHandlePtr()

ParkingLotHandlePtr isc::hooks::CalloutHandle::getParkingLotHandlePtr | ( |  | ) | const

Returns pointer to the parking lot handle for this hook point.

Returns
  pointer to the parking lot handle

Definition at line 75 of file callout_handle.cc.

Referenced by lease4_offer(), isc::ha::HAImpl::leases4Committed(), isc::ha::HAImpl::leases6Committed(), subnet4_select(), and subnet6_select().

## ◆ getStatus()

CalloutNextStep isc::hooks::CalloutHandle::getStatus | ( |  | ) | const
| inline

Returns the next processing step.

Gets the current value of the next step. See setStatus for detailed definition.

Returns
  Current value of the skip flag.

Definition at line 241 of file callout_handle.h.

Referenced by addr6_register(), buffer4_receive(), isc::ha::HAImpl::buffer4Receive(), buffer6_receive(), isc::ha::HAImpl::buffer6Receive(), isc::limits::LimitManager::cb_updated(), d2_srv_configured(), ddns4_update(), ddns6_update(), isc::limits::LimitManager::dhcp_srv_configured(), host4_identifier(), host6_identifier(), lease4_decline(), lease4_expire(), lease4_offer(), lease4_recover(), lease4_release(), lease4_renew(), lease4_select(), lease4_server_decline(), lease6_decline(), lease6_expire(), lease6_rebind(), lease6_recover(), lease6_release(), lease6_renew(), lease6_select(), isc::limits::LimitManager::lease_callout(), leases4_committed(), leases6_committed(), pkt4_receive(), pkt4_send(), pkt6_receive(), pkt6_send(), isc::limits::LimitManager::pkt_receive(), select_key(), subnet4_select(), subnet6_select(), and isc::limits::LimitManager::subnet_select().

## ◆ setArgument()

template<typename T>

void isc::hooks::CalloutHandle::setArgument | ( | const std::string & | name,
|  | T | value )
| inline

Set argument.

Sets the value of an argument. The argument is created if it does not already exist.

Parameters

  name | Name of the argument.
  value | Value to set. That can be of any data type.

Definition at line 147 of file callout_handle.h.

Referenced by isc::class_cmds::ClassCmdsImpl::addClass(), cb6_updated(), isc::ha::HAImpl::continueHandler(), d2_srv_configured(), ddns4_update(), ddns6_update(), isc::class_cmds::ClassCmdsImpl::delClass(), dhcp4_srv_configured(), dhcp6_srv_configured(), isc::gss_tsig::GssTsigImpl::getAllHandler(), isc::class_cmds::ClassCmdsImpl::getClass(), isc::class_cmds::ClassCmdsImpl::getClassList(), isc::gss_tsig::GssTsigImpl::getHandler(), isc::ha::HAImpl::haResetHandler(), isc::ha::HAImpl::heartbeatHandler(), host4_identifier(), host6_identifier(), isc::gss_tsig::GssTsigImpl::keyDelHandler(), isc::gss_tsig::GssTsigImpl::keyExpireHandler(), isc::gss_tsig::GssTsigImpl::keyGetHandler(), lease4_decline(), lease4_release(), isc::ha::HAImpl::lease4ServerDecline(), isc::gss_tsig::GssTsigImpl::listHandler(), isc::ha::HAImpl::maintenanceCancelHandler(), isc::ha::HAImpl::maintenanceNotifyHandler(), isc::ha::HAImpl::maintenanceStartHandler(), network4_add(), network4_del(), network4_get(), network4_list(), network4_subnet_add(), network4_subnet_del(), network6_add(), network6_del(), network6_get(), network6_list(), network6_subnet_add(), network6_subnet_del(), isc::gss_tsig::GssTsigImpl::purgeAllHandler(), isc::gss_tsig::GssTsigImpl::purgeHandler(), isc::gss_tsig::GssTsigImpl::rekeyAllHandler(), isc::gss_tsig::GssTsigImpl::rekeyHandler(), isc::ha::HAImpl::scopesHandler(), select_key(), isc::config::CmdsImpl::setResponse(), subnet4_add(), subnet4_del(), subnet4_delta_add(), subnet4_delta_del(), subnet4_get(), subnet4_list(), subnet4_select(), subnet4_update(), subnet6_add(), subnet6_del(), subnet6_delta_add(), subnet6_delta_del(), subnet6_get(), subnet6_list(), subnet6_select(), subnet6_update(), isc::ha::HAImpl::syncCompleteNotifyHandler(), isc::ha::HAImpl::synchronizeHandler(), isc::class_cmds::ClassCmdsImpl::updateClass(), isc::lease_query::LeaseQueryImpl4::upgradeHandler(), and isc::lease_query::LeaseQueryImpl6::upgradeHandler().

## ◆ setContext()

template<typename T>

void isc::hooks::CalloutHandle::setContext | ( | const std::string & | name,
|  | T | value )
| inline

Set context.

Sets an element in the context associated with the current library. If an element of the name is already present, it is replaced.

Parameters

  name | Name of the element in the context to set.
  value | Value to set.

Definition at line 253 of file callout_handle.h.

Referenced by lease4_decline(), lease4_release(), lease6_decline(), lease6_release(), leases4_committed(), leases6_committed(), pkt4_receive(), pkt4_send(), pkt6_receive(), pkt6_send(), isc::flex_id::retrieveFlexId(), isc::ha::HAImpl::subnet4Select(), and isc::ha::HAImpl::subnet6Select().

## ◆ setCurrentHook()

void isc::hooks::CalloutHandle::setCurrentHook | ( | int | hook_index | ) |
| inline

Set current hook index.

Parameters

  hook_index | The hook index

Definition at line 388 of file callout_handle.h.

Referenced by isc::hooks::CalloutManager::callCallouts().

## ◆ setCurrentLibrary()

void isc::hooks::CalloutHandle::setCurrentLibrary | ( | int | library_index | ) |
| inline

Set current library index.

Parameters

  library_index | The library index

Definition at line 374 of file callout_handle.h.

Referenced by isc::hooks::CalloutManager::callCallouts().

## ◆ setStatus()

void isc::hooks::CalloutHandle::setStatus | ( | const CalloutNextStep | next | ) |
| inline

Sets the next processing step.

This method is used by the callouts to determine the next step in processing. This method replaces former setSkip() method that allowed only two values.

Currently there are three possible value allowed: NEXT_STEP_CONTINUE - tells the server to continue processing as usual (equivalent of previous setSkip(false) )

NEXT_STEP_SKIP - tells the server to skip the processing. Exact meaning is hook specific. See hook documentation for details. (equivalent of previous setSkip(true))

NEXT_STEP_DROP - tells the server to unconditionally drop the packet and do not process it further.

NEXT_STEP_PARK - tells the server to "park" the packet. The packet will wait in the queue for being unparked, e.g. as a result of completion of the asynchronous performed by the hooks library operation.

This variable is interrogated by the server to see if the remaining callouts associated with the current hook should be bypassed.

Parameters

  next | New value of the next step status.

Definition at line 231 of file callout_handle.h.

Referenced by buffer4_receive(), isc::ha::HAImpl::buffer4Receive(), buffer6_receive(), isc::ha::HAImpl::buffer6Receive(), isc::hooks::CalloutManager::callCallouts(), d2_srv_configured(), dhcp4_srv_configured(), dhcp6_srv_configured(), lease4_offer(), isc::ha::HAImpl::lease4Expire(), isc::ha::HAImpl::lease4ServerDecline(), isc::ha::HAImpl::lease6Expire(), isc::limits::LimitManager::lease_callout(), isc::ha::HAImpl::leases4Committed(), isc::ha::HAImpl::leases6Committed(), pkt4_send(), isc::limits::LimitManager::pkt_receive(), select_key(), subnet4_select(), isc::ha::HAImpl::subnet4Select(), subnet6_select(), isc::ha::HAImpl::subnet6Select(), and isc::limits::LimitManager::subnet_select().

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

- callout_handle.h
- callout_handle.cc