Class: Face

Face

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."); }, verify: false // If false, don't verify and call upcall with Closure.UPCALL_CONTENT_UNVERIFIED. }
Source:

Classes

InterestFilterEntry
PendingInterest
RegisteredPrefix

Methods

(static) FetchNdndidClosure()

This is a closure to receive the Data for Face.ndndIdFetcher and call registerPrefixHelper(registeredPrefixId, prefix, callerClosure, flags).
Source:

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

This is a closure to receive the response Data packet from the register prefix interest sent to the connected NDN hub. If this gets a bad response or a timeout, 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, name, template) → {number}

Send the interest through the transport, read the entire response and call onData. If the interest times out according to interest lifetime, call onTimeout (if not omitted). There are two forms of expressInterest. The first form takes the exact interest (including lifetime): expressInterest(interest, onData [, onTimeout]). The second form creates the interest from a name and optional interest template: expressInterest(name [, template], onData [, onTimeout]). This also supports the deprecated form expressInterest(name, closure [, template]), but you should use the other forms.
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.
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.
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).
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. Set the PITTable and call this.transport.send to send the interest.
Source:

expressInterestWithClosure(the, closure) → {number}

A private method to send the the interest to host:port, read the entire response and call closure.upcall(Closure.UPCALL_CONTENT (or Closure.UPCALL_CONTENT_UNVERIFIED), new UpcallInfo(this, interest, 0, data)).
Parameters:
Name Type Description
the Interest interest, already processed with a template (if supplied).
closure Closure
Deprecated:
  • Use expressInterest with callback functions, not Closure.
Source:
Returns:
The pending interest ID which can be used with removePendingInterest.
Type
number

extractEntriesForExpressedInterest(name) → {Array.<Face.PendingInterest>}

Find all entries from this.pendingInterestTable where the name conforms to the entry's interest selectors, remove the entries from the table, cancel their timeout timers and return them.
Parameters:
Name Type Description
name Name The name to find the interest for (from the incoming data packet).
Source:
Returns:
The matching entries from this.pendingInterestTable, or [] if none are found.
Type
Array.<Face.PendingInterest>

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)

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().
Source:

nfdRegisterPrefix(registeredPrefixId, prefix, closure, flags, onRegisterFailed, commandKeyChain, commandCertificateName)

Do the work of registerPrefix to register with NFD.
Parameters:
Name Type Description
registeredPrefixId number The Face.RegisteredPrefix.getNextRegisteredPrefixId() 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
closure Closure
flags ForwardingFlags
onRegisterFailed function
commandKeyChain KeyChain
commandCertificateName Name
Source:

nodeMakeCommandInterest(interest, keyChain, certificateName, wireFormat)

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.
Source:

onReceivedElement()

This is called when an entire binary XML element is received, such as a Data or Interest. Look up in the PITTable and call the closure callback.
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, flags, intFlags) → {number}

Register prefix with the connected NDN hub and call onInterest when a matching interest is received. This uses the form: registerPrefix(name, onInterest, onRegisterFailed [, flags]). This also supports the deprecated form registerPrefix(name, closure [, intFlags]), but you should use the main form.
Parameters:
Name Type Description
prefix Name The Name prefix.
onInterest function (optional) If not None, 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.
onRegisterFailed function If register prefix fails for any reason, this calls onRegisterFailed(prefix) where: prefix is the prefix given to registerPrefix.
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.
intFlags number (optional) (only for the deprecated form of registerPrefix) The integer NDNx flags for finer control of which interests are forward to the application.
Source:
Returns:
The registered prefix ID which can be used with removeRegisteredPrefix.
Type
number

registerPrefixHelper(registeredPrefixId, prefix, closure, flags, onRegisterFailed) → {undefined}

Do the work of registerPrefix once we know we are connected with an ndndid.
Parameters:
Name Type Description
registeredPrefixId type The Face.RegisteredPrefix.getNextRegisteredPrefixId() 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
closure Closure
flags ForwardingFlags
onRegisterFailed function
Source:
Returns:
Type
undefined

registerPrefixWithClosure(prefix, closure, flags, onRegisterFailed) → {number}

A private method to register the prefix with the host, receive the data and call closure.upcall(Closure.UPCALL_INTEREST, new UpcallInfo(this, interest, 0, null)).
Parameters:
Name Type Description
prefix Name
closure Closure | function or onInterest.
flags ForwardingFlags
onRegisterFailed function (optional) If called from the non-deprecated registerPrefix, call onRegisterFailed(prefix) if registration fails.
Deprecated:
  • Use registerPrefix with callback functions, not Closure.
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).
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: