Face Class

A Face provides the top-level interface to the library. It holds a connection to a forwarder and supports interest / data exchange.

[C++]:
#include <ndn-cpp/face.hpp>
Namespace: ndn
[Python]:Module: pyndn
[Java]:Package: net.named_data.jndn

Face Constructors

Face Constructor (explicit Transport)

Create a new Face object with the given Transport to manage NDN communication.

[C++]:
Face(
    const ptr_lib::shared_ptr<Transport>& transport,
    const ptr_lib::shared_ptr<const Transport::ConnectionInfo>& connectionInfo
);
[Python]:
def __init__(self,
    transport,  # Transport
    connectionInfo  # Transport.ConnectionInfo
)
[JavaScript]:
var Face = function Face(
    transport,  // Transport
    connectionInfo  // Transport.ConnectionInfo
)
[Java]:
public Face(
    Transport transport,
    Transport.ConnectionInfo connectionInfo
)
Parameters:
  • transport
    An object of a subclass of Transport to use for communication.
  • connectionInfo
    This must be a ConnectionInfo from the same subclass of Transport as transport. [JavaScript only: If connectionInfo is omitted and transport is a new UnixTransport() then attempt to create to the Unix socket for the local forwarder.]

Face Constructor (default Transport)

Create a new Face object with optional settings to manage NDN communication.

[C++]:
Face(
    [const char* host]
    [, unsigned short port]
);
[Python]:
def __init__(self
  [, host  # str]
  [, port  # int]
)
[JavaScript]:
var Face = function Face(
    [settings // associative array]
)
[Java]:
public Face(
    [String host]
    [, int port]
)
Parameters:
  • host

    (optional) The host to connect to. If omitted, use “localhost” with the default TcpTransport.

  • port

    (optional) The port to connect to. If omitted, use 6363 with the default TcpTransport.

  • settings

    (JavaScript only) (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
                // getHostAndPort 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.
    

Face.expressInterest Methods

Face.expressInterest Method (from Interest)

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

Note

[except JavaScript] Your application must call processEvents. The onData callback is called on the same thread that calls processEvents.

[C++]:
uint64_t expressInterest(
    const Interest& interest,
    const OnData& onData,
    [, const OnTimeout& onTimeout]
    [, const OnNetworkNack& onNetworkNack]
);
[Python]:
# Returns int
def expressInterest(self,
    interest,         # Interest
    onData            # function object
    [, onTimeout      # function object]
    [, onNetworkNack  # function object]
)
[JavaScript]:
// Returns number
Face.prototype.expressInterest = function(
    interest          // Interest
    onData,           // function
    [, onTimeout      // function]
    [, onNetworkNack  // function]
)
[Java]:
public long expressInterest(
    Interest interest,
    OnData onData,
    [, OnTimeout onTimeout]
    [, OnNetworkNack onNetworkNack]
)
Parameters:
  • interest

    The Interest to send which includes the interest lifetime for the timeout.

  • onData

    When a matching data packet is received, this calls onData(interest, data) where:

    • interest is the interest given to expressInterest.
    • 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

    (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

    (optional) When a network Nack packet for the interest is received and onNetworkNack is supplied, this calls onData(interest, networkNack) where:

    • interest is the interest given to expressInterest.
    • networkNack is the received NetworkNack object.

    If onNetworkNack is called then onTimeout is not called. However, if a network Nack is received and onNetworkNack not supplied, do nothing and wait for the interest to time out.

    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.

Returns:

The pending interest ID which can be used with removePendingInterest.

Throw:

Throw an exception if the encoded interest size exceeds getMaxNdnPacketSize().

Face.expressInterest Method (from Name)

Encode name as an Interest, using the interestTemplate if supplied, send the interest through the transport, read the entire response and call onData, onTimeout or onNetworkNack as described below.

Note

[except JavaScript] Your application must call processEvents. The onData callback is called on the same thread that calls processEvents.

[C++]:
uint64_t expressInterest(
    const Name& name,
    [, const Interest* interestTemplate]
    const OnData& onData,
    [, const OnTimeout& onTimeout]
    [, const OnNetworkNack& onNetworkNack]
);
[Python]:
# Returns int
def expressInterest(self,
    name                # Name
    [, interestTemplate # Interest]
    onData,             # function object
    [, onTimeout        # function object]
    [, onNetworkNack    # function object]
)
[JavaScript]:
// Returns number
Face.prototype.expressInterest = function(
    name,               // Name
    [, interestTemplate // Interest]
    onData,             // function
    [, onTimeout        // function]
    [, onNetworkNack    // function]
)
[Java]:
public long expressInterest(
    Name name,
    [, Interest interestTemplate]
    OnData onData,
    [, OnTimeout onTimeout]
    [, OnNetworkNack onNetworkNack]
)
Parameters:
  • name

    The Name for the interest.

  • interestTemplate

    (optional) If not omitted, copy the interest selectors from this Interest. If omitted, use a default interest lifetime.

  • onData

    When a matching data packet is received, this calls onData(interest, data) where:

    • interest is the interest given to expressInterest.
    • 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

    (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

    (optional) When a network Nack packet for the interest is received and onNetworkNack is supplied, this calls onData(interest, networkNack) where:

    • interest is the interest given to expressInterest.
    • networkNack is the received NetworkNack object.

    If onNetworkNack is called then onTimeout is not called. However, if a network Nack is received and onNetworkNack not supplied, do nothing and wait for the interest to time out.

    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.

Returns:

The pending interest ID which can be used with removePendingInterest.

Throw:

Throw an exception if the encoded interest size exceeds getMaxNdnPacketSize().

Face.getMaxNdnPacketSize Method

This is a static method to 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.

[C++]:
static size_t getMaxNdnPacketSize();
[Python]:
# Returns int
@staticmethod
def getMaxNdnPacketSize()
[JavaScript]:
// Returns number
Face.getMaxNdnPacketSize = function()
[Java]:
public static int getMaxNdnPacketSize()
Returns:

The maximum NDN packet size.

Face.isLocal Method

Experimental

This method is experimental. The API is not finalized.

Check if the face is local based on the current connection through the Transport. This affects the processing of registerPrefix with NFD: if the NFD is local, registration occurs with the ‘/localhost/nfd/…’ prefix; if non-local, remote prefix registration is attempted using ‘/localhop/nfd/…’ . Some Transport subclasses may cause network I/O (e.g. an IP host name lookup).

[C++]:
bool isLocal();
[Python]:
# Returns bool
def isLocal()
[JavaScript]:
Face.prototype.isLocal = function(
    onResult,  // function
    onError    // function
)
[Java]:
public boolean isLocal()
Parameters:
  • onResult
    (JavaScript only) 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 async network I/O (e.g. an IP host name lookup).
  • onError
    (JavaScript only) On failure for DNS lookup or other error, this calls onError(message) where message is an error string.
Returns:

(except JavaScript) True if the face is local, false if not.

Face.makeCommandInterest Method

Experimental

This method is experimental. The API is not finalized.

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.

[C++]:
void makeCommandInterest(
    Interest& interest
);
[Python]:
def makeCommandInterest(self,
    interest  // Interest
)
[JavaScript]:
Face.prototype.makeCommandInterest = function(
    interest  // Interest
)
[Java]:
public void makeCommandInterest(
  Interest interest
)
Parameters:
  • interest
    The interest whose name is appended with components.

Face.processEvents Method

[except JavaScript] 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).

[C++]:
void processEvents();
[Python]:
def processEvents(self)
[Java]:
public void processEvents()
Throw:

This may throw an exception, for example in processing incoming data. If you call this from a main event loop, you should catch and log/dicard exceptions.

Face.putData Method

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

[C++]:
void putData(
    const Data& data
);
[Python]:
def putData(self,
    data  # Data
)
[JavaScript]:
Face.prototype.putData = function(
    data  // Data
)
[Java]:
public void putData(
    Data data
)
Parameters:
  • data
    The Data packet which satisfies the interest.
Throw:

Throw an exception if the encoded Data packet size exceeds getMaxNdnPacketSize().

Face.registerPrefix Method

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 connects to a local or remote forwarder according to isLocal.

Note

[except JavaScript] Your application must call processEvents. The onInterest callback is called on the same thread that calls processEvents.

[C++]:
uint64_t registerPrefix(
    const Name &prefix,
    const OnInterestCallback &onInterest,
    const OnRegisterFailed &onRegisterFailed
    [, const OnRegisterSuccess &onRegisterSuccess]
    [, const ForwardingFlags& flags]
)
[Python]:
# Returns int
def registerPrefix(self,
    prefix,               # Name
    onInterest,           # function object
    onRegisterFailed      # function object
    [, onRegisterSuccess  # function object]
    [, flags              # ForwardingFlags]
)
[JavaScript]:
// Returns number
Face.prototype.registerPrefix = function(
    prefix,               // Name
    onInterest,           // function
    onRegisterFailed      // function
    [, onRegisterSuccess  // function]
    [, flags              // ForwardingFlags]
)
[Java]:
public long registerPrefix(
    Name prefix,
    OnInterestCallback onInterest,
    OnRegisterFailed onRegisterFailed
    [, OnRegisterSuccess onRegisterSuccess]
    [, ForwardingFlags flags]
)
Parameters:
  • prefix

    The Name prefix to register.

  • onInterest

    (optional) If supplied then this creates an InterestFilter from prefix so that when an interest is received which matches the name prefix, this calls onInterest(prefix, interest, face, interestFilterId, filter) where:

    • prefix is the Name prefix given to registerPrefix.
    • interest is the received Interest.
    • face is the Face with the connection which received the interest. You should encode a signed Data packet and send it using putData.
    • interestFilterId is the interest filter ID which can be used with unsetInterestFilter.
    • filter is the InterestFilter created from the prefix.

    If onInterest is an empty OnInterestCallback() (C++) or null (JavaScript, Java) or None (PyNDN), it is ignored and you must call setInterestFilter.

    Note

    You must not change the prefix or filter objects - if you need to change them 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.

  • onRegisterFailed

    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

    (optional) When this receives a success message from the forwarder, this calls onRegisterSuccess(prefix, registeredPrefixId) where:

    • prefix is the prefix given to registerPrefix.
    • registeredPrefixId is the value returned by registerPrefix.

    (The onRegisterSuccess parameter comes after onRegisterFailed because it can be 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 how and which Interests should be forwarded towards the face. If omitted, use the default flags defined by the default ForwardingFlags constructor.

Returns:

The registered prefix ID which can be used with removeRegisteredPrefix.

Face.removePendingInterest Method

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.

[C++]:
void removePendingInterest(
    uint64_t pendingInterestId
);
[Python]:
def removePendingInterest(self,
    pendingInterestId  # int
)
[JavaScript]:
Face.prototype.removePendingInterest = function(
    pendingInterestId  // number
)
[Java]:
public void removePendingInterest(
    long pendingInterestId
)
Parameters:
  • pendingInterestId
    The ID returned from expressInterest.

Face.removeRegisteredPrefix Method

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.

[C++]:
void removeRegisteredPrefix(
    uint64_t registeredPrefixId
);
[Python]:
def removeRegisteredPrefix(self,
    registeredPrefixId  # int
)
[JavaScript]:
Face.prototype.removeRegisteredPrefix = function(
    registeredPrefixId  // number
)
[Java]:
public void removeRegisteredPrefix(
    long registeredPrefixId
)
Parameters:
  • registeredPrefixId
    The ID returned from registerPrefix.

Face.send Method

Send the encoded packet out through the face.

[C++]:
void send(
    const Blob& encoding
);

void send(
    const uint8_t* encoding,
    size_t encodingLength
);
[Python]:
def send(self,
    encoding  # Blob or an array type with int elements
)
[JavaScript]:
Face.prototype.send = function(
    encoding  // Blob or Buffer
)
[Java]:
public void send(
    Blob encoding
)

public void send(
    ByteBuffer encoding
)
Parameters:
  • encoding
    The Blob or byte array with the the encoded packet to send.
  • encodingLength
    (C++ only) The length of the encoding byte array.
Throw:

Throw an exception if the encoded packet size exceeds getMaxNdnPacketSize().

Face.setCommandCertificateName Method

Set the certificate name used to sign command interest (e.g. for registerPrefix), using the KeyChain that was set with setCommandSigningInfo.

[C++]:
void setCommandCertificateName(
    const Name& certificateName
);
[Python]:
def setCommandCertificateName(self,
    certificateName  # Name
)
[JavaScript]:
Face.prototype.setCommandCertificateName = function(
    certificateName  // Name
)
[Java]:
public void setCommandCertificateName(
    Name certificateName
)
Parameters:
  • certificateName
    The certificate name for signing interest. This makes a copy of the Name.

Face.setCommandSigningInfo Method

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

[C++]:
void setCommandSigningInfo(
    KeyChain& keyChain,
    const Name& certificateName
);
[Python]:
def setCommandSigningInfo(self,
    keyChain         # KeyChain
    certificateName  # Name
)
[JavaScript]:
Face.prototype.setCommandSigningInfo = function(
    keyChain         // KeyChain
    certificateName  // Name
)
[Java]:
public void setCommandSigningInfo(
    KeyChain keyChain,
    Name certificateName
)
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 interest. This makes a copy of the Name. You can get the default certificate name with keyChain.getDefaultCertificateName() .

Face.setInterestFilter Methods

Face.setInterestFilter Method (from InterestFilter)

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.

[C++]:
uint64_t setInterestFilter(
    const InterestFilter& filter,
    const OnInterestCallback &onInterest
)
[Python]:
# Returns int
def setInterestFilter(self,
    filter,     # InterestFilter
    onInterest  # function object
)
[JavaScript]:
// Returns number
Face.prototype.setInterestFilter = function(
    filter,     // InterestFilter
    onInterest  // function
)
[Java]:
public long setInterestFilter(
    InterestFilter filter,
    OnInterestCallback onInterest
)
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

    (optional) This creates an InterestFilter from prefix so that when an interest is received which matches the name prefix, this calls onInterest(prefix, interest, face, interestFilterId, filter) where:

    • prefix is the Name prefix given to setInterestFilter.
    • interest is the received Interest.
    • face is the Face with the connection which received the interest. You should encode a signed Data packet and send it using putData.
    • interestFilterId is the interest filter ID which can be used with unsetInterestFilter.
    • filter is the InterestFilter created from the prefix.

    Note

    You must not change the prefix or filter objects - if you need to change them 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.

Returns:

The interest filter ID which can be used with unsetInterestFilter.

Face.setInterestFilter Method (from prefix)

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.

[C++]:
uint64_t setInterestFilter(
    const Name &prefix,
    const OnInterestCallback &onInterest
)
[Python]:
# Returns int
def setInterestFilter(self,
    prefix,     # Name
    onInterest  # function object
)
[JavaScript]:
// Returns number
Face.prototype.setInterestFilter = function(
    prefix,     // Name
    onInterest  // function
)
[Java]:
public long setInterestFilter(
    Name prefix,
    OnInterestCallback onInterest
)
Parameters:
  • prefix

    The Name prefix used to match the name of an incoming Interest.

  • onInterest

    (optional) This creates an InterestFilter from prefix so that when an interest is received which matches the name prefix, this calls onInterest(prefix, interest, face, interestFilterId, filter) where:

    • prefix is the Name prefix given to setInterestFilter.
    • interest is the received Interest.
    • face is the Face with the connection which received the interest. You should encode a signed Data packet and send it using putData.
    • interestFilterId is the interest filter ID which can be used with unsetInterestFilter.
    • filter is the InterestFilter created from the prefix.

    Note

    You must not change the prefix or filter objects - if you need to change them 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.

Returns:

The interest filter ID which can be used with unsetInterestFilter.

Face.unsetInterestFilter Method

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.

[C++]:
void unsetInterestFilter(
    uint64_t interestFilterId
);
[Python]:
def unsetInterestFilter(self,
    interestFilterId  # int
)
[JavaScript]:
Face.prototype.unsetInterestFilter = function(
    interestFilterId  // number
)
[Java]:
public void unsetInterestFilter(
    long interestFilterId
)
Parameters: