A Discrete-Event Network Simulator
API
Loading...
Searching...
No Matches
ipv4.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2007 INRIA
3 *
4 * SPDX-License-Identifier: GPL-2.0-only
5 *
6 * Author: Mathieu Lacage <mathieu.lacage@sophia.inria.fr>
7 */
8#ifndef IPV4_H
9#define IPV4_H
10
12#include "ipv4-route.h"
13
14#include "ns3/callback.h"
15#include "ns3/deprecated.h"
16#include "ns3/ipv4-address.h"
17#include "ns3/object.h"
18#include "ns3/socket.h"
19
20#include <stdint.h>
21
22namespace ns3
23{
24
25class Node;
26class NetDevice;
27class Packet;
28class Ipv4RoutingProtocol;
29class IpL4Protocol;
30class Ipv4Header;
31
32/**
33 * \ingroup internet
34 * \defgroup ipv4 IPv4 classes and sub-modules
35 */
36/**
37 * \ingroup ipv4
38 * \brief Access to the IPv4 forwarding table, interfaces, and configuration
39 *
40 * This class defines the API to manipulate the following aspects of
41 * the IPv4 implementation:
42 * -# set/get an Ipv4RoutingProtocol
43 * -# register a NetDevice for use by the Ipv4 layer (basically, to
44 * create Ipv4-related state such as addressing and neighbor cache that
45 * is associated with a NetDevice)
46 * -# manipulate the status of the NetDevice from the Ipv4 perspective,
47 * such as marking it as Up or Down,
48 * -# adding, deleting, and getting addresses associated to the Ipv4
49 * interfaces.
50 * -# exporting Ipv4 configuration attributes
51 *
52 * Each NetDevice has conceptually a single Ipv4 interface associated
53 * with it (the corresponding structure in the Linux Ipv4 implementation
54 * is struct in_device). Each interface may have one or more Ipv4
55 * addresses associated with it. Each Ipv4 address may have different
56 * subnet mask, scope, etc., so all of this per-address information
57 * is stored in an Ipv4InterfaceAddress class (the corresponding
58 * structure in Linux is struct in_ifaddr)
59 *
60 * Ipv4 attributes such as whether IP forwarding is enabled and disabled
61 * are also stored in this class
62 *
63 * TO DO: Add API to allow access to the Ipv4 neighbor table
64 *
65 * \see Ipv4RoutingProtocol
66 * \see Ipv4InterfaceAddress
67 */
68class Ipv4 : public Object
69{
70 public:
71 /**
72 * \brief Get the type ID.
73 * \return the object TypeId
74 */
75 static TypeId GetTypeId();
76 Ipv4();
77 ~Ipv4() override;
78
79 /**
80 * \brief Register a new routing protocol to be used by this Ipv4 stack
81 *
82 * This call will replace any routing protocol that has been previously
83 * registered. If you want to add multiple routing protocols, you must
84 * add them to a Ipv4ListRoutingProtocol directly.
85 *
86 * \param routingProtocol smart pointer to Ipv4RoutingProtocol object
87 */
88 virtual void SetRoutingProtocol(Ptr<Ipv4RoutingProtocol> routingProtocol) = 0;
89
90 /**
91 * \brief Get the routing protocol to be used by this Ipv4 stack
92 *
93 * \returns smart pointer to Ipv4RoutingProtocol object, or null pointer if none
94 */
96
97 /**
98 * \param device device to add to the list of Ipv4 interfaces
99 * which can be used as output interfaces during packet forwarding.
100 * \returns the index of the Ipv4 interface added.
101 *
102 * Once a device has been added, it can never be removed: if you want
103 * to disable it, you can invoke Ipv4::SetDown which will
104 * make sure that it is never used during packet forwarding.
105 */
107
108 /**
109 * \returns the number of interfaces added by the user.
110 */
111 virtual uint32_t GetNInterfaces() const = 0;
112
113 /**
114 * \brief Return the interface number of the interface that has been
115 * assigned the specified IP address.
116 *
117 * \param address The IP address being searched for
118 * \returns The interface number of the Ipv4 interface with the given
119 * address or -1 if not found.
120 *
121 * Each IP interface has one or more IP addresses associated with it.
122 * This method searches the list of interfaces for one that holds a
123 * particular address. This call takes an IP address as a parameter and
124 * returns the interface number of the first interface that has been assigned
125 * that address, or -1 if not found. There must be an exact match; this
126 * method will not match broadcast or multicast addresses.
127 */
128 virtual int32_t GetInterfaceForAddress(Ipv4Address address) const = 0;
129
130 /**
131 * \param packet packet to send
132 * \param source source address of packet
133 * \param destination address of packet
134 * \param protocol number of packet
135 * \param route route entry
136 *
137 * Higher-level layers call this method to send a packet
138 * down the stack to the MAC and PHY layers.
139 */
140 virtual void Send(Ptr<Packet> packet,
141 Ipv4Address source,
142 Ipv4Address destination,
143 uint8_t protocol,
144 Ptr<Ipv4Route> route) = 0;
145
146 /**
147 * \param packet packet to send
148 * \param ipHeader IP Header
149 * \param route route entry
150 *
151 * Higher-level layers call this method to send a packet with IPv4 Header
152 * (Intend to be used with IpHeaderInclude attribute.)
153 */
154 virtual void SendWithHeader(Ptr<Packet> packet, Ipv4Header ipHeader, Ptr<Ipv4Route> route) = 0;
155
156 /**
157 * \param protocol a template for the protocol to add to this L4 Demux.
158 *
159 * Invoke Copy on the input template to get a copy of the input
160 * protocol which can be used on the Node on which this L4 Demux
161 * is running. The new L4Protocol is registered internally as
162 * a working L4 Protocol and returned from this method.
163 * The caller does not get ownership of the returned pointer.
164 */
165 virtual void Insert(Ptr<IpL4Protocol> protocol) = 0;
166
167 /**
168 * \brief Add a L4 protocol to a specific interface.
169 *
170 * This may be called multiple times for multiple interfaces for the same
171 * protocol. To insert for all interfaces, use the separate
172 * Insert (Ptr<IpL4Protocol> protocol) method.
173 *
174 * Setting a protocol on a specific interface will overwrite the
175 * previously bound protocol.
176 *
177 * \param protocol L4 protocol.
178 * \param interfaceIndex interface index.
179 */
180 virtual void Insert(Ptr<IpL4Protocol> protocol, uint32_t interfaceIndex) = 0;
181
182 /**
183 * \param protocol protocol to remove from this demux.
184 *
185 * The input value to this method should be the value
186 * returned from the Ipv4L4Protocol::Insert method.
187 */
188 virtual void Remove(Ptr<IpL4Protocol> protocol) = 0;
189
190 /**
191 * \brief Remove a L4 protocol from a specific interface.
192 * \param protocol L4 protocol to remove.
193 * \param interfaceIndex interface index.
194 */
195 virtual void Remove(Ptr<IpL4Protocol> protocol, uint32_t interfaceIndex) = 0;
196
197 /**
198 * \brief Determine whether address and interface corresponding to
199 * received packet can be accepted for local delivery
200 *
201 * \param address The IP address being considered
202 * \param iif The incoming Ipv4 interface index
203 * \returns true if the address is associated with the interface index
204 *
205 * This method can be used to determine whether a received packet has
206 * an acceptable address for local delivery on the host. The address
207 * may be a unicast, multicast, or broadcast address. This method will
208 * return true if address is an exact match of a unicast address on
209 * one of the host's interfaces (see below), if address corresponds to
210 * a multicast group that the host has joined (and the incoming device
211 * is acceptable), or if address corresponds to a broadcast address.
212 *
213 * If the Ipv4 attribute StrongEndSystemModel is true, the address must match one assigned to
214 * the incoming device. If the attribute is false, the unicast address may match any of the Ipv4
215 * addresses on any interface.
216 */
217 virtual bool IsDestinationAddress(Ipv4Address address, uint32_t iif) const = 0;
218
219 /**
220 * \brief Return the interface number of first interface found that
221 * has an Ipv4 address within the prefix specified by the input
222 * address and mask parameters
223 *
224 * \param address The IP address assigned to the interface of interest.
225 * \param mask The IP prefix to use in the mask
226 * \returns The interface number of the Ipv4 interface with the given
227 * address or -1 if not found.
228 *
229 * Each IP interface has one or more IP addresses associated with it.
230 * This method searches the list of interfaces for the first one found
231 * that holds an address that is included within the prefix
232 * formed by the input address and mask parameters. The value -1 is
233 * returned if no match is found.
234 */
235 virtual int32_t GetInterfaceForPrefix(Ipv4Address address, Ipv4Mask mask) const = 0;
236
237 /**
238 * \param interface The interface number of an Ipv4 interface.
239 * \returns The NetDevice associated with the Ipv4 interface number.
240 */
241 virtual Ptr<NetDevice> GetNetDevice(uint32_t interface) = 0;
242
243 /**
244 * \param device The NetDevice for an Ipv4Interface
245 * \returns The interface number of an Ipv4 interface or -1 if not found.
246 */
248
249 /**
250 * \param interface Interface number of an Ipv4 interface
251 * \param address Ipv4InterfaceAddress address to associate with the underlying Ipv4 interface
252 * \returns true if the operation succeeded
253 */
254 virtual bool AddAddress(uint32_t interface, Ipv4InterfaceAddress address) = 0;
255
256 /**
257 * \param interface Interface number of an Ipv4 interface
258 * \returns the number of Ipv4InterfaceAddress entries for the interface.
259 */
260 virtual uint32_t GetNAddresses(uint32_t interface) const = 0;
261
262 /**
263 * Because addresses can be removed, the addressIndex is not guaranteed
264 * to be static across calls to this method.
265 *
266 * \param interface Interface number of an Ipv4 interface
267 * \param addressIndex index of Ipv4InterfaceAddress
268 * \returns the Ipv4InterfaceAddress associated to the interface and addressIndex
269 */
270 virtual Ipv4InterfaceAddress GetAddress(uint32_t interface, uint32_t addressIndex) const = 0;
271
272 /**
273 * Remove the address at addressIndex on named interface. The addressIndex
274 * for all higher indices will decrement by one after this method is called;
275 * so, for example, to remove 5 addresses from an interface i, one could
276 * call RemoveAddress (i, 0); 5 times.
277 *
278 * \param interface Interface number of an Ipv4 interface
279 * \param addressIndex index of Ipv4InterfaceAddress to remove
280 * \returns true if the operation succeeded
281 */
282 virtual bool RemoveAddress(uint32_t interface, uint32_t addressIndex) = 0;
283
284 /**
285 * \brief Remove the given address on named Ipv4 interface
286 *
287 * \param interface Interface number of an Ipv4 interface
288 * \param address The address to remove
289 * \returns true if the operation succeeded
290 */
291 virtual bool RemoveAddress(uint32_t interface, Ipv4Address address) = 0;
292
293 /**
294 * \brief Return the first primary source address with scope less than
295 * or equal to the requested scope, to use in sending a packet to
296 * destination dst out of the specified device.
297 *
298 * This method mirrors the behavior of Linux inet_select_addr() and is
299 * provided because interfaces may have multiple IP addresses configured
300 * on them with different scopes, and with a primary and secondary status.
301 * Secondary addresses are never returned.
302 * \see Ipv4InterfaceAddress
303 *
304 * If a non-zero device pointer is provided, the method first tries to
305 * return a primary address that is configured on that device, and whose
306 * subnet matches that of dst and whose scope is less than or equal to
307 * the requested scope. If a primary address does not match the
308 * subnet of dst but otherwise matches the scope, it is returned.
309 * If no such address on the device is found, the other devices are
310 * searched in order of their interface index, but not considering dst
311 * as a factor in the search. Because a loopback interface is typically
312 * the first one configured on a node, it will be the first alternate
313 * device to be tried. Addresses scoped at LINK scope are not returned
314 * in this phase.
315 *
316 * If no device pointer is provided, the same logic as above applies, only
317 * that there is no preferred device that is consulted first. This means
318 * that if the device pointer is null, input parameter dst will be ignored.
319 *
320 * If there are no possible addresses to return, a warning log message
321 * is issued and the all-zeroes address is returned.
322 *
323 * \param device output NetDevice (optionally provided, only to constrain the search)
324 * \param dst Destination address to match, if device is provided
325 * \param scope Scope of returned address must be less than or equal to this
326 * \returns the first primary Ipv4Address that meets the search criteria
327 */
330 Ipv4Address dst,
332
333 /**
334 * \param interface The interface number of an Ipv4 interface
335 * \param metric routing metric (cost) associated to the underlying
336 * Ipv4 interface
337 */
338 virtual void SetMetric(uint32_t interface, uint16_t metric) = 0;
339
340 /**
341 * \param interface The interface number of an Ipv4 interface
342 * \returns routing metric (cost) associated to the underlying
343 * Ipv4 interface
344 */
345 virtual uint16_t GetMetric(uint32_t interface) const = 0;
346
347 /**
348 * \param interface Interface number of Ipv4 interface
349 * \returns the Maximum Transmission Unit (in bytes) associated
350 * to the underlying Ipv4 interface
351 */
352 virtual uint16_t GetMtu(uint32_t interface) const = 0;
353
354 /**
355 * \param interface Interface number of Ipv4 interface
356 * \returns true if the underlying interface is in the "up" state,
357 * false otherwise.
358 */
359 virtual bool IsUp(uint32_t interface) const = 0;
360
361 /**
362 * \param interface Interface number of Ipv4 interface
363 *
364 * Set the interface into the "up" state. In this state, it is
365 * considered valid during Ipv4 forwarding.
366 */
367 virtual void SetUp(uint32_t interface) = 0;
368
369 /**
370 * \param interface Interface number of Ipv4 interface
371 *
372 * Set the interface into the "down" state. In this state, it is
373 * ignored during Ipv4 forwarding.
374 */
375 virtual void SetDown(uint32_t interface) = 0;
376
377 /**
378 * \param interface Interface number of Ipv4 interface
379 * \returns true if IP forwarding enabled for input datagrams on this device
380 */
381 virtual bool IsForwarding(uint32_t interface) const = 0;
382
383 /**
384 * \param interface Interface number of Ipv4 interface
385 * \param val Value to set the forwarding flag
386 *
387 * If set to true, IP forwarding is enabled for input datagrams on this device
388 */
389 virtual void SetForwarding(uint32_t interface, bool val) = 0;
390
391 /**
392 * \brief Choose the source address to use with destination address.
393 * \param interface interface index
394 * \param dest IPv4 destination address
395 * \return IPv4 source address to use
396 */
398
399 /**
400 * \param protocolNumber number of protocol to lookup
401 * in this L4 Demux
402 * \returns a matching L4 Protocol
403 *
404 * This method is typically called by lower layers
405 * to forward packets up the stack to the right protocol.
406 */
407 virtual Ptr<IpL4Protocol> GetProtocol(int protocolNumber) const = 0;
408
409 /**
410 * \brief Get L4 protocol by protocol number for the specified interface.
411 * \param protocolNumber protocol number
412 * \param interfaceIndex interface index, -1 means "any" interface.
413 * \return corresponding IpL4Protocol or 0 if not found
414 */
415 virtual Ptr<IpL4Protocol> GetProtocol(int protocolNumber, int32_t interfaceIndex) const = 0;
416
417 /**
418 * \brief Creates a raw socket
419 *
420 * \returns a smart pointer to the instantiated raw socket
421 */
423
424 /**
425 * \brief Deletes a particular raw socket
426 *
427 * \param socket Smart pointer to the raw socket to be deleted
428 */
429 virtual void DeleteRawSocket(Ptr<Socket> socket) = 0;
430
431 static const uint32_t IF_ANY = 0xffffffff; //!< interface wildcard, meaning any interface
432
433 private:
434 // Indirect the Ipv4 attributes through private pure virtual methods
435
436 /**
437 * \brief Set or unset the IP forwarding state
438 * \param forward the forwarding state
439 */
440 virtual void SetIpForward(bool forward) = 0;
441 /**
442 * \brief Get the IP forwarding state
443 * \returns true if IP is in forwarding state
444 */
445 virtual bool GetIpForward() const = 0;
446
447 /**
448 * \brief Get the Weak Es Model status
449 *
450 * RFC1122 term for whether host accepts datagram with a dest. address on another interface
451 * \returns true for Weak Es Model activated
452 */
453 NS_DEPRECATED_3_41("Use GetStrongEndSystemModel instead")
454 virtual bool GetWeakEsModel() const = 0;
455
456 /**
457 * \brief Set or unset the Weak Es Model
458 *
459 * RFC1122 term for whether host accepts datagram with a dest. address on another interface
460 * \param model true for Weak Es Model
461 */
463 virtual void SetWeakEsModel(bool model) = 0;
464
465 /**
466 * \brief Set or unset the Strong End System Model
467 *
468 * RFC1122 term for whether host rejects datagram with a dest. address on another interface
469 * \param model true for Strong End System Model
470 */
471 virtual void SetStrongEndSystemModel(bool model) = 0;
472 /**
473 * \brief Get the Strong End System Model status
474 *
475 * RFC1122 term for whether host rejects datagram with a dest. address on another interface
476 * \returns true for Strong End System Model activated
477 */
478 virtual bool GetStrongEndSystemModel() const = 0;
479};
480
481} // namespace ns3
482
483#endif /* IPV4_H */
Ipv4 addresses are stored in host order in this class.
Packet header for IPv4.
Definition ipv4-header.h:23
Access to the IPv4 forwarding table, interfaces, and configuration.
Definition ipv4.h:69
virtual int32_t GetInterfaceForAddress(Ipv4Address address) const =0
Return the interface number of the interface that has been assigned the specified IP address.
virtual bool GetIpForward() const =0
Get the IP forwarding state.
virtual bool GetStrongEndSystemModel() const =0
Get the Strong End System Model status.
virtual void SetIpForward(bool forward)=0
Set or unset the IP forwarding state.
virtual void SetStrongEndSystemModel(bool model)=0
Set or unset the Strong End System Model.
Ipv4()
Definition ipv4.cc:65
virtual void DeleteRawSocket(Ptr< Socket > socket)=0
Deletes a particular raw socket.
virtual bool IsForwarding(uint32_t interface) const =0
virtual Ptr< Ipv4RoutingProtocol > GetRoutingProtocol() const =0
Get the routing protocol to be used by this Ipv4 stack.
virtual void SetMetric(uint32_t interface, uint16_t metric)=0
virtual void SetRoutingProtocol(Ptr< Ipv4RoutingProtocol > routingProtocol)=0
Register a new routing protocol to be used by this Ipv4 stack.
virtual void SetWeakEsModel(bool model)=0
Set or unset the Weak Es Model.
virtual void Insert(Ptr< IpL4Protocol > protocol)=0
virtual uint32_t GetNAddresses(uint32_t interface) const =0
virtual void Remove(Ptr< IpL4Protocol > protocol)=0
virtual bool RemoveAddress(uint32_t interface, Ipv4Address address)=0
Remove the given address on named Ipv4 interface.
virtual uint16_t GetMtu(uint32_t interface) const =0
virtual Ipv4InterfaceAddress GetAddress(uint32_t interface, uint32_t addressIndex) const =0
Because addresses can be removed, the addressIndex is not guaranteed to be static across calls to thi...
virtual uint32_t AddInterface(Ptr< NetDevice > device)=0
virtual bool GetWeakEsModel() const =0
Get the Weak Es Model status.
virtual void SendWithHeader(Ptr< Packet > packet, Ipv4Header ipHeader, Ptr< Ipv4Route > route)=0
virtual Ptr< IpL4Protocol > GetProtocol(int protocolNumber) const =0
virtual void SetUp(uint32_t interface)=0
virtual Ipv4Address SelectSourceAddress(Ptr< const NetDevice > device, Ipv4Address dst, Ipv4InterfaceAddress::InterfaceAddressScope_e scope)=0
Return the first primary source address with scope less than or equal to the requested scope,...
virtual Ptr< NetDevice > GetNetDevice(uint32_t interface)=0
virtual void Send(Ptr< Packet > packet, Ipv4Address source, Ipv4Address destination, uint8_t protocol, Ptr< Ipv4Route > route)=0
virtual bool IsDestinationAddress(Ipv4Address address, uint32_t iif) const =0
Determine whether address and interface corresponding to received packet can be accepted for local de...
virtual void Insert(Ptr< IpL4Protocol > protocol, uint32_t interfaceIndex)=0
Add a L4 protocol to a specific interface.
static const uint32_t IF_ANY
interface wildcard, meaning any interface
Definition ipv4.h:431
static TypeId GetTypeId()
Get the type ID.
Definition ipv4.cc:25
virtual Ptr< IpL4Protocol > GetProtocol(int protocolNumber, int32_t interfaceIndex) const =0
Get L4 protocol by protocol number for the specified interface.
virtual int32_t GetInterfaceForDevice(Ptr< const NetDevice > device) const =0
virtual int32_t GetInterfaceForPrefix(Ipv4Address address, Ipv4Mask mask) const =0
Return the interface number of first interface found that has an Ipv4 address within the prefix speci...
virtual void SetDown(uint32_t interface)=0
virtual Ipv4Address SourceAddressSelection(uint32_t interface, Ipv4Address dest)=0
Choose the source address to use with destination address.
virtual bool RemoveAddress(uint32_t interface, uint32_t addressIndex)=0
Remove the address at addressIndex on named interface.
virtual uint16_t GetMetric(uint32_t interface) const =0
virtual bool AddAddress(uint32_t interface, Ipv4InterfaceAddress address)=0
virtual uint32_t GetNInterfaces() const =0
virtual void Remove(Ptr< IpL4Protocol > protocol, uint32_t interfaceIndex)=0
Remove a L4 protocol from a specific interface.
virtual Ptr< Socket > CreateRawSocket()=0
Creates a raw socket.
virtual void SetForwarding(uint32_t interface, bool val)=0
virtual bool IsUp(uint32_t interface) const =0
~Ipv4() override
Definition ipv4.cc:70
a class to store IPv4 address information on an interface
a class to represent an Ipv4 address mask
A base class which provides memory management and object aggregation.
Definition object.h:78
Smart pointer class similar to boost::intrusive_ptr.
a unique identifier for an interface.
Definition type-id.h:48
#define NS_DEPRECATED_3_41(msg)
Tag for things deprecated in version ns-3.41.
Definition deprecated.h:105
Every class exported by the ns3 library is enclosed in the ns3 namespace.