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);

line

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).

line

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.

line

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