From 6b29b3c817eb3632c97d9bbd6329cde9eca580a6 Mon Sep 17 00:00:00 2001
From: "Gustavo J. A. M. Carneiro" <gjc@inescporto.pt>
Date: Fri, 27 Jul 2007 15:38:04 +0100
Subject: [PATCH] Add documentation for the dynamic routing interfaces.  Change
 Ipv4::AddRoutingProtocol priority parameter type from int to int16_t to make
 way for in the future providing stable sorting of routing protocols of the
 same priority.

---
 src/internet-node/ipv4-impl.cc |  2 +-
 src/internet-node/ipv4-impl.h  |  2 +-
 src/node/ipv4.h                | 66 +++++++++++++++++++++++++++++++---
 3 files changed, 64 insertions(+), 6 deletions(-)

diff --git a/src/internet-node/ipv4-impl.cc b/src/internet-node/ipv4-impl.cc
index 020413896..307425114 100644
--- a/src/internet-node/ipv4-impl.cc
+++ b/src/internet-node/ipv4-impl.cc
@@ -41,7 +41,7 @@ Ipv4Impl::DoDispose (void)
 
 void
 Ipv4Impl::AddRoutingProtocol (Ptr<Ipv4RoutingProtocol> routingProtocol,
-                              int priority)
+                              int16_t priority)
 {
   m_ipv4->AddRoutingProtocol (routingProtocol, priority);
 }
diff --git a/src/internet-node/ipv4-impl.h b/src/internet-node/ipv4-impl.h
index 32d9e5c68..445c10454 100644
--- a/src/internet-node/ipv4-impl.h
+++ b/src/internet-node/ipv4-impl.h
@@ -36,7 +36,7 @@ public:
   virtual ~Ipv4Impl ();
 
   virtual void AddRoutingProtocol (Ptr<Ipv4RoutingProtocol> routingProtocol,
-                                   int priority);
+                                   int16_t priority);
 
   virtual void AddHostRouteTo (Ipv4Address dest, 
 			       Ipv4Address nextHop, 
diff --git a/src/node/ipv4.h b/src/node/ipv4.h
index 1a957a4ee..76d88faea 100644
--- a/src/node/ipv4.h
+++ b/src/node/ipv4.h
@@ -35,14 +35,40 @@ class Ipv4Route;
 class Ipv4Header; // FIXME: ipv4-header.h needs to move from module
                   // "internet-node" to module "node"
 
+/**
+ * \brief Base class for IPv4 routing protocols.
+ *
+ * This class represents the interface between the IPv4 routing core
+ * and a specific IPv4 routing protocol.  The interface is
+ * asynchronous (callback based) in order to support reactive routing
+ * protocols (e.g. AODV).
+ */
 class Ipv4RoutingProtocol : public Object
 {
 public:
   // void (*RouteReply) (bool found, Ipv4Route route, Packet packet, Ipv4Header const &ipHeader);
-  typedef Callback<void, bool, Ipv4Route const&, Packet, Ipv4Header const &> RouteReplyCallback;
+
 
   /**
-   * \brief Asynchronously requests a route for a given packet and IP header 
+   * \brief Callback to be invoked when route discovery is completed
+   *
+   * \param bool flag indicating whether a route was actually found;
+   * when this is false, the Ipv4Route parameter is ignored
+   *
+   * \param Ipv4Route the route found
+   *
+   * \param Packet the packet for which a route was requested; can be
+   * modified by the routing protocol
+   *
+   * \param Ipv4Header the IP header supplied to the route request
+   * method (possibly modified in case a new routing header is
+   * inserted and consequently the protocol type has to change).
+   *
+   */
+  typedef Callback<void, bool, const Ipv4Route&, Packet, const Ipv4Header&> RouteReplyCallback;
+
+  /**
+   * \brief Asynchronously requests a route for a given packet and IP header
    *
    * \param ipHeader IP header of the packet
    * \param packet packet that is being sent or forwarded
@@ -50,8 +76,30 @@ public:
    *
    * \returns true if the routing protocol should be able to get the
    * route, false otherwise.
+   *
+   * This method is called whenever a node's IPv4 forwarding engine
+   * needs to lookup a route for a given packet and IP header.
+   *
+   * The routing protocol implementation may determine immediately it
+   * should not be handling this particular the route request.  For
+   * instance, a routing protocol may decline to search for routes for
+   * certain classes of addresses, like link-local.  In this case,
+   * RequestRoute() should return false and the routeReply callback
+   * must not be invoked.
+   *
+   * If the routing protocol implementations assumes it can provide
+   * the requested route, then it should return true, and the
+   * routeReply callback must be invoked, either immediately before
+   * returning true (synchronously), or in the future (asynchronous).
+   * The routing protocol may use any information available in the IP
+   * header and packet as routing key, although most routing protocols
+   * use only the destination address (as given by
+   * ipHeader.GetDestination ()).  The routing protocol is also
+   * allowed to add a new header to the packet, which will appear
+   * immediately after the IP header, although most routing do not
+   * insert any extra header.
    */
-  virtual bool RequestRoute (Ipv4Header const &ipHeader,
+  virtual bool RequestRoute (const Ipv4Header &ipHeader,
                              Packet packet,
                              RouteReplyCallback routeReply) = 0;
 };
@@ -73,8 +121,18 @@ public:
   Ipv4 ();
   virtual ~Ipv4 ();
 
+  /**
+   * \brief Register a new routing protocol to be used in this IPv4 stack
+   * 
+   * \param routingProtocol new routing protocol implementation object
+   * \param priority priority to give to this routing protocol.
+   * Values may range between -32768 and +32767.  The priority 0
+   * corresponds to static routing table lookups, higher values have
+   * more priority.  The order by which routing protocols with the
+   * same priority value are consulted is undefined.
+   */
   virtual void AddRoutingProtocol (Ptr<Ipv4RoutingProtocol> routingProtocol,
-                                   int priority) = 0;
+                                   int16_t priority) = 0;
   
   /**
    * \param dest destination address