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

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 ()

const PendingInterestId *	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...

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	removeAllPendingInterests ()
	Cancel all previously expressed Interests. More...

void	removePendingInterest (const PendingInterestId *pendingInterestId)
	Cancel previously expressed Interest. 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...

void	shutdown ()
	Shutdown face operations. More...

void	unregisterPrefix (const RegisteredPrefixId *registeredPrefixId, const UnregisterPrefixSuccessCallback &onSuccess, const UnregisterPrefixFailureCallback &onFailure)
	Unregister prefix from RIB. 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...

Protected Member Functions
virtual void	doProcessEvents (time::milliseconds timeout, bool keepThread)

shared_ptr< Transport >	getTransport ()

Detailed Description

Provide a communication channel with local or remote NDN forwarder.

Definition at line 95 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

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.

Exceptions

ConfigFile::Error 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 59 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

ioService A reference to boost::io_service object that should control all IO operations.

Exceptions

ConfigFile::Error the configuration file cannot be parsed or specifies an unsupported protocol

Definition at line 68 of file face.cpp.

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

explicit

Create Face using TcpTransport.

Parameters

host	IP address or hostname of the NDN forwarder
port	port number or service name of the NDN forwarder (default: "6363")

Definition at line 76 of file face.cpp.

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

Create Face using given transport and KeyChain.

Parameters

transport	the transport for lower layer communication. If nullptr, a default transport will be used.
keyChain	the KeyChain to sign commands

See also: Face(shared_ptr<Transport>)

Exceptions

ConfigFile::Error 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 85 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

transport	the transport for lower layer communication. If nullptr, a default transport will be used.
ioService	the io_service that controls all IO operations

See also: Face(boost::asio::io_service&); Face(shared_ptr<Transport>)

Exceptions

ConfigFile::Error 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 93 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

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

See also: Face(boost::asio::io_service&); Face(shared_ptr<Transport>, KeyChain&)

Exceptions

ConfigFile::Error 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 101 of file face.cpp.

ndn::Face::~Face ( )

virtualdefault

Member Function Documentation

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

protectedvirtual

Definition at line 314 of file face.cpp.

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

Express Interest.

Parameters

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

Exceptions

OversizedPacketError encoded Interest size exceeds MAX_NDN_PACKET_SIZE

Definition at line 178 of file face.cpp.

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

inline

Returns: reference to IO service object

Definition at line 477 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 172 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, 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

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)

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

OversizedPacketError encoded packet size exceeds MAX_NDN_PACKET_SIZE

Definition at line 456 of file face.hpp.

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

Publish data packet.

Parameters

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.

Exceptions

OversizedPacketError encoded 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

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

Exceptions

OversizedPacketError encoded Nack size exceeds MAX_NDN_PACKET_SIZE

Definition at line 226 of file face.cpp.

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

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

Returns: The registered prefix ID which can be used with unregisterPrefix

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 )

Cancel previously expressed Interest.

Parameters

pendingInterestId The ID returned from expressInterest.

Definition at line 195 of file face.cpp.

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

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.

Returns: Opaque registered prefix ID which can be used with unsetInterestFilter or removeRegisteredPrefix

Definition at line 235 of file face.cpp.

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

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.

Returns: Opaque registered prefix ID which can be used with unsetInterestFilter or removeRegisteredPrefix

Definition at line 245 of file face.cpp.

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

Set InterestFilter to dispatch incoming matching interest to onInterest callback.

Parameters

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.

Returns: Opaque interest filter ID which can be used with unsetInterestFilter

Definition at line 262 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 IO service and if the same IO service is shared between multiple Faces or with other IO objects (e.g., Scheduler).

Definition at line 353 of file face.cpp.

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

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

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

registeredPrefixId The ID returned from registerPrefix

Definition at line 288 of file face.cpp.

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

interestFilterId The ID returned from setInterestFilter.

Definition at line 296 of file face.cpp.

ndn-cxx: NDN C++ library with eXperimental eXtensions 0.6.0 documentation

Classes

Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation