docs/source/applications.rst - ndnSIM - Gitiles

 ndnSIM applications
 ===================

 ndnSIM includes a few reference applications that can be used as a base for NDN simulations.

 Reference applications
 ++++++++++++++++++++++

 ConsumerCbr
 ^^^^^^^^^^^^^^^

 :ndnsim:`ConsumerCbr` an application that generates Interest traffic with predefined pattern (constant frequency, constant average rate with inter-Interest gap distributed uniformly at random, exponentially at random, etc.).

 .. code-block:: c++

    // Create application using the app helper
    ndn::AppHelper helper ("ns3::ndn::ConsumerCbr");

 This applications has the following attributes:

 * Frequency

   .. note::
      default: ``1.0`` (1 per second)

   Either exact (for contant version) or expected (for randomized version) frequency with which Interests are generated

   .. code-block:: c++

      // Set attribute using the app helper
      helper.SetAttribute ("Frequency", DoubleValue (1.0));

 * Randomize

   .. note::
      default: ``"none"``

   Specify whether to do randomization for inter-Interest gap or not.  The following variants are currently supported:

   - ``"none"``: no randomization

   - ``"uniform"``: uniform distribution in range (0, 1/Frequency)

   - ``"exponential"``: exponential distribution with mean 1/Frequency

   .. code-block:: c++

      // Set attribute using the app helper
      helper.SetAttribute ("Randomize", StringValue ("uniform"));

 ConsumerBatches
 ^^^^^^^^^^^^^^^^^^^

 :ndnsim:`ConsumerBatches` is an on-off-style application gen- erating a specified number of Interests at specified points of simulation.

 .. code-block:: c++

    // Create application using the app helper
    ndn::AppHelper consumerHelper ("ns3::ndn::ConsumerBatches");

 This applications has the following attributes:

 * Batches

   .. note::
      default: Empty

   Specify exact pattern of Interest packets, specifying when and how many Interest packets should be sent.
   The following example defines that 1 Interest should be requested at time 1s, 5 Interests at time 5s, and 2 Interests at time 10s.:

   .. code-block:: c++

      // Set attribute using the app helper
      helper.SetAttribute ("Batches", StringValue ("1s 1 2s 5 10s 2"));


 ConsumerWindow
 ^^^^^^^^^^^^^^^^^^

 :ndnsim:`ConsumerWindow` is an application generating a variable rate Interest traffic. It relies on an optional NACK-Interest feature and implements a simple sliding-window-based Interest generation mechanism.

 .. code-block:: c++

    // Create application using the app helper
    ndn::AppHelper consumerHelper ("ns3::ndn::ConsumerWindow");


 This applications has the following attributes:

 * Window

   .. note::
      default: ``1``

   Initial number of Interests that will be send out without waiting for the data (number of outstanding Interests)

 * PayloadSize

   .. note::
      default: ``1040``

   Expected size of the Data payload (necessary only when Size is specified)

 * Size

   .. note::
      default: ``-1``

   Amount of data to be requested (will stop issuing Interests after ``Size`` data is received)

   If ``Size`` is set to -1, Interests will be requested till the end of the simulation.

 Producer
 ^^^^^^^^^^^^

 :ndnsim:`Producer` a simple Interest-sink application, which replying every incoming Interest with Data packet with a specified size and name same as in Interest.

 .. code-block:: c++

    // Create application using the app helper
    ndn::AppHelper consumerHelper ("ns3::ndn::Producer");


 Custom applications
 +++++++++++++++++++

 Applications interact with the core of the system using :ndnsim:`AppFace` realization of Face abstraction.
 To simplify implementation of specific NDN application, ndnSIM provides a base :ndnsim:`App` class that takes care of creating :ndnsim:`AppFace` and registering it inside the NDN protocol stack, as well as provides default processing for incoming Interest and Data packets.

 .. Base App class
 .. ^^^^^^^^^^^^^^^^^^


 Customer example
 ^^^^^^^^^^^^^^^^

 The following code shows how a simple ndnSIM application can be created.
 For details refer to API documentation of ndnSIM and NS-3.

 .. code-block:: c++

     class CustomApp : public ndn::App
     {
     public:
       // overridden from ndn::App

       // Processing upon start of the application
       virtual void
       StartApplication ()
       {
         // initialize ndn::App
         ndn::App::StartApplication ();

         // Create a name components object for name ``/prefix/sub``
 	Ptr<ndn::NameComponents> prefix = Create<ndn::NameComponents> (); // now prefix contains ``/``
 	prefix->Add ("prefix"); // now prefix contains ``/prefix``
 	prefix->Add ("sub"); // now prefix contains ``/prefix/sub``

         /////////////////////////////////////////////////////////////////////////////
         // Creating FIB entry that ensures that we will receive incoming Interests //
         /////////////////////////////////////////////////////////////////////////////

         // Get FIB object
         Ptr<ndn::Fib> fib = GetNode ()->GetObject<ndn::Fib> ();

         // Add entry to FIB
         // Note that ``m_face`` is cretaed by ndn::App
         ndn::fib::EntryContainer::type::iterator fibEntry = fib->Add (*prefix, m_face, 0);

         /////////////////////////////////////
 	// Sending one Interest packet out //
         /////////////////////////////////////

         // Create and configure ndn::InterestHeader
         ndn::InterestHeader interestHeader;
         UniformVariable rand (0,std::numeric_limits<uint32_t>::max ());
         interestHeader.SetNonce            (rand.GetValue ());
         interestHeader.SetName             (prefix);
         interestHeader.SetInterestLifetime (Seconds (1.0));

         // Create packet and add ndn::InterestHeader
         Ptr<Packet> packet = Create<Packet> ();
         packet->AddHeader (interestHeader);

         // Forward packet to lower (network) layer
         m_protocolHandler (packet);

         // Call trace (for logging purposes)
         m_transmittedInterests (&interestHeader, this, m_face);
       }

       // Processing when application is stopped
       virtual void
       StopApplication ()
       {
         // cleanup ndn::App
         ndn::App::StopApplication ();
       }

       // Callback that will be called when Interest arrives
       virtual void
       OnInterest (const Ptr<const ndn::InterestHeader> &interest, Ptr<Packet> packet)
       {
         // Create and configure ndn::ContentObjectHeader and ndn::ContentObjectTail
         // (header is added in front of the packet, tail is added at the end of the packet)

         ndn::ContentObjectHeader data;
         data.SetName (Create<ndn::NameComponents> (interest->GetName ())); // data will have the same name as Interests

         ndn::ContentObjectTail trailer; // doesn't require any configuration

         // Create packet and add header and trailer
         Ptr<Packet> packet = Create<Packet> (1024);
         packet->AddHeader (data);
         packet->AddTrailer (trailer);

         // Forward packet to lower (network) layer
         m_protocolHandler (packet);

         // Call trace (for logging purposes)
         m_transmittedInterests (&interestHeader, this, m_face);
         m_transmittedContentObjects (&data, packet, this, m_face);
       }

       // Callback that will be called when Data arrives
       virtual void
       OnContentObject (const Ptr<const ndn::ContentObjectHeader> &contentObject,
                        Ptr<Packet> payload)
       {
         std::cout << "DATA received for name " << contentObject->GetName () << std::endl;
       }
     };

 Producer example (Interest hijacker)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

 The following code demonstrates how to implement a basic producer application that "hijacks" all incoming Interests.

 .. code-block:: c++

     #include "ns3/core-module.h"
     #include "ns3/network-module.h"
     #include "ns3/ndnSIM-module.h"

     using namespace ns3;

     class Hijacker : public ndn::App
     {
     public:
       static TypeId
       GetTypeId ();

       Hijacker ()
       {
       }

       // inherited from NdnApp
       void OnInterest (const Ptr<const ndn::InterestHeader> &interest, Ptr<Packet> packet)
       {
         ndn::App::OnInterest (interest, packet); // forward call to perform app-level tracing
         // do nothing else (hijack interest)
       }

     protected:
       // inherited from Application base class.
       virtual void
       StartApplication ()
       {
         App::StartApplication ();

         // equivalent to setting interest filter for "/" prefix
         Ptr<ndn::Fib> fib = GetNode ()->GetObject<ndn::Fib> ();
         Ptr<ndn::fib::Entry> fibEntry = fib->Add ("/", m_face, 0);
         fibEntry->UpdateStatus (m_face, ndn::fib::FaceMetric::NDN_FIB_GREEN);
       }

       virtual void
       StopApplication ()
       {
         App::StopApplication ();
       }
     };

     // Necessary if you are planning to use ndn::AppHelper
     NS_OBJECT_ENSURE_REGISTERED (Hijacker);

     TypeId
     Hijacker::GetTypeId ()
     {
       static TypeId tid = TypeId ("ndn::Hijacker")
         .SetParent<ndn::App> ()
         .AddConstructor<Hijacker> ()
         ;

       return tid;
     }


 After defining this class, you can use it with :ndnsim:`ndn::AppHelper`. For example:

 .. code-block:: c++

     ...
     ndn::AppHelper producerHelper ("ndn::Hijacker");
     producerHelper.Install (producerNode);
     ...
	ndnSIM applications
	===================

	ndnSIM includes a few reference applications that can be used as a base for NDN simulations.

	Reference applications
	++++++++++++++++++++++

	ConsumerCbr
	^^^^^^^^^^^^^^^

	:ndnsim:`ConsumerCbr` an application that generates Interest traffic with predefined pattern (constant frequency, constant average rate with inter-Interest gap distributed uniformly at random, exponentially at random, etc.).

	.. code-block:: c++

	// Create application using the app helper
	ndn::AppHelper helper ("ns3::ndn::ConsumerCbr");

	This applications has the following attributes:

	* Frequency

	.. note::
	default: ``1.0`` (1 per second)

	Either exact (for contant version) or expected (for randomized version) frequency with which Interests are generated

	.. code-block:: c++

	// Set attribute using the app helper
	helper.SetAttribute ("Frequency", DoubleValue (1.0));

	* Randomize

	.. note::
	default: ``"none"``

	Specify whether to do randomization for inter-Interest gap or not. The following variants are currently supported:

	- ``"none"``: no randomization

	- ``"uniform"``: uniform distribution in range (0, 1/Frequency)

	- ``"exponential"``: exponential distribution with mean 1/Frequency

	.. code-block:: c++

	// Set attribute using the app helper
	helper.SetAttribute ("Randomize", StringValue ("uniform"));

	ConsumerBatches
	^^^^^^^^^^^^^^^^^^^

	:ndnsim:`ConsumerBatches` is an on-off-style application gen- erating a specified number of Interests at specified points of simulation.

	.. code-block:: c++

	// Create application using the app helper
	ndn::AppHelper consumerHelper ("ns3::ndn::ConsumerBatches");

	This applications has the following attributes:

	* Batches

	.. note::
	default: Empty

	Specify exact pattern of Interest packets, specifying when and how many Interest packets should be sent.
	The following example defines that 1 Interest should be requested at time 1s, 5 Interests at time 5s, and 2 Interests at time 10s.:

	.. code-block:: c++

	// Set attribute using the app helper
	helper.SetAttribute ("Batches", StringValue ("1s 1 2s 5 10s 2"));


	ConsumerWindow
	^^^^^^^^^^^^^^^^^^

	:ndnsim:`ConsumerWindow` is an application generating a variable rate Interest traffic. It relies on an optional NACK-Interest feature and implements a simple sliding-window-based Interest generation mechanism.

	.. code-block:: c++

	// Create application using the app helper
	ndn::AppHelper consumerHelper ("ns3::ndn::ConsumerWindow");


	This applications has the following attributes:

	* Window

	.. note::
	default: ``1``

	Initial number of Interests that will be send out without waiting for the data (number of outstanding Interests)

	* PayloadSize

	.. note::
	default: ``1040``

	Expected size of the Data payload (necessary only when Size is specified)

	* Size

	.. note::
	default: ``-1``

	Amount of data to be requested (will stop issuing Interests after ``Size`` data is received)

	If ``Size`` is set to -1, Interests will be requested till the end of the simulation.

	Producer
	^^^^^^^^^^^^

	:ndnsim:`Producer` a simple Interest-sink application, which replying every incoming Interest with Data packet with a specified size and name same as in Interest.

	.. code-block:: c++

	// Create application using the app helper
	ndn::AppHelper consumerHelper ("ns3::ndn::Producer");


	Custom applications
	+++++++++++++++++++

	Applications interact with the core of the system using :ndnsim:`AppFace` realization of Face abstraction.
	To simplify implementation of specific NDN application, ndnSIM provides a base :ndnsim:`App` class that takes care of creating :ndnsim:`AppFace` and registering it inside the NDN protocol stack, as well as provides default processing for incoming Interest and Data packets.

	.. Base App class
	.. ^^^^^^^^^^^^^^^^^^



	Customer example
	^^^^^^^^^^^^^^^^

	The following code shows how a simple ndnSIM application can be created.
	For details refer to API documentation of ndnSIM and NS-3.

	.. code-block:: c++

	class CustomApp : public ndn::App
	{
	public:
	// overridden from ndn::App

	// Processing upon start of the application
	virtual void
	StartApplication ()
	{
	// initialize ndn::App
	ndn::App::StartApplication ();

	// Create a name components object for name ``/prefix/sub``
	Ptr<ndn::NameComponents> prefix = Create<ndn::NameComponents> (); // now prefix contains ``/``
	prefix->Add ("prefix"); // now prefix contains ``/prefix``
	prefix->Add ("sub"); // now prefix contains ``/prefix/sub``

	/////////////////////////////////////////////////////////////////////////////
	// Creating FIB entry that ensures that we will receive incoming Interests //
	/////////////////////////////////////////////////////////////////////////////

	// Get FIB object
	Ptr<ndn::Fib> fib = GetNode ()->GetObject<ndn::Fib> ();

	// Add entry to FIB
	// Note that ``m_face`` is cretaed by ndn::App
	ndn::fib::EntryContainer::type::iterator fibEntry = fib->Add (*prefix, m_face, 0);

	/////////////////////////////////////
	// Sending one Interest packet out //
	/////////////////////////////////////

	// Create and configure ndn::InterestHeader
	ndn::InterestHeader interestHeader;
	UniformVariable rand (0,std::numeric_limits<uint32_t>::max ());
	interestHeader.SetNonce (rand.GetValue ());
	interestHeader.SetName (prefix);
	interestHeader.SetInterestLifetime (Seconds (1.0));

	// Create packet and add ndn::InterestHeader
	Ptr<Packet> packet = Create<Packet> ();
	packet->AddHeader (interestHeader);

	// Forward packet to lower (network) layer
	m_protocolHandler (packet);

	// Call trace (for logging purposes)
	m_transmittedInterests (&interestHeader, this, m_face);
	}

	// Processing when application is stopped
	virtual void
	StopApplication ()
	{
	// cleanup ndn::App
	ndn::App::StopApplication ();
	}

	// Callback that will be called when Interest arrives
	virtual void
	OnInterest (const Ptr<const ndn::InterestHeader> &interest, Ptr<Packet> packet)
	{
	// Create and configure ndn::ContentObjectHeader and ndn::ContentObjectTail
	// (header is added in front of the packet, tail is added at the end of the packet)

	ndn::ContentObjectHeader data;
	data.SetName (Create<ndn::NameComponents> (interest->GetName ())); // data will have the same name as Interests

	ndn::ContentObjectTail trailer; // doesn't require any configuration

	// Create packet and add header and trailer
	Ptr<Packet> packet = Create<Packet> (1024);
	packet->AddHeader (data);
	packet->AddTrailer (trailer);

	// Forward packet to lower (network) layer
	m_protocolHandler (packet);

	// Call trace (for logging purposes)
	m_transmittedInterests (&interestHeader, this, m_face);
	m_transmittedContentObjects (&data, packet, this, m_face);
	}

	// Callback that will be called when Data arrives
	virtual void
	OnContentObject (const Ptr<const ndn::ContentObjectHeader> &contentObject,
	Ptr<Packet> payload)
	{
	std::cout << "DATA received for name " << contentObject->GetName () << std::endl;
	}
	};

	Producer example (Interest hijacker)
	^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

	The following code demonstrates how to implement a basic producer application that "hijacks" all incoming Interests.

	.. code-block:: c++

	#include "ns3/core-module.h"
	#include "ns3/network-module.h"
	#include "ns3/ndnSIM-module.h"

	using namespace ns3;

	class Hijacker : public ndn::App
	{
	public:
	static TypeId
	GetTypeId ();

	Hijacker ()
	{
	}

	// inherited from NdnApp
	void OnInterest (const Ptr<const ndn::InterestHeader> &interest, Ptr<Packet> packet)
	{
	ndn::App::OnInterest (interest, packet); // forward call to perform app-level tracing
	// do nothing else (hijack interest)
	}

	protected:
	// inherited from Application base class.
	virtual void
	StartApplication ()
	{
	App::StartApplication ();

	// equivalent to setting interest filter for "/" prefix
	Ptr<ndn::Fib> fib = GetNode ()->GetObject<ndn::Fib> ();
	Ptr<ndn::fib::Entry> fibEntry = fib->Add ("/", m_face, 0);
	fibEntry->UpdateStatus (m_face, ndn::fib::FaceMetric::NDN_FIB_GREEN);
	}

	virtual void
	StopApplication ()
	{
	App::StopApplication ();
	}
	};

	// Necessary if you are planning to use ndn::AppHelper
	NS_OBJECT_ENSURE_REGISTERED (Hijacker);

	TypeId
	Hijacker::GetTypeId ()
	{
	static TypeId tid = TypeId ("ndn::Hijacker")
	.SetParent<ndn::App> ()
	.AddConstructor<Hijacker> ()
	;

	return tid;
	}


	After defining this class, you can use it with :ndnsim:`ndn::AppHelper`. For example:

	.. code-block:: c++

	...
	ndn::AppHelper producerHelper ("ndn::Hijacker");
	producerHelper.Install (producerNode);
	...