00001 /* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */ 00002 /* 00003 * Copyright (c) 2007 INRIA 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: Mathieu Lacage <mathieu.lacage@sophia.inria.fr> 00019 */ 00020 #ifndef IPV4_H 00021 #define IPV4_H 00022 00023 #include <stdint.h> 00024 #include "ns3/ipv4-address.h" 00025 #include "ns3/object.h" 00026 #include "ns3/callback.h" 00027 #include "ipv4-route.h" 00028 00029 namespace ns3 { 00030 00031 class Node; 00032 class NetDevice; 00033 class Packet; 00034 class Ipv4Route; 00035 class Ipv4Header; 00036 00037 /** 00038 * \ingroup node 00039 * \defgroup ipv4 Ipv4 00040 */ 00041 00042 /** 00043 * \ingroup ipv4 00044 * 00045 * \brief Base class for IPv4 routing protocols. 00046 * 00047 * This class represents the interface between the IPv4 routing core 00048 * and a specific IPv4 routing protocol. The interface is 00049 * asynchronous (callback based) in order to support reactive routing 00050 * protocols (e.g. AODV). 00051 */ 00052 class Ipv4RoutingProtocol : public Object 00053 { 00054 public: 00055 // void (*RouteReply) (bool found, Ipv4Route route, Packet packet, Ipv4Header const &ipHeader); 00056 00057 00058 /** 00059 * \brief Callback to be invoked when route discovery is completed 00060 * 00061 * \param bool flag indicating whether a route was actually found; 00062 * when this is false, the Ipv4Route parameter is ignored 00063 * 00064 * \param Ipv4Route the route found 00065 * 00066 * \param Packet the packet for which a route was requested; can be 00067 * modified by the routing protocol 00068 * 00069 * \param Ipv4Header the IP header supplied to the route request 00070 * method (possibly modified in case a new routing header is 00071 * inserted and consequently the protocol type has to change). 00072 * 00073 */ 00074 typedef Callback<void, bool, const Ipv4Route&, Ptr<Packet>, const Ipv4Header&> RouteReplyCallback; 00075 00076 /** 00077 * \brief Request that a packet be routed. 00078 * 00079 * \param ifIndex The interface index on which the packet was received. 00080 * \param ipHeader IP header of the packet 00081 * \param packet packet that is being sent or forwarded 00082 * \param routeReply callback that will receive the route reply 00083 * 00084 * \returns true if the routing protocol should be able to get the 00085 * route, false otherwise. 00086 * 00087 * This method is called whenever a node's IPv4 forwarding engine 00088 * needs to lookup a route for a given packet and IP header. 00089 * 00090 * The routing protocol implementation may determine immediately it 00091 * should not be handling this particular the route request. For 00092 * instance, a routing protocol may decline to search for routes for 00093 * certain classes of addresses, like link-local. In this case, 00094 * RequestRoute() should return false and the routeReply callback 00095 * must not be invoked. 00096 * 00097 * If the routing protocol implementation assumes that it can provide 00098 * the requested route, then it should return true, and the 00099 * routeReply callback must be invoked, either immediately before 00100 * returning true (synchronously), or in the future (asynchronous). 00101 * The routing protocol may use any information available in the IP 00102 * header and packet as routing key, although most routing protocols 00103 * use only the destination address (as given by 00104 * ipHeader.GetDestination ()). The routing protocol is also 00105 * allowed to add a new header to the packet, which will appear 00106 * immediately after the IP header, although most routing do not 00107 * insert any extra header. 00108 * 00109 * Multicast routing is expected to be supported in this method. If a 00110 * multicast route is encountered, all routes to a given multicast 00111 * destination will be serviced by cloning the packet and calling the 00112 * route reply callback once for each outgoing interface in the route. 00113 */ 00114 virtual bool RequestRoute (uint32_t ifIndex, 00115 const Ipv4Header &ipHeader, 00116 Ptr<Packet> packet, 00117 RouteReplyCallback routeReply) = 0; 00118 00119 /** 00120 * \brief Synchronously check to see if we can determine the interface index 00121 * that will be used if a packet is sent to this destination. 00122 * 00123 * This method addresses a problem in the IP stack where a destination address 00124 * must be present and checksummed into the IP header before the actual 00125 * interface over which the packet is sent can be determined. The answer is 00126 * to implement a known and intentional cross-layer violation. This is the 00127 * endpoint of a call chain that started up quite high in the stack (sockets) 00128 * and has found its way down to the Ipv4L3Protocol which is consulting the 00129 * routing protocols for what they would do if presented with a packet of the 00130 * given destination. 00131 * 00132 * Note that the a single interface index is returned. This means that if 00133 * the destination address is a multicast, and an explicit route is present 00134 * that includeds multiple output interfaces, that route cannot be used. 00135 * 00136 * If there are multiple paths out of the node, the resolution is performed 00137 * by Ipv4L3Protocol::GetIfIndexforDestination which has access to more 00138 * contextual information that is useful for making a determination. 00139 * 00140 * \param destination The Ipv4Address if the destination of a hypothetical 00141 * packet. This may be a multicast group address. 00142 * \param ifIndex A reference to the interface index over which a packet 00143 * sent to this destination would be sent. 00144 * \return Returns true if a route is found to the destination that involves 00145 * a single output interface index, otherwise false. 00146 * 00147 * \see Ipv4StaticRouting 00148 * \see Ipv4RoutingProtocol 00149 * \see Ipv4L3Protocol 00150 */ 00151 virtual bool RequestIfIndex (Ipv4Address destination, 00152 uint32_t& ifIndex) = 0; 00153 00154 static const uint32_t IF_INDEX_ANY = 0xffffffff; 00155 }; 00156 00157 /** 00158 * \brief Access to the Ipv4 forwarding table and to the ipv4 interfaces 00159 * 00160 * This class allows you to create ipv4 interfaces based on a NetDevice. 00161 * Multiple interfaces can be created for a single NetDevice, hence 00162 * achieving multihoming. 00163 * 00164 * This class also allows you to control the content of the ipv4 00165 * forwarding table. 00166 */ 00167 class Ipv4 : public Object 00168 { 00169 public: 00170 static TypeId GetTypeId (void); 00171 Ipv4 (); 00172 virtual ~Ipv4 (); 00173 00174 /** 00175 * \brief Register a new routing protocol to be used in this IPv4 stack 00176 * 00177 * \param routingProtocol new routing protocol implementation object 00178 * \param priority priority to give to this routing protocol. 00179 * Values may range between -32768 and +32767. The priority 0 00180 * corresponds to static routing table lookups, higher values have 00181 * more priority. The order by which routing protocols with the 00182 * same priority value are consulted is undefined. 00183 */ 00184 virtual void AddRoutingProtocol (Ptr<Ipv4RoutingProtocol> routingProtocol, 00185 int16_t priority) = 0; 00186 00187 /** 00188 * \param dest destination address 00189 * \param nextHop address of next hop. 00190 * \param interface interface of next hop. 00191 * 00192 * Add route to host dest through host nextHop 00193 * on interface. 00194 */ 00195 virtual void AddHostRouteTo (Ipv4Address dest, 00196 Ipv4Address nextHop, 00197 uint32_t interface) = 0; 00198 /** 00199 * \param dest destination address 00200 * \param interface of next hop 00201 * 00202 * add route to host dest on interface. 00203 */ 00204 virtual void AddHostRouteTo (Ipv4Address dest, 00205 uint32_t interface) = 0; 00206 00207 /** 00208 * \param network destination network 00209 * \param networkMask netmask of destination network 00210 * \param nextHop address of next hop 00211 * \param interface interface of next hop 00212 * 00213 * add route to network dest with netmask 00214 * through host nextHop on interface 00215 */ 00216 virtual void AddNetworkRouteTo (Ipv4Address network, 00217 Ipv4Mask networkMask, 00218 Ipv4Address nextHop, 00219 uint32_t interface) = 0; 00220 00221 /** 00222 * \param network destination network 00223 * \param networkMask netmask of destination network 00224 * \param interface interface of next hop 00225 * 00226 * add route to network dest with netmask 00227 * on interface 00228 */ 00229 virtual void AddNetworkRouteTo (Ipv4Address network, 00230 Ipv4Mask networkMask, 00231 uint32_t interface) = 0; 00232 /** 00233 * \param nextHop address of default next hop 00234 * \param interface interface of default next hop. 00235 * 00236 * set the default route to host nextHop on 00237 * interface. 00238 */ 00239 virtual void SetDefaultRoute (Ipv4Address nextHop, 00240 uint32_t interface) = 0; 00241 00242 /** 00243 * \returns the number of entries in the routing table. 00244 */ 00245 virtual uint32_t GetNRoutes (void) = 0; 00246 00247 /** 00248 * \param i index of route to return 00249 * \returns the route whose index is i 00250 */ 00251 virtual Ipv4Route GetRoute (uint32_t i) = 0; 00252 00253 /** 00254 * \param i index of route to remove from routing table. 00255 */ 00256 virtual void RemoveRoute (uint32_t i) = 0; 00257 00258 /** 00259 * \brief Add a static multicast route for a given multicast source and 00260 * group. 00261 * 00262 * \param origin The Ipv4 address of the multicast source. 00263 * \param group The multicast group address. 00264 * \param inputInterface The interface index over which the packet arrived. 00265 * \param outputInterfaces The list of output interface indices over which 00266 * the packet should be sent (excluding the inputInterface). 00267 */ 00268 virtual void AddMulticastRoute (Ipv4Address origin, 00269 Ipv4Address group, 00270 uint32_t inputInterface, 00271 std::vector<uint32_t> outputInterfaces) = 0; 00272 /** 00273 * \brief Remove a static multicast route for a given multicast source and 00274 * group. 00275 * 00276 * \param origin The Ipv4 address of the multicast source. 00277 * \param group The multicast group address. 00278 * \param inputInterface The interface index over which the packet arrived. 00279 */ 00280 virtual void RemoveMulticastRoute (Ipv4Address origin, 00281 Ipv4Address group, 00282 uint32_t inputInterface) = 0; 00283 00284 /** 00285 * \brief Set the default static multicast route. 00286 * 00287 * \param outputInterface The network output interface index over which 00288 * packets without specific routes should be sent. 00289 */ 00290 virtual void SetDefaultMulticastRoute (uint32_t outputInterface) = 0; 00291 00292 /** 00293 * \returns the number of entries in the multicast routing table. 00294 */ 00295 virtual uint32_t GetNMulticastRoutes (void) const = 0; 00296 00297 /** 00298 * \param i index of route to return 00299 * \returns the route whose index is i 00300 */ 00301 virtual Ipv4MulticastRoute GetMulticastRoute (uint32_t i) const = 0; 00302 00303 /** 00304 * \param i index of route to remove from routing table. 00305 */ 00306 virtual void RemoveMulticastRoute (uint32_t i) = 0; 00307 00308 /** 00309 * \param device device to add to the list of ipv4 interfaces 00310 * which can be used as output interfaces during packet forwarding. 00311 * \returns the index of the ipv4 interface added. 00312 * 00313 * Once a device has been added, it can never be removed: if you want 00314 * to disable it, you can invoke Ipv4::SetDown which will 00315 * make sure that it is never used during packet forwarding. 00316 */ 00317 virtual uint32_t AddInterface (Ptr<NetDevice> device) = 0; 00318 00319 /** 00320 * \returns the number of interfaces added by the user. 00321 */ 00322 virtual uint32_t GetNInterfaces (void) = 0; 00323 00324 /** 00325 * \brief Find and return the interface ID of the interface that has been 00326 * assigned the specified IP address. 00327 * \param addr The IP address assigned to the interface of interest. 00328 * \returns The index of the ipv4 interface with the given address. 00329 * 00330 * Each IP interface has an IP address associated with it. It is often 00331 * useful to search the list of interfaces for one that corresponds to 00332 * a known IP Address. This call takes an IP address as a parameter and 00333 * returns the interface index of the first interface that has been assigned 00334 * that address. If the address is not found, this function asserts. 00335 */ 00336 virtual uint32_t FindInterfaceForAddr (Ipv4Address addr) const = 0; 00337 00338 /** 00339 * \brief Find and return the interface ID of the interface that has been 00340 * assigned the specified (masked) IP address. 00341 * \param addr The IP address assigned to the interface of interest. 00342 * \param mask The address mask to be used in address matching. 00343 * \returns The index of the ipv4 interface with the given address. 00344 * 00345 * Each IP interface has an IP address associated with it. It is often 00346 * useful to search the list of interfaces for one that corresponds to 00347 * a known IP Address. This call takes an IP address and an IP address 00348 * mask as parameters and returns the interface index of the first interface 00349 * that matches the masked IP address. 00350 */ 00351 virtual uint32_t FindInterfaceForAddr (Ipv4Address addr, 00352 Ipv4Mask mask) const = 0; 00353 00354 /** 00355 * \brief Find and return the interface ID of the interface that has been 00356 * associated with the specified (masked) NetDevice 00357 * \param nd The net device of the interface of interest. 00358 * \returns The index of the ipv4 interface associated with the given net 00359 * device or -1 if not found. 00360 * 00361 * Each IP interface is associated with a net device. It is often 00362 * useful to search the list of interfaces for one that corresponds to 00363 * a known net device. This call takes an smart pointer to a net device 00364 * and returns the interface index of the first interface that matches the 00365 * net device. 00366 */ 00367 virtual int32_t FindInterfaceForDevice(Ptr<NetDevice> nd) const = 0; 00368 00369 /** 00370 * \param i index of ipv4 interface 00371 * \returns the NetDevice associated with the ipv4 interface index 00372 */ 00373 virtual Ptr<NetDevice> GetNetDevice (uint32_t i) = 0; 00374 00375 /** 00376 * \brief Join a multicast group for a given multicast source and 00377 * group. 00378 * 00379 * \param origin The Ipv4 address of the multicast source. 00380 * \param group The multicast group address. 00381 */ 00382 virtual void JoinMulticastGroup (Ipv4Address origin, Ipv4Address group) = 0; 00383 00384 /** 00385 * \brief Leave a multicast group for a given multicast source and 00386 * group. 00387 * 00388 * \param origin The Ipv4 address of the multicast source. 00389 * \param group The multicast group address. 00390 */ 00391 virtual void LeaveMulticastGroup (Ipv4Address origin, Ipv4Address group) = 0; 00392 00393 /** 00394 * \param i index of ipv4 interface 00395 * \param address address to associate to the underlying ipv4 interface 00396 */ 00397 virtual void SetAddress (uint32_t i, Ipv4Address address) = 0; 00398 00399 /** 00400 * \param i index of ipv4 interface 00401 * \param mask mask to associate to the underlying ipv4 interface 00402 */ 00403 virtual void SetNetworkMask (uint32_t i, Ipv4Mask mask) = 0; 00404 00405 /** 00406 * \param i index of ipv4 interface 00407 * \returns the mask associated to the underlying ipv4 interface 00408 */ 00409 virtual Ipv4Mask GetNetworkMask (uint32_t i) const = 0; 00410 00411 /** 00412 * \param i index of ipv4 interface 00413 * \param metric routing metric (cost) associated to the underlying 00414 * ipv4 interface 00415 */ 00416 virtual void SetMetric (uint32_t i, uint16_t metric) = 0; 00417 00418 /** 00419 * \param i index of ipv4 interface 00420 * \returns routing metric (cost) associated to the underlying 00421 * ipv4 interface 00422 */ 00423 virtual uint16_t GetMetric (uint32_t i) const = 0; 00424 00425 /** 00426 * \param i index of ipv4 interface 00427 * \returns the address associated to the underlying ipv4 interface 00428 * 00429 * Note that the broadcast address for this interface may be fetched 00430 * from the Ipv4Address object returned here using 00431 * Ipv4Address::GetSubnetDirectedBroadcast(mask), where the mask for 00432 * the interface may be retrived using Ipv4::GetNetworkMask(i). 00433 */ 00434 virtual Ipv4Address GetAddress (uint32_t i) const = 0; 00435 00436 /** 00437 * \param destination The IP address of a hypothetical destination. 00438 * \returns The IP address assigned to the interface that will be used 00439 * if we were to send a packet to destination. 00440 * 00441 * Note that the broadcast address for this interface may be fetched 00442 * from the Ipv4Address object returned here using 00443 * Ipv4Address::GetSubnetDirectedBroadcast(mask), where the mask for 00444 * the interface may be retrived using Ipv4::GetNetworkMask(i). 00445 */ 00446 virtual Ipv4Address GetSourceAddress (Ipv4Address destination) const = 0; 00447 00448 /** 00449 * \param dest The IP address of a hypothetical destination. 00450 * \param ifIndex filled in with the interface index that will be used to 00451 * send a packet to the hypothetical destination. 00452 * \returns true if a single interface can be identified, false otherwise. 00453 */ 00454 virtual bool GetIfIndexForDestination (Ipv4Address dest, 00455 uint32_t &ifIndex) const = 0; 00456 00457 /** 00458 * \param i index of ipv4 interface 00459 * \returns the Maximum Transmission Unit (in bytes) associated 00460 * to the underlying ipv4 interface 00461 */ 00462 virtual uint16_t GetMtu (uint32_t i) const = 0; 00463 00464 /** 00465 * \param i index of ipv4 interface 00466 * \returns true if the underlying interface is in the "up" state, 00467 * false otherwise. 00468 */ 00469 virtual bool IsUp (uint32_t i) const = 0; 00470 00471 /** 00472 * \param i index of ipv4 interface 00473 * 00474 * Set the interface into the "up" state. In this state, it is 00475 * considered valid during ipv4 forwarding. 00476 */ 00477 virtual void SetUp (uint32_t i) = 0; 00478 00479 /** 00480 * \param i index of ipv4 interface 00481 * 00482 * Set the interface into the "down" state. In this state, it is 00483 * ignored during ipv4 forwarding. 00484 */ 00485 virtual void SetDown (uint32_t i) = 0; 00486 00487 /** 00488 * \brief Convenience function to return the ifIndex corresponding 00489 * to the Ipv4Address provided 00490 * 00491 * \param addr Ipv4Address 00492 * \param mask corresponding Ipv4Mask 00493 * \returns ifIndex corresponding to a/amask 00494 */ 00495 virtual uint32_t GetIfIndexByAddress (Ipv4Address addr, 00496 Ipv4Mask mask = Ipv4Mask("255.255.255.255")); 00497 }; 00498 00499 } // namespace ns3 00500 00501 #endif /* IPV4_H */