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.
--- a/src/internet-node/ipv4-impl.cc Thu Jul 26 12:27:49 2007 +0100
+++ b/src/internet-node/ipv4-impl.cc Fri Jul 27 15:38:04 2007 +0100
@@ -41,7 +41,7 @@
void
Ipv4Impl::AddRoutingProtocol (Ptr<Ipv4RoutingProtocol> routingProtocol,
- int priority)
+ int16_t priority)
{
m_ipv4->AddRoutingProtocol (routingProtocol, priority);
}
--- a/src/internet-node/ipv4-impl.h Thu Jul 26 12:27:49 2007 +0100
+++ b/src/internet-node/ipv4-impl.h Fri Jul 27 15:38:04 2007 +0100
@@ -36,7 +36,7 @@
virtual ~Ipv4Impl ();
virtual void AddRoutingProtocol (Ptr<Ipv4RoutingProtocol> routingProtocol,
- int priority);
+ int16_t priority);
virtual void AddHostRouteTo (Ipv4Address dest,
Ipv4Address nextHop,
--- a/src/node/ipv4.h Thu Jul 26 12:27:49 2007 +0100
+++ b/src/node/ipv4.h Fri Jul 27 15:38:04 2007 +0100
@@ -35,14 +35,40 @@
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 @@
*
* \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 @@
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