cnet's Application Programming Interface

NAME

CNET_set_wlan_model - define a WLAN signal propagation function

SYNOPSIS

#include <cnet.h> typedef enum { WLAN_TOOWEAK, WLAN_TOONOISY, WLAN_RECEIVED } WLANRESULT; typedef struct { int tx_n; CnetPosition tx_pos; WLANINFO *tx_info; int rx_n; CnetPosition rx_pos; WLANINFO *rx_info; double rx_strength_dBm; } WLANSIGNAL; int CNET_set_wlan_model( WLANRESULT (*newmodel)(WLANSIGNAL *sig) );

DESCRIPTION

CNET_set_wlan_model permits a simulation to register a function that determines the extent and success of wireless signal propagation. Only one such function is recorded per-simulation.

If NULL is provided as the single parameter, cnet uses its own internal (default) function.

Each time a wireless signal leaves its transmitting node, the new propagation model function is called with a pointer to a WLANSIGNAL structure whose elements describe the transmitting (tx_*) and receiving nodes (rx_*) and their WLAN links.

The first 4 fields of the WLANSIGNAL structure provide the transmitter's node number, the transmitter's x and y coordinates on the simulation map, and the characteristics of the transmitter's link. The next 4 fields provide the same information about the receiving node. The final field enables the function to report (to cnet) the strength of the signal arriving at the receiver (in dBm).

The return type of the function is WLANRESULT - the function must return WLAN_TOOWEAK (if the receiver cannot hear the signal at all), WLAN_TOONOISY (if the receiver cannot discern the signal from the background noise), or WLAN_RECEIVED (if the signal is heard and decodable).

If the result is WLAN_TOOWEAK, the (potential) receiver will be unaware of the signal at all, otherwise the receiver may learn of the signal by calling CNET_carrier_sense. If the result is WLAN_RECEIVED, the EV_PHYSICALREADY event will (soon) be raised in the receiver.

RETURN VALUE

The value 0 is always returned.