ns-3: API and model change history

ns-3 is an evolving system and there will be API or behavioral changes from time to time. Users who try to use scripts or models across versions of ns-3 may encounter problems at compile time, run time, or may see the simulation output change.

We have adopted the development policy that we are going to try to ease the impact of these changes on users by documenting these changes in a single place (this file), and not by providing a temporary or permanent backward-compatibility software layer.

The goal is that users who encounter a problem when trying to use older code with newer code should be able to consult this file to find guidance as to how to fix the problem. For instance, if a method name or signature has changed, it should be stated what the new replacement name is.

Note that users who upgrade the simulator across versions, or who work directly out of the development tree, may find that simulation output changes even when the compilation doesn't break, such as when a simulator default value is changed. Therefore, it is good practice for _anyone_ using code across multiple ns-3 releases to consult this file, as well as the RELEASE_NOTES, to understand what has changed over time.

This file is a best-effort approach to solving this issue; we will do our best but can guarantee that there will be things that fall through the cracks, unfortunately. If you, as a user, can suggest improvements to this file based on your experience, please contribute a patch or drop us a note on ns-developers mailing list.

changes from ns-3.1 to ns-3.2

new API in existing classes:

01-08-2008; changeset a18520551cdf

class ArpCache has two new attributes: MaxRetries and a Drop trace. It also has some new public methods but these are mostly for internal use.

changes to existing API:

25-08-2008; changeset e5ab96db540e

bug 273: constify packet pointers.
The normal and the promiscuous receive callbacks of the NetDevice API have been changed from:
```
Callback,Ptr,uint16_t,const Address &>
Callback, Ptr, uint16_t,
         const Address &, const Address &, enum PacketType >
```
to:
```
Callback,Ptr,uint16_t,const Address &>
Callback, Ptr, uint16_t,
         const Address &, const Address &, enum PacketType >
```
to avoid the kind of bugs reported in bug 273. Users who implement a subclass of the NetDevice base class need to change the signature of their SetReceiveCallback and SetPromiscReceiveCallback methods.

04-08-2008; changeset cba7b2b80fe8

Cleanup of MTU confusion and initialization in CsmaNetDevice
The MTU of the CsmaNetDevice defaulted to 65535. This did not correspond with the expected MTU found in Ethernet-like devices. Also there was not clear documentation regarding which MTU was being set. There are two MTU here, one at the MAC level and one at the PHY level. We split out the MTU setting to make this more clear and set the default PHY level MTU to 1500 to be more like Ethernet. The encapsulation mode defaults to LLC/SNAP which then puts the MAC level MTU at 1492 by default. We allow users to now set the encapsulation mode, MAC MTU and PHY MTU while keeping the three values consistent. See the Doxygen of CsmaNetDevice::SetMaxPayloadLength for a detailed description of the issues and solution.

21-07-2008; changeset 99698bc858e8

class NetDevice has added a pure virtual method that must be implemented by all subclasses:
```
virtual void SetPromiscReceiveCallback (PromiscReceiveCallback cb) = 0;
```
All NetDevices must support this method, and must call this callback when processing packets in the receive direction (the appropriate place to call this is device-dependent). An approach to stub this out temporarily, if you do not care about immediately enabling this functionality, would be to add this to your device:
```
void
ExampleNetDevice::SetPromiscReceiveCallback
(NetDevice::PromiscReceiveCallback cb)
{ 
  NS_ASSERT_MSG (false, "No implementation yet for
SetPromiscReceiveCallback");
}
```
To implement this properly, consult the CsmaNetDevice for examples of when the m_promiscRxCallback is called.

03-07-2008; changeset d5f8e5fae1c6

Miscellaneous cleanup of Udp Helper API, to fix bug 234

class UdpEchoServerHelper
{
public:
- UdpEchoServerHelper ();
- void SetPort (uint16_t port); 
+ UdpEchoServerHelper (uint16_t port);
+ 
+ void SetAttribute (std::string name, const AttributeValue &value);
ApplicationContainer Install (NodeContainer c);

class UdpEchoClientHelper
{
public:
- UdpEchoClientHelper ();
+ UdpEchoClientHelper (Ipv4Address ip, uint16_t port);
- void SetRemote (Ipv4Address ip, uint16_t port);
- void SetAppAttribute (std::string name, const AttributeValue &value);
+ void SetAttribute (std::string name, const AttributeValue &value);
ApplicationContainer Install (NodeContainer c);

03-07-2008; changeset 3cdd9d60f7c7

Rename all instances method names using "Set..Parameter" to "Set..Attribute" (bug 232)

How to fix your code: Any use of helper API that was using a method "Set...Parameter()" should be changed to read "Set...Attribute()". e.g.

- csma.SetChannelParameter ("DataRate", DataRateValue (5000000));
- csma.SetChannelParameter ("Delay", TimeValue (MilliSeconds (2)));
+ csma.SetChannelAttribute ("DataRate", DataRateValue (5000000));
+ csma.SetChannelAttribute ("Delay", TimeValue (MilliSeconds (2)));

changed behavior:

28-07-2008; changeset 6f68f1044df1
- OLSR: HELLO messages hold time changed to 3*hello interval from hello interval. This is an important bug fix as hold time == refresh time was never intentional, as it leads to instability in neighbor detection.