ndn::mgmt::Dispatcher Class Reference

Implements a request dispatcher on server side of NFD Management protocol. More...

#include <ndn-cxx/mgmt/dispatcher.hpp>

Inheritance diagram for ndn::mgmt::Dispatcher:

Collaboration diagram for ndn::mgmt::Dispatcher:

Public Member Functions
	Dispatcher (Face &face, KeyChain &keyChain, const security::SigningInfo &signingInfo=security::SigningInfo(), size_t imsCapacity=256)
	Constructor.
template<typename Command >
void	addControlCommand (Authorization authorize, ControlCommandHandler handle)
	Register a ControlCommand (new style).
template<typename ParametersType , std::enable_if_t< std::is_convertible_v< ParametersType *, ControlParametersBase * >, int > = 0>
void	addControlCommand (const PartialName &relPrefix, Authorization authorize, ValidateParameters validate, ControlCommandHandler handle)
	Register a ControlCommand (old style).
PostNotification	addNotificationStream (const PartialName &relPrefix)
	Register a NotificationStream.
void	addStatusDataset (const PartialName &relPrefix, Authorization authorize, StatusDatasetHandler handle)
	Register a StatusDataset or a prefix under which StatusDatasets can be requested.
void	addTopPrefix (const Name &prefix, bool wantRegister=true, const security::SigningInfo &signingInfo=security::SigningInfo())
	Add a top-level prefix.
void	removeTopPrefix (const Name &prefix)
	Remove a top-level prefix.

Detailed Description

Implements a request dispatcher on server side of NFD Management protocol.

Definition at line 140 of file dispatcher.hpp.

Constructor & Destructor Documentation

Dispatcher()

ndn::mgmt::Dispatcher::Dispatcher	(	Face &	face,
		KeyChain &	keyChain,
		const security::SigningInfo &	signingInfo = security::SigningInfo(),
		size_t	imsCapacity = 256
	)

Constructor.

Parameters

face	the Face on which the dispatcher operates
keyChain	a KeyChain to sign Data
signingInfo	signing parameters to sign Data with keyChain
imsCapacity	capacity of the internal InMemoryStorage used by dispatcher

Definition at line 44 of file dispatcher.cpp.

Member Function Documentation

addControlCommand() [1/2]

template<typename Command >

void ndn::mgmt::Dispatcher::addControlCommand ( Authorization  authorize, ControlCommandHandler  handle  )

inline

Register a ControlCommand (new style).

Template Parameters

Command

The type of ControlCommand to register.

Parameters

authorize	Callback to authorize the incoming commands.
handle	Callback to handle the commands.

Precondition

No top-level prefix has been added.

Exceptions

std::out_of_range	relPrefix overlaps with an existing relPrefix.
std::domain_error	One or more top-level prefixes have been added.

Procedure for processing a ControlCommand registered through this function:

1. Extract the parameters from the request by invoking Command::parseRequest on the incoming Interest; if parsing fails, abort these steps.
2. Perform authorization; if the authorization is rejected, perform the RejectReply action and abort these steps.
3. Validate the parameters with Command::validateRequest.
4. Normalize the parameters with Command::applyDefaultsToRequest.
5. If either step 3 or 4 fails, create a ControlResponse with StatusCode 400 and go to step 7.
6. Invoke the command handler, wait until CommandContinuation is called.
7. Encode the ControlResponse into one Data packet.
8. Sign the Data packet.
9. If the Data packet is too large, log an error and abort these steps.
10. Send the signed Data packet.

Definition at line 268 of file dispatcher.hpp.

addControlCommand() [2/2]

template<typename ParametersType , std::enable_if_t< std::is_convertible_v< ParametersType *, ControlParametersBase * >, int > = 0>

void ndn::mgmt::Dispatcher::addControlCommand ( const PartialName &  relPrefix, Authorization  authorize, ValidateParameters  validate, ControlCommandHandler  handle  )

inline

Register a ControlCommand (old style).

Template Parameters

ParametersType

Concrete subclass of ControlParameters used by this command.

Parameters

relPrefix	The name prefix for this command relative to the top-level prefix, e.g., "faces/create". The prefixes across all ControlCommands, StatusDatasets, and NotificationStreams must not overlap (no relPrefix is a prefix of another relPrefix).
authorize	Callback to authorize the incoming commands
validate	Callback to validate parameters of the incoming commands
handle	Callback to handle the commands

Precondition

No top-level prefix has been added.

Exceptions

std::out_of_range	relPrefix overlaps with an existing relPrefix.
std::domain_error	One or more top-level prefixes have been added.

Procedure for processing a ControlCommand registered through this function:

1. Extract the NameComponent containing ControlParameters (the component after relPrefix), and parse ControlParameters into ParametersType; if parsing fails, abort these steps.
2. Perform authorization; if the authorization is rejected, perform the RejectReply action and abort these steps.
3. Validate the ControlParameters; if validation fails, create a ControlResponse with StatusCode 400 and go to step 5.
4. Invoke the command handler, wait until CommandContinuation is called.
5. Encode the ControlResponse into one Data packet.
6. Sign the Data packet.
7. If the Data packet is too large, log an error and abort these steps.
8. Send the signed Data packet.

Definition at line 220 of file dispatcher.hpp.

addNotificationStream()

PostNotification ndn::mgmt::Dispatcher::addNotificationStream

(

const PartialName &

relPrefix

)

Register a NotificationStream.

Parameters

relPrefix

The name prefix for this notification stream relative to the top-level prefix, e.g., "faces/events". The prefixes across all ControlCommands, StatusDatasets, and NotificationStreams must not overlap (no relPrefix is a prefix of another relPrefix).

Returns

A function object that can be called to post a notification.

Precondition

No top-level prefix has been added.

Exceptions

std::out_of_range	relPrefix overlaps with an existing relPrefix.
std::domain_error	One or more top-level prefixes have been added.

Procedure for posting a notification:

1. If no top-level prefix has been added, or more than one top-level prefixes have been added, log an error and abort these steps.
2. Assign the next sequence number to the notification.
3. Place the notification block into one Data packet under the sole top-level prefix.
4. Sign the Data packet.
5. If the Data packet is too large, log an error and abort these steps.
6. Send the signed Data packet.

Definition at line 300 of file dispatcher.cpp.

addStatusDataset()

void ndn::mgmt::Dispatcher::addStatusDataset	(	const PartialName &	relPrefix,
		Authorization	authorize,
		StatusDatasetHandler	handle
	)

Register a StatusDataset or a prefix under which StatusDatasets can be requested.

Parameters

relPrefix	The name prefix for this dataset relative to the top-level prefix, e.g., "faces/list". The prefixes across all ControlCommands, StatusDatasets, and NotificationStreams must not overlap (no relPrefix is a prefix of another relPrefix).
authorize	should set identity to Name() if the dataset is public
handle	Callback to process the incoming dataset requests

Precondition

No top-level prefix has been added.

Exceptions

std::out_of_range	relPrefix overlaps with an existing relPrefix.
std::domain_error	One or more top-level prefixes have been added.

The payload of the returned status dataset data packet is at most half of the maximum data packet size.

Procedure for processing a StatusDataset request:

1. If the request Interest contains version or segment components, abort these steps (note: the request may contain more components after relPrefix, e.g., a query condition).
2. Perform authorization; if the authorization is rejected, perform the RejectReply action and abort these steps.
3. Invoke the handler, store blocks passed to StatusDatasetContext::append calls in a buffer, wait until StatusDatasetContext::end is called.
4. Allocate a version.
5. Segment the buffer into one or more segments under the allocated version, such that the Data packets will not become too large after signing.
6. Set FinalBlockId on at least the last segment.
7. Sign the Data packets.
8. Send the signed Data packets.

As an optimization, a Data packet may be sent as soon as enough octets have been collected through StatusDatasetContext::append calls.

Definition at line 226 of file dispatcher.cpp.

addTopPrefix()

void ndn::mgmt::Dispatcher::addTopPrefix	(	const Name &	prefix,
		bool	wantRegister = true,
		const security::SigningInfo &	signingInfo = security::SigningInfo()
	)

Add a top-level prefix.

Parameters

prefix	top-level prefix to add, e.g., "/localhost/nfd"
wantRegister	whether prefix registration should be performed through the Face
signingInfo	signing parameters to sign the prefix registration command

Exceptions

std::out_of_range

prefix overlaps with an existing top-level prefix

Procedure for adding a top-level prefix:

1. If the new top-level prefix overlaps with an existing top-level prefix (one top-level prefix is a prefix of another top-level prefix), throw std::out_of_range.
2. If wantRegister is true, invoke Face::registerPrefix for the top-level prefix. The returned RegisteredPrefixHandle shall be recorded internally, indexed by the top-level prefix.
3. For each relPrefix from ControlCommands and StatusDatasets, join the top-level prefix with relPrefix to obtain the full prefix and invoke the non-registering overload of Face::setInterestFilter, with the InterestHandler set to an appropriate function to handle incoming Interests for the ControlCommand or StatusDataset. The returned InterestFilterHandle shall be recorded internally, indexed by the top-level prefix.

Definition at line 54 of file dispatcher.cpp.

removeTopPrefix()

void ndn::mgmt::Dispatcher::removeTopPrefix

(

const Name &

prefix

)

Remove a top-level prefix.

Parameters

prefix

top-level prefix to remove, e.g., "/localhost/nfd"

Procedure for removing a top-level prefix:

1. If the top-level prefix has not been added, abort these steps.
2. If the top-level prefix has been added with wantRegister, unregister the prefix.
3. Clear all Interest filters previously set by addTopPrefix().

Definition at line 86 of file dispatcher.cpp.