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	Impl
	implementation detail of Face More...

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 (DummyIoService &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...

virtual	~Face ()

PendingInterestHandle	expressInterest (const Interest &interest, const DataCallback &afterSatisfied, const NackCallback &afterNacked, const TimeoutCallback &afterTimeout)
	Express Interest. More...

void	removeAllPendingInterests ()
	Cancel all previously expressed Interests. More...

size_t	getNPendingInterests () const
	Get number of pending Interests. More...

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 an InterestFilter to dispatch matching incoming Interests to `onInterest` callback. 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	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...

DummyIoService &	getIoService ()

Public Attributes
NDN_CXX_PUBLIC_WITH_TESTS_ELSE_PROTECTED	__pad0__: shared_ptr<Transport> getTransport() const { return m_transport

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

Detailed Description

Provide a communication channel with local or remote NDN forwarder.

Definition at line 90 of file face.hpp.

Constructor & Destructor Documentation

◆ Face() [1/3]

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

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

◆ Face() [2/3]

ndn::Face::Face ( DummyIoService & 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 64 of file face.cpp.

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

◆ Face() [3/3]

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

References IO_CAPTURE_WEAK_IMPL, IO_CAPTURE_WEAK_IMPL_END, ndn::security::v2::KeyChain, nonstd::optional_lite::std11::move(), and ~Face().

◆ ~Face()

ndn::Face::~Face ( )

virtualdefault

Referenced by Face().

Member Function Documentation

◆ expressInterest()

PendingInterestHandle 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

Returns: A handle for canceling the pending Interest.

Definition at line 123 of file face.cpp.

References IO_CAPTURE_WEAK_IMPL, and IO_CAPTURE_WEAK_IMPL_END.

Referenced by ndn::security::v2::CertificateFetcherFromNetwork::doFetch(), ndn::security::v2::CertificateFetcherDirectFetch::doFetch(), ndn::security::v2::CertificateBundleFetcher::doFetch(), ndn::util::NotificationSubscriberBase::stop(), and ndn::nfd::Controller::~Controller().

◆ removeAllPendingInterests()

void ndn::Face::removeAllPendingInterests ( )

Cancel all previously expressed Interests.

Definition at line 141 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 149 of file face.cpp.

◆ setInterestFilter() [1/3]

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

filter	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
signingInfo	Signing parameters. When omitted, a default parameters used in the signature will be used.
flags	Prefix registration flags

Returns: A handle for unregistering the prefix and unsetting the Interest filter.

Definition at line 171 of file face.cpp.

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

◆ setInterestFilter() [2/3]

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

filter	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
signingInfo	Signing parameters. When omitted, a default parameters used in the signature will be used.
flags	Prefix registration flags

Returns: A handle for unregistering the prefix and unsetting the Interest filter.

Definition at line 179 of file face.cpp.

References ndn::InterestFilter::getPrefix(), and ndn::nfd::CommandOptions::setSigningInfo().

◆ setInterestFilter() [3/3]

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

Set an InterestFilter to dispatch matching incoming Interests to onInterest callback.

Parameters

filter	Interest filter
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 a prefix with the forwarder, use registerPrefix() or one of the other two setInterestFilter() overloads.

Returns: A handle for unsetting the Interest filter.

Definition at line 193 of file face.cpp.

References IO_CAPTURE_WEAK_IMPL, and IO_CAPTURE_WEAK_IMPL_END.

◆ registerPrefix()

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

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	Signing parameters. When omitted, a default parameters used in the signature will be used.
flags	Prefix registration flags

Returns: A handle for unregistering the prefix.

See also: nfd::RouteFlags

Definition at line 205 of file face.cpp.

References nonstd::optional_lite::nullopt, and ndn::nfd::CommandOptions::setSigningInfo().

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

◆ put() [1/2]

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

References IO_CAPTURE_WEAK_IMPL, and IO_CAPTURE_WEAK_IMPL_END.

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

◆ put() [2/2]

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

References IO_CAPTURE_WEAK_IMPL, and IO_CAPTURE_WEAK_IMPL_END.

◆ processEvents()

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 (with the default timeout of 0) to process I/O on the face. To exit cleanly on a producer, clear any Interest filters 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

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

OversizedPacketError encoded packet size exceeds MAX_NDN_PACKET_SIZE

Definition at line 357 of file face.hpp.

References websocketpp::transport::error::timeout.

◆ shutdown()

void ndn::Face::shutdown ( )

Shutdown face operations.

This method cancels all pending operations and closes the connection to the 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 may cause outgoing packets to be lost. Producers that shut down immediately after sending a Data packet should instead clear all Interest filters to shut down cleanly.

See also: processEvents()

Definition at line 224 of file face.cpp.

References IO_CAPTURE_WEAK_IMPL, and IO_CAPTURE_WEAK_IMPL_END.

◆ getIoService()

DummyIoService& ndn::Face::getIoService ( )

inline

Returns: Dereferenced nullptr (cannot use IoService in simulations), preserved for API compatibility

Definition at line 383 of file face.hpp.

References NDN_CXX_PUBLIC_WITH_TESTS_ELSE_PROTECTED.

Referenced by nfd::rib::Service::Service(), and ndn::util::DummyClientFace::~DummyClientFace().

◆ doProcessEvents()

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

protectedvirtual

Definition at line 219 of file face.cpp.

Referenced by ndn::util::DummyClientFace::unlink().

Member Data Documentation

◆ pad0

NDN_CXX_PUBLIC_WITH_TESTS_ELSE_PROTECTED ndn::Face::__pad0__

Definition at line 396 of file face.hpp.

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

ndnSIM/ndn-cxx/ndn-cxx/face.hpp
ndnSIM/ndn-cxx/ndn-cxx/face.cpp

Classes

Public Member Functions

Public Attributes

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ Face() [1/3]

◆ Face() [2/3]

◆ Face() [3/3]

◆ ~Face()

Member Function Documentation

◆ expressInterest()

◆ removeAllPendingInterests()

◆ getNPendingInterests()

◆ setInterestFilter() [1/3]

◆ setInterestFilter() [2/3]

◆ setInterestFilter() [3/3]

◆ registerPrefix()

◆ put() [1/2]

◆ put() [2/2]

◆ processEvents()

◆ shutdown()

◆ getIoService()

◆ doProcessEvents()

Member Data Documentation

◆ __pad0__

◆ pad0