piles of doxygen, changes to SetDefaultMulticastRoute plumbing

src/internet-node/ipv4-impl.cc

@@ -106,13 +106,9 @@ Ipv4Impl::AddMulticastRoute (Ipv4Address origin,
 }
 
 void
-Ipv4Impl::SetDefaultMulticastRoute (Ipv4Address origin, 
-                                    Ipv4Address group,
-                                    uint32_t inputInterface,
-                                    std::vector<uint32_t> outputInterfaces)
+Ipv4Impl::SetDefaultMulticastRoute (uint32_t outputInterface)
 {
-  m_ipv4->SetDefaultMulticastRoute (origin, group, inputInterface, 
-                                    outputInterfaces);
+  m_ipv4->SetDefaultMulticastRoute (outputInterface);
 }
 
 uint32_t 

src/internet-node/ipv4-impl.h

@@ -62,9 +62,7 @@ public:
                                   uint32_t inputInterface,
                                   std::vector<uint32_t> outputInterfaces);
 
-  virtual void SetDefaultMulticastRoute (Ipv4Address origin,
-    Ipv4Address group, uint32_t inputInterface,
-    std::vector<uint32_t> outputInterfaces);
+  virtual void SetDefaultMulticastRoute (uint32_t outputInterface);
 
   virtual uint32_t GetNMulticastRoutes (void) const;
   virtual Ipv4MulticastRoute GetMulticastRoute (uint32_t i) const;

src/internet-node/ipv4-l3-protocol.cc

@@ -356,17 +356,12 @@ Ipv4L3Protocol::AddMulticastRoute (Ipv4Address origin,
 }
 
 void 
-Ipv4L3Protocol::SetDefaultMulticastRoute (
-  Ipv4Address origin,
-  Ipv4Address group, 
-  uint32_t inputInterface,
-  std::vector<uint32_t> outputInterfaces)
+Ipv4L3Protocol::SetDefaultMulticastRoute (uint32_t outputInterface)
 {
-  NS_DEBUG("Ipv4L3Protocol::SetDefaultMulticastRoute (" << origin << ", " <<
-    group << ", " << inputInterface << ", " << &outputInterfaces << ")");
+  NS_DEBUG("Ipv4L3Protocol::SetDefaultMulticastRoute (" << outputInterface <<
+    ")");
 
-  m_staticRouting->SetDefaultMulticastRoute (origin, group, inputInterface,
-    outputInterfaces);
+  m_staticRouting->SetDefaultMulticastRoute (outputInterface);
 }
 
 uint32_t 

src/internet-node/ipv4-l3-protocol.h

@@ -163,10 +163,7 @@ public:
                           uint32_t inputInterface,
                           std::vector<uint32_t> outputInterfaces);
 
-  void SetDefaultMulticastRoute (Ipv4Address origin,
-                                 Ipv4Address group,
-                                 uint32_t inputInterface,
-                                 std::vector<uint32_t> outputInterfaces);
+  void SetDefaultMulticastRoute (uint32_t onputInterface);
 
   uint32_t GetNMulticastRoutes (void) const;
   Ipv4MulticastRoute *GetMulticastRoute (uint32_t i) const;

src/internet-node/ipv4-static-routing.cc

@@ -101,15 +101,19 @@ Ipv4StaticRouting::AddMulticastRoute(Ipv4Address origin,
 }
 
 void 
-Ipv4StaticRouting::SetDefaultMulticastRoute(
-  Ipv4Address origin,
-  Ipv4Address group,
-  uint32_t inputInterface,
-  std::vector<uint32_t> outputInterfaces)
+Ipv4StaticRouting::SetDefaultMulticastRoute(uint32_t outputInterface)
 {
+  Ipv4Address origin = Ipv4Address::GetAny ();
+  Ipv4Address group = Ipv4Address::GetAny ();
+  uint32_t inputInterface = Ipv4RoutingProtocol::IF_INDEX_ANY;
+
+  std::vector<uint32_t> outputInterfaces (1);
+  outputInterfaces[0] = outputInterface;
+  
   Ipv4MulticastRoute *route = new Ipv4MulticastRoute ();
   *route = Ipv4MulticastRoute::CreateMulticastRoute (origin, group, 
     inputInterface, outputInterfaces);
+
   delete m_defaultMulticastRoute;
   m_defaultMulticastRoute = route;
 }
@@ -177,7 +181,7 @@ Ipv4StaticRouting::GetDefaultMulticastRoute () const
   return 0;
 }
 
-void 
+bool
 Ipv4StaticRouting::RemoveMulticastRoute(Ipv4Address origin,
                                         Ipv4Address group,
                                         uint32_t inputInterface)
@@ -196,9 +200,10 @@ Ipv4StaticRouting::RemoveMulticastRoute(Ipv4Address origin,
         {
           delete *i;
           m_multicastRoutes.erase (i);
-          return;
+          return true;
         }
     }
+  return false;
 }
 
 void 

src/internet-node/ipv4-static-routing.h

@@ -45,57 +45,418 @@ class TraceResolver;
 class TraceContext;
 
 
+/**
+ * @brief Static routing protocol for IP version 4 stacks.
+ *
+ * In ns-3 we have the concept of a pluggable routing protocol.  Routing
+ * protocols are added to a list maintained by the Ipv4L3Protocol.  Every 
+ * stack gets one routing protocol for free -- the Ipv4StaticRouting routing
+ * protocol is added in the constructor of the Ipv4L3Protocol (this is the 
+ * piece of code that implements the functionality of the IP layer).
+ *
+ * The Ipv4StaticRouting class inherits from the abstract base class 
+ * Ipv4RoutingProtocol that defines the interface methods that a routing 
+ * protocol must support.
+ *
+ * When a packet arrives in the Ipv4L3Protocol for transmission, it comes
+ * either from a local source via Ipv4L3Protocol::Send or from a remote 
+ * source via Ipv4L3Protocol::Forwarding.  In both cases, a function is called
+ * (Ipv4L3Protocol::Lookup) to look up the routing information for the packet.
+ *
+ * The lookup function iterates through the list of routing protocols asking
+ * each to see if it can find a route and send the packet.  A callback is 
+ * provided during each of these calls that should be considered a pre-
+ * packaged send call.  This is done to allow asynchronous calls into 
+ * routing subsystems in order to support on-demand routing, for example.  The
+ * method for requesting this operation is Ipv4StaticRouting::RequestRoute for
+ * the static routing protocol.
+ *
+ * Each routing protocol is also free to implement its own methods for managing
+ * routes which you will find below.  This class manages a set of "static" or
+ * manually configured routes for host, network and multicast routes.
+ *
+ * @see Ipv4RoutingProtocol
+ * @see Ipv4L3Protocol::AddRoutingProtocol
+ * @see Ipv4L3Protocol::Ipv4L3Protocol
+ */
 class Ipv4StaticRouting : public Ipv4RoutingProtocol
 {
-
 public:
+/**
+ * @brief Construct an empty Ipv4StaticRouting routing protocol,
+ * @internal
+ *
+ * The Ipv4StaticRouting class supports host, network and multicast routes.
+ * This method initializes the lists containing these routes to empty.
+ *
+ * @see Ipv4StaticRouting
+ */
   Ipv4StaticRouting ();
 
+/**
+ * @brief Request that a check for a route bw performed and if a route is found
+ * that the packet be sent on its way using the pre-packaged send callback.
+ *
+ * The source and destination IP addresses for the packet in question are found
+ * in the provided Ipv4Header.  There are two major processing forks depending
+ * on the type of destination address.  
+ *
+ * If the destination address is unicast then the routing table is consulted 
+ * for a route to the destination and if it is found, the routeReply callback
+ * is executed to send the packet (with the found route).
+ * 
+ * If the destination address is a multicast, then the exact processing steps
+ * depend on whether or not the packet has been sourced locally.  This is 
+ * determined by the parameter ifIndex.  This is the interface index over which
+ * this packet was received.  If the packet has not been received over a
+ * network interface, this index will be set to 
+ * Ipv4RoutingProtocol::IF_INDEX_ANY (a very large number).  In that case, 
+ * we want to avoid the requirement that an explicit route out of each node 
+ * must be set, so we don't do anything here.
+ * 
+ * If the packet is a multicast destination and has been received over a 
+ * network interface, a call to this method implies that the packet is being
+ * forwarded.  In that case, there must be an explicit route out of the node.
+ * A multicast route references the source address, the destination address
+ * (the multicast group) and the input interface in order to find a route.
+ * We consult the multicast routing table and, if a route is found, send the
+ * packet out of as many interfaces as required using the provided callback
+ * (think of it as a pre-packaged send call).
+ *
+ * @param ifIndex The network interface index over which the packed was 
+ * received.  If the packet is from a local source, ifIndex will be set to
+ * Ipv4RoutingProtocol::IF_INDEX_ANY.
+ * @param ipHeader the Ipv4Header containing the source and destination IP
+ * addresses for the packet.
+ * @param packet The packet to be sent if a route is found.
+ * @param routeReply A callback that packaged up the call to actually send the
+ * packet.
+ * @return Returns true if a route is found and the packet has been sent,
+ * otherwise returns false indicating that the next routing protocol should
+ * be consulted.  In practice, the static routing protocol is the last chance
+ * protocol.
+ *
+ * @see Ipv4StaticRouting
+ * @see Ipv4RoutingProtocol
+ */
   virtual bool RequestRoute (uint32_t ifIndex,
                              Ipv4Header const &ipHeader,
                              Packet packet,
                              RouteReplyCallback routeReply);
 
+/**
+ * @brief Check to see if we can determine the interface index that will be
+ * used if a packet is sent to this destination.
+ *
+ * This method addresses a problem in the IP stack where a destination address
+ * must be present and checksummed into the IP header before the actual 
+ * interface over which the packet is sent can be determined.  The answer is
+ * to implement a known and intentional cross-layer violation.  This is the
+ * endpoint of a call chain that started up quite high in the stack (sockets)
+ * and has found its way down to the Ipv4L3Protocol which is consulting the
+ * routing protocols for what they would do if presented with a packet of the
+ * given destination.
+ *
+ * Note that the a single interface index is returned.  This means that if
+ * the destination address is a multicast, and an explicit route is present
+ * that includeds multiple output interfaces, that route cannot be used.
+ * 
+ * If there are multiple paths out of the node, the resolution is performed
+ * by Ipv4L3Protocol::GetIfIndexforDestination which has access to more 
+ * contextual information that is useful for making a determination.
+ *
+ * @param destination The Ipv4Address if the destination of a hypothetical 
+ * packet.  This may be a multicast group address.
+ * @param ifIndex A reference to the interface index over which a packet
+ * sent to this destination would be sent.
+ * @return Returns true if a route is found to the destination that involves
+ * a single output interface index, otherwise returns false indicating that
+ * the next routing protocol should be consulted.  In practice, the static 
+ * routing protocol is the last chance protocol.
+ *
+ * @see Ipv4StaticRouting
+ * @see Ipv4RoutingProtocol
+ * @see Ipv4L3Protocol
+ */
   virtual bool RequestIfIndex (Ipv4Address destination, uint32_t& ifIndex);
 
+/**
+ * @brief Add a host route to the static routing table.
+ *
+ * @param dest The Ipv4Address destination for this route.
+ * @param nextHop The Ipv4Address of the next hop in the route.
+ * @param interface The network interface index used to send packets to the
+ * destination.
+ *
+ * @see Ipv4Address
+ */
   void AddHostRouteTo (Ipv4Address dest, 
                        Ipv4Address nextHop, 
                        uint32_t interface);
+/**
+ * @brief Add a host route to the static routing table.
+ *
+ * @param dest The Ipv4Address destination for this route.
+ * @param interface The network interface index used to send packets to the
+ * destination.
+ *
+ * @see Ipv4Address
+ */
   void AddHostRouteTo (Ipv4Address dest, 
                        uint32_t interface);
 
+/**
+ * @brief Add a network route to the static routing table.
+ *
+ * @param network The Ipv4Address network for this route.
+ * @param networkmask The Ipv4Mask to extract the network.
+ * @param nextHop The next hop in the route to the destination network.
+ * @param interface The network interface index used to send packets to the
+ * destination.
+ *
+ * @see Ipv4Address
+ */
   void AddNetworkRouteTo (Ipv4Address network, 
                           Ipv4Mask networkMask, 
                           Ipv4Address nextHop, 
                           uint32_t interface);
+
+/**
+ * @brief Add a network route to the static routing table.
+ *
+ * @param network The Ipv4Address network for this route.
+ * @param networkmask The Ipv4Mask to extract the network.
+ * @param interface The network interface index used to send packets to the
+ * destination.
+ *
+ * @see Ipv4Address
+ */
   void AddNetworkRouteTo (Ipv4Address network, 
                           Ipv4Mask networkMask, 
                           uint32_t interface);
+
+/**
+ * @brief Add a default route to the static routing table.
+ *
+ * This method tells the routing system what to do in the case where a specific
+ * route to a destination is not found.  The system forwards packets to the
+ * specified node in the hope that it knows better how to route the packet.
+ * 
+ * If the default route is set, it is returned as the selected route from 
+ * LookupStatic irrespective of destination address if no specific route is
+ * found.
+ *
+ * @param nextHop The Ipv4Address to send packets to in the hope that they
+ * will be forwarded correctly.
+ * @param interface The network interface index used to send packets.
+ *
+ * @see Ipv4Address
+ * @see Ipv4StaticRouting::Lookup
+ */
   void SetDefaultRoute (Ipv4Address nextHop, 
                         uint32_t interface);
+
+/**
+ * @brief Get the number of individual unicast routes that have been added
+ * to the routing table.
+ *
+ * @warning The default route counts as one of the routes.
+ */
   uint32_t GetNRoutes (void);
+
+/**
+ * @brief Get the default route from the static routing table.
+ *
+ * @return If the default route is set, a pointer to that Ipv4Route is
+ * returned, otherwise a zero pointer is returned.
+ *
+ * @see Ipv4Route
+ */
   Ipv4Route *GetDefaultRoute (void);
+
+/**
+ * @brief Get a route from the static unicast routing table.
+ *
+ * Externally, the unicast static routing table appears simply as a table with
+ * n entries.  The one sublety of note is that if a default route has been set
+ * it will appear as the zeroth entry in the table.  This means that if you
+ * add only a default route, the table will have one entry that can be accessed
+ * either by explicity calling GetDefaultRoute () or by calling GetRoute (0).
+ * 
+ * Similarly, if the default route has been set, calling RemoveRoute (0) will
+ * remove the default route.
+ *
+ * @param i The index (into the routing table) of the route to retrieve.  If
+ * the default route has been set, it will occupy index zero.
+ * @return If route is set, a pointer to that Ipv4Route is returned, otherwise
+ * a zero pointer is returned.
+ *
+ * @see Ipv4Route
+ * @see Ipv4StaticRouting::RemoveRoute
+ */
   Ipv4Route *GetRoute (uint32_t i);
+
+/**
+ * @brief Remove a route from the static unicast routing table.
+ *
+ * Externally, the unicast static routing table appears simply as a table with
+ * n entries.  The one sublety of note is that if a default route has been set
+ * it will appear as the zeroth entry in the table.  This means that if the
+ * default route has been set, calling RemoveRoute (0) will remove the
+ * default route.
+ *
+ * @param i The index (into the routing table) of the route to remove.  If
+ * the default route has been set, it will occupy index zero.
+ *
+ * @see Ipv4Route
+ * @see Ipv4StaticRouting::GetRoute
+ * @see Ipv4StaticRouting::AddRoute
+ */
   void RemoveRoute (uint32_t i);
 
+/**
+ * @brief Add a multicast route to the static routing table.
+ *
+ * A multicast route must specify an origin IP address -- the address of the
+ * node that originates packets destined for a given multicast group.  This
+ * address may be Ipv4Address::GetAny (typically 0.0.0.0) if the multicast
+ * group is open, or it may specify a single IP address if the multicast
+ * group is closed.  The route must also specify the multicast group address.
+ *
+ * For each route, the input nework interface must be specified.  For 
+ * forwarding operations, this is the interface index that you expect multicast
+ * packets to arrive over.  If you want to specify routes off of a local node
+ * for given multicast groups, this index may be set to 
+ * Ipv4RoutingProtocol::IF_INDEX_ANY.
+ *
+ * For each route, a vector of output network interfaces must also be 
+ * specified.  When the RequestRoute operation is performed, copies of a 
+ * packet are sent out all of the specified interfaces.
+ * 
+ * @param origin The Ipv4Address of the origin of packets for this route.  May
+ * be Ipv4Address:GetAny for open groups.
+ * @param group The Ipv4Address of the multicast group or this route.
+ * @param inputInterface The input network interface index over which to 
+ * expect packets destined for this route.  May be
+ * Ipv4RoutingProtocol::IF_INDEX_ANY for packets of local origin.
+ * @param outputInterface A vector of network interface indices used to specify
+ * how to send packets to the destination(s).
+ *
+ * @see Ipv4Address
+ */
   void AddMulticastRoute (Ipv4Address origin,
                           Ipv4Address group,
                           uint32_t inputInterface,
                           std::vector<uint32_t> outputInterfaces);
 
-  void SetDefaultMulticastRoute (Ipv4Address origin,
-                                 Ipv4Address group,
-                                 uint32_t inputInterface,
-                                 std::vector<uint32_t> outputInterfaces);
+/**
+ * @brief Add a default multicast route to the static routing table.
+ *
+ * This is the multicast equivalent of the unicast version SetDefaultRoute.
+ * We tell the routing system what to do in the case where a specific route
+ * to a destination multicast group is not found.  The system forwards 
+ * packets out the specified interface in the hope that "something out there"
+ * knows better how to route the packet.
+ *
+ * Since we're basically forwarding packets to some entity we think may know
+ * better what to do, we don't pay attention to subleties like origin address
+ * and input interface, nor do we worry about forwarding out multiple 
+ * interfaces.  If the default multicast route is set, it is returned as the
+ * selected route from LookupStatic irrespective of origin, multicast group or
+ * input interface if another specific route is not found.
+ *
+ * @param outputInterface The network interface index used to specify where
+ * to send packets in the case of unknown routes.
+ *
+ * @see Ipv4Address
+ */
+  void SetDefaultMulticastRoute (uint32_t outputInterface);
 
+/**
+ * @brief Get the number of individual multicast routes that have been added
+ * to the routing table.
+ *
+ * @warning The default multicast route counts as one of the routes.
+ */
   uint32_t GetNMulticastRoutes (void) const;
+
+/**
+ * @brief Get a route from the static multicast routing table.
+ *
+ * Externally, the multicast static routing table appears simply as a table 
+ * with n entries.  The one sublety of note is that if a default route has 
+ * been set it will appear as the zeroth entry in the table.  This means that 
+ * if you add only a default route, the table will have one entry that can be
+ * accessed either by explicity calling GetDefaultMulticastRoute () or by
+ * calling GetMulticastRoute (0).
+ * 
+ * Similarly, if the default route has been set, calling 
+ * RemoveMulticastRoute (0) will remove the default route.
+ *
+ * @param i The index (into the routing table) of the multicast route to
+ * retrieve.  If the default route has been set, it will occupy index zero.
+ * @return If route <i> is set, a pointer to that Ipv4MulticastRoute is
+ * returned, otherwise a zero pointer is returned.
+ *
+ * @see Ipv4MulticastRoute
+ * @see Ipv4StaticRouting::RemoveRoute
+ */
   Ipv4MulticastRoute *GetMulticastRoute (uint32_t i) const;
+
+/**
+ * @brief Get the default multicast route from the static routing table.
+ *
+ * @return If the default route is set, a pointer to that Ipv4MulticastRoute is
+ * returned, otherwise a zero pointer is returned.
+ *
+ * @see Ipv4Route
+ */
   Ipv4MulticastRoute *GetDefaultMulticastRoute (void) const;
 
-  void RemoveMulticastRoute (Ipv4Address origin,
+/**
+ * @brief Remove a route from the static multicast routing table.
+ *
+ * Externally, the multicast static routing table appears simply as a table 
+ * with n entries.  The one sublety of note is that if a default multicast
+ * route has been set it will appear as the zeroth entry in the table.  This
+ * means that the default route may be removed by calling this method with
+ * appropriate wildcard parameters.
+ *
+ * This method causes the multicast routing table to be searched for the first
+ * route that matches the parameters and removes it.
+ *
+ * @param origin The IP address specified as the origin of packets for the
+ * route.
+ * @param origin The IP address specified as the multicast group addres of
+ * the route.
+ * @param inputInterfade The network interface index specified as the expected
+ * input interface for the route.
+ * @returns True if a route was found and removed, false otherwise.
+ *
+ * @see Ipv4Route
+ * @see Ipv4StaticRouting::GetRoute
+ * @see Ipv4StaticRouting::AddRoute
+ */
+  bool RemoveMulticastRoute (Ipv4Address origin,
                              Ipv4Address group,
                              uint32_t inputInterface);
 
+/**
+ * @brief Remove a route from the static multicast routing table.
+ *
+ * Externally, the multicast static routing table appears simply as a table 
+ * with n entries.  The one sublety of note is that if a default multicast
+ * route has been set it will appear as the zeroth entry in the table.  This 
+ * means that if the default route has been set, calling 
+ * RemoveMulticastRoute (0) will remove the default route.
+ *
+ * @param index The index (into the multicast routing table) of the route to
+ * remove.  If the default route has been set, it will occupy index zero.
+ *
+ * @see Ipv4Route
+ * @see Ipv4StaticRouting::GetRoute
+ * @see Ipv4StaticRouting::AddRoute
+ */
   void RemoveMulticastRoute (uint32_t index);
 
 protected: