Class: Face

Face(transport, connectionInfo, settings)

new Face(transport, connectionInfo, settings)

Create a new Face with the given settings. This throws an exception if Face.supported is false. There are two forms of the constructor. The first form takes the transport and connectionInfo: Face(transport, connectionInfo). The second form takes an optional settings object: Face([settings]).
Parameters:
Name Type Description
transport Transport An object of a subclass of Transport to use for communication.
connectionInfo Transport.ConnectionInfo This must be a ConnectionInfo from the same subclass of Transport as transport. If omitted and transport is a new UnixTransport() then attempt to create to the Unix socket for the local forwarder.
settings Object (optional) An associative array with the following defaults: { getTransport: function() { return new WebSocketTransport(); }, // If in the browser. OR function() { return new TcpTransport(); }, // If in Node.js. // If getTransport creates a UnixTransport and connectionInfo is null, // then connect to the local forwarder's Unix socket. getConnectionInfo: transport.defaultGetConnectionInfo, // a function, on each call it returns a new Transport.ConnectionInfo or null if there are no more hosts. // If connectionInfo or host is not null, getConnectionInfo is ignored. connectionInfo: null, host: null, // If null and connectionInfo is null, use getConnectionInfo when connecting. // However, if connectionInfo is not null, use it instead. port: 9696, // If in the browser. OR 6363, // If in Node.js. // However, if connectionInfo is not null, use it instead. onopen: function() { if (LOG > 3) console.log("NDN connection established."); }, onclose: function() { if (LOG > 3) console.log("NDN connection closed."); }, }
Source:

Methods

(static) getMaxNdnPacketSize() → {number}

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.
Source:
Returns:
The maximum NDN packet size.
Type
number

(static) getSupported()

Return true if necessary JavaScript support is available, else log an error and return false.
Source:

(static) getUnixSocketFilePathForLocalhost()

If the forwarder's Unix socket file path exists, then return the file path. Otherwise return an empty string. This uses Node.js blocking file system utilities.
Source:
Returns:
The Unix socket file path to use, or an empty string.

(static) makeShuffledHostGetConnectionInfo(hostList, port, makeConnectionInfo) → {function}

Return a function that selects a host at random from hostList and returns makeConnectionInfo(host, port), and if no more hosts remain, return null.
Parameters:
Name Type Description
hostList Array.<string> An array of host names.
port number The port for the connection.
makeConnectionInfo function This calls makeConnectionInfo(host, port) to make the Transport.ConnectionInfo. For example: function(host, port) { return new TcpTransport.ConnectionInfo(host, port); }
Source:
Returns:
A function which returns a Transport.ConnectionInfo.
Type
function

(static) RegisterResponse()

A RegisterResponse has onData to receive the response Data packet from the register prefix interest sent to the connected NDN hub. If this gets a bad response or onTimeout is called, then call onRegisterFailed.
Source:

closeByTransport()

This is called by the Transport when the connection is closed by the remote host.
Source:

connectAndExecute()

Assume this.getConnectionInfo is not null. This is called when this.connectionInfo is null or its host is not alive. Get a connectionInfo, connect, then execute onConnected().
Source:

expressInterest(interest, onData, onTimeout, onNetworkNack, name, template, (optional)) → {number}

Send the interest through the transport, read the entire response and call onData, onTimeout or onNetworkNack as described below. There are two forms of expressInterest. The first form takes the exact interest (including lifetime): expressInterest(interest, onData [, onTimeout] [, onNetworkNack] [, wireFormat]). The second form creates the interest from a name and optional interest template: expressInterest(name [, template], onData [, onTimeout] [, onNetworkNack] [, wireFormat]).
Parameters:
Name Type Description
interest Interest The Interest to send which includes the interest lifetime for the timeout.
onData function 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. NOTE: You must not change the interest object - if you need to change it then make a copy. 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 function (optional) If the interest times out according to the interest lifetime, this calls onTimeout(interest) where: interest is the interest given to expressInterest. 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 function (optional) 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. interest is the sent Interest and networkNack is the received NetworkNack. If onNetworkNack is supplied, then onTimeout must be supplied too. However, if a network Nack is received and onNetworkNack is null, do nothing and wait for the interest to time out. (Therefore, an application which does not yet process a network Nack reason treats a Nack the same as a timeout.) 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.
name Name The Name for the interest. (only used for the second form of expressInterest).
template Interest (optional) If not omitted, copy the interest selectors from this Interest. If omitted, use a default interest lifetime. (only used for the second form of expressInterest).
(optional) WireFormat A WireFormat object used to encode the message. If omitted, use WireFormat.getDefaultWireFormat().
Source:
Throws:
Error If the encoded interest size exceeds Face.getMaxNdnPacketSize().
Returns:
The pending interest ID which can be used with removePendingInterest.
Type
number

expressInterestHelper()

Do the work of reconnectAndExpressInterest once we know we are connected. Add the PendingInterest and call this.transport.send to send the interest.
Source:

getNextEntryId() → {number}

An internal method to get the next unique entry ID for the pending interest table, interest filter table, etc. Most entry IDs are for the pending interest table (there usually are not many interest filter table entries) so we use a common pool to only have to have one method which is called by Face.
Source:
Returns:
The next entry ID.
Type
number

isLocal(onResult, onError)

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).
Parameters:
Name Type Description
onResult function On success, this calls onResult(isLocal) where isLocal is true if the host is local, false if not. We use callbacks because this may need to do network I/O (e.g. an IP host name lookup).
onError function On failure for DNS lookup or other error, this calls onError(message) where message is an error string.
Source:

makeCommandInterest(interest, wireFormat, onComplete)

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:
Name Type Description
interest Interest The interest whose name is appended with components.
wireFormat WireFormat (optional) A WireFormat object used to encode the SignatureInfo and to encode the interest name for signing. If omitted, use WireFormat.getDefaultWireFormat().
onComplete function (optional) This calls onComplete() when complete. If omitted, block until complete. (Some crypto/database libraries only use a callback, so onComplete is required to use these.)
Source:

nfdRegisterPrefix(registeredPrefixId, prefix, onInterest, flags, onRegisterFailed, onRegisterSuccess, commandKeyChain, commandCertificateName, wireFormat)

Do the work of registerPrefix to register with NFD.
Parameters:
Name Type Description
registeredPrefixId number The Face.getNextEntryId() which registerPrefix got so it could return it to the caller. If this is 0, then don't add to registeredPrefixTable (assuming it has already been done).
prefix Name
onInterest function
flags ForwardingFlags
onRegisterFailed function
onRegisterSuccess function
commandKeyChain KeyChain
commandCertificateName Name
wireFormat WireFormat
Source:

nodeMakeCommandInterest(interest, keyChain, certificateName, wireFormat, onComplete)

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:
Name Type Description
interest Interest The interest whose name is appended with components.
keyChain KeyChain The KeyChain for calling sign.
certificateName Name The certificate name of the key to use for signing.
wireFormat WireFormat A WireFormat object used to encode the SignatureInfo and to encode the interest name for signing.
onComplete function (optional) This calls onComplete() when complete. (Some crypto/database libraries only use a callback, so onComplete is required to use these.)
Source:

onReceivedElement()

This is called when an entire element is received, such as a Data or Interest.
Source:

putData(data, wireFormat)

The OnInterest callback calls this to put a Data packet which satisfies an Interest.
Parameters:
Name Type Description
data Data The Data packet which satisfies the interest.
wireFormat WireFormat (optional) A WireFormat object used to encode the Data packet. If omitted, use WireFormat.getDefaultWireFormat().
Source:
Throws:
Error If the encoded Data packet size exceeds getMaxNdnPacketSize().

reconnectAndExpressInterest()

If the host and port are different than the ones in this.transport, then call this.transport.connect to change the connection (or connect for the first time). Then call expressInterestHelper.
Source:

registerPrefix(prefix, onInterest, onRegisterFailed, onRegisterSuccess, flags) → {number}

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. This uses the form:
Parameters:
Name Type Description
prefix Name The Name prefix.
onInterest function (optional) If not null, 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: You must not change the prefix object - if you need to change it then make a copy. If onInterest is null, 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 function If register prefix fails for any reason, 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 function (optional) When this receives a success message, this calls onRegisterSuccess(prefix, registeredPrefixId) where prefix is the prefix given to registerPrefix and registeredPrefixId is the value retured by registerPrefix. If onRegisterSuccess is null or omitted, this does not use it. (The onRegisterSuccess parameter comes after onRegisterFailed because it can be null 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 ForwardingFlags (optional) The ForwardingFlags object for finer control of which interests are forward to the application. If omitted, use the default flags defined by the default ForwardingFlags constructor.
Source:
Returns:
The registered prefix ID which can be used with removeRegisteredPrefix.
Type
number

removePendingInterest(pendingInterestId)

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:
Name Type Description
pendingInterestId number The ID returned from expressInterest.
Source:

removeRegisteredPrefix(registeredPrefixId)

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:
Name Type Description
registeredPrefixId number The ID returned from registerPrefix.
Source:

send(encoding)

Send the encoded packet out through the transport.
Parameters:
Name Type Description
encoding Buffer The Buffer with the encoded packet to send.
Source:
Throws:
Error If the encoded packet size exceeds getMaxNdnPacketSize().

setCommandCertificateName(certificateName)

Set the certificate name used to sign command interest (e.g. for registerPrefix), using the KeyChain that was set with setCommandSigningInfo.
Parameters:
Name Type Description
certificateName Name The certificate name for signing interest. This makes a copy of the Name.
Source:

setCommandSigningInfo(keyChain, certificateName)

Set the KeyChain and certificate name used to sign command interests (e.g. for registerPrefix).
Parameters:
Name Type Description
keyChain 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 Name The certificate name for signing interests. This makes a copy of the Name. You can get the default certificate name with keyChain.getDefaultCertificateName() .
Source:

setInterestFilter(filter, prefix, onInterest)

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. There are two forms of setInterestFilter. The first form uses the exact given InterestFilter: setInterestFilter(filter, onInterest). The second form creates an InterestFilter from the given prefix Name: setInterestFilter(prefix, onInterest).
Parameters:
Name Type Description
filter InterestFilter The InterestFilter with a prefix and optional regex filter used to match the name of an incoming Interest. This makes a copy of filter.
prefix Name The Name prefix used to match the name of an incoming Interest.
onInterest function 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.
Source:

unsetInterestFilter(interestFilterId)

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:
Name Type Description
interestFilterId number The ID returned from setInterestFilter.
Source: