1 /* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */ 2 /* 3 * Copyright (c) 2009 University of Washington 4 * 5 * This program is free software; you can redistribute it and/or modify 6 * it under the terms of the GNU General Public License version 2 as 7 * published by the Free Software Foundation; 8 * 9 * This program is distributed in the hope that it will be useful, 10 * but WITHOUT ANY WARRANTY; without even the implied warranty of 11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 12 * GNU General Public License for more details. 13 * 14 * You should have received a copy of the GNU General Public License 15 * along with this program; if not, write to the Free Software 16 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA 17 */ 18 #ifndef IPV4_ROUTING_PROTOCOL_H 19 #define IPV4_ROUTING_PROTOCOL_H 20 21 #include "ns3/packet.h" 22 #include "ns3/callback.h" 23 #include "ns3/object.h" 24 #include "ns3/socket.h" 25 #include "ipv4-header.h" 26 #include "ns3/ipv4-interface-address.h" 27 #include "ipv4.h" 28 #include "ns3/output-stream-wrapper.h" 29 #include "ns3/nstime.h" 30 31 namespace ns3 { 32 33 class Ipv4MulticastRoute; 34 class Ipv4Route; 35 class NetDevice; 36 37 /** 38 * \ingroup internet 39 * \defgroup ipv4Routing IPv4 Routing Protocols. 40 * 41 * The classes in this group implement different routing protocols 42 * for IPv4. Other modules could implement further protocols 43 * (e.g., AODV, OLSR, etc.). 44 */ 45 46 /** 47 * \ingroup ipv4Routing 48 * \brief Abstract base class for IPv4 routing protocols. 49 * 50 * Defines two virtual functions for packet routing and forwarding. The first, 51 * RouteOutput(), is used for locally originated packets, and the second, 52 * RouteInput(), is used for forwarding and/or delivering received packets. 53 * Also defines the signatures of four callbacks used in RouteInput(). 54 * 55 */ 56 class Ipv4RoutingProtocol : public Object 57 { 58 public: 59 /** 60 * \brief Get the type ID. 61 * \return the object TypeId 62 */ 63 static TypeId GetTypeId (void); 64 65 /// Callback for unicast packets to be forwarded 66 typedef Callback<void, Ptr<Ipv4Route>, Ptr<const Packet>, const Ipv4Header &> UnicastForwardCallback; 67 68 /// Callback for multicast packets to be forwarded 69 typedef Callback<void, Ptr<Ipv4MulticastRoute>, Ptr<const Packet>, const Ipv4Header &> MulticastForwardCallback; 70 71 /// Callback for packets to be locally delivered 72 typedef Callback<void, Ptr<const Packet>, const Ipv4Header &, uint32_t > LocalDeliverCallback; 73 74 /// Callback for routing errors (e.g., no route found) 75 typedef Callback<void, Ptr<const Packet>, const Ipv4Header &, Socket::SocketErrno > ErrorCallback; 76 77 /** 78 * \brief Query routing cache for an existing route, for an outbound packet 79 * 80 * This lookup is used by transport protocols. It does not cause any 81 * packet to be forwarded, and is synchronous. Can be used for 82 * multicast or unicast. The Linux equivalent is ip_route_output() 83 * 84 * The header input parameter may have an uninitialized value 85 * for the source address, but the destination address should always be 86 * properly set by the caller. 87 * 88 * \param p packet to be routed. Note that this method may modify the packet. 89 * Callers may also pass in a null pointer. 90 * \param header input parameter (used to form key to search for the route) 91 * \param oif Output interface Netdevice. May be zero, or may be bound via 92 * socket options to a particular output interface. 93 * \param sockerr Output parameter; socket errno 94 * 95 * \returns a code that indicates what happened in the lookup 96 */ 97 virtual Ptr<Ipv4Route> RouteOutput (Ptr<Packet> p, const Ipv4Header &header, Ptr<NetDevice> oif, Socket::SocketErrno &sockerr) = 0; 98 99 /** 100 * \brief Route an input packet (to be forwarded or locally delivered) 101 * 102 * This lookup is used in the forwarding process. The packet is 103 * handed over to the Ipv4RoutingProtocol, and will get forwarded onward 104 * by one of the callbacks. The Linux equivalent is ip_route_input(). 105 * There are four valid outcomes, and a matching callbacks to handle each. 106 * 107 * \param p received packet 108 * \param header input parameter used to form a search key for a route 109 * \param idev Pointer to ingress network device 110 * \param ucb Callback for the case in which the packet is to be forwarded 111 * as unicast 112 * \param mcb Callback for the case in which the packet is to be forwarded 113 * as multicast 114 * \param lcb Callback for the case in which the packet is to be locally 115 * delivered 116 * \param ecb Callback to call if there is an error in forwarding 117 * \returns true if the Ipv4RoutingProtocol takes responsibility for 118 * forwarding or delivering the packet, false otherwise 119 */ 120 virtual bool RouteInput (Ptr<const Packet> p, const Ipv4Header &header, Ptr<const NetDevice> idev, 121 UnicastForwardCallback ucb, MulticastForwardCallback mcb, 122 LocalDeliverCallback lcb, ErrorCallback ecb) = 0; 123 124 /** 125 * \param interface the index of the interface we are being notified about 126 * 127 * Protocols are expected to implement this method to be notified of the state change of 128 * an interface in a node. 129 */ 130 virtual void NotifyInterfaceUp (uint32_t interface) = 0; 131 /** 132 * \param interface the index of the interface we are being notified about 133 * 134 * Protocols are expected to implement this method to be notified of the state change of 135 * an interface in a node. 136 */ 137 virtual void NotifyInterfaceDown (uint32_t interface) = 0; 138 139 /** 140 * \param interface the index of the interface we are being notified about 141 * \param address a new address being added to an interface 142 * 143 * Protocols are expected to implement this method to be notified whenever 144 * a new address is added to an interface. Typically used to add a 'network route' on an 145 * interface. Can be invoked on an up or down interface. 146 */ 147 virtual void NotifyAddAddress (uint32_t interface, Ipv4InterfaceAddress address) = 0; 148 149 /** 150 * \param interface the index of the interface we are being notified about 151 * \param address a new address being added to an interface 152 * 153 * Protocols are expected to implement this method to be notified whenever 154 * a new address is removed from an interface. Typically used to remove the 'network route' of an 155 * interface. Can be invoked on an up or down interface. 156 */ 157 virtual void NotifyRemoveAddress (uint32_t interface, Ipv4InterfaceAddress address) = 0; 158 159 /** 160 * \param ipv4 the ipv4 object this routing protocol is being associated with 161 * 162 * Typically, invoked directly or indirectly from ns3::Ipv4::SetRoutingProtocol 163 */ 164 virtual void SetIpv4 (Ptr<Ipv4> ipv4) = 0; 165 166 /** 167 * \brief Print the Routing Table entries 168 * 169 * \param stream The ostream the Routing table is printed to 170 * \param unit The time unit to be used in the report 171 */ 172 virtual void PrintRoutingTable (Ptr<OutputStreamWrapper> stream, Time::Unit unit = Time::S) const = 0; 173 174 }; 175 176 } // namespace ns3 177 178 #endif /* IPV4_ROUTING_PROTOCOL_H */ 179