Provide a communication channel with local or remote NDN forwarder. More...
#include <face.hpp>
Classes | |
class | Error |
class | OversizedPacketError |
Exception thrown when attempting to send a packet over size limit. More... | |
Public Member Functions | |
Face (shared_ptr< Transport > transport=nullptr) | |
Create Face using given transport (or default transport if omitted) More... | |
Face (boost::asio::io_service &ioService) | |
Create Face using default transport and given io_service. More... | |
Face (shared_ptr< Transport > transport, KeyChain &keyChain) | |
Create Face using given transport and KeyChain. More... | |
Face (shared_ptr< Transport > transport, boost::asio::io_service &ioService) | |
Create Face using given transport and IO service. More... | |
Face (shared_ptr< Transport > transport, boost::asio::io_service &ioService, KeyChain &keyChain) | |
Create a new Face using given Transport and IO service. More... | |
virtual | ~Face () |
const PendingInterestId * | expressInterest (const Interest &interest, const DataCallback &afterSatisfied, const NackCallback &afterNacked, const TimeoutCallback &afterTimeout) |
Express Interest. More... | |
void | removePendingInterest (const PendingInterestId *pendingInterestId) |
Cancel previously expressed Interest. More... | |
void | removeAllPendingInterests () |
Cancel all previously expressed Interests. More... | |
size_t | getNPendingInterests () const |
Get number of pending Interests. More... | |
const RegisteredPrefixId * | setInterestFilter (const InterestFilter &interestFilter, const InterestCallback &onInterest, const RegisterPrefixFailureCallback &onFailure, const security::SigningInfo &signingInfo=security::SigningInfo(), uint64_t flags=nfd::ROUTE_FLAG_CHILD_INHERIT) |
Set InterestFilter to dispatch incoming matching interest to onInterest callback and register the filtered prefix with the connected NDN forwarder. More... | |
const RegisteredPrefixId * | setInterestFilter (const InterestFilter &interestFilter, const InterestCallback &onInterest, const RegisterPrefixSuccessCallback &onSuccess, const RegisterPrefixFailureCallback &onFailure, const security::SigningInfo &signingInfo=security::SigningInfo(), uint64_t flags=nfd::ROUTE_FLAG_CHILD_INHERIT) |
Set InterestFilter to dispatch incoming matching interest to onInterest callback and register the filtered prefix with the connected NDN forwarder. More... | |
const InterestFilterId * | setInterestFilter (const InterestFilter &interestFilter, const InterestCallback &onInterest) |
Set InterestFilter to dispatch incoming matching interest to onInterest callback. More... | |
const RegisteredPrefixId * | registerPrefix (const Name &prefix, const RegisterPrefixSuccessCallback &onSuccess, const RegisterPrefixFailureCallback &onFailure, const security::SigningInfo &signingInfo=security::SigningInfo(), uint64_t flags=nfd::ROUTE_FLAG_CHILD_INHERIT) |
Register prefix with the connected NDN forwarder. More... | |
void | unsetInterestFilter (const RegisteredPrefixId *registeredPrefixId) |
Remove the registered prefix entry with the registeredPrefixId. More... | |
void | unsetInterestFilter (const InterestFilterId *interestFilterId) |
Remove previously set InterestFilter from library's FIB. More... | |
void | unregisterPrefix (const RegisteredPrefixId *registeredPrefixId, const UnregisterPrefixSuccessCallback &onSuccess, const UnregisterPrefixFailureCallback &onFailure) |
Unregister prefix from RIB. More... | |
void | put (Data data) |
Publish data packet. More... | |
void | put (lp::Nack nack) |
Send a network NACK. More... | |
void | processEvents (time::milliseconds timeout=time::milliseconds::zero(), bool keepThread=false) |
Process any data to receive or call timeout callbacks. More... | |
void | shutdown () |
Shutdown face operations. More... | |
boost::asio::io_service & | getIoService () |
Return nullptr (cannot use IoService in simulations), preserved for API compatibility. More... | |
Public Attributes | |
NDN_CXX_PUBLIC_WITH_TESTS_ELSE_PROTECTED | __pad0__: shared_ptr<Transport> getTransport() |
Protected Member Functions | |
virtual void | doProcessEvents (time::milliseconds timeout, bool keepThread) |
Provide a communication channel with local or remote NDN forwarder.
|
explicit |
Create Face using given transport (or default transport if omitted)
transport | the transport for lower layer communication. If nullptr, a default transport will be used. The default transport is determined from a FaceUri in NDN_CLIENT_TRANSPORT environ, a FaceUri in configuration file 'transport' key, or UnixTransport. |
ConfigFile::Error | transport is nullptr, and the configuration file cannot be parsed or specifies an unsupported protocol |
Definition at line 65 of file face.cpp.
References ns3::ndn::StackHelper::getKeyChain().
|
explicit |
Create Face using default transport and given io_service.
Usage examples:
or
ioService | A reference to boost::io_service object that should control all IO operations. |
ConfigFile::Error | the configuration file cannot be parsed or specifies an unsupported protocol |
Definition at line 71 of file face.cpp.
References ns3::ndn::StackHelper::getKeyChain().
ndn::Face::Face | ( | shared_ptr< Transport > | transport, |
KeyChain & | keyChain | ||
) |
Create Face using given transport and KeyChain.
transport | the transport for lower layer communication. If nullptr, a default transport will be used. |
keyChain | the KeyChain to sign commands |
ConfigFile::Error | transport is nullptr, and the configuration file cannot be parsed or specifies an unsupported protocol |
ndn::Face::Face | ( | shared_ptr< Transport > | transport, |
boost::asio::io_service & | ioService | ||
) |
Create Face using given transport and IO service.
transport | the transport for lower layer communication. If nullptr, a default transport will be used. |
ioService | the io_service that controls all IO operations |
ConfigFile::Error | transport is nullptr, and the configuration file cannot be parsed or specifies an unsupported protocol |
Definition at line 83 of file face.cpp.
References ns3::ndn::StackHelper::getKeyChain().
ndn::Face::Face | ( | shared_ptr< Transport > | transport, |
boost::asio::io_service & | ioService, | ||
KeyChain & | keyChain | ||
) |
Create a new Face using given Transport and IO service.
transport | the transport for lower layer communication. If nullptr, a default transport will be used. |
ioService | the io_service that controls all IO operations |
keyChain | the KeyChain to sign commands |
ConfigFile::Error | transport is nullptr, and the configuration file cannot be parsed or specifies an unsupported protocol |
Definition at line 89 of file face.cpp.
References nfd::face::GenericLinkService::Options::allowLocalFields, IO_CAPTURE_WEAK_IMPL, IO_CAPTURE_WEAK_IMPL_END, ndn::security::v2::KeyChain, and ~Face().
|
virtualdefault |
Referenced by Face().
const PendingInterestId * ndn::Face::expressInterest | ( | const Interest & | interest, |
const DataCallback & | afterSatisfied, | ||
const NackCallback & | afterNacked, | ||
const TimeoutCallback & | afterTimeout | ||
) |
Express Interest.
interest | the Interest; a copy will be made, so that the caller is not required to maintain the argument unchanged |
afterSatisfied | function to be invoked if Data is returned |
afterNacked | function to be invoked if Network NACK is returned |
afterTimeout | function to be invoked if neither Data nor Network NACK is returned within InterestLifetime |
OversizedPacketError | encoded Interest size exceeds MAX_NDN_PACKET_SIZE |
Definition at line 144 of file face.cpp.
References IO_CAPTURE_WEAK_IMPL, IO_CAPTURE_WEAK_IMPL_END, and NDN_LOG_DEBUG.
Referenced by ndn::nfd::Controller::Controller(), ndn::security::v2::CertificateFetcherFromNetwork::doFetch(), ndn::security::v2::CertificateFetcherDirectFetch::doFetch(), ndn::security::v2::CertificateBundleFetcher::doFetch(), and ndn::util::NotificationSubscriberBase::stop().
void ndn::Face::removePendingInterest | ( | const PendingInterestId * | pendingInterestId | ) |
Cancel previously expressed Interest.
pendingInterestId | The ID returned from expressInterest. |
Definition at line 161 of file face.cpp.
References IO_CAPTURE_WEAK_IMPL, and IO_CAPTURE_WEAK_IMPL_END.
Referenced by ndn::util::NotificationSubscriberBase::stop().
void ndn::Face::removeAllPendingInterests | ( | ) |
Cancel all previously expressed Interests.
Definition at line 169 of file face.cpp.
References IO_CAPTURE_WEAK_IMPL, and IO_CAPTURE_WEAK_IMPL_END.
size_t ndn::Face::getNPendingInterests | ( | ) | const |
const RegisteredPrefixId * ndn::Face::setInterestFilter | ( | const InterestFilter & | interestFilter, |
const InterestCallback & | onInterest, | ||
const RegisterPrefixFailureCallback & | onFailure, | ||
const security::SigningInfo & | signingInfo = security::SigningInfo() , |
||
uint64_t | flags = nfd::ROUTE_FLAG_CHILD_INHERIT |
||
) |
Set InterestFilter to dispatch incoming matching interest to onInterest callback and register the filtered prefix with the connected NDN forwarder.
This version of setInterestFilter combines setInterestFilter and registerPrefix operations and is intended to be used when only one filter for the same prefix needed to be set. When multiple names sharing the same prefix should be dispatched to different callbacks, use one registerPrefix call, followed (in onSuccess callback) by a series of setInterestFilter calls.
interestFilter | Interest filter (prefix part will be registered with the forwarder) |
onInterest | A callback to be called when a matching interest is received |
onFailure | A callback to be called when prefixRegister command fails |
flags | (optional) RIB flags |
signingInfo | (optional) Signing parameters. When omitted, a default parameters used in the signature will be used. |
Definition at line 201 of file face.cpp.
Referenced by ndn::mgmt::Dispatcher::addTopPrefix().
const RegisteredPrefixId * ndn::Face::setInterestFilter | ( | const InterestFilter & | interestFilter, |
const InterestCallback & | onInterest, | ||
const RegisterPrefixSuccessCallback & | onSuccess, | ||
const RegisterPrefixFailureCallback & | onFailure, | ||
const security::SigningInfo & | signingInfo = security::SigningInfo() , |
||
uint64_t | flags = nfd::ROUTE_FLAG_CHILD_INHERIT |
||
) |
Set InterestFilter to dispatch incoming matching interest to onInterest callback and register the filtered prefix with the connected NDN forwarder.
This version of setInterestFilter combines setInterestFilter and registerPrefix operations and is intended to be used when only one filter for the same prefix needed to be set. When multiple names sharing the same prefix should be dispatched to different callbacks, use one registerPrefix call, followed (in onSuccess callback) by a series of setInterestFilter calls.
interestFilter | Interest filter (prefix part will be registered with the forwarder) |
onInterest | A callback to be called when a matching interest is received |
onSuccess | A callback to be called when prefixRegister command succeeds |
onFailure | A callback to be called when prefixRegister command fails |
flags | (optional) RIB flags |
signingInfo | (optional) Signing parameters. When omitted, a default parameters used in the signature will be used. |
Definition at line 211 of file face.cpp.
References ndn::nfd::CommandOptions::setSigningInfo().
const InterestFilterId * ndn::Face::setInterestFilter | ( | const InterestFilter & | interestFilter, |
const InterestCallback & | onInterest | ||
) |
Set InterestFilter to dispatch incoming matching interest to onInterest callback.
interestFilter | Interest |
onInterest | A callback to be called when a matching interest is received |
This method modifies library's FIB only, and does not register the prefix with the forwarder. It will always succeed. To register prefix with the forwarder, use registerPrefix, or use the setInterestFilter overload taking two callbacks.
Definition at line 228 of file face.cpp.
References IO_CAPTURE_WEAK_IMPL, and IO_CAPTURE_WEAK_IMPL_END.
const RegisteredPrefixId * ndn::Face::registerPrefix | ( | const Name & | prefix, |
const RegisterPrefixSuccessCallback & | onSuccess, | ||
const RegisterPrefixFailureCallback & | onFailure, | ||
const security::SigningInfo & | signingInfo = security::SigningInfo() , |
||
uint64_t | flags = nfd::ROUTE_FLAG_CHILD_INHERIT |
||
) |
Register prefix with the connected NDN forwarder.
This method only modifies forwarder's RIB and does not associate any onInterest callbacks. Use setInterestFilter method to dispatch incoming Interests to the right callbacks.
prefix | A prefix to register with the connected NDN forwarder |
onSuccess | A callback to be called when prefixRegister command succeeds |
onFailure | A callback to be called when prefixRegister command fails |
signingInfo | (optional) Signing parameters. When omitted, a default parameters used in the signature will be used. |
flags | Prefix registration flags |
Definition at line 241 of file face.cpp.
References ndn::nfd::CommandOptions::setSigningInfo().
Referenced by ndn::mgmt::Dispatcher::addTopPrefix().
void ndn::Face::unsetInterestFilter | ( | const RegisteredPrefixId * | registeredPrefixId | ) |
Remove the registered prefix entry with the registeredPrefixId.
This does not affect another registered prefix with a different registeredPrefixId, even it if has the same prefix name. If there is no entry with the registeredPrefixId, do nothing.
unsetInterestFilter will use the same credentials as original setInterestFilter/registerPrefix command
registeredPrefixId | The ID returned from registerPrefix |
Definition at line 254 of file face.cpp.
References IO_CAPTURE_WEAK_IMPL, and IO_CAPTURE_WEAK_IMPL_END.
Referenced by ndn::mgmt::Dispatcher::removeTopPrefix().
void ndn::Face::unsetInterestFilter | ( | const InterestFilterId * | interestFilterId | ) |
Remove previously set InterestFilter from library's FIB.
This method always succeeds and will NOT send any request to the connected forwarder.
interestFilterId | The ID returned from setInterestFilter. |
Definition at line 262 of file face.cpp.
References IO_CAPTURE_WEAK_IMPL, and IO_CAPTURE_WEAK_IMPL_END.
void ndn::Face::unregisterPrefix | ( | const RegisteredPrefixId * | registeredPrefixId, |
const UnregisterPrefixSuccessCallback & | onSuccess, | ||
const UnregisterPrefixFailureCallback & | onFailure | ||
) |
Unregister prefix from RIB.
unregisterPrefix will use the same credentials as original setInterestFilter/registerPrefix command
If registeredPrefixId was obtained using setInterestFilter, the corresponding InterestFilter will be unset too.
registeredPrefixId | The ID returned from registerPrefix |
onSuccess | Callback to be called when operation succeeds |
onFailure | Callback to be called when operation fails |
Definition at line 270 of file face.cpp.
References IO_CAPTURE_WEAK_IMPL, and IO_CAPTURE_WEAK_IMPL_END.
Referenced by ndn::mgmt::Dispatcher::removeTopPrefix().
void ndn::Face::put | ( | Data | data | ) |
Publish data packet.
data | the Data; a copy will be made, so that the caller is not required to maintain the argument unchanged |
This method can be called to satisfy incoming Interests, or to add Data packet into the cache of the local NDN forwarder if forwarder is configured to accept unsolicited Data.
OversizedPacketError | encoded Data size exceeds MAX_NDN_PACKET_SIZE |
Definition at line 183 of file face.cpp.
References ndn::Data::getName(), IO_CAPTURE_WEAK_IMPL, IO_CAPTURE_WEAK_IMPL_END, and NDN_LOG_DEBUG.
Referenced by ndn::util::NotificationStream< Notification >::postNotification(), and ndn::mgmt::Dispatcher::removeTopPrefix().
void ndn::Face::put | ( | lp::Nack | nack | ) |
Send a network NACK.
nack | the Nack; a copy will be made, so that the caller is not required to maintain the argument unchanged |
OversizedPacketError | encoded Nack size exceeds MAX_NDN_PACKET_SIZE |
Definition at line 192 of file face.cpp.
References ndn::lp::Nack::getHeader(), ndn::lp::Nack::getInterest(), ndn::lp::NackHeader::getReason(), IO_CAPTURE_WEAK_IMPL, IO_CAPTURE_WEAK_IMPL_END, and NDN_LOG_DEBUG.
|
inline |
Process any data to receive or call timeout callbacks.
This call will block forever (default timeout == 0) to process IO on the face. To exit, one expected to call face.shutdown() from one of the callback methods.
If positive timeout is specified, then processEvents will exit after this timeout, if not stopped earlier with face.shutdown() or when all active events finish. The call can be called repeatedly, if desired.
If negative timeout is specified, then processEvents will not block and process only pending events.
timeout | maximum time to block the thread |
keepThread | Keep thread in a blocked state (in event processing), even when there are no outstanding events (e.g., no Interest/Data is expected) |
OversizedPacketError | encoded packet size exceeds MAX_NDN_PACKET_SIZE |
Definition at line 447 of file face.hpp.
References websocketpp::transport::error::timeout.
void ndn::Face::shutdown | ( | ) |
Shutdown face operations.
This method cancels all pending operations and closes connection to NDN Forwarder.
Note that this method does not stop IO service and if the same IO service is shared between multiple Faces or with other IO objects (e.g., Scheduler).
Definition at line 285 of file face.cpp.
References IO_CAPTURE_WEAK_IMPL, and IO_CAPTURE_WEAK_IMPL_END.
|
inline |
Return nullptr (cannot use IoService in simulations), preserved for API compatibility.
Definition at line 468 of file face.hpp.
References NDN_CXX_PUBLIC_WITH_TESTS_ELSE_PROTECTED.
Referenced by ndn::util::DummyClientFace::DummyClientFace().
|
protectedvirtual |
Definition at line 280 of file face.cpp.
Referenced by ndn::util::DummyClientFace::receive().
NDN_CXX_PUBLIC_WITH_TESTS_ELSE_PROTECTED ndn::Face::__pad0__ |