ndn::Face Class Reference

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

#include <ndn-cxx/face.hpp>

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

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 (const std::string &host, const std::string &port="6363")
 Create Face using TcpTransport. 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 ()
 
PendingInterestHandle expressInterest (const Interest &interest, const DataCallback &afterSatisfied, const NackCallback &afterNacked, const TimeoutCallback &afterTimeout)
 Express Interest. More...
 
boost::asio::io_service & getIoService ()
 
size_t getNPendingInterests () const
 Get number of pending Interests. More...
 
void processEvents (time::milliseconds timeout=time::milliseconds::zero(), bool keepThread=false)
 Process any data to receive or call timeout callbacks. More...
 
void put (Data data)
 Publish data packet. More...
 
void put (lp::Nack nack)
 Send a network NACK. More...
 
RegisteredPrefixHandle 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 removeAllPendingInterests ()
 Cancel all previously expressed Interests. More...
 
void removePendingInterest (const PendingInterestId *pendingInterestId)
 
RegisteredPrefixHandle setInterestFilter (const InterestFilter &filter, 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...
 
RegisteredPrefixHandle setInterestFilter (const InterestFilter &filter, 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...
 
InterestFilterHandle setInterestFilter (const InterestFilter &filter, const InterestCallback &onInterest)
 Set InterestFilter to dispatch incoming matching interest to onInterest callback. More...
 
void shutdown ()
 Shutdown face operations. More...
 
void unregisterPrefix (const RegisteredPrefixId *registeredPrefixId, const UnregisterPrefixSuccessCallback &onSuccess, const UnregisterPrefixFailureCallback &onFailure)
 
void unsetInterestFilter (const RegisteredPrefixId *registeredPrefixId)
 
void unsetInterestFilter (const InterestFilterId *interestFilterId)
 

Protected Member Functions

virtual void doProcessEvents (time::milliseconds timeout, bool keepThread)
 
shared_ptr< TransportgetTransport ()
 

Detailed Description

Provide a communication channel with local or remote NDN forwarder.

Definition at line 93 of file face.hpp.

Constructor & Destructor Documentation

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::Errortransport 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 58 of file face.cpp.

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

ndn::Face::Face ( const std::string &  host,
const std::string &  port = "6363" 
)
explicit

Create Face using TcpTransport.

Parameters
hostIP address or hostname of the NDN forwarder
portport number or service name of the NDN forwarder (default: "6363")

Definition at line 75 of file face.cpp.

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::Errortransport 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 84 of file face.cpp.

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::Errortransport 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 92 of file face.cpp.

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::Errortransport 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 100 of file face.cpp.

ndn::Face::~Face ( )
virtualdefault

Member Function Documentation

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

Definition at line 300 of file face.cpp.

PendingInterestHandle 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
Exceptions
OversizedPacketErrorencoded Interest size exceeds MAX_NDN_PACKET_SIZE
Returns
A handle for canceling the pending Interest.

Definition at line 177 of file face.cpp.

boost::asio::io_service& ndn::Face::getIoService ( )
inline
Returns
reference to io_service object

Definition at line 467 of file face.hpp.

size_t ndn::Face::getNPendingInterests ( ) const

Get number of pending Interests.

Definition at line 211 of file face.cpp.

shared_ptr< Transport > ndn::Face::getTransport ( )
protected
Returns
underlying transport

Definition at line 171 of file face.cpp.

void ndn::Face::processEvents ( 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 cleanly on a producer, unset any Interest filters with unsetInterestFilter() and wait for processEvents() to return. To exit after an error, one can call shutdown(). In consumer applications, processEvents() will return when all expressed Interests have been satisfied, Nacked, or timed out. To terminate earlier, a consumer application should cancel all previously expressed and still-pending Interests.

If a positive timeout is specified, then processEvents() will exit after this timeout, provided it is not stopped earlier with shutdown() or when all active events finish. processEvents() can be called repeatedly, if desired.

If a negative timeout is specified, then processEvents will not block and will 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). If timeout is zero and this parameter is true, the only way to stop processEvents() is to call shutdown().
Note
This may 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.
Exceptions
OversizedPacketErrorencoded packet size exceeds MAX_NDN_PACKET_SIZE

Definition at line 442 of file face.hpp.

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

Publish data packet.

Parameters
datathe 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.

Exceptions
OversizedPacketErrorencoded Data size exceeds MAX_NDN_PACKET_SIZE

Definition at line 217 of file face.cpp.

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

Send a network NACK.

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

Definition at line 225 of file face.cpp.

RegisteredPrefixHandle 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
signingInfoSigning parameters. When omitted, a default parameters used in the signature will be used.
flagsPrefix registration flags
Returns
A handle for unregistering the prefix.
See also
nfd::RouteFlags

Definition at line 275 of file face.cpp.

void ndn::Face::removeAllPendingInterests ( )

Cancel all previously expressed Interests.

Definition at line 203 of file face.cpp.

void ndn::Face::removePendingInterest ( const PendingInterestId *  pendingInterestId)
inline
Deprecated:
use PendingInterestHandle::cancel()

Definition at line 248 of file face.hpp.

RegisteredPrefixHandle ndn::Face::setInterestFilter ( const InterestFilter filter,
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
filterInterest 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
signingInfoSigning parameters. When omitted, a default parameters used in the signature will be used.
flagsPrefix registration flags
Returns
A handle for unregistering the prefix and unsetting the Interest filter.

Definition at line 233 of file face.cpp.

RegisteredPrefixHandle ndn::Face::setInterestFilter ( const InterestFilter filter,
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
filterInterest 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
signingInfoSigning parameters. When omitted, a default parameters used in the signature will be used.
flagsPrefix registration flags
Returns
A handle for unregistering the prefix and unsetting the Interest filter.

Definition at line 241 of file face.cpp.

InterestFilterHandle ndn::Face::setInterestFilter ( const InterestFilter filter,
const InterestCallback onInterest 
)

Set InterestFilter to dispatch incoming matching interest to onInterest callback.

Parameters
filterInterest filter
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
A handle for unsetting the Interest filter.

Definition at line 255 of file face.cpp.

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 the io_service if it is shared between multiple Faces or with other IO objects (e.g., Scheduler).

Warning
Calling this method could cause outgoing packets to be lost. Producers that shut down immediately after sending a Data packet should instead use unsetInterestFilter() to shut down cleanly.

Definition at line 337 of file face.cpp.

void ndn::Face::unregisterPrefix ( const RegisteredPrefixId *  registeredPrefixId,
const UnregisterPrefixSuccessCallback onSuccess,
const UnregisterPrefixFailureCallback onFailure 
)
inline
void ndn::Face::unsetInterestFilter ( const RegisteredPrefixId *  registeredPrefixId)
inline
void ndn::Face::unsetInterestFilter ( const InterestFilterId *  interestFilterId)
inline
Deprecated:
use InterestFilterHandle::cancel()

Definition at line 372 of file face.hpp.