40.2.4 Agent upcalls to applications

Since presently in ns there is no actual data being passed between applications, agents can instead announce to applications the occurrence of certain events at the transport layer through ``upcalls.'' For example, applications can be notified of the arrival of a number of bytes of data; this information may aid the application in modelling real-world application behavior more closely. Two basic ``upcalls'' have been implemented in base class Application and in the transport agents:

• recv(int nbytes)--Announces that nbytes of data have been received by the agent. For UDP agents, this signifies the arrival of a single packet. For TCP agents, this signifies the ``delivery'' of an amount of in-sequence data, which may be larger than that contained in a single packet (due to the possibility of network reordering).
• resume()--This indicates to the application that the transport agent has sent out all of the data submitted to it up to that point in time. For TCP, it does not indicate whether the data has been ACKed yet, only that it has been sent out for the first time.

The default behavior is as follows: Depending on whether the application has been implemented in C++ or OTcl, these C++ functions call a similarly named (recv, resume) function in the application, if such methods have been defined.

Although strictly not a callback to applications, certain Agents have implemented a callback from C++ to OTcl-level that has been used by applications such as HTTP simulators. This callback method, done{}, is used in TCP agents. In TCP, done{} is called when a TCP sender has received ACKs for all of its data and is now closed; it therefore can be used to simulate a blocked TCP connection. The done{} method was primarily used before this API was completed, but may still be useful for applications that do not want to use resume().

To use done{} for FullTcp, for example, you can try:

        set myagent [new Agent/TCP/FullTcp]
        $myagent proc done { } {
            ... code you want ...
        }

If you want all the FullTCP's to have the same code you could also do:

        Agent/TCP/FullTcp instproc done {} {
            ... code you want ...
        }

By default, done{} does nothing.