cnet's Application Programming Interface

NAME

CNET_get_wlaninfo - get the transmission and reception characteristics of a WLAN link

SYNOPSIS

#include <cnet.h> typedef struct { double frequency_GHz; double tx_power_dBm; double tx_cable_loss_dBm; double tx_antenna_gain_dBi; double rx_antenna_gain_dBi; double rx_cable_loss_dBm; double rx_sensitivity_dBm; double rx_signal_to_noise_dBm; double sleep_current_mA; double idle_current_mA; double tx_current_mA; double rx_current_mA; } WLANINFO; int CNET_get_wlaninfo(int link, WLANINFO *wlaninfo);

DESCRIPTION

CNET_get_wlaninfo retrieves the transmission and reception characteristics of a link of type LT_WLAN.

CNET_get_wlaninfo assumes that its second argument is a pointer to a WLANINFO structure, whose definition is provided in <cnet.h> . The fields defining the transmitting "half" of each LT_WLAN link are prefixed by tx_, and the fields defining the receiving "half" are prefixed by rx_ .

The units of transmission and reception power are decibel-milliwatts (dBm), with values near 15.0dBm being typical for a PCMCIA-type wireless card. An equivalent power measured in Watts (typically 30mW for a PCMCIA card) is related to power measured in decibel-milliwatts using the formula:

    dBm  =  10*log10(Watts / 0.001)

A WLAN link may be in one of four states. In sleep state, a link cannot transmit nor receive signals, and consumes very little energy. From idle state, the link may be asked to temporarily enter transmit state to transmit a signal, and will temporarily enter receive state to receive each signal within range. Idle, transmit, and receive states all consume considerably more energy than idle state. The battery energy consumed by these four states depends on how long the link is in each state.

RETURN VALUE

The value 0 is returned on success. On failure, the value -1 is returned, and the global variable cnet_errno is set to one of the following values to describe the error:

ER_BADLINK

The value of link is not a valid link number.

ER_NOTSUPPORTED

The indicated link is not of type LT_WLAN.

SEE ALSO

CNET_set_wlaninfo.