NS-3 based Named Data Networking (NDN) simulator
ndnSIM 2.3: NDN, CCN, CCNx, content centric networks
API Documentation
ndn::Face Class Reference

Provide a communication channel with local or remote NDN forwarder. More...

#include <face.hpp>

Inheritance diagram for ndn::Face:
Collaboration diagram for ndn::Face:

Classes

class  Error
 

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...
 
 ~Face ()
 
const PendingInterestId * expressInterest (const Interest &interest, const DataCallback &afterSatisfied, const NackCallback &afterNacked, const TimeoutCallback &afterTimeout)
 Express Interest. More...
 
const PendingInterestId * expressInterest (const Interest &interest, const OnData &onData, const OnTimeout &onTimeout=nullptr)
 Express Interest. More...
 
const PendingInterestId * expressInterest (const Name &name, const Interest &tmpl, const OnData &onData, const OnTimeout &onTimeout=nullptr)
 Express Interest using name and Interest template. 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...
 
 DEPRECATED (const RegisteredPrefixId *setInterestFilter(const InterestFilter &interestFilter, const OnInterest &onInterest, const RegisterPrefixSuccessCallback &onSuccess, const RegisterPrefixFailureCallback &onFailure, const security::v1::IdentityCertificate &certificate, 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...
 
 DEPRECATED (const RegisteredPrefixId *setInterestFilter(const InterestFilter &interestFilter, const OnInterest &onInterest, const RegisterPrefixFailureCallback &onFailure, const security::v1::IdentityCertificate &certificate, 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...
 
 DEPRECATED (const RegisteredPrefixId *setInterestFilter(const InterestFilter &interestFilter, const OnInterest &onInterest, const RegisterPrefixSuccessCallback &onSuccess, const RegisterPrefixFailureCallback &onFailure, const Name &identity, 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...
 
 DEPRECATED (const RegisteredPrefixId *setInterestFilter(const InterestFilter &interestFilter, const OnInterest &onInterest, const RegisterPrefixFailureCallback &onFailure, const Name &identity, 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 * 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...
 
 DEPRECATED (const RegisteredPrefixId *registerPrefix(const Name &prefix, const RegisterPrefixSuccessCallback &onSuccess, const RegisterPrefixFailureCallback &onFailure, const security::v1::IdentityCertificate &certificate, uint64_t flags=nfd::ROUTE_FLAG_CHILD_INHERIT))
 Register prefix with the connected NDN forwarder. More...
 
 DEPRECATED (const RegisteredPrefixId *registerPrefix(const Name &prefix, const RegisterPrefixSuccessCallback &onSuccess, const RegisterPrefixFailureCallback &onFailure, const Name &identity, uint64_t flags=nfd::ROUTE_FLAG_CHILD_INHERIT))
 Register prefix with the connected NDN forwarder and call onInterest when a matching interest is received. 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 (const Data &data)
 Publish data packet. More...
 
void put (const lp::Nack &nack)
 sends a Network NACK More...
 
void processEvents (const 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 (const time::milliseconds &timeout, bool keepThread)
 

Detailed Description

Provide a communication channel with local or remote NDN forwarder.

Definition at line 125 of file face.hpp.

Constructor & Destructor Documentation

◆ Face() [1/5]

ndn::Face::Face ( shared_ptr< Transport transport = nullptr)
explicit

Create Face using given transport (or default transport if omitted)

Parameters
transportthe 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.
Exceptions
ConfigFile::Errorif transport is nullptr, and the configuration file cannot be parsed or specifies an unsupported protocol
Note
shared_ptr is passed by value because ownership is shared with this class

Definition at line 53 of file face.cpp.

References ns3::ndn::StackHelper::getKeyChain().

◆ Face() [2/5]

ndn::Face::Face ( boost::asio::io_service &  ioService)
explicit

Create Face using default transport and given io_service.

Usage examples:

Face face1;
Face face2(face1.getIoService());
// Now the following ensures that events on both faces are processed
face1.processEvents();
// or face1.getIoService().run();

or

boost::asio::io_service ioService;
Face face1(ioService);
Face face2(ioService);
ioService.run();
Parameters
ioServiceA reference to boost::io_service object that should control all IO operations.
Exceptions
ConfigFile::Errorthe configuration file cannot be parsed or specifies an unsupported protocol

Definition at line 59 of file face.cpp.

References ns3::ndn::StackHelper::getKeyChain().

◆ Face() [3/5]

ndn::Face::Face ( shared_ptr< Transport transport,
KeyChain keyChain 
)

Create Face using given transport and KeyChain.

Parameters
transportthe transport for lower layer communication. If nullptr, a default transport will be used.
keyChainthe KeyChain to sign commands
See also
Face(shared_ptr<Transport>)
Exceptions
ConfigFile::Errorif transport is nullptr, and the configuration file cannot be parsed or specifies an unsupported protocol
Note
shared_ptr is passed by value because ownership is shared with this class

Definition at line 65 of file face.cpp.

◆ Face() [4/5]

ndn::Face::Face ( shared_ptr< Transport transport,
boost::asio::io_service &  ioService 
)

Create Face using given transport and IO service.

Parameters
transportthe transport for lower layer communication. If nullptr, a default transport will be used.
ioServicethe io_service that controls all IO operations
See also
Face(boost::asio::io_service&)
Face(shared_ptr<Transport>)
Exceptions
ConfigFile::Errorif transport is nullptr, and the configuration file cannot be parsed or specifies an unsupported protocol
Note
shared_ptr is passed by value because ownership is shared with this class

Definition at line 71 of file face.cpp.

References ns3::ndn::StackHelper::getKeyChain().

◆ Face() [5/5]

ndn::Face::Face ( shared_ptr< Transport transport,
boost::asio::io_service &  ioService,
KeyChain keyChain 
)

Create a new Face using given Transport and IO service.

Parameters
transportthe transport for lower layer communication. If nullptr, a default transport will be used.
ioServicethe io_service that controls all IO operations
keyChainthe KeyChain to sign commands
See also
Face(boost::asio::io_service&)
Face(shared_ptr<Transport>, KeyChain&)
Exceptions
ConfigFile::Errorif transport is nullptr, and the configuration file cannot be parsed or specifies an unsupported protocol
Note
shared_ptr is passed by value because ownership is shared with this class

Definition at line 77 of file face.cpp.

References nfd::face::GenericLinkService::Options::allowLocalFields, IO_CAPTURE_WEAK_IMPL, IO_CAPTURE_WEAK_IMPL_END, and ~Face().

◆ ~Face()

ndn::Face::~Face ( )
default

Referenced by Face().

Member Function Documentation

◆ expressInterest() [1/3]

const PendingInterestId * ndn::Face::expressInterest ( const Interest interest,
const DataCallback afterSatisfied,
const NackCallback afterNacked,
const TimeoutCallback afterTimeout 
)

Express Interest.

Parameters
interestthe Interest; a copy will be made, so that the caller is not required to maintain the argument unchanged
afterSatisfiedfunction to be invoked if Data is returned
afterNackedfunction to be invoked if Network NACK is returned
afterTimeoutfunction to be invoked if neither Data nor Network NACK is returned within InterestLifetime

Definition at line 132 of file face.cpp.

References IO_CAPTURE_WEAK_IMPL, IO_CAPTURE_WEAK_IMPL_END, and ndn::MAX_NDN_PACKET_SIZE.

Referenced by ndn::security::Validator::afterCheckPolicy(), ndn::nfd::Controller::Controller(), expressInterest(), ndn::security::Validator::onNack(), and ndn::security::Validator::onTimeout().

◆ expressInterest() [2/3]

const PendingInterestId * ndn::Face::expressInterest ( const Interest interest,
const OnData onData,
const OnTimeout onTimeout = nullptr 
)

Express Interest.

Parameters
interestAn Interest to be expressed
onDataCallback to be called when a matching data packet is received
onTimeout(optional) A function object to call if the interest times out or is Nacked
Returns
The pending interest ID which can be used with removePendingInterest
Exceptions
Errorwhen Interest size exceeds maximum limit (MAX_NDN_PACKET_SIZE)
Deprecated:
use expressInterest(Interest, DataCallback, NackCallback, TimeoutCallback)

Definition at line 153 of file face.cpp.

References expressInterest().

◆ expressInterest() [3/3]

const PendingInterestId * ndn::Face::expressInterest ( const Name name,
const Interest tmpl,
const OnData onData,
const OnTimeout onTimeout = nullptr 
)

Express Interest using name and Interest template.

Parameters
nameName of the Interest
tmplInterest template to fill parameters
onDataCallback to be called when a matching data packet is received
onTimeout(optional) A function object to call if the interest times out or is Nacked
Returns
Opaque pending interest ID which can be used with removePendingInterest
Exceptions
Errorwhen Interest size exceeds maximum limit (MAX_NDN_PACKET_SIZE)
Deprecated:
use expressInterest(Interest, DataCallback, NackCallback, TimeoutCallback)

Definition at line 174 of file face.cpp.

References expressInterest(), and ndn::tlv::Interest.

◆ removePendingInterest()

void ndn::Face::removePendingInterest ( const PendingInterestId *  pendingInterestId)

Cancel previously expressed Interest.

Parameters
pendingInterestIdThe ID returned from expressInterest.

Definition at line 182 of file face.cpp.

References IO_CAPTURE_WEAK_IMPL, and IO_CAPTURE_WEAK_IMPL_END.

Referenced by ndn::util::NotificationSubscriber< FaceEventNotification >::stop().

◆ removeAllPendingInterests()

void ndn::Face::removeAllPendingInterests ( )

Cancel all previously expressed Interests.

Definition at line 190 of file face.cpp.

References IO_CAPTURE_WEAK_IMPL, and IO_CAPTURE_WEAK_IMPL_END.

◆ getNPendingInterests()

size_t ndn::Face::getNPendingInterests ( ) const

Get number of pending Interests.

Definition at line 198 of file face.cpp.

◆ setInterestFilter() [1/3]

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.

Parameters
interestFilterInterest filter (prefix part will be registered with the forwarder)
onInterestA callback to be called when a matching interest is received
onFailureA 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.
Returns
Opaque registered prefix ID which can be used with unsetInterestFilter or removeRegisteredPrefix

Definition at line 260 of file face.cpp.

Referenced by ndn::mgmt::Dispatcher::addTopPrefix(), and setInterestFilter().

◆ setInterestFilter() [2/3]

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.

Parameters
interestFilterInterest filter (prefix part will be registered with the forwarder)
onInterestA callback to be called when a matching interest is received
onSuccessA callback to be called when prefixRegister command succeeds
onFailureA 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.
Returns
Opaque registered prefix ID which can be used with unsetInterestFilter or removeRegisteredPrefix

Definition at line 270 of file face.cpp.

References ndn::nfd::CommandOptions::setSigningInfo().

◆ setInterestFilter() [3/3]

const InterestFilterId * ndn::Face::setInterestFilter ( const InterestFilter interestFilter,
const InterestCallback onInterest 
)

Set InterestFilter to dispatch incoming matching interest to onInterest callback.

Parameters
interestFilterInterest
onInterestA 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.

Returns
Opaque interest filter ID which can be used with unsetInterestFilter

Definition at line 287 of file face.cpp.

References ndn::Name::empty(), ndn::Data::getName(), IO_CAPTURE_WEAK_IMPL, IO_CAPTURE_WEAK_IMPL_END, setInterestFilter(), ndn::security::signingByCertificate(), and ndn::security::signingByIdentity().

◆ DEPRECATED() [1/6]

ndn::Face::DEPRECATED ( const RegisteredPrefixId *  setInterestFilterconst InterestFilter &interestFilter, const OnInterest &onInterest, const RegisterPrefixSuccessCallback &onSuccess, const RegisterPrefixFailureCallback &onFailure, const security::v1::IdentityCertificate &certificate, 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.

Deprecated:
Use override with SigningInfo instead of this function

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.

Parameters
interestFilterInterest filter (prefix part will be registered with the forwarder)
onInterestA callback to be called when a matching interest is received
onSuccessA callback to be called when prefixRegister command succeeds
onFailureA callback to be called when prefixRegister command fails
flags(optional) RIB flags
certificate(optional) A certificate under which the prefix registration command is signed. When omitted, a default certificate of the default identity is used to sign the registration command
Returns
Opaque registered prefix ID which can be used with unsetInterestFilter or removeRegisteredPrefix

◆ DEPRECATED() [2/6]

ndn::Face::DEPRECATED ( const RegisteredPrefixId *  setInterestFilterconst InterestFilter &interestFilter, const OnInterest &onInterest, const RegisterPrefixFailureCallback &onFailure, const security::v1::IdentityCertificate &certificate, 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.

Deprecated:
Use override with SigningInfo instead of this function

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.

Parameters
interestFilterInterest filter (prefix part will be registered with the forwarder)
onInterestA callback to be called when a matching interest is received
onFailureA callback to be called when prefixRegister command fails
flags(optional) RIB flags
certificate(optional) A certificate under which the prefix registration command is signed. When omitted, a default certificate of the default identity is used to sign the registration command
Returns
Opaque registered prefix ID which can be used with unsetInterestFilter or removeRegisteredPrefix

◆ DEPRECATED() [3/6]

ndn::Face::DEPRECATED ( const RegisteredPrefixId *  setInterestFilterconst InterestFilter &interestFilter, const OnInterest &onInterest, const RegisterPrefixSuccessCallback &onSuccess, const RegisterPrefixFailureCallback &onFailure, const Name &identity, 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.

Deprecated:
Use override with SigningInfo instead of this function

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.

Parameters
interestFilterInterest filter (prefix part will be registered with the forwarder)
onInterestA callback to be called when a matching interest is received
onSuccessA callback to be called when prefixRegister command succeeds
onFailureA callback to be called when prefixRegister command fails
identityA signing identity. A prefix registration command is signed under the default certificate of this identity
flags(optional) RIB flags
Returns
Opaque registered prefix ID which can be used with removeRegisteredPrefix

◆ DEPRECATED() [4/6]

ndn::Face::DEPRECATED ( const RegisteredPrefixId *  setInterestFilterconst InterestFilter &interestFilter, const OnInterest &onInterest, const RegisterPrefixFailureCallback &onFailure, const Name &identity, 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.

Deprecated:
Use override with SigningInfo instead of this function

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.

Parameters
interestFilterInterest filter (prefix part will be registered with the forwarder)
onInterestA callback to be called when a matching interest is received
onFailureA callback to be called when prefixRegister command fails
identityA signing identity. A prefix registration command is signed under the default certificate of this identity
flags(optional) RIB flags
Returns
Opaque registered prefix ID which can be used with removeRegisteredPrefix

◆ registerPrefix()

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.

Parameters
prefixA prefix to register with the connected NDN forwarder
onSuccessA callback to be called when prefixRegister command succeeds
onFailureA callback to be called when prefixRegister command fails
signingInfo(optional) Signing parameters. When omitted, a default parameters used in the signature will be used.
flagsPrefix registration flags
Returns
The registered prefix ID which can be used with unregisterPrefix
See also
nfd::RouteFlags

Definition at line 358 of file face.cpp.

References ndn::Name::empty(), ndn::Data::getName(), ndn::nfd::CommandOptions::setSigningInfo(), ndn::security::signingByCertificate(), and ndn::security::signingByIdentity().

Referenced by ndn::mgmt::Dispatcher::addTopPrefix().

◆ DEPRECATED() [5/6]

ndn::Face::DEPRECATED ( const RegisteredPrefixId *  registerPrefixconst Name &prefix, const RegisterPrefixSuccessCallback &onSuccess, const RegisterPrefixFailureCallback &onFailure, const security::v1::IdentityCertificate &certificate, uint64_t flags=nfd::ROUTE_FLAG_CHILD_INHERIT)

Register prefix with the connected NDN forwarder.

Deprecated:
Use override with SigningInfo instead of this function

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.

Parameters
prefixA prefix to register with the connected NDN forwarder
onSuccessA callback to be called when prefixRegister command succeeds
onFailureA callback to be called when prefixRegister command fails
certificate(optional) A certificate under which the prefix registration command is signed. When omitted, a default certificate of the default identity is used to sign the registration command
flags(optional) RIB flags
Returns
The registered prefix ID which can be used with unregisterPrefix

◆ DEPRECATED() [6/6]

ndn::Face::DEPRECATED ( const RegisteredPrefixId *  registerPrefixconst Name &prefix, const RegisterPrefixSuccessCallback &onSuccess, const RegisterPrefixFailureCallback &onFailure, const Name &identity, uint64_t flags=nfd::ROUTE_FLAG_CHILD_INHERIT)

Register prefix with the connected NDN forwarder and call onInterest when a matching interest is received.

Deprecated:
Use override with SigningInfo instead of this function

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.

Parameters
prefixA prefix to register with the connected NDN forwarder
onSuccessA callback to be called when prefixRegister command succeeds
onFailureA callback to be called when prefixRegister command fails
identityA signing identity. A prefix registration command is signed under the default certificate of this identity
flags(optional) RIB flags
Returns
The registered prefix ID which can be used with unregisterPrefix

◆ unsetInterestFilter() [1/2]

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

Parameters
registeredPrefixIdThe ID returned from registerPrefix

Definition at line 398 of file face.cpp.

References IO_CAPTURE_WEAK_IMPL, and IO_CAPTURE_WEAK_IMPL_END.

Referenced by ndn::mgmt::Dispatcher::removeTopPrefix().

◆ unsetInterestFilter() [2/2]

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.

Parameters
interestFilterIdThe ID returned from setInterestFilter.

Definition at line 406 of file face.cpp.

References IO_CAPTURE_WEAK_IMPL, and IO_CAPTURE_WEAK_IMPL_END.

◆ unregisterPrefix()

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.

Parameters
registeredPrefixIdThe ID returned from registerPrefix
onSuccessCallback to be called when operation succeeds
onFailureCallback to be called when operation fails

Definition at line 414 of file face.cpp.

References IO_CAPTURE_WEAK_IMPL, and IO_CAPTURE_WEAK_IMPL_END.

Referenced by ndn::mgmt::Dispatcher::removeTopPrefix().

◆ put() [1/2]

void ndn::Face::put ( const Data data)

Publish data packet.

This method can be called to satisfy the incoming Interest or to put Data packet into the cache of the local NDN forwarder.

Parameters
dataData packet to publish. It is highly recommended to use Data packet that was created using make_shared<Data>(...). Otherwise, put() will make an extra copy of the Data packet to ensure validity of published Data until asynchronous put() operation finishes.
Exceptions
Errorwhen Data size exceeds maximum limit (MAX_NDN_PACKET_SIZE)

Definition at line 204 of file face.cpp.

References ndn::lp::Packet::add(), ndn::Block::begin(), ndn::Block::end(), ndn::TagHost::getTag(), IO_CAPTURE_WEAK_IMPL, IO_CAPTURE_WEAK_IMPL_END, ndn::MAX_NDN_PACKET_SIZE, ndn::Block::size(), ndn::lp::Packet::wireEncode(), and ndn::Data::wireEncode().

Referenced by ndn::util::NotificationStream< Notification >::postNotification(), and ndn::mgmt::Dispatcher::removeTopPrefix().

◆ put() [2/2]

void ndn::Face::put ( const lp::Nack nack)

sends a Network NACK

Parameters
nackthe Nack; a copy will be made, so that the caller is not required to maintain the argument unchanged

Definition at line 237 of file face.cpp.

References ndn::lp::Packet::add(), ndn::lp::Nack::getHeader(), ndn::lp::Nack::getInterest(), ndn::TagHost::getTag(), IO_CAPTURE_WEAK_IMPL, IO_CAPTURE_WEAK_IMPL_END, ndn::MAX_NDN_PACKET_SIZE, ndn::Block::size(), ndn::lp::Packet::wireEncode(), and ndn::Interest::wireEncode().

◆ processEvents()

void ndn::Face::processEvents ( const time::milliseconds &  timeout = time::milliseconds::zero(),
bool  keepThread = false 
)
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.

Parameters
timeoutmaximum time to block the thread
keepThreadKeep thread in a blocked state (in event processing), even when there are no outstanding events (e.g., no Interest/Data is expected)
Exceptions
Thismay throw an exception for reading data or in the callback for processing the data. If you call this from an main event loop, you may want to catch and log/disregard all exceptions.

Definition at line 669 of file face.hpp.

◆ shutdown()

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 429 of file face.cpp.

References IO_CAPTURE_WEAK_IMPL, and IO_CAPTURE_WEAK_IMPL_END.

◆ getIoService()

boost::asio::io_service& ndn::Face::getIoService ( )
inline

Return nullptr (cannot use IoService in simulations), preserved for API compatibility.

Definition at line 690 of file face.hpp.

References NDN_CXX_PUBLIC_WITH_TESTS_ELSE_PROTECTED.

Referenced by ndn::util::DummyClientFace::DummyClientFace(), ndn::security::ValidatorConfig::ValidatorConfig(), and ndn::security::ValidatorRegex::ValidatorRegex().

◆ doProcessEvents()

void ndn::Face::doProcessEvents ( const time::milliseconds &  timeout,
bool  keepThread 
)
protectedvirtual

Definition at line 424 of file face.cpp.

Referenced by ndn::util::DummyClientFace::receive< lp::Nack >().

Member Data Documentation

◆ __pad0__

Definition at line 700 of file face.hpp.


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