00001 // -*- Mode: C++; c-file-style: "gnu"; indent-tabs-mode:nil; -*- 00002 // 00003 // Copyright (c) 2006 Georgia Tech Research Corporation 00004 // 00005 // This program is free software; you can redistribute it and/or modify 00006 // it under the terms of the GNU General Public License version 2 as 00007 // published by the Free Software Foundation; 00008 // 00009 // This program is distributed in the hope that it will be useful, 00010 // but WITHOUT ANY WARRANTY; without even the implied warranty of 00011 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 00012 // GNU General Public License for more details. 00013 // 00014 // You should have received a copy of the GNU General Public License 00015 // along with this program; if not, write to the Free Software 00016 // Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA 00017 // 00018 // Author: George F. Riley<riley@ece.gatech.edu> 00019 // Gustavo Carneiro <gjc@inescporto.pt> 00020 // 00021 00022 #ifndef IPV4_STATIC_ROUTING_H 00023 #define IPV4_STATIC_ROUTING_H 00024 00025 #include <list> 00026 #include <stdint.h> 00027 #include "ns3/ipv4-address.h" 00028 #include "ns3/ipv4-header.h" 00029 #include "ns3/ptr.h" 00030 #include "ns3/ipv4.h" 00031 00032 namespace ns3 { 00033 00034 class Packet; 00035 class NetDevice; 00036 class Ipv4Interface; 00037 class Ipv4Address; 00038 class Ipv4Header; 00039 class Ipv4Route; 00040 class Node; 00041 00042 00043 /** 00044 * @brief Static routing protocol for IP version 4 stacks. 00045 * 00046 * In ns-3 we have the concept of a pluggable routing protocol. Routing 00047 * protocols are added to a list maintained by the Ipv4L3Protocol. Every 00048 * stack gets one routing protocol for free -- the Ipv4StaticRouting routing 00049 * protocol is added in the constructor of the Ipv4L3Protocol (this is the 00050 * piece of code that implements the functionality of the IP layer). 00051 * 00052 * The Ipv4StaticRouting class inherits from the abstract base class 00053 * Ipv4RoutingProtocol that defines the interface methods that a routing 00054 * protocol must support. 00055 * 00056 * When a packet arrives in the Ipv4L3Protocol for transmission, it comes 00057 * either from a local source via Ipv4L3Protocol::Send or from a remote 00058 * source via Ipv4L3Protocol::Forwarding. In both cases, a function is called 00059 * (Ipv4L3Protocol::Lookup) to look up the routing information for the packet. 00060 * 00061 * The lookup function iterates through the list of routing protocols asking 00062 * each to see if it can find a route and send the packet. A callback is 00063 * provided during each of these calls that should be considered a pre- 00064 * packaged send call. This is done to allow asynchronous calls into 00065 * routing subsystems in order to support on-demand routing, for example. The 00066 * method for requesting this operation is Ipv4StaticRouting::RequestRoute for 00067 * the static routing protocol. 00068 * 00069 * Each routing protocol is also free to implement its own methods for managing 00070 * routes which you will find below. This class manages a set of "static" or 00071 * manually configured routes for host, network and multicast routes. 00072 * 00073 * @see Ipv4RoutingProtocol 00074 * @see Ipv4L3Protocol::AddRoutingProtocol 00075 * @see Ipv4L3Protocol::Ipv4L3Protocol 00076 */ 00077 class Ipv4StaticRouting : public Ipv4RoutingProtocol 00078 { 00079 public: 00080 /** 00081 * @brief Construct an empty Ipv4StaticRouting routing protocol, 00082 * @internal 00083 * 00084 * The Ipv4StaticRouting class supports host, network and multicast routes. 00085 * This method initializes the lists containing these routes to empty. 00086 * 00087 * @see Ipv4StaticRouting 00088 */ 00089 Ipv4StaticRouting (); 00090 00091 /** 00092 * @brief Request that a check for a route bw performed and if a route is found 00093 * that the packet be sent on its way using the pre-packaged send callback. 00094 * 00095 * The source and destination IP addresses for the packet in question are found 00096 * in the provided Ipv4Header. There are two major processing forks depending 00097 * on the type of destination address. 00098 * 00099 * If the destination address is unicast then the routing table is consulted 00100 * for a route to the destination and if it is found, the routeReply callback 00101 * is executed to send the packet (with the found route). 00102 * 00103 * If the destination address is a multicast, then the exact processing steps 00104 * depend on whether or not the packet has been sourced locally. This is 00105 * determined by the parameter ifIndex. This is the interface index over which 00106 * this packet was received. If the packet has not been received over a 00107 * network interface, this index will be set to 00108 * Ipv4RoutingProtocol::IF_INDEX_ANY (a very large number). In that case, 00109 * we want to avoid the requirement that an explicit route out of each node 00110 * must be set, so we don't do anything here. 00111 * 00112 * If the packet is a multicast destination and has been received over a 00113 * network interface, a call to this method implies that the packet is being 00114 * forwarded. In that case, there must be an explicit route out of the node. 00115 * A multicast route references the source address, the destination address 00116 * (the multicast group) and the input interface in order to find a route. 00117 * We consult the multicast routing table and, if a route is found, send the 00118 * packet out of as many interfaces as required using the provided callback 00119 * (think of it as a pre-packaged send call). 00120 * 00121 * @param ifIndex The network interface index over which the packed was 00122 * received. If the packet is from a local source, ifIndex will be set to 00123 * Ipv4RoutingProtocol::IF_INDEX_ANY. 00124 * @param ipHeader the Ipv4Header containing the source and destination IP 00125 * addresses for the packet. 00126 * @param packet The packet to be sent if a route is found. 00127 * @param routeReply A callback that packaged up the call to actually send the 00128 * packet. 00129 * @return Returns true if a route is found and the packet has been sent, 00130 * otherwise returns false indicating that the next routing protocol should 00131 * be consulted. In practice, the static routing protocol is the last chance 00132 * protocol. 00133 * 00134 * @see Ipv4StaticRouting 00135 * @see Ipv4RoutingProtocol 00136 */ 00137 virtual bool RequestRoute (uint32_t ifIndex, 00138 Ipv4Header const &ipHeader, 00139 Ptr<Packet> packet, 00140 RouteReplyCallback routeReply); 00141 00142 /** 00143 * @brief Check to see if we can determine the interface index that will be 00144 * used if a packet is sent to this destination. 00145 * 00146 * This method addresses a problem in the IP stack where a destination address 00147 * must be present and checksummed into the IP header before the actual 00148 * interface over which the packet is sent can be determined. The answer is 00149 * to implement a known and intentional cross-layer violation. This is the 00150 * endpoint of a call chain that started up quite high in the stack (sockets) 00151 * and has found its way down to the Ipv4L3Protocol which is consulting the 00152 * routing protocols for what they would do if presented with a packet of the 00153 * given destination. 00154 * 00155 * Note that the a single interface index is returned. This means that if 00156 * the destination address is a multicast, and an explicit route is present 00157 * that includeds multiple output interfaces, that route cannot be used. 00158 * 00159 * If there are multiple paths out of the node, the resolution is performed 00160 * by Ipv4L3Protocol::GetIfIndexforDestination which has access to more 00161 * contextual information that is useful for making a determination. 00162 * 00163 * @param destination The Ipv4Address if the destination of a hypothetical 00164 * packet. This may be a multicast group address. 00165 * @param ifIndex A reference to the interface index over which a packet 00166 * sent to this destination would be sent. 00167 * @return Returns true if a route is found to the destination that involves 00168 * a single output interface index, otherwise returns false indicating that 00169 * the next routing protocol should be consulted. In practice, the static 00170 * routing protocol is the last chance protocol. 00171 * 00172 * @see Ipv4StaticRouting 00173 * @see Ipv4RoutingProtocol 00174 * @see Ipv4L3Protocol 00175 */ 00176 virtual bool RequestIfIndex (Ipv4Address destination, uint32_t& ifIndex); 00177 00178 /** 00179 * @brief Add a host route to the static routing table. 00180 * 00181 * @param dest The Ipv4Address destination for this route. 00182 * @param nextHop The Ipv4Address of the next hop in the route. 00183 * @param interface The network interface index used to send packets to the 00184 * destination. 00185 * 00186 * @see Ipv4Address 00187 */ 00188 void AddHostRouteTo (Ipv4Address dest, 00189 Ipv4Address nextHop, 00190 uint32_t interface); 00191 /** 00192 * @brief Add a host route to the static routing table. 00193 * 00194 * @param dest The Ipv4Address destination for this route. 00195 * @param interface The network interface index used to send packets to the 00196 * destination. 00197 * 00198 * @see Ipv4Address 00199 */ 00200 void AddHostRouteTo (Ipv4Address dest, 00201 uint32_t interface); 00202 00203 /** 00204 * @brief Add a network route to the static routing table. 00205 * 00206 * @param network The Ipv4Address network for this route. 00207 * @param networkMask The Ipv4Mask to extract the network. 00208 * @param nextHop The next hop in the route to the destination network. 00209 * @param interface The network interface index used to send packets to the 00210 * destination. 00211 * 00212 * @see Ipv4Address 00213 */ 00214 void AddNetworkRouteTo (Ipv4Address network, 00215 Ipv4Mask networkMask, 00216 Ipv4Address nextHop, 00217 uint32_t interface); 00218 00219 /** 00220 * @brief Add a network route to the static routing table. 00221 * 00222 * @param network The Ipv4Address network for this route. 00223 * @param networkMask The Ipv4Mask to extract the network. 00224 * @param interface The network interface index used to send packets to the 00225 * destination. 00226 * 00227 * @see Ipv4Address 00228 */ 00229 void AddNetworkRouteTo (Ipv4Address network, 00230 Ipv4Mask networkMask, 00231 uint32_t interface); 00232 00233 /** 00234 * @brief Add a default route to the static routing table. 00235 * 00236 * This method tells the routing system what to do in the case where a specific 00237 * route to a destination is not found. The system forwards packets to the 00238 * specified node in the hope that it knows better how to route the packet. 00239 * 00240 * If the default route is set, it is returned as the selected route from 00241 * LookupStatic irrespective of destination address if no specific route is 00242 * found. 00243 * 00244 * @param nextHop The Ipv4Address to send packets to in the hope that they 00245 * will be forwarded correctly. 00246 * @param interface The network interface index used to send packets. 00247 * 00248 * @see Ipv4Address 00249 * @see Ipv4StaticRouting::Lookup 00250 */ 00251 void SetDefaultRoute (Ipv4Address nextHop, 00252 uint32_t interface); 00253 00254 /** 00255 * @brief Get the number of individual unicast routes that have been added 00256 * to the routing table. 00257 * 00258 * @warning The default route counts as one of the routes. 00259 */ 00260 uint32_t GetNRoutes (void); 00261 00262 /** 00263 * @brief Get the default route from the static routing table. 00264 * 00265 * @return If the default route is set, a pointer to that Ipv4Route is 00266 * returned, otherwise a zero pointer is returned. 00267 * 00268 * @see Ipv4Route 00269 */ 00270 Ipv4Route *GetDefaultRoute (void); 00271 00272 /** 00273 * @brief Get a route from the static unicast routing table. 00274 * 00275 * Externally, the unicast static routing table appears simply as a table with 00276 * n entries. The one sublety of note is that if a default route has been set 00277 * it will appear as the zeroth entry in the table. This means that if you 00278 * add only a default route, the table will have one entry that can be accessed 00279 * either by explicity calling GetDefaultRoute () or by calling GetRoute (0). 00280 * 00281 * Similarly, if the default route has been set, calling RemoveRoute (0) will 00282 * remove the default route. 00283 * 00284 * @param i The index (into the routing table) of the route to retrieve. If 00285 * the default route has been set, it will occupy index zero. 00286 * @return If route is set, a pointer to that Ipv4Route is returned, otherwise 00287 * a zero pointer is returned. 00288 * 00289 * @see Ipv4Route 00290 * @see Ipv4StaticRouting::RemoveRoute 00291 */ 00292 Ipv4Route *GetRoute (uint32_t i); 00293 00294 /** 00295 * @brief Remove a route from the static unicast routing table. 00296 * 00297 * Externally, the unicast static routing table appears simply as a table with 00298 * n entries. The one sublety of note is that if a default route has been set 00299 * it will appear as the zeroth entry in the table. This means that if the 00300 * default route has been set, calling RemoveRoute (0) will remove the 00301 * default route. 00302 * 00303 * @param i The index (into the routing table) of the route to remove. If 00304 * the default route has been set, it will occupy index zero. 00305 * 00306 * @see Ipv4Route 00307 * @see Ipv4StaticRouting::GetRoute 00308 * @see Ipv4StaticRouting::AddRoute 00309 */ 00310 void RemoveRoute (uint32_t i); 00311 00312 /** 00313 * @brief Add a multicast route to the static routing table. 00314 * 00315 * A multicast route must specify an origin IP address, a multicast group and 00316 * an input network interface index as conditions and provide a vector of 00317 * output network interface indices over which packets matching the conditions 00318 * are sent. 00319 * 00320 * Typically there are two main types of multicast routes: routes of the 00321 * first kind are used during forwarding. All of the conditions must be 00322 * exlicitly provided. The second kind of routes are used to get packets off 00323 * of a local node. The difference is in the input interface. Routes for 00324 * forwarding will always have an explicit input interface specified. Routes 00325 * off of a node will always set the input interface to a wildcard specified 00326 * by the index Ipv4RoutingProtocol::IF_INDEX_ANY. 00327 * 00328 * For routes off of a local node wildcards may be used in the origin and 00329 * multicast group addresses. The wildcard used for Ipv4Adresses is that 00330 * address returned by Ipv4Address::GetAny () -- typically "0.0.0.0". Usage 00331 * of a wildcard allows one to specify default behavior to varying degrees. 00332 * 00333 * For example, making the origin address a wildcard, but leaving the 00334 * multicast group specific allows one (in the case of a node with multiple 00335 * interfaces) to create different routes using different output interfaces 00336 * for each multicast group. 00337 * 00338 * If the origin and multicast addresses are made wildcards, you have created 00339 * essentially a default multicast address that can forward to multiple 00340 * interfaces. Compare this to the actual default multicast address that is 00341 * limited to specifying a single output interface for compatibility with 00342 * existing functionality in other systems. 00343 * 00344 * @param origin The Ipv4Address of the origin of packets for this route. May 00345 * be Ipv4Address:GetAny for open groups. 00346 * @param group The Ipv4Address of the multicast group or this route. 00347 * @param inputInterface The input network interface index over which to 00348 * expect packets destined for this route. May be 00349 * Ipv4RoutingProtocol::IF_INDEX_ANY for packets of local origin. 00350 * @param outputInterfaces A vector of network interface indices used to specify 00351 * how to send packets to the destination(s). 00352 * 00353 * @see Ipv4Address 00354 */ 00355 void AddMulticastRoute (Ipv4Address origin, 00356 Ipv4Address group, 00357 uint32_t inputInterface, 00358 std::vector<uint32_t> outputInterfaces); 00359 00360 /** 00361 * @brief Add a default multicast route to the static routing table. 00362 * 00363 * This is the multicast equivalent of the unicast version SetDefaultRoute. 00364 * We tell the routing system what to do in the case where a specific route 00365 * to a destination multicast group is not found. The system forwards 00366 * packets out the specified interface in the hope that "something out there" 00367 * knows better how to route the packet. This method is only used in 00368 * initially sending packets off of a host. The default multicast route is 00369 * not consulted during forwarding -- exact routes must be specified using 00370 * AddMulticastRoute for that case. 00371 * 00372 * Since we're basically sending packets to some entity we think may know 00373 * better what to do, we don't pay attention to "subtleties" like origin 00374 * address, nor do we worry about forwarding out multiple interfaces. If the 00375 * default multicast route is set, it is returned as the selected route from 00376 * LookupStatic irrespective of origin or multicast group if another specific 00377 * route is not found. 00378 * 00379 * @param outputInterface The network interface index used to specify where 00380 * to send packets in the case of unknown routes. 00381 * 00382 * @see Ipv4Address 00383 */ 00384 void SetDefaultMulticastRoute (uint32_t outputInterface); 00385 00386 /** 00387 * @brief Get the number of individual multicast routes that have been added 00388 * to the routing table. 00389 * 00390 * @warning The default multicast route counts as one of the routes. 00391 */ 00392 uint32_t GetNMulticastRoutes (void) const; 00393 00394 /** 00395 * @brief Get a route from the static multicast routing table. 00396 * 00397 * Externally, the multicast static routing table appears simply as a table 00398 * with n entries. The one sublety of note is that if a default route has 00399 * been set it will appear as the zeroth entry in the table. This means that 00400 * if you add only a default route, the table will have one entry that can be 00401 * accessed either by explicity calling GetDefaultMulticastRoute () or by 00402 * calling GetMulticastRoute (0). 00403 * 00404 * Similarly, if the default route has been set, calling 00405 * RemoveMulticastRoute (0) will remove the default route. 00406 * 00407 * @param i The index (into the routing table) of the multicast route to 00408 * retrieve. If the default route has been set, it will occupy index zero. 00409 * @return If route \e i is set, a pointer to that Ipv4MulticastRoute is 00410 * returned, otherwise a zero pointer is returned. 00411 * 00412 * @see Ipv4MulticastRoute 00413 * @see Ipv4StaticRouting::RemoveRoute 00414 */ 00415 Ipv4MulticastRoute *GetMulticastRoute (uint32_t i) const; 00416 00417 /** 00418 * @brief Get the default multicast route from the static routing table. 00419 * 00420 * @return If the default route is set, a pointer to that Ipv4MulticastRoute is 00421 * returned, otherwise a zero pointer is returned. 00422 * 00423 * @see Ipv4Route 00424 */ 00425 Ipv4MulticastRoute *GetDefaultMulticastRoute (void) const; 00426 00427 /** 00428 * @brief Remove a route from the static multicast routing table. 00429 * 00430 * Externally, the multicast static routing table appears simply as a table 00431 * with n entries. The one sublety of note is that if a default multicast 00432 * route has been set it will appear as the zeroth entry in the table. This 00433 * means that the default route may be removed by calling this method with 00434 * appropriate wildcard parameters. 00435 * 00436 * This method causes the multicast routing table to be searched for the first 00437 * route that matches the parameters and removes it. 00438 * 00439 * Wildcards may be provided to this function, but the wildcards are used to 00440 * exacly match wildcards in the routes (see AddMulticastRoute). That is, 00441 * calling RemoveMulticastRoute with the origin set to "0.0.0.0" will not 00442 * remove routes with any address in the origin, but will only remove routes 00443 * with "0.0.0.0" set as the the origin. 00444 * 00445 * @param origin The IP address specified as the origin of packets for the 00446 * route. 00447 * @param group The IP address specified as the multicast group addres of 00448 * the route. 00449 * @param inputInterface The network interface index specified as the expected 00450 * input interface for the route. 00451 * @returns true if a route was found and removed, false otherwise. 00452 * 00453 * @see Ipv4MulticastRoute 00454 * @see Ipv4StaticRouting::AddMulticastRoute 00455 */ 00456 bool RemoveMulticastRoute (Ipv4Address origin, 00457 Ipv4Address group, 00458 uint32_t inputInterface); 00459 00460 /** 00461 * @brief Remove a route from the static multicast routing table. 00462 * 00463 * Externally, the multicast static routing table appears simply as a table 00464 * with n entries. The one sublety of note is that if a default multicast 00465 * route has been set it will appear as the zeroth entry in the table. This 00466 * means that if the default route has been set, calling 00467 * RemoveMulticastRoute (0) will remove the default route. 00468 * 00469 * @param index The index (into the multicast routing table) of the route to 00470 * remove. If the default route has been set, it will occupy index zero. 00471 * 00472 * @see Ipv4Route 00473 * @see Ipv4StaticRouting::GetRoute 00474 * @see Ipv4StaticRouting::AddRoute 00475 */ 00476 void RemoveMulticastRoute (uint32_t index); 00477 00478 protected: 00479 void DoDispose (void); 00480 00481 private: 00482 typedef std::list<Ipv4Route *> HostRoutes; 00483 typedef std::list<Ipv4Route *>::const_iterator HostRoutesCI; 00484 typedef std::list<Ipv4Route *>::iterator HostRoutesI; 00485 typedef std::list<Ipv4Route *> NetworkRoutes; 00486 typedef std::list<Ipv4Route *>::const_iterator NetworkRoutesCI; 00487 typedef std::list<Ipv4Route *>::iterator NetworkRoutesI; 00488 00489 typedef std::list<Ipv4MulticastRoute *> MulticastRoutes; 00490 typedef std::list<Ipv4MulticastRoute *>::const_iterator MulticastRoutesCI; 00491 typedef std::list<Ipv4MulticastRoute *>::iterator MulticastRoutesI; 00492 00493 Ipv4Route *LookupStatic (Ipv4Address dest); 00494 Ipv4MulticastRoute *LookupStatic (Ipv4Address origin, Ipv4Address group, 00495 uint32_t ifIndex); 00496 00497 HostRoutes m_hostRoutes; 00498 NetworkRoutes m_networkRoutes; 00499 Ipv4Route *m_defaultRoute; 00500 Ipv4MulticastRoute *m_defaultMulticastRoute; 00501 MulticastRoutes m_multicastRoutes; 00502 }; 00503 00504 } // Namespace ns3 00505 00506 #endif /* IPV4_STATIC_ROUTING_H */