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.

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

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

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.

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

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().

◆ 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 pkt4_receive(), and pkt6_receive().

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

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

◆ 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(), dhcp4_srv_configured(), dhcp6_srv_configured(), and pkt4_send().

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

Public Types

Public Member Functions

Detailed Description

Member Typedef Documentation

◆ ContextCollection

◆ ElementCollection

Member Enumeration Documentation

◆ CalloutNextStep

Constructor & Destructor Documentation

◆ CalloutHandle()

◆ ~CalloutHandle()

Member Function Documentation

◆ deleteAllArguments()

◆ deleteAllContext()

◆ deleteArgument()

◆ deleteContext()

◆ getArgument()

◆ getArgumentNames()

◆ getContext()

◆ getContextNames()

◆ getCurrentHook()

◆ getCurrentLibrary()

◆ getHookName()

◆ getOptionalContext()

◆ getParkingLotHandlePtr()

◆ getStatus()

◆ setArgument()

◆ setContext()

◆ setCurrentHook()

◆ setCurrentLibrary()

◆ setStatus()