Classes | Public Member Functions | List of all members
ndn::mgmt::Dispatcher Class Reference

represents a 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 More...
 
virtual ~Dispatcher ()
 
template<typename CP >
void addControlCommand (const PartialName &relPrefix, Authorization authorize, ValidateParameters validate, ControlCommandHandler handle)
 register a ControlCommand More...
 
PostNotification addNotificationStream (const PartialName &relPrefix)
 register a NotificationStream More...
 
void addStatusDataset (const PartialName &relPrefix, Authorization authorize, StatusDatasetHandler handle)
 register a StatusDataset or a prefix under which StatusDatasets can be requested More...
 
void addTopPrefix (const Name &prefix, bool wantRegister=true, const security::SigningInfo &signingInfo=security::SigningInfo())
 add a top-level prefix More...
 
void removeTopPrefix (const Name &prefix)
 remove a top-level prefix More...
 

Detailed Description

represents a dispatcher on server side of NFD Management protocol

Definition at line 130 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
facethe Face on which the dispatcher operates
keyChaina KeyChain to sign Data
signingInfosigning parameters to sign Data with keyChain
imsCapacitycapacity of the internal InMemoryStorage used by dispatcher

Definition at line 45 of file dispatcher.cpp.

◆ ~Dispatcher()

ndn::mgmt::Dispatcher::~Dispatcher ( )
virtualdefault

Member Function Documentation

◆ addControlCommand()

template<typename CP >
void ndn::mgmt::Dispatcher::addControlCommand ( const PartialName &  relPrefix,
Authorization  authorize,
ValidateParameters  validate,
ControlCommandHandler  handle 
)

register a ControlCommand

Template Parameters
CPsubclass of ControlParameters used by this command
Parameters
relPrefixa prefix for this command, e.g., "faces/create"; relPrefixes in ControlCommands, StatusDatasets, NotificationStreams must be non-overlapping (no relPrefix is a prefix of another relPrefix)
authorizeCallback to authorize the incoming commands
validateCallback to validate parameters of the incoming commands
handleCallback to handle the commands
Precondition
no top-level prefix has been added
Exceptions
std::out_of_rangerelPrefix overlaps with an existing relPrefix
std::domain_errorone or more top-level prefix has been added

Procedure for processing a ControlCommand:

  1. extract the NameComponent containing ControlParameters (the component after relPrefix), and parse ControlParameters into type CP; if parsing fails, abort these steps
  2. perform authorization; if authorization is rejected, perform the RejectReply action, and abort these steps
  3. validate ControlParameters; if validation fails, make ControlResponse with StatusCode 400, and go to step 5
  4. invoke 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, abort these steps and log an error
  8. send the signed Data packet

Definition at line 460 of file dispatcher.hpp.

◆ addNotificationStream()

PostNotification ndn::mgmt::Dispatcher::addNotificationStream ( const PartialName &  relPrefix)

register a NotificationStream

Parameters
relPrefixa prefix for this notification stream, e.g., "faces/events"; relPrefixes in ControlCommands, StatusDatasets, NotificationStreams must be non-overlapping (no relPrefix is a prefix of another relPrefix)
Returns
a function into which notifications can be posted
Precondition
no top-level prefix has been added
Exceptions
std::out_of_rangerelPrefix overlaps with an existing relPrefix
std::domain_errorone or more top-level prefix has 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, abort these steps and log an error
  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, abort these steps and log an error
  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
relPrefixa prefix for this dataset, e.g., "faces/list"; relPrefixes in ControlCommands, StatusDatasets, NotificationStreams must be non-overlapping (no relPrefix is a prefix of another relPrefix)
authorizeshould set identity to Name() if the dataset is public
handleCallback to process the incoming dataset requests
Precondition
no top-level prefix has been added
Exceptions
std::out_of_rangerelPrefix overlaps with an existing relPrefix
std::domain_errorone or more top-level prefix has 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 authorization is rejected, perform the RejectReply action, and abort these steps
  3. invoke handler, store blocks passed to StatusDatasetAppend calls in a buffer, wait until StatusDatasetEnd 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 StatusDatasetAppend calls.

Definition at line 223 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
prefixa top-level prefix, e.g., "/localhost/nfd"
wantRegisterwhether prefix registration should be performed through the Face
signingInfosigning parameters to sign the prefix registration command
Exceptions
std::out_of_rangeprefix 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::domain_error
  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. foreach relPrefix from ControlCommands and StatusDatasets, join the top-level prefix with the relPrefix to obtain the full prefix, and invoke non-registering overload of face.setInterestFilter, with the InterestHandler set to an appropriate private method 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 58 of file dispatcher.cpp.

◆ removeTopPrefix()

void ndn::mgmt::Dispatcher::removeTopPrefix ( const Name &  prefix)

remove a top-level prefix

Parameters
prefixa top-level prefix, 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. unset each Interest filter recorded during addTopPrefix,

Definition at line 88 of file dispatcher.cpp.