Kea 2.7.4
|
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. | |
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:
Definition at line 78 of file callout_handle.h.
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.
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.
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.
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.
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.
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.
|
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.
|
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.
|
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.
name | Name of the element in the argument list to set. |
Definition at line 191 of file callout_handle.h.
|
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.
name | Name of the context item to delete. |
Definition at line 336 of file callout_handle.h.
|
inline |
Get argument.
Gets the value of an argument.
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. |
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 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().
vector< string > isc::hooks::CalloutHandle::getArgumentNames | ( | ) | const |
Get argument names.
Returns a vector holding the names of arguments in the argument vector.
Definition at line 65 of file callout_handle.cc.
|
inline |
Get context.
Gets an element from the context associated with the current library.
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. |
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 pkt4_send(), pkt6_send(), subnet4_select(), and subnet6_select().
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.
Definition at line 110 of file callout_handle.cc.
|
inline |
Get current hook index.
Definition at line 381 of file callout_handle.h.
|
inline |
Get current library index.
Definition at line 367 of file callout_handle.h.
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.
Definition at line 125 of file callout_handle.cc.
References isc::hooks::ServerHooks::getName().
|
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.
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. |
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 300 of file callout_handle.h.
ParkingLotHandlePtr isc::hooks::CalloutHandle::getParkingLotHandlePtr | ( | ) | const |
Returns pointer to the parking lot handle for this hook point.
Definition at line 75 of file callout_handle.cc.
References isc::hooks::ServerHooks::getParkingLotPtr().
|
inline |
Returns the next processing step.
Gets the current value of the next step. See setStatus for detailed definition.
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().
|
inline |
Set argument.
Sets the value of an argument. The argument is created if it does not already exist.
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 dhcp4_srv_configured(), dhcp6_srv_configured(), isc::config::CmdsImpl::setResponse(), subnet4_select(), and subnet6_select().
|
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.
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 pkt4_receive(), and pkt6_receive().
|
inline |
Set current hook index.
hook_index | The hook index |
Definition at line 388 of file callout_handle.h.
|
inline |
Set current library index.
library_index | The library index |
Definition at line 374 of file callout_handle.h.
|
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.
next | New 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().