The cnet network simulator - Application Layer
Keywords: network simulator simulation protocol undergraduate teaching

### cnet's Application Layer

The Application Layer (either the internal default version or one provided with the -A option) has the responsibility of generating messages to be delivered to other Application Layers. An Application Layer will not generate a message for its own node. The required destination node is identified by its network address and not node number. Each node's address and node number will in fact be the same, unless the `address` attribute is specified in the topology file.

When cnet informs your protocols that the Application Layer has a message for delivery, your protocols will read the message into a buffer supplied by you. You must first indicate the maximum message size that you are willing to receive. A successful read will then ``fill-in'' the address of the message's destination node and the actual length of the message. Your protocols are simply presented with ``a lump of bytes'', at least 32 bytes long, which they must deliver to other Application Layers. The message is to be considered as opaque data, its contents are immaterial, though suffice to say that there is sufficient information in the message for cnet to diagnose most protocol errors for you. A typical sequence is:

        char     msgbuffer[ MAX_MESSAGE_SIZE ];
        CnetAddr destaddr;
        int      length;

        length = sizeof(msgbuffer);
        result = CNET_read_application(&destaddr, msgbuffer, &length);
        /* prepare message for transmission ... */

When the message reaches the correct destination node, it may be written to the Application Layer:

        /* ... receive message from another node */
        result = CNET_write_application(msgbuffer, &length);

### Enabling and disabling the Application Layer

Protocols will typically need to restrict, or throttle, the generation of messages for certain destination nodes. This may be achieved using the functions `CNET_enable_application` and `CNET_disable_application` which each accept a single parameter indicating which destination address to throttle. For example, if the node whose address is `busynode` becomes busy or swamped, we can stop our Application Layer from generating messages for this node with:

        result = CNET_disable_application(busynode);

Similarly, we can permit messages to be generated for all nodes (other than ourselves, of course) with:

        result = CNET_enable_application(ALLNODES);

This function would typically be called in each node's `reboot_node()` function.

The default Application Layer prefers to generate messages for ``close nodes'', with a message having twice the chance of being for an immediate neighbour as for a node two hops away (and so on).

### The Application Layer functions

`int CNET_read_application(CnetAddr *dest, char *msg, int *len);`

  On invocation, `len` must point to an integer indicating the maximum number of bytes that may be copied into `msg`. On return, `len` will point to an integer now indicating the number of bytes copied into `msg`. The network address of the required destination node is copied into `destaddr`.

  Possible errors: `ER_BADSIZE, ER_NOTREADY, ER_NOTSUPPORTED.`

`int CNET_write_application(char *msg, int *len);`

  Passes a number of bytes, pointed to by `msg`, ``up to'' the Application Layer. On invocation, `len` must point to an integer indicating the number of bytes to be taken from `msg`. On return, `len` will point to an integer now indicating the number of bytes accepted by the Application Layer.

  Possible errors: `ER_BADARG, ER_BADSENDER, ER_BADSESSION, ER_BADSIZE, ER_CORRUPTDATA, ER_NOTFORME, ER_NOTREADY, ER_NOTSUPPORTED, ER_OUTOFSEQ.`

`int CNET_enable_application(CnetAddr destaddr);`

  Permits the Application Layer to generate messages to the node with the indicated network address. If the `destaddr` is the symbolic constant `ALLNODES`, message generation to all nodes will be enabled. Initially, message generation to all destination nodes is disabled and must be enabled to begin the generation of messages.

  Possible errors: `ER_NOTSUPPORTED.`

`int CNET_disable_application(CnetAddr destaddr);`

  Prevents the Application Layer from generating new messages to the node with the indicated network address. If the `destaddr` is the symbolic constant `ALLNODES`, message generation to all nodes will be disabled. This function should be called when a harried node runs out of buffer space, or perhaps while routing information is being gathered.

  Possible errors: `ER_NOTSUPPORTED.`

cnet was written and is maintained by Chris McDonald (chris@cs.uwa.edu.au)