Kea 2.7.4
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, ElementCollectionContextCollection
 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 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

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
managerPointer to the callout manager object.
lmcollPointer 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.

◆ ~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
nameName 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
nameName 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
nameName 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
NoSuchArgumentNo argument with the given name is present.
boost::bad_any_castAn 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 buffer4_receive(), dhcp4_srv_configured(), dhcp6_srv_configured(), isc::config::CmdsImpl::extractCommand(), pkt4_receive(), pkt4_send(), pkt6_receive(), pkt6_send(), subnet4_select(), and subnet6_select().

◆ 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
nameName 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
NoSuchCalloutContextThrown if no context element with the name "name" is present.
boost::bad_any_castThrown 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 pkt4_send(), pkt6_send(), 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.

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

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

References isc::hooks::ServerHooks::getName().

+ Here is the call graph for this function:

◆ 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
nameName 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_castThrown 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.

References isc::hooks::ServerHooks::getParkingLotPtr().

+ Here is the call graph for this function:

◆ 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 buffer4_receive(), buffer6_receive(), lease4_server_decline(), leases4_committed(), leases6_committed(), pkt4_receive(), pkt4_send(), pkt6_receive(), pkt6_send(), subnet4_select(), and subnet6_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
nameName of the argument.
valueValue to set. That can be of any data type.

Definition at line 147 of file callout_handle.h.

Referenced by dhcp4_srv_configured(), dhcp6_srv_configured(), isc::config::CmdsImpl::setResponse(), subnet4_select(), and subnet6_select().

◆ 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
nameName of the element in the context to set.
valueValue to set.

Definition at line 253 of file callout_handle.h.

Referenced by pkt4_receive(), and pkt6_receive().

◆ setCurrentHook()

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

Set current hook index.

Parameters
hook_indexThe hook index

Definition at line 388 of file callout_handle.h.

◆ setCurrentLibrary()

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

Set current library index.

Parameters
library_indexThe library index

Definition at line 374 of file callout_handle.h.

◆ 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
nextNew value of the next step status.

Definition at line 231 of file callout_handle.h.

Referenced by buffer4_receive(), dhcp4_srv_configured(), dhcp6_srv_configured(), and pkt4_send().


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