/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
/*
* Copyright (c) 2007 INRIA
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License version 2 as
* published by the Free Software Foundation;
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
*
* Author: Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
*/
#ifndef IPV4_H
#define IPV4_H
#include <stdint.h>
#include "ns3/ipv4-address.h"
#include "ns3/ipv4-interface-address.h"
#include "ns3/object.h"
#include "ns3/callback.h"
#include "ipv4-route.h"
namespace ns3 {
class Node;
class NetDevice;
class Packet;
class Ipv4Route;
class Ipv4Header;
/**
* \ingroup node
* \defgroup ipv4 Ipv4
*/
/**
* \ingroup ipv4
*
* \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);
/**
* \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&, Ptr<Packet>, const Ipv4Header&> RouteReplyCallback;
/**
* \brief Request that a packet be routed.
*
* \param interface The interface index on which the packet was received.
* \param ipHeader IP header of the packet
* \param packet packet that is being sent or forwarded
* \param routeReply callback that will receive the route reply
*
* \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 implementation assumes that 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.
*
* Multicast routing is expected to be supported in this method. If a
* multicast route is encountered, all routes to a given multicast
* destination will be serviced by cloning the packet and calling the
* route reply callback once for each outgoing interface in the route.
*/
virtual bool RequestRoute (uint32_t interface,
const Ipv4Header &ipHeader,
Ptr<Packet> packet,
RouteReplyCallback routeReply) = 0;
/**
* \brief Synchronously 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::GetInterfaceforDestination 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 interface 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 false.
*
* \see Ipv4StaticRouting
* \see Ipv4RoutingProtocol
* \see Ipv4L3Protocol
*/
virtual bool RequestInterface (Ipv4Address destination,
uint32_t& interface) = 0;
static const uint32_t INTERFACE_ANY = 0xffffffff;
};
/**
* \brief Access to the Ipv4 forwarding table and to the ipv4 interfaces
*
* This class allows you to create ipv4 interfaces based on a NetDevice.
* Multiple interfaces can be created for a single NetDevice, hence
* achieving multihoming.
*
* This class also allows you to control the content of the ipv4
* forwarding table.
*/
class Ipv4 : public Object
{
public:
static TypeId GetTypeId (void);
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,
int16_t priority) = 0;
/**
* \param dest destination address
* \param nextHop address of next hop.
* \param interface interface of next hop.
*
* Add route to host dest through host nextHop
* on interface.
*/
virtual void AddHostRouteTo (Ipv4Address dest,
Ipv4Address nextHop,
uint32_t interface) = 0;
/**
* \param dest destination address
* \param interface of next hop
*
* add route to host dest on interface.
*/
virtual void AddHostRouteTo (Ipv4Address dest,
uint32_t interface) = 0;
/**
* \param network destination network
* \param networkMask netmask of destination network
* \param nextHop address of next hop
* \param interface interface of next hop
*
* add route to network dest with netmask
* through host nextHop on interface
*/
virtual void AddNetworkRouteTo (Ipv4Address network,
Ipv4Mask networkMask,
Ipv4Address nextHop,
uint32_t interface) = 0;
/**
* \param network destination network
* \param networkMask netmask of destination network
* \param interface interface of next hop
*
* add route to network dest with netmask
* on interface
*/
virtual void AddNetworkRouteTo (Ipv4Address network,
Ipv4Mask networkMask,
uint32_t interface) = 0;
/**
* \param nextHop address of default next hop
* \param interface interface of default next hop.
*
* set the default route to host nextHop on
* interface.
*/
virtual void SetDefaultRoute (Ipv4Address nextHop,
uint32_t interface) = 0;
/**
* \returns the number of entries in the routing table.
*/
virtual uint32_t GetNRoutes (void) = 0;
/**
* \param i index of route to return
* \returns the route whose index is i
*/
virtual Ipv4Route GetRoute (uint32_t i) = 0;
/**
* \param i index of route to remove from routing table.
*/
virtual void RemoveRoute (uint32_t i) = 0;
/**
* \brief Add a static multicast route for a given multicast source and
* group.
*
* \param origin The Ipv4 address of the multicast source.
* \param group The multicast group address.
* \param inputInterface The interface index over which the packet arrived.
* \param outputInterfaces The list of output interface indices over which
* the packet should be sent (excluding the inputInterface).
*/
virtual void AddMulticastRoute (Ipv4Address origin,
Ipv4Address group,
uint32_t inputInterface,
std::vector<uint32_t> outputInterfaces) = 0;
/**
* \brief Remove a static multicast route for a given multicast source and
* group.
*
* \param origin The Ipv4 address of the multicast source.
* \param group The multicast group address.
* \param inputInterface The interface index over which the packet arrived.
*/
virtual void RemoveMulticastRoute (Ipv4Address origin,
Ipv4Address group,
uint32_t inputInterface) = 0;
/**
* \brief Set the default static multicast route.
*
* \param outputInterface The network output interface index over which
* packets without specific routes should be sent.
*/
virtual void SetDefaultMulticastRoute (uint32_t outputInterface) = 0;
/**
* \returns the number of entries in the multicast routing table.
*/
virtual uint32_t GetNMulticastRoutes (void) const = 0;
/**
* \param i index of route to return
* \returns the route whose index is i
*/
virtual Ipv4MulticastRoute GetMulticastRoute (uint32_t i) const = 0;
/**
* \param i index of route to remove from routing table.
*/
virtual void RemoveMulticastRoute (uint32_t i) = 0;
/**
* \param device device to add to the list of ipv4 interfaces
* which can be used as output interfaces during packet forwarding.
* \returns the index of the ipv4 interface added.
*
* Once a device has been added, it can never be removed: if you want
* to disable it, you can invoke Ipv4::SetDown which will
* make sure that it is never used during packet forwarding.
*/
virtual uint32_t AddInterface (Ptr<NetDevice> device) = 0;
/**
* \returns the number of interfaces added by the user.
*/
virtual uint32_t GetNInterfaces (void) const = 0;
/**
* \brief Find and return the interface ID of the interface that has been
* assigned the specified IP address.
* \param addr The IP address assigned to the interface of interest.
* \returns The index of the ipv4 interface with the given address.
*
* Each IP interface has an IP address associated with it. It is often
* useful to search the list of interfaces for one that corresponds to
* a known IP Address. This call takes an IP address as a parameter and
* returns the interface index of the first interface that has been assigned
* that address. If the address is not found, this function asserts.
*/
virtual uint32_t FindInterfaceForAddr (Ipv4Address addr) const = 0;
/**
* \brief Find and return the interface ID of the interface that has been
* assigned the specified (masked) IP address.
* \param addr The IP address assigned to the interface of interest.
* \param mask The address mask to be used in address matching.
* \returns The index of the ipv4 interface with the given address.
*
* Each IP interface has an IP address associated with it. It is often
* useful to search the list of interfaces for one that corresponds to
* a known IP Address. This call takes an IP address and an IP address
* mask as parameters and returns the interface index of the first interface
* that matches the masked IP address.
*/
virtual uint32_t FindInterfaceForAddr (Ipv4Address addr,
Ipv4Mask mask) const = 0;
/**
* \brief Find and return the interface ID of the interface that has been
* associated with the specified (masked) NetDevice
* \param nd The net device of the interface of interest.
* \returns The index of the ipv4 interface associated with the given net
* device or -1 if not found.
*
* Each IP interface is associated with a net device. It is often
* useful to search the list of interfaces for one that corresponds to
* a known net device. This call takes an smart pointer to a net device
* and returns the interface index of the first interface that matches the
* net device.
*/
virtual int32_t FindInterfaceForDevice(Ptr<NetDevice> nd) const = 0;
/**
* \param i index of ipv4 interface
* \returns the NetDevice associated with the ipv4 interface index
*/
virtual Ptr<NetDevice> GetNetDevice (uint32_t i) = 0;
/**
* \brief Join a multicast group for a given multicast source and
* group.
*
* \param origin The Ipv4 address of the multicast source.
* \param group The multicast group address.
*/
virtual void JoinMulticastGroup (Ipv4Address origin, Ipv4Address group) = 0;
/**
* \brief Leave a multicast group for a given multicast source and
* group.
*
* \param origin The Ipv4 address of the multicast source.
* \param group The multicast group address.
*/
virtual void LeaveMulticastGroup (Ipv4Address origin, Ipv4Address group) = 0;
/**
* \param interface Interface number of an Ipv4 interface
* \param address Ipv4InterfaceAddress address to associate with the underlying Ipv4 interface
* \returns The address index of the newly-added address
*/
virtual uint32_t AddAddress (uint32_t interface, Ipv4InterfaceAddress address) = 0;
/**
* \param interface Interface number of an Ipv4 interface
* \returns the number of Ipv4InterfaceAddress entries for the interface.
*/
virtual uint32_t GetNAddresses (uint32_t interface) const = 0;
/**
* \param interface Interface number of an Ipv4 interface
* \param addressIndex index of Ipv4InterfaceAddress
* \returns the Ipv4InterfaceAddress associated to the interface and addresIndex
*/
virtual Ipv4InterfaceAddress GetAddress (uint32_t interface, uint32_t addressIndex) const = 0;
/**
* \param i index of ipv4 interface
* \param metric routing metric (cost) associated to the underlying
* ipv4 interface
*/
virtual void SetMetric (uint32_t i, uint16_t metric) = 0;
/**
* \param i index of ipv4 interface
* \returns routing metric (cost) associated to the underlying
* ipv4 interface
*/
virtual uint16_t GetMetric (uint32_t i) const = 0;
/**
* \param destination The IP address of a hypothetical destination.
* \returns The IP address assigned to the interface that will be used
* if we were to send a packet to destination.
*
* Note that the broadcast address for this interface may be fetched
* from the Ipv4Address object returned here using
* Ipv4Address::GetSubnetDirectedBroadcast(mask), where the mask for
* the interface may be retrived using Ipv4::GetNetworkMask(i).
*/
virtual Ipv4Address GetSourceAddress (Ipv4Address destination) const = 0;
/**
* \param dest The IP address of a hypothetical destination.
* \param interface filled in with the interface index that will be used to
* send a packet to the hypothetical destination.
* \returns true if a single interface can be identified, false otherwise.
*/
virtual bool GetInterfaceForDestination (Ipv4Address dest,
uint32_t &interface) const = 0;
/**
* \param i index of ipv4 interface
* \returns the Maximum Transmission Unit (in bytes) associated
* to the underlying ipv4 interface
*/
virtual uint16_t GetMtu (uint32_t i) const = 0;
/**
* \param i index of ipv4 interface
* \returns true if the underlying interface is in the "up" state,
* false otherwise.
*/
virtual bool IsUp (uint32_t i) const = 0;
/**
* \param i index of ipv4 interface
*
* Set the interface into the "up" state. In this state, it is
* considered valid during ipv4 forwarding.
*/
virtual void SetUp (uint32_t i) = 0;
/**
* \param i index of ipv4 interface
*
* Set the interface into the "down" state. In this state, it is
* ignored during ipv4 forwarding.
*/
virtual void SetDown (uint32_t i) = 0;
/**
* \brief Convenience function to return the interface corresponding
* to the Ipv4Address provided
*
* \param addr Ipv4Address
* \param mask corresponding Ipv4Mask
* \returns interface corresponding to a/amask
*/
virtual uint32_t GetInterfaceByAddress (Ipv4Address addr,
Ipv4Mask mask = Ipv4Mask("255.255.255.255"));
};
} // namespace ns3
#endif /* IPV4_H */