cnet's datatypes, event types, and error types

cnet's provides a number of datatypes, necessary to identify node types, link types, events, and errors. Each datatype is defined in the <cnet.h> header file. The datatypes are:

The CnetNodeType enumerated type

Each node is either a host (such as a workstation), a router, a mobile node (such as a wireless PDA), or a wireless accesspoint. The type of a node may be determined by examining its value of nodeinfo.nodetype. For example:

    if(nodeinfo.nodetype == NT_HOST)
        CNET_set_handler(EV_APPLICATIONREADY, appl_ready, 0);

CnetNodeType meaning
NT_HOST this node is a host with an Application Layer and keyboard
NT_ROUTER this node is a router without an Application Layer or keyboard
NT_MOBILE this node may move, may only have wireless links, maintains a record of its battery level, and has an Application Layer and keyboard
NT_ACCESSPOINT this node is a wireless accesspoint, must have at least one wireless link, and has no Application Layer or keyboard

Note that calls to the functions

    CNET_write_application,
    CNET_read_application,
    CNET_enable_application,
    CNET_disable_application and
    CNET_set_handler(EV_APPLICATIONLAYER,...) or
    CNET_set_handler(EV_KEYBOARDREADY,...)

are only valid if called from a node of type NT_HOST or NT_MOBILE.

Calls to the functions

    CNET_set_position, and
    CNET_set_battery

are only valid if called from a node of type NT_MOBILE.

The CnetLinkType enumerated type

Each node's links provide either a loopback service, wide-area-networking, local-area-networking, or wireless-local-area-networking. The type of a link may be determined by examining the value of linkinfo[link].linktype. For example:

    if(linkinfo[link].linktype == LT_LAN)
        if(CNET_lan_busy(link))
            ..........

CnetLinkType meaning
LT_LOOPBACK this link (which will always be link 0) is used to quickly transmit data from a node to itself
LT_WAN this link connects this node to one other node via a dedicated, point-to-point wide-area network link
LT_LAN this link connects this node to other nodes via a simulation of an IEEE-802.3 shared segment
LT_WLAN this link provides a wireless "connection" to all other wireless links that can receive its transmission

Calls to the function

    CNET_set_nicaddr

may only be made for links of type LT_LAN or LT_WLAN.

The CnetColour type

Colours are employed for some simple activities when cnet's execution is displayed via its GUI. Colours are simple C strings, such as "red" or "blue", hexadecimal RGB-triples such as "#ffaa00", or the special value CNET_LED_OFF.

When drawing datalink frames, protocol code may specify the colour to be used to highlight each field in each frame.

When wishing to present a quick indication of a node's status, the function CNET_set_LED may be called with the desired colour (string).

When drawing the wireless transmissions of wireless LANs, the function CNET_set_wlancolour may be called to request how each transmission is drawn.

The CnetError enumerated type

Most cnet API functions return the integer 0 on success and the integer -1 on failure. The most recent error status is stored in the global variable cnet_errno. All values of cnet_errno will be instances of the enumerated type CnetError. Functions do not set the value of cnet_errno to ER_OK if their execution was successful.

Errors may be reported to stderr with CNET_perror() and their error message string accessed from cnet_errstr[(int)cnet_errno]. For example:

    if(CNET_write_application(msgbuffer, &msglength) != 0) {
        // an error has occured
        if(cnet_errno == ER_BADSESSION) {
            // handle this special case
            ....
        }
        else {
            CNET_perror("writing to application");
        }
    }

CnetError meaning
ER_OK No error
ER_BADALLOC Allocation of dynamic memory failed
ER_BADARG Invalid argument passed to a function
ER_BADEVENT Invalid event passed to a function
ER_BADLINK Invalid link number passed to a function
ER_BADNODE Invalid node passed to a function
ER_BADPOSITION Attempt to move mobile node off the map
ER_BADSENDER Application Layer given message from an unknown node
ER_BADSESSION Application Layer given message from incorrect session
ER_BADSIZE Indicated length is of incorrect size
ER_BADTIMER Invalid CnetTimerID passed to a function
ER_CORRUPTFRAME Attempt to transfer corrupt data (only seen if -e provided)
ER_DUPLICATEMSG Application Layer given a duplicate message
ER_LINKDOWN Attempt to transmit on a link which is down
ER_MISSINGMSG Application Layer given a message before all previous ones
ER_NOBATTERY Battery exhaused on a mobile node
ER_NOTFORME Application Layer given a message for another node
ER_NOTREADY Function called when service not available
ER_NOTSUPPORTED Invalid operation for this node or link type
ER_TOOBUSY Link is too busy/congested to handle request

The CnetEvent enumerated type

All events in cnet are of type CnetEvent. Events are raised when a number of important things occur that (possibly) require action from your protocols. Interest may be registered in each event by calling the function CNET_set_handler and passing to it a function, an event handler, to be called when the event is raised. By default, no events are of interest (all are ignored).

When an event of interest is raised, its event handler is called, with the event (an instance of CnetEvent) passed as the first parameter.

CnetEvent meaning
EV_NULL this event is used internally and is never seen by your protocols
EV_REBOOT raised as reboot_node(EV_REBOOT, ... , ...)
EV_SHUTDOWN raised before cnet is (cleanly) terminated
EV_APPLICATIONREADY raised when there is a message ready for delivery
EV_PHYSICALREADY raised when a frame arrives at one of the links
EV_FRAMECOLLISION raised when a frame collides on LT_LAN or LT_WLAN
EV_KEYBOARDREADY raised when an input line is entered from the keyboard
EV_LINKSTATE raised when a link changes state (either up or down)
EV_DRAWFRAME raised when a frame is to be drawn in 2-node world
EV_PERIODIC raised periodically if the -f option provided
EV_UPDATEGUI raised whenever the Tcl/Tk GUI is being updated, as requested by the -u option
EV_DEBUG0..EV_DEBUG4 raised when one of the debug buttons (under Tcl/Tk) is pressed
EV_TIMER0..EV_TIMER9 raised when a timer on any of the 10 timer queues expires

The CnetNICaddr datatype

Each Physical Layer link of type LT_WAN, LT_LAN, or LT_WLAN has a specific Network Interface Card (NIC) address. cnet provides the CnetNICaddr datatype to represent the addresses of its NICs, as an array of LEN_NICADDR (=6) unsigned characters. Although cnet does not require it, it is anticipated that frames will carry the address of their source and destination Network Interface Cards (NIC) near the beginning of the frame.

cnet provides the functions CNET_parse_nicaddr and CNET_format_nicaddr to convert between character strings and the CnetNICaddr datatype.

The CnetTime datatype

All times and periods in cnet are stored as an integral number of microsconds. This requires a sufficiently long integer representation to avoid values "wrapping around" in most simulations. cnet employs ISO-C99's standard int64_t datatype to represent time:

    typedef int64_t    CnetTime;

and all function arguments and structure fields requiring a number of microseconds, employ the CnetTime type. Standard integer arithmetic, such as addition and subtraction, and comparisons may be performed on CnetTime values, and they may be conveniently formatted with CNET_format64.

The WLANRESULT enumerated type

A simulation needing to define its own WLAN signal propagation model, will call CNET_set_wlan_model to register a function that determines the extent and success of wireless signal propagation. This function must return one of the values of WLANRESULT:

WLANRESULT meaning
WLAN_TOOWEAK the receiver cannot hear the WLAN signal at all
WLAN_TOONOISY the receiver can hear the WLAN signal, but cannot discern its contents from the background noise
WLAN_RECEIVED the WLAN signal is both heard and decodable


 cnet v3.3.3, written by Chris.McDonald@uwa.edu.au
 Last modified: Tue Oct 13 1:07PM 2015