The Face class provides the main methods for NDN communication. More...

#include <face.hpp>

Inheritance diagram for ndn::Face:

Public Types
typedef func_lib::function< void()>	Callback
	Face::Callback is used internally in callLater.

Public Member Functions
	Face (const ptr_lib::shared_ptr< Transport > &transport, const ptr_lib::shared_ptr< const Transport::ConnectionInfo > &connectionInfo)
	Create a new Face for communication with an NDN hub with the given Transport object and connectionInfo. More...

	Face (const char *host, unsigned short port=6363)
	Create a new Face for communication with an NDN hub at host:port using the default TcpTransport. More...

	Face ()
	Create a new Face for communication with an NDN hub using a default connection as follows. More...

virtual uint64_t	expressInterest (const Interest &interest, const OnData &onData, const OnTimeout &onTimeout, const OnNetworkNack &onNetworkNack, WireFormat &wireFormat=*WireFormat::getDefaultWireFormat())
	Send the Interest through the transport, read the entire response and call onData, onTimeout or onNetworkNack as described below. More...

virtual uint64_t	expressInterest (const Name &name, const Interest interestTemplate, const OnData &onData, const OnTimeout &onTimeout, const OnNetworkNack &onNetworkNack, WireFormat &wireFormat=WireFormat::getDefaultWireFormat())
	Encode name as an Interest. More...

uint64_t	expressInterest (const Name &name, const OnData &onData, const OnTimeout &onTimeout, const OnNetworkNack &onNetworkNack, WireFormat &wireFormat=*WireFormat::getDefaultWireFormat())
	Encode name as an Interest, using a default interest lifetime. More...

uint64_t	expressInterest (const Interest &interest, const OnData &onData, const OnTimeout &onTimeout=OnTimeout(), WireFormat &wireFormat=*WireFormat::getDefaultWireFormat())
	Send the Interest through the transport, read the entire response and call onData or onTimeout as described below. More...

uint64_t	expressInterest (const Name &name, const Interest interestTemplate, const OnData &onData, const OnTimeout &onTimeout=OnTimeout(), WireFormat &wireFormat=WireFormat::getDefaultWireFormat())
	Encode name as an Interest. More...

uint64_t	expressInterest (const Name &name, const OnData &onData, const OnTimeout &onTimeout=OnTimeout(), WireFormat &wireFormat=*WireFormat::getDefaultWireFormat())
	Encode name as an Interest, using a default interest lifetime. More...

virtual void	removePendingInterest (uint64_t pendingInterestId)
	Remove the pending interest entry with the pendingInterestId from the pending interest table. More...

void	setCommandSigningInfo (KeyChain &keyChain, const Name &certificateName)
	Set the KeyChain and certificate name used to sign command interests (e.g. More...

void	setCommandCertificateName (const Name &certificateName)
	Set the certificate name used to sign command interest (e.g. More...

KeyChain *	getCommandKeyChain ()

const Name &	getCommandCertificateName ()

virtual void	makeCommandInterest (Interest &interest, WireFormat &wireFormat=*WireFormat::getDefaultWireFormat())
	Append a timestamp component and a random value component to interest's name. More...

virtual uint64_t	registerPrefix (const Name &prefix, const OnInterestCallback &onInterest, const OnRegisterFailed &onRegisterFailed, const OnRegisterSuccess &onRegisterSuccess, const ForwardingFlags &flags=ForwardingFlags(), WireFormat &wireFormat=*WireFormat::getDefaultWireFormat())
	Register prefix with the connected NDN hub and call onInterest when a matching interest is received. More...

uint64_t	registerPrefix (const Name &prefix, const OnInterestCallback &onInterest, const OnRegisterFailed &onRegisterFailed, const ForwardingFlags &flags, WireFormat &wireFormat=*WireFormat::getDefaultWireFormat())
	Register prefix with the connected NDN hub and call onInterest when a matching interest is received. More...

uint64_t	registerPrefix (const Name &prefix, const OnInterestCallback &onInterest, const OnRegisterFailed &onRegisterFailed)
	Register prefix with the connected NDN hub and call onInterest when a matching interest is received. More...

uint64_t DEPRECATED_IN_NDN_CPP	registerPrefix (const Name &prefix, const OnInterest &onInterest, const OnRegisterFailed &onRegisterFailed, const ForwardingFlags &flags=ForwardingFlags(), WireFormat &wireFormat=*WireFormat::getDefaultWireFormat())

virtual void	removeRegisteredPrefix (uint64_t registeredPrefixId)
	Remove the registered prefix entry with the registeredPrefixId from the registered prefix table. More...

virtual uint64_t	setInterestFilter (const InterestFilter &filter, const OnInterestCallback &onInterest)
	Add an entry to the local interest filter table to call the onInterest callback for a matching incoming Interest. More...

virtual uint64_t	setInterestFilter (const Name &prefix, const OnInterestCallback &onInterest)
	Add an entry to the local interest filter table to call the onInterest callback for a matching incoming Interest. More...

virtual void	unsetInterestFilter (uint64_t interestFilterId)
	Remove the interest filter entry which has the interestFilterId from the interest filter table. More...

void	putData (const Data &data, WireFormat &wireFormat=*WireFormat::getDefaultWireFormat())
	The OnInterestCallback calls this to put a Data packet which satisfies an Interest. More...

void	send (const Blob &encoding)
	Send the encoded packet out through the face. More...

virtual void	send (const uint8_t *encoding, size_t encodingLength)
	Send the encoded packet out through the face. More...

void	processEvents ()
	Process any packets to receive and call callbacks such as onData, onInterest or onTimeout. More...

virtual bool	isLocal ()
	Check if the face is local based on the current connection through the Transport; some Transport may cause network I/O (e.g. More...

void	shutdown ()
	Shut down and disconnect this Face.

virtual void	callLater (Milliseconds delayMilliseconds, const Callback &callback)
	Call callback() after the given delay. More...

Static Public Member Functions
static size_t	getMaxNdnPacketSize ()
	Get the practical limit of the size of a network-layer packet. More...

Static Protected Member Functions
static std::string	getUnixSocketFilePathForLocalhost ()
	If the forwarder's Unix socket file path exists, then return the file path. More...

static ptr_lib::shared_ptr< const Interest >	getInterestCopy (const Name &name, const Interest *interestTemplate)
	Do the work of expressInterest to make an Interest based on name and interestTemplate. More...

Protected Attributes
Node *	node_

KeyChain *	commandKeyChain_

Name	commandCertificateName_

Detailed Description

The Face class provides the main methods for NDN communication.

Constructor & Destructor Documentation

ndn::Face::Face	(	const ptr_lib::shared_ptr< Transport > &	transport,
		const ptr_lib::shared_ptr< const Transport::ConnectionInfo > &	connectionInfo
	)

Create a new Face for communication with an NDN hub with the given Transport object and connectionInfo.

Parameters

transport	A shared_ptr to a Transport object used for communication.
transport	A shared_ptr to a Transport::ConnectionInfo to be used to connect to the transport.

ndn::Face::Face	(	const char *	host,
		unsigned short	port = `6363`
	)

Create a new Face for communication with an NDN hub at host:port using the default TcpTransport.

Parameters

host	The host of the NDN hub.
port	(optional) The port of the NDN hub. If omitted, use 6363.

ndn::Face::Face ( )

Create a new Face for communication with an NDN hub using a default connection as follows.

If the forwarder's Unix socket file exists, then connect using UnixTransport. Otherwise, connect to "localhost" on port 6363 using TcpTransport.

Member Function Documentation

void ndn::Face::callLater	(	Milliseconds	delayMilliseconds,
		const Callback &	callback
	)

virtual

Call callback() after the given delay.

Even though this is public, it is not part of the public API of Face. This default implementation just calls Node::callLater, but a subclass can override.

Parameters

delayMilliseconds	The delay in milliseconds.
callback	This calls callback.callback() after the delay.

Reimplemented in ndn::ThreadsafeFace.

uint64_t ndn::Face::expressInterest	(	const Interest &	interest,
		const OnData &	onData,
		const OnTimeout &	onTimeout,
		const OnNetworkNack &	onNetworkNack,
		WireFormat &	wireFormat = `*WireFormat::getDefaultWireFormat()`
	)

virtual

Send the Interest through the transport, read the entire response and call onData, onTimeout or onNetworkNack as described below.

Parameters

interest	A reference to the Interest. This copies the Interest.
onData	When a matching data packet is received, this calls onData(interest, data) where interest is the interest given to expressInterest and data is the received Data object. This copies the function object, so you may need to use func_lib::ref() as appropriate. NOTE: The library will log any exceptions thrown by this callback, but for better error handling the callback should catch and properly handle any exceptions.
onTimeout	If the interest times out according to the interest lifetime, this calls onTimeout(interest) where interest is the interest given to expressInterest. If onTimeout is an empty OnTimeout(), this does not use it. This copies the function object, so you may need to use func_lib::ref() as appropriate. NOTE: The library will log any exceptions thrown by this callback, but for better error handling the callback should catch and properly handle any exceptions.
onNetworkNack	When a network Nack packet for the interest is received and onNetworkNack is not null, this calls onNetworkNack(interest, networkNack) and does not call onTimeout. However, if a network Nack is received and onNetworkNack is an empty OnNetworkNack(), do nothing and wait for the interest to time out. This copies the function object, so you may need to use func_lib::ref() as appropriate. NOTE: The library will log any exceptions thrown by this callback, but for better error handling the callback should catch and properly handle any exceptions.
wireFormat	(optional) A WireFormat object used to encode the message. If omitted, use WireFormat getDefaultWireFormat().

Returns: The pending interest ID which can be used with removePendingInterest.

Exceptions

runtime_error If the encoded interest size exceeds getMaxNdnPacketSize().

Reimplemented in ndn::ThreadsafeFace.

uint64_t ndn::Face::expressInterest	(	const Name &	name,
		const Interest *	interestTemplate,
		const OnData &	onData,
		const OnTimeout &	onTimeout,
		const OnNetworkNack &	onNetworkNack,
		WireFormat &	wireFormat = `*WireFormat::getDefaultWireFormat()`
	)

virtual

Encode name as an Interest.

If interestTemplate is not 0, use its interest selectors. Send the Interest through the transport, read the entire response and call onData, onTimeout or onNetworkNack as described below.

Parameters

name	A reference to a Name for the interest. This copies the Name.
interestTemplate	if not 0, copy interest selectors from the template. This does not keep a pointer to the Interest object.
onData	When a matching data packet is received, this calls onData(interest, data) where interest is the interest given to expressInterest and data is the received Data object. This copies the function object, so you may need to use func_lib::ref() as appropriate. NOTE: The library will log any exceptions thrown by this callback, but for better error handling the callback should catch and properly handle any exceptions.
onTimeout	If the interest times out according to the interest lifetime, this calls onTimeout(interest) where interest is the interest given to expressInterest. If onTimeout is an empty OnTimeout(), this does not use it. This copies the function object, so you may need to use func_lib::ref() as appropriate. NOTE: The library will log any exceptions thrown by this callback, but for better error handling the callback should catch and properly handle any exceptions.
onNetworkNack	When a network Nack packet for the interest is received and onNetworkNack is not null, this calls onNetworkNack(interest, networkNack) and does not call onTimeout. However, if a network Nack is received and onNetworkNack is an empty OnNetworkNack(), do nothing and wait for the interest to time out. This copies the function object, so you may need to use func_lib::ref() as appropriate. NOTE: The library will log any exceptions thrown by this callback, but for better error handling the callback should catch and properly handle any exceptions.
wireFormat	(optional) A WireFormat object used to encode the message. If omitted, use WireFormat getDefaultWireFormat().

Returns: The pending interest ID which can be used with removePendingInterest.

Exceptions

runtime_error If the encoded interest size exceeds getMaxNdnPacketSize().

Reimplemented in ndn::ThreadsafeFace.

uint64_t ndn::Face::expressInterest	(	const Name &	name,
		const OnData &	onData,
		const OnTimeout &	onTimeout,
		const OnNetworkNack &	onNetworkNack,
		WireFormat &	wireFormat = `*WireFormat::getDefaultWireFormat()`
	)

inline

Encode name as an Interest, using a default interest lifetime.

Send the Interest through the transport, read the entire response and call onData, onTimeout or onNetworkNack as described below.

Parameters

name	A reference to a Name for the interest. This copies the Name.
onData	When a matching data packet is received, this calls onData(interest, data) where interest is the interest given to expressInterest and data is the received Data object. This copies the function object, so you may need to use func_lib::ref() as appropriate. NOTE: The library will log any exceptions thrown by this callback, but for better error handling the callback should catch and properly handle any exceptions.
onTimeout	If the interest times out according to the interest lifetime, this calls onTimeout(interest) where interest is the interest given to expressInterest. If onTimeout is an empty OnTimeout(), this does not use it. This copies the function object, so you may need to use func_lib::ref() as appropriate. NOTE: The library will log any exceptions thrown by this callback, but for better error handling the callback should catch and properly handle any exceptions.
onNetworkNack	When a network Nack packet for the interest is received and onNetworkNack is not null, this calls onNetworkNack(interest, networkNack) and does not call onTimeout. However, if a network Nack is received and onNetworkNack is an empty OnNetworkNack(), do nothing and wait for the interest to time out. This copies the function object, so you may need to use func_lib::ref() as appropriate. NOTE: The library will log any exceptions thrown by this callback, but for better error handling the callback should catch and properly handle any exceptions.
wireFormat	(optional) A WireFormat object used to encode the message. If omitted, use WireFormat getDefaultWireFormat().

Returns: The pending interest ID which can be used with removePendingInterest.

Exceptions

runtime_error If the encoded interest size exceeds getMaxNdnPacketSize().

uint64_t ndn::Face::expressInterest	(	const Interest &	interest,
		const OnData &	onData,
		const OnTimeout &	onTimeout = `OnTimeout()`,
		WireFormat &	wireFormat = `*WireFormat::getDefaultWireFormat()`
	)

inline

Send the Interest through the transport, read the entire response and call onData or onTimeout as described below.

Parameters

interest	A reference to the Interest. This copies the Interest.
onData	When a matching data packet is received, this calls onData(interest, data) where interest is the interest given to expressInterest and data is the received Data object. This copies the function object, so you may need to use func_lib::ref() as appropriate. NOTE: The library will log any exceptions thrown by this callback, but for better error handling the callback should catch and properly handle any exceptions.
onTimeout	(optional) If the interest times out according to the interest lifetime, this calls onTimeout(interest) where interest is the interest given to expressInterest. If onTimeout is omitted or an empty OnTimeout(), this does not use it. This copies the function object, so you may need to use func_lib::ref() as appropriate. NOTE: The library will log any exceptions thrown by this callback, but for better error handling the callback should catch and properly handle any exceptions.
wireFormat	(optional) A WireFormat object used to encode the message. If omitted, use WireFormat getDefaultWireFormat().

Returns: The pending interest ID which can be used with removePendingInterest.

Exceptions

runtime_error If the encoded interest size exceeds getMaxNdnPacketSize().

uint64_t ndn::Face::expressInterest	(	const Name &	name,
		const Interest *	interestTemplate,
		const OnData &	onData,
		const OnTimeout &	onTimeout = `OnTimeout()`,
		WireFormat &	wireFormat = `*WireFormat::getDefaultWireFormat()`
	)

inline

Encode name as an Interest.

If interestTemplate is not 0, use its interest selectors. Send the Interest through the transport, read the entire response and call onData or onTimeout as described below.

Parameters

interest	A reference to the Interest. This copies the Interest.
onData	When a matching data packet is received, this calls onData(interest, data) where interest is the interest given to expressInterest and data is the received Data object. This copies the function object, so you may need to use func_lib::ref() as appropriate. NOTE: The library will log any exceptions thrown by this callback, but for better error handling the callback should catch and properly handle any exceptions.
onTimeout	(optional) If the interest times out according to the interest lifetime, this calls onTimeout(interest) where interest is the interest given to expressInterest. If onTimeout is omitted or an empty OnTimeout(), this does not use it. This copies the function object, so you may need to use func_lib::ref() as appropriate. NOTE: The library will log any exceptions thrown by this callback, but for better error handling the callback should catch and properly handle any exceptions.
wireFormat	(optional) A WireFormat object used to encode the message. If omitted, use WireFormat getDefaultWireFormat().

Returns: The pending interest ID which can be used with removePendingInterest.

Exceptions

runtime_error If the encoded interest size exceeds getMaxNdnPacketSize().

uint64_t ndn::Face::expressInterest	(	const Name &	name,
		const OnData &	onData,
		const OnTimeout &	onTimeout = `OnTimeout()`,
		WireFormat &	wireFormat = `*WireFormat::getDefaultWireFormat()`
	)

inline

Encode name as an Interest, using a default interest lifetime.

Send the Interest through the transport, read the entire response and call onData or onTimeout as described below.

Parameters

interest	A reference to the Interest. This copies the Interest.
onData	When a matching data packet is received, this calls onData(interest, data) where interest is the interest given to expressInterest and data is the received Data object. This copies the function object, so you may need to use func_lib::ref() as appropriate. NOTE: The library will log any exceptions thrown by this callback, but for better error handling the callback should catch and properly handle any exceptions.
onTimeout	(optional) If the interest times out according to the interest lifetime, this calls onTimeout(interest) where interest is the interest given to expressInterest. If onTimeout is omitted or an empty OnTimeout(), this does not use it. This copies the function object, so you may need to use func_lib::ref() as appropriate. NOTE: The library will log any exceptions thrown by this callback, but for better error handling the callback should catch and properly handle any exceptions.
wireFormat	(optional) A WireFormat object used to encode the message. If omitted, use WireFormat getDefaultWireFormat().

Returns: The pending interest ID which can be used with removePendingInterest.

Exceptions

runtime_error If the encoded interest size exceeds getMaxNdnPacketSize().

static ptr_lib::shared_ptr<const Interest> ndn::Face::getInterestCopy	(	const Name &	name,
		const Interest *	interestTemplate
	)

inlinestaticprotected

Do the work of expressInterest to make an Interest based on name and interestTemplate.

Parameters

name	A reference to a Name for the interest. This copies the Name.
interestTemplate	if not 0, copy interest selectors from the template. This does not keep a pointer to the Interest object.

Returns: A shared_ptr of the Interest, suitable for Node.expressInterest.

static size_t ndn::Face::getMaxNdnPacketSize ( )

inlinestatic

Get the practical limit of the size of a network-layer packet.

If a packet is larger than this, the library or application MAY drop it. This is a static inline method wrapping a const, so you can to use as a constant, e.g.: uint8_t buffer[Face::getMaxNdnPacketSize()].

Returns: The maximum NDN packet size.

static std::string ndn::Face::getUnixSocketFilePathForLocalhost ( )

staticprotected

If the forwarder's Unix socket file path exists, then return the file path.

Otherwise return an empty string.

Returns: The Unix socket file path to use, or an empty string.

bool ndn::Face::isLocal ( )

virtual

Check if the face is local based on the current connection through the Transport; some Transport may cause network I/O (e.g.

an IP host name lookup).

Returns: True if the face is local, false if not.

Note: This is an experimental feature. This API may change in the future.

void ndn::Face::makeCommandInterest	(	Interest &	interest,
		WireFormat &	wireFormat = `*WireFormat::getDefaultWireFormat()`
	)

virtual

Append a timestamp component and a random value component to interest's name.

Then use the keyChain and certificateName from setCommandSigningInfo to sign the interest. If the interest lifetime is not set, this sets it.

Parameters

interest	The interest whose name is appended with components.
wireFormat	A WireFormat object used to encode the SignatureInfo and to encode the interest name for signing. If omitted, use WireFormat getDefaultWireFormat().

Note: This method is an experimental feature. See the API docs for more detail at http://named-data.net/doc/ndn-ccl-api/face.html#face-makecommandinterest-method .

void ndn::Face::processEvents ( )

Process any packets to receive and call callbacks such as onData, onInterest or onTimeout.

This returns immediately if there is no data to receive. This blocks while calling the callbacks. You should repeatedly call this from an event loop, with calls to sleep as needed so that the loop doesn’t use 100% of the CPU. Since processEvents modifies the pending interest table, your application should make sure that it calls processEvents in the same thread as expressInterest (which also modifies the pending interest table).

Exceptions

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.

void ndn::Face::putData	(	const Data &	data,
		WireFormat &	wireFormat = `*WireFormat::getDefaultWireFormat()`
	)

The OnInterestCallback calls this to put a Data packet which satisfies an Interest.

Parameters

data	The Data packet which satisfies the interest.
wireFormat	(optional) A WireFormat object used to encode the Data packet. If omitted, use WireFormat getDefaultWireFormat().

Exceptions

runtime_error If the encoded Data packet size exceeds getMaxNdnPacketSize().

uint64_t ndn::Face::registerPrefix	(	const Name &	prefix,
		const OnInterestCallback &	onInterest,
		const OnRegisterFailed &	onRegisterFailed,
		const OnRegisterSuccess &	onRegisterSuccess,
		const ForwardingFlags &	flags = `ForwardingFlags()`,
		WireFormat &	wireFormat = `*WireFormat::getDefaultWireFormat()`
	)

virtual

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

To register a prefix with NFD, you must first call setCommandSigningInfo.

Parameters

prefix	A reference to a Name for the prefix to register. This copies the Name.
onInterest	(optional) If not an empty OnInterestCallback(), this creates an interest filter from prefix so that when an Interest is received which matches the filter, this calls the function object onInterest(prefix, interest, face, interestFilterId, filter). This copies the function object, so you may need to use func_lib::ref() as appropriate. If onInterest is an empty OnInterestCallback(), it is ignored and you must call setInterestFilter. NOTE: The library will log any exceptions thrown by this callback, but for better error handling the callback should catch and properly handle any exceptions.
onRegisterFailed	A function object to call if failed to retrieve the connected hub’s ID or failed to register the prefix. This calls onRegisterFailed(prefix) where prefix is the prefix given to registerPrefix. NOTE: The library will log any exceptions thrown by this callback, but for better error handling the callback should catch and properly handle any exceptions.
onRegisterSuccess	(optional) A function object to call registerPrefix receives a success message from the forwarder. This calls onRegisterSuccess(prefix, registeredPrefixId) where prefix and registeredPrefixId are the values given to registerPrefix. If onRegisterSuccess is an empty OnRegisterSuccess(), this does not use it. (The onRegisterSuccess parameter comes after onRegisterFailed because it can be empty or omitted, unlike onRegisterFailed.) NOTE: The library will log any exceptions thrown by this callback, but for better error handling the callback should catch and properly handle any exceptions.
flags	(optional) The flags for finer control of which interests are forward to the application. If omitted, use the default flags defined by the default ForwardingFlags constructor.
wireFormat	(optional) A WireFormat object used to encode the message. If omitted, use WireFormat getDefaultWireFormat().

Returns: The registered prefix ID which can be used with removeRegisteredPrefix.

Reimplemented in ndn::ThreadsafeFace.

uint64_t ndn::Face::registerPrefix	(	const Name &	prefix,
		const OnInterestCallback &	onInterest,
		const OnRegisterFailed &	onRegisterFailed,
		const ForwardingFlags &	flags,
		WireFormat &	wireFormat = `*WireFormat::getDefaultWireFormat()`
	)

inline

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

To register a prefix with NFD, you must first call setCommandSigningInfo.

Parameters

prefix	A reference to a Name for the prefix to register. This copies the Name.
onInterest	(optional) If not an empty OnInterestCallback(), this creates an interest filter from prefix so that when an Interest is received which matches the filter, this calls the function object onInterest(prefix, interest, face, interestFilterId, filter). This copies the function object, so you may need to use func_lib::ref() as appropriate. If onInterest is an empty OnInterestCallback(), it is ignored and you must call setInterestFilter. NOTE: The library will log any exceptions thrown by this callback, but for better error handling the callback should catch and properly handle any exceptions.
onRegisterFailed	A function object to call if failed to retrieve the connected hub’s ID or failed to register the prefix. This calls onRegisterFailed(prefix) where prefix is the prefix given to registerPrefix. NOTE: The library will log any exceptions thrown by this callback, but for better error handling the callback should catch and properly handle any exceptions.
flags	The flags for finer control of which interests are forward to the application. If omitted, use the default flags defined by the default ForwardingFlags constructor.
wireFormat	(optional) A WireFormat object used to encode the message. If omitted, use WireFormat getDefaultWireFormat().

Returns: The registered prefix ID which can be used with removeRegisteredPrefix.

uint64_t ndn::Face::registerPrefix	(	const Name &	prefix,
		const OnInterestCallback &	onInterest,
		const OnRegisterFailed &	onRegisterFailed
	)

inline

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

To register a prefix with NFD, you must first call setCommandSigningInfo.

Parameters

prefix	A reference to a Name for the prefix to register. This copies the Name.
onInterest	(optional) If not an empty OnInterestCallback(), this creates an interest filter from prefix so that when an Interest is received which matches the filter, this calls the function object onInterest(prefix, interest, face, interestFilterId, filter). This copies the function object, so you may need to use func_lib::ref() as appropriate. If onInterest is an empty OnInterestCallback(), it is ignored and you must call setInterestFilter. NOTE: The library will log any exceptions thrown by this callback, but for better error handling the callback should catch and properly handle any exceptions.
onRegisterFailed	A function object to call if failed to retrieve the connected hub’s ID or failed to register the prefix. This calls onRegisterFailed(prefix) where prefix is the prefix given to registerPrefix. NOTE: The library will log any exceptions thrown by this callback, but for better error handling the callback should catch and properly handle any exceptions.

Returns: The registered prefix ID which can be used with removeRegisteredPrefix.

uint64_t ndn::Face::registerPrefix	(	const Name &	prefix,
		const OnInterest &	onInterest,
		const OnRegisterFailed &	onRegisterFailed,
		const ForwardingFlags &	flags = `ForwardingFlags()`,
		WireFormat &	wireFormat = `*WireFormat::getDefaultWireFormat()`
	)

Deprecated:: Use registerPrefix where onInterest is an OnInterestCallback (which is passed this Face for calling putData) instead of the deprecated OnInterest (which is passed a Transport object).

void ndn::Face::removePendingInterest ( uint64_t pendingInterestId )

virtual

Remove the pending interest entry with the pendingInterestId from the pending interest table.

This does not affect another pending interest with a different pendingInterestId, even if it has the same interest name. If there is no entry with the pendingInterestId, do nothing.

Parameters

pendingInterestId The ID returned from expressInterest.

Reimplemented in ndn::ThreadsafeFace.

void ndn::Face::removeRegisteredPrefix ( uint64_t registeredPrefixId )

virtual

Remove the registered prefix entry with the registeredPrefixId from the registered prefix table.

This does not affect another registered prefix with a different registeredPrefixId, even if it has the same prefix name. If an interest filter was automatically created by registerPrefix, also remove it. If there is no entry with the registeredPrefixId, do nothing.

Parameters

registeredPrefixId The ID returned from registerPrefix.

Reimplemented in ndn::ThreadsafeFace.

void ndn::Face::send ( const Blob & encoding )

inline

Send the encoded packet out through the face.

Parameters

encoding The blob with the the encoded packet to send.

Exceptions

runtime_error If the encoded Data packet size exceeds getMaxNdnPacketSize().

void ndn::Face::send	(	const uint8_t *	encoding,
		size_t	encodingLength
	)

virtual

Send the encoded packet out through the face.

Parameters

encoding	The array of bytes for the encoded packet to send.
encodingLength	The number of bytes in the encoding array.

Exceptions

runtime_error If the encoded Data packet size exceeds getMaxNdnPacketSize().

Reimplemented in ndn::ThreadsafeFace.

void ndn::Face::setCommandCertificateName ( const Name & certificateName )

inline

Set the certificate name used to sign command interest (e.g.

for registerPrefix), using the KeyChain that was set with setCommandSigningInfo.

Parameters

certificateName The certificate name for signing interest. This makes a copy of the Name.

void ndn::Face::setCommandSigningInfo	(	KeyChain &	keyChain,
		const Name &	certificateName
	)

inline

Set the KeyChain and certificate name used to sign command interests (e.g.

for registerPrefix).

Parameters

keyChain	The KeyChain object for signing interests, which must remain valid for the life of this Face. You must create the KeyChain object and pass it in. You can create a default KeyChain for your system with the default KeyChain constructor.
certificateName	The certificate name for signing interests. This makes a copy of the Name. You can get the default certificate name with keyChain.getDefaultCertificateName() .

uint64_t ndn::Face::setInterestFilter	(	const InterestFilter &	filter,
		const OnInterestCallback &	onInterest
	)

virtual

Add an entry to the local interest filter table to call the onInterest callback for a matching incoming Interest.

This method only modifies the library's local callback table and does not register the prefix with the forwarder. It will always succeed. To register a prefix with the forwarder, use registerPrefix.

Parameters

filter	The InterestFilter with a prefix and optional regex filter used to match the name of an incoming Interest. This makes a copy of filter.
onInterest	When an Interest is received which matches the filter, this calls onInterest(prefix, interest, face, interestFilterId, filter). NOTE: The library will log any exceptions thrown by this callback, but for better error handling the callback should catch and properly handle any exceptions.

Returns: The interest filter ID which can be used with unsetInterestFilter.

Reimplemented in ndn::ThreadsafeFace.

uint64_t ndn::Face::setInterestFilter	(	const Name &	prefix,
		const OnInterestCallback &	onInterest
	)

virtual

Add an entry to the local interest filter table to call the onInterest callback for a matching incoming Interest.

This method only modifies the library's local callback table and does not register the prefix with the forwarder. It will always succeed. To register a prefix with the forwarder, use registerPrefix.

Parameters

prefix	The Name prefix used to match the name of an incoming Interest.
onInterest	This creates an interest filter from prefix so that when an Interest is received which matches the filter, this calls onInterest(prefix, interest, face, interestFilterId, filter). NOTE: The library will log any exceptions thrown by this callback, but for better error handling the callback should catch and properly handle any exceptions.

Returns: The interest filter ID which can be used with unsetInterestFilter.

Reimplemented in ndn::ThreadsafeFace.

void ndn::Face::unsetInterestFilter ( uint64_t interestFilterId )

virtual

Remove the interest filter entry which has the interestFilterId from the interest filter table.

This does not affect another interest filter with a different interestFilterId, even if it has the same prefix name. If there is no entry with the interestFilterId, do nothing.

Parameters

interestFilterId The ID returned from setInterestFilter.

Reimplemented in ndn::ThreadsafeFace.

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

include/ndn-cpp/face.hpp
src/face.cpp

Public Types

Public Member Functions

Static Public Member Functions

Static Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation