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.putNack Method

Experimental

This method is an experimental feature, and the API may change.

The OnInterest callback can call this to put a Nack for the received Interest.

[C++]:

void putNack(
    const Interest& interest,
    const NetworkNack& networkNack
);

[Python]:

def putNack(self,
    interest,    # Interest
    networkNack  # NetworkNack
)

[JavaScript]:

Face.prototype.putNack = function(
    interest,    // Interest
    networkNack  // NetworkNack
)

[Java]:

public void putNack(
    Interest interest,
    NetworkNack networkNack
)

Parameters:

• interest

  The Interest to put in the Nack packet.

• networkNack

  The NetworkNack with the reason code. For example,

  • C++: NetworkNack().setReason(ndn_NetworkNackReason_NO_ROUTE)
  • Python: NetworkNack().setReason(NetworkNack.Reason.NO_ROUTE)
  • Java and JavaScript: new NetworkNack().setReason(NetworkNack.Reason.NO_ROUTE)

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 RegistrationOptions& registrationOptions]
)

[Python]:

# Returns int
def registerPrefix(self,
    prefix,               # Name
    onInterest,           # function object
    onRegisterFailed      # function object
    [, onRegisterSuccess  # function object]
    [, registrationOptions # RegistrationOptions]
)

[JavaScript]:

// Returns number
Face.prototype.registerPrefix = function(
    prefix,               // Name
    onInterest,           // function
    onRegisterFailed      // function
    [, onRegisterSuccess  // function]
    [, registrationOptions // RegistrationOptions]
)

[Java]:

public long registerPrefix(
    Name prefix,
    OnInterestCallback onInterest,
    OnRegisterFailed onRegisterFailed
    [, OnRegisterSuccess onRegisterSuccess]
    [, RegistrationOptions registrationOptions]
)

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.

• registrationOptions

  (optional) The registration options for finer control of how to forward an interest and other options. If omitted, use the default RegistrationOptions 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.setInterestLoopbackEnabled Method

Enable or disable Interest loopback. If Interest loopback is enabled, then an Interest to expressInterest is also sent to each of the matching OnInterest callbacks that the application gave to registerPrefix or setInterestFilter, and a Data that the application gives to putData can satisfy pending Interests. This way one part of an application can do Interest/Data exchange with another part through the same Face. Interest loopback is disabled by default.

[C++]:

void setInterestLoopbackEnabled(
    bool interestLoopbackEnabled
);

[Python]:

def setInterestLoopbackEnabled(self,
    interestLoopbackEnabled  # bool
)

[JavaScript]:

Face.prototype.setInterestLoopbackEnabled = function(
    interestLoopbackEnabled  // boolean
)

[Java]:

public final void setInterestLoopbackEnabled(
    boolean interestLoopbackEnabled
)

Parameters:

• interestLoopbackEnabled

  If true, enable Interest loopback, otherwise disable it.

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:

• interestFilterId

  The ID returned from setInterestFilter.