blob: 1c1fe0c230af1fcebaabb07a4ffba68e8b34f794 [file] [log] [blame]
/*
* ScanCncn.h
*
* Copyright(c) 1998 - 2010 Texas Instruments. All rights reserved.
* All rights reserved.
*
* Redistribution and use in source and binary forms, with or without
* modification, are permitted provided that the following conditions
* are met:
*
* * Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
* * Redistributions in binary form must reproduce the above copyright
* notice, this list of conditions and the following disclaimer in
* the documentation and/or other materials provided with the
* distribution.
* * Neither the name Texas Instruments nor the names of its
* contributors may be used to endorse or promote products derived
* from this software without specific prior written permission.
*
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
* "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
* LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
* A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
* OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
* DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
* THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
* (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
* OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
*/
/** \file ScanCncn.h
* \brief Scan concentartor module API
*
* \see ScanCncn.c
*/
#ifndef __SCANCNCN_H__
#define __SCANCNCN_H__
#include "osTIType.h"
#include "TWDriver.h"
#include "scrApi.h"
#include "mlmeApi.h"
#define SCAN_CNCN_APP_SCAN_TABLE_ENTRIES 64
/** \enum EScanCncnClient
* \brief Scan Concentrator Client
*
* \par Description
* Enumerates the different possible clients requesting scan from the scan concentrator
*
* \sa
*/
typedef enum
{
/* 0 */ SCAN_SCC_ROAMING_IMMED, /**< Indicates a scan from the immediate scan for a roaming client */
/* 1 */ SCAN_SCC_ROAMING_CONT, /**< Indicates a scan from the continuous scan for a roaming client */
/* 2 */ SCAN_SCC_DRIVER, /**< Indicates a scan from the driver client (SME scan) */
/* 3 */ SCAN_SCC_APP_PERIODIC, /**< Indicates application (user) periodic scan */
/* 4 */ SCAN_SCC_APP_ONE_SHOT, /**< Indicates application (user) one shot scan */
/* 5 */ SCAN_SCC_NUM_OF_CLIENTS, /**< Number of scan clients (used internally) */
/* 6 */ SCAN_SCC_NO_CLIENT /**< No valid scan clients (used internally) */
} EScanCncnClient;
/** \enum EScanCncnResultStatus
* \brief Scan Concentrator Result Status
*
* \par Description
* Enumerates the possible scan result statuses
*
* \sa
*/
typedef enum
{
/* 0 */ SCAN_CRS_RECEIVED_FRAME = 0, /**< Scan is still running; management frame information is passed. */
/* 1 */ SCAN_CRS_SCAN_COMPLETE_OK, /**< Scan completed successfully */
/* 2 */ SCAN_CRS_SCAN_RUNNING, /**< Scan started successfully and now is running */
/* 3 */ SCAN_CRS_SCAN_FAILED, /**<
* scan failed due to unexpected situation (SCR reject, no
* channels available, scan SRV returned TI_NOK, etc)
*/
/* 4 */ SCAN_CRS_SCAN_STOPPED, /**< scan stopped by user */
/* 5 */ SCAN_CRS_TSF_ERROR, /**< TSF error (AP recovery) occurred (for SPS only):
* SPS was not performed because current TSF value is less than designated TSF value.
*/
/* 6 */ SCAN_CRS_SCAN_ABORTED_FW_RESET, /**< scan aborted due to FW reset */
/* 7 */ SCAN_CRS_SCAN_ABORTED_HIGHER_PRIORITY, /**< Scan was aborted because of a higher priority client request of the channel (switched channel) */
/* 8 */ SCAN_CRS_NUM_OF_RES_STATUS /**< number of possible result status */
} EScanCncnResultStatus;
/** \struct TScanFrameInfo
* \brief Scan Fram Information
*
* \par Description
* This structure contains a single frame information, returned by the result CB when a frame is available.
* It is used to pass scan results (beacons and probe responses).
*
* \sa
*/
typedef struct
{
TMacAddr* bssId; /* BSSID (MAC address) of the AP from which the frame was received */
mlmeFrameInfo_t* parsedIEs; /* Information elements in the frame, which is parsed */
ERadioBand band; /* Band on which the frame was received */
TI_UINT8 channel; /* Channel on which the frame was received */
TI_UINT32 staTSF; /* TSF of the station when the frame was received */
TI_INT8 rssi; /* RSSI level at which frame was received */
TI_INT8 snr; /* SNR level at which frame was received */
ERate rate; /* Bitrate at which frame was received */
TI_UINT8* buffer; /* Frame information elements, unparsed */
TI_UINT16 bufferLength; /* Length of the frame unparsed information elements */
} TScanFrameInfo;
/** \typedef TScanResultCB
* \brief Defines the function prototype for the scan result callback
* (notification by the scan concentrator to a client of either a scan
* termination or a result frame received).
*/
/**
* \brief Scan Result CB
*
* \param clientObj - TWD module object handle
* \param status - TID number
* \param frameInfo - Policy : Enable / Disable
* \param SPSStatus - Mac address of: SA as receiver / RA as initiator
* \return void
*
* \par Description
* Defines the function prototype for the scan result callback
* (notification by the scan concentrator to a client of either a scan termination or a result frame received)
* This CB is egistered by each client and invoked by the scan concentrator, passes scan results to the caller.
*
* \sa
*/
typedef void (*TScanResultCB) (TI_HANDLE clientObj, EScanCncnResultStatus status,
TScanFrameInfo* frameInfo, TI_UINT16 SPSStatus);
TI_HANDLE scanCncn_Create (TI_HANDLE hOS);
void scanCncn_Destroy (TI_HANDLE hScanCncn);
void scanCncn_Init (TStadHandlesList *pStadHandles);
void scanCncn_SetDefaults (TI_HANDLE hScanCncn, TScanCncnInitParams* pScanCncnInitParams);
void scanCncn_SwitchToConnected (TI_HANDLE hScanCncn);
void scanCncn_SwitchToNotConnected (TI_HANDLE hScanCncn);
void scanCncn_SwitchToIBSS (TI_HANDLE hScanCncn);
/**
* \brief Starts a one-shot scan operation
*
* \param hScanCncn - Handle to the scan concentrator object
* \param eClient - The client requesting the scan operation
* \param pScanParams - Parameters for the requested scan
* \return Scan Concentrator Result Status:
* SCAN_CRS_SCAN_RUNNING - scan started successfully and is now running
* SCAN_CRS_SCAN_FAILED - scan failed to start due to an unexpected error
*
* \par Description
* Starts a one-shot scan operation:
* - copies scan params to scan concentrator object
* - copies current SSID for roaming scans
* - verifies the requested channels with the reg doamin
* - if needed, adjust to SG compensation values
* - send an event to the client SM
*
* \sa scanCncn_StopScan
*/
EScanCncnResultStatus scanCncn_Start1ShotScan (TI_HANDLE hScanCncn, EScanCncnClient eClient, TScanParams* pScanParams);
/**
* \brief Stop an on-going one-shot scan operation
*
* \param hScanCncn - Handle to the scan concentrator object
* \param eClient - The client requesting to stop the scan operation
* \return void
*
* \par Description
* Set necessary flags and send a stop scan event to the client SM
*
* \sa scanCncn_Start1ShotScan
*/
void scanCncn_StopScan (TI_HANDLE hScanCncn, EScanCncnClient eClient);
EScanCncnResultStatus scanCncn_StartPeriodicScan (TI_HANDLE hScanCncn, EScanCncnClient eClient,
TPeriodicScanParams *pScanParams);
void scanCncn_StopPeriodicScan (TI_HANDLE hScanCncn, EScanCncnClient eClient);
/**
* \brief Registers a scan complete object
*
* \param hScanCncn - Handle to the scan concentrator object
* \param eClient - The client requesting to stop the scan operation
* \param scanResultCBFunc - Pointer to the resulting callback function
* \param scanResultCBObj - Object passed to the scan resulting callback function
* \return void
*
* \par Description
* Registers a callback function for a client that is called for every scan result and scan complete event.
* It is called by each client one time before issuing a scan request.
*
* \sa
*/
void scanCncn_RegisterScanResultCB (TI_HANDLE hScanCncn, EScanCncnClient eClient,
TScanResultCB scanResultCBFunc, TI_HANDLE scanResultCBObj);
void scanCncn_ScanCompleteNotificationCB (TI_HANDLE hScanCncn, EScanResultTag eTag,
TI_UINT32 uResultCount, TI_UINT16 SPSStatus,
TI_BOOL bTSFError, TI_STATUS scanStatus,
TI_STATUS PSMode);
void scanCncn_MlmeResultCB (TI_HANDLE hScanCncn, TMacAddr* bssid, mlmeFrameInfo_t* frameInfo,
TRxAttr* pRxAttr, TI_UINT8* buffer, TI_UINT16 bufferLength);
void scanCncn_ScrRoamingImmedCB (TI_HANDLE hScanCncn, EScrClientRequestStatus eRequestStatus,
EScrResourceId eResource, EScePendReason ePendReason);
void scanCncn_ScrRoamingContCB (TI_HANDLE hScanCncn, EScrClientRequestStatus eRequestStatus,
EScrResourceId eResource, EScePendReason ePendReason);
void scanCncn_ScrAppCB (TI_HANDLE hScanCncn, EScrClientRequestStatus eRequestStatus,
EScrResourceId eResource, EScePendReason ePendReason );
void scanCncn_ScrDriverCB (TI_HANDLE hScanCncn, EScrClientRequestStatus eRequestStatus,
EScrResourceId eResource, EScePendReason ePendReason);
void scanCncn_SGconfigureScanParams (TI_HANDLE hScanCncn, TI_BOOL bUseSGParams,
TI_UINT8 probeReqPercent, TI_UINT32 SGcompensationMaxTime,
TI_UINT32 SGcompensationPercent);
/* Scan concentrator application functions */
TI_STATUS scanCncnApp_SetParam (TI_HANDLE hScanCncn, paramInfo_t *pParam);
TI_STATUS scanCncnApp_GetParam (TI_HANDLE hScanCncn, paramInfo_t *pParam);
void scanCncn_AppScanResultCB (TI_HANDLE hScanCncn, EScanCncnResultStatus status,
TScanFrameInfo* frameInfo, TI_UINT16 SPSStatus);
void scanCncn_PeriodicScanCompleteCB (TI_HANDLE hScanCncn, char* str, TI_UINT32 strLen);
void scanCncn_PeriodicScanReportCB (TI_HANDLE hScanCncn, char* str, TI_UINT32 strLen);
#endif /* __SCANCNCN_H__ */