Revision 6

Overview

Several new commands have been added to the SANA-II API to facilitate use of IEEE 802.11 wireless network devices in client and ad-hoc modes. The new commands are split into two overlapping sets. One set needs to be implemented by drivers for Soft-MAC wireless devices, while the other is implemented for Hard-MAC devices.

Soft-MAC commands
S2_SETOPTIONS
S2_SETKEY
S2_WRITEMGMT
S2_READMGMT

Hard-MAC commands
S2_SETOPTIONS
S2_SETKEY
S2_GETNETWORKS
S2_GETNETWORKINFO
S2_GETSIGNALQUALITY

New constant and structure definitions

See new sana2wireless.h file.

Description of new commands

S2_SETOPTIONS

/****** sana2.device/S2_SETOPTIONS *****************************************
*
*   NAME
*	S2_SETOPTIONS -- Set network options.
*
*   FUNCTION
*	Set various parameters for the network interface. This command
*	should be called before going online to set any essential parameters
*	not covered elsewhere. The S2INFO_#? tags used are defined in the
*	devices/sana2wireless.h include file.
*
*   INPUTS
*	ios2_Data - Pointer to a taglist that specifies parameters to use.
*
*   RESULTS
*	io_Error - Zero if successful; non-zero otherwise.
*	ios2_WireError - More specific error code.
*
****************************************************************************
*
*/

S2_SETKEY

/****** sana2.device/S2_SETKEY *********************************************
*
*   NAME
*	S2_SETKEY -- Set an encryption key.
*
*   FUNCTION
*	Sets one of the encryption keys for the device. Note that
*	ios2_StatData, if used, points to a byte array representing the RX
*	RX counter value.
*
*   INPUTS
*	ios2_WireError - Key index.
*	ios2_PacketType - Encryption type (e.g. S2ENC_WEP).
*	ios2_DataLength - Key length.
*	ios2_Data - Key.
*	ios2_StatData - RX counter number (NULL if unused).
*
*   RESULTS
*	io_Error - Zero if successful; non-zero otherwise.
*	ios2_WireError - More specific error code.
*
****************************************************************************
*
*/

S2_WRITEMGMT

/****** sana2.device/S2_WRITEMGMT ******************************************
*
*   NAME
*	S2_WRITEMGMT -- Write a management frame.
*
*   FUNCTION
*	Writes a raw IEEE 802.11 management frame to the device. The buffer
*	management mechanism used is simpler than that used for data
*	packets (e.g. with CMD_WRITE): a buffer pointer and a length value
*	are passed to the device.
*
*   INPUTS
*	ios2_DataLength - full frame length.
*	ios2_Data - pointer to a complete IEEE 802.11 management frame.
*
*   RESULTS
*	io_Error - Zero if successful; non-zero otherwise.
*	ios2_WireError - More specific error code.
*
****************************************************************************
*
*/

S2_READMGMT

/****** sana2.device/S2_READMGMT *******************************************
*
*   NAME
*	S2_READMGMT -- Read a management frame.
*
*   FUNCTION
*	Reads a raw IEEE 802.11 management frame from the device. The buffer
*	management mechanism used is simpler than that used for data
*	packets (e.g. with CMD_READ): a buffer pointer and a length value
*	are passed to the device.
*
*	As with CMDREAD/S2_READORPHAN, multiple S2_READMGMT requests can
*	(and should) be queued concurrently to ensure no incoming frames are
*	missed.
*
*   INPUTS
*	ios2_DataLength - size of frame buffer.
*	ios2_Data - pointer to a frame buffer.
*
*   RESULTS
*	io_Error - Zero if successful; non-zero otherwise.
*	ios2_WireError - More specific error code.
*	ios2_DataLength - actual size of received frame.
*	ios2_Data - pointer to the filled frame buffer.
*
****************************************************************************
*
*/

S2_GETSIGNALQUALITY

/****** prism2.device/S2_GETSIGNALQUALITY **********************************
*
*   NAME
*	S2_GETSIGNALQUALITY -- Get signal quality statistics.
*
*   FUNCTION
*	This command fills in the supplied Sana2SignalQuality structure with
*	current signal and noise levels. The unit for these figures is dBm.
*	Typically, they are negative values.
*
*   INPUTS
*	ios2_StatData - Pointer to Sana2SignalQuality structure.
*
*   RESULTS
*	io_Error - Zero if successful; non-zero otherwise.
*	ios2_WireError - More specific error code.
*	ios2_StatData - Pointer to filled Sana2SignalQuality structure.
*
****************************************************************************
*
*/

S2_GETNETWORKS

/****** prism2.device/S2_GETNETWORKS ***************************************
*
*   NAME
*	S2_GETNETWORKS -- Scan for available networks.
*
*   FUNCTION
*	This command supplies details of available networks. If the scan
*	should be limited to one specific network, the S2INFO_SSID tag
*	should specify its name.
*
*	If this command completes successfully, ios2_StatData will contain
*	an array of pointers to tag lists, each of which contains
*	information on a single network. The device will set ios2_DataLength
*	to the number of elements in this array.
*
*	The returned taglists are allocated from the supplied memory pool.
*	To discard the results of this command, the entire memory pool
*	should be destroyed.
*
*	The S2INFO_#? tags used with this command are defined in the
*	devices/sana2wireless.h include file.
*
*   INPUTS
*	ios2_Data - Pointer to an Exec memory pool.
*	ios2_StatData - Pointer to taglist that specifies parameters to use.
*
*   RESULTS
*	ios2_DataLength - Number of tag lists returned.
*	ios2_Data - Remains unchanged.
*	ios2_StatData - Pointer to an array of tag lists.
*	io_Error - Zero if successful; non-zero otherwise.
*	ios2_WireError - More specific error code.
*
****************************************************************************
*
*/

S2_GETNETWORKINFO

/****** prism2.device/S2_GETNETWORKINFO ************************************
*
*   NAME
*	S2_GETNETWORKINFO -- Get information on current network.
*
*   FUNCTION
*	This command provides information on the status of the currently
*	used network. If this command completes successfully, ios2_StatData
*	will contain a pointer to a tag list that contains information on
*	the network. The S2INFO_#? tags used are defined in the
*	devices/sana2wireless.h include file.
*
*	The returned taglist is allocated from the supplied memory pool.
*	To discard the results of this command, the entire memory pool
*	should be destroyed.
*
*   INPUTS
*	ios2_Data - Pointer to an Exec memory pool.
*
*   RESULTS
*	ios2_Data - Remains unchanged.
*	ios2_StatData - Pointer to a tag list.
*	io_Error - Zero if successful; non-zero otherwise.
*	ios2_WireError - More specific error code.
*
****************************************************************************
*
*/