1 /* 2 * ScanCncn.h 3 * 4 * Copyright(c) 1998 - 2010 Texas Instruments. All rights reserved. 5 * All rights reserved. 6 * 7 * Redistribution and use in source and binary forms, with or without 8 * modification, are permitted provided that the following conditions 9 * are met: 10 * 11 * * Redistributions of source code must retain the above copyright 12 * notice, this list of conditions and the following disclaimer. 13 * * Redistributions in binary form must reproduce the above copyright 14 * notice, this list of conditions and the following disclaimer in 15 * the documentation and/or other materials provided with the 16 * distribution. 17 * * Neither the name Texas Instruments nor the names of its 18 * contributors may be used to endorse or promote products derived 19 * from this software without specific prior written permission. 20 * 21 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 22 * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 23 * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR 24 * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT 25 * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 26 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT 27 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 28 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 29 * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 30 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE 31 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 32 */ 33 34 /** \file ScanCncn.h 35 * \brief Scan concentartor module API 36 * 37 * \see ScanCncn.c 38 */ 39 40 #ifndef __SCANCNCN_H__ 41 #define __SCANCNCN_H__ 42 43 #include "osTIType.h" 44 #include "TWDriver.h" 45 #include "scrApi.h" 46 #include "mlmeApi.h" 47 48 #define SCAN_CNCN_APP_SCAN_TABLE_ENTRIES 64 49 50 /** \enum EScanCncnClient 51 * \brief Scan Concentrator Client 52 * 53 * \par Description 54 * Enumerates the different possible clients requesting scan from the scan concentrator 55 * 56 * \sa 57 */ 58 typedef enum 59 { 60 /* 0 */ SCAN_SCC_ROAMING_IMMED, /**< Indicates a scan from the immediate scan for a roaming client */ 61 /* 1 */ SCAN_SCC_ROAMING_CONT, /**< Indicates a scan from the continuous scan for a roaming client */ 62 /* 2 */ SCAN_SCC_DRIVER, /**< Indicates a scan from the driver client (SME scan) */ 63 /* 3 */ SCAN_SCC_APP_PERIODIC, /**< Indicates application (user) periodic scan */ 64 /* 4 */ SCAN_SCC_APP_ONE_SHOT, /**< Indicates application (user) one shot scan */ 65 /* 5 */ SCAN_SCC_NUM_OF_CLIENTS, /**< Number of scan clients (used internally) */ 66 /* 6 */ SCAN_SCC_NO_CLIENT /**< No valid scan clients (used internally) */ 67 68 } EScanCncnClient; 69 70 /** \enum EScanCncnResultStatus 71 * \brief Scan Concentrator Result Status 72 * 73 * \par Description 74 * Enumerates the possible scan result statuses 75 * 76 * \sa 77 */ 78 typedef enum 79 { 80 /* 0 */ SCAN_CRS_RECEIVED_FRAME = 0, /**< Scan is still running; management frame information is passed. */ 81 /* 1 */ SCAN_CRS_SCAN_COMPLETE_OK, /**< Scan completed successfully */ 82 /* 2 */ SCAN_CRS_SCAN_RUNNING, /**< Scan started successfully and now is running */ 83 /* 3 */ SCAN_CRS_SCAN_FAILED, /**< 84 * scan failed due to unexpected situation (SCR reject, no 85 * channels available, scan SRV returned TI_NOK, etc) 86 */ 87 /* 4 */ SCAN_CRS_SCAN_STOPPED, /**< scan stopped by user */ 88 /* 5 */ SCAN_CRS_TSF_ERROR, /**< TSF error (AP recovery) occurred (for SPS only): 89 * SPS was not performed because current TSF value is less than designated TSF value. 90 */ 91 /* 6 */ SCAN_CRS_SCAN_ABORTED_FW_RESET, /**< scan aborted due to FW reset */ 92 /* 7 */ SCAN_CRS_SCAN_ABORTED_HIGHER_PRIORITY, /**< Scan was aborted because of a higher priority client request of the channel (switched channel) */ 93 /* 8 */ SCAN_CRS_NUM_OF_RES_STATUS /**< number of possible result status */ 94 95 } EScanCncnResultStatus; 96 97 /** \struct TScanFrameInfo 98 * \brief Scan Fram Information 99 * 100 * \par Description 101 * This structure contains a single frame information, returned by the result CB when a frame is available. 102 * It is used to pass scan results (beacons and probe responses). 103 * 104 * \sa 105 */ 106 typedef struct 107 { 108 TMacAddr* bssId; /* BSSID (MAC address) of the AP from which the frame was received */ 109 mlmeFrameInfo_t* parsedIEs; /* Information elements in the frame, which is parsed */ 110 ERadioBand band; /* Band on which the frame was received */ 111 TI_UINT8 channel; /* Channel on which the frame was received */ 112 TI_UINT32 staTSF; /* TSF of the station when the frame was received */ 113 TI_INT8 rssi; /* RSSI level at which frame was received */ 114 TI_INT8 snr; /* SNR level at which frame was received */ 115 ERate rate; /* Bitrate at which frame was received */ 116 TI_UINT8* buffer; /* Frame information elements, unparsed */ 117 TI_UINT16 bufferLength; /* Length of the frame unparsed information elements */ 118 } TScanFrameInfo; 119 120 /** \typedef TScanResultCB 121 * \brief Defines the function prototype for the scan result callback 122 * (notification by the scan concentrator to a client of either a scan 123 * termination or a result frame received). 124 */ 125 /** 126 * \brief Scan Result CB 127 * 128 * \param clientObj - TWD module object handle 129 * \param status - TID number 130 * \param frameInfo - Policy : Enable / Disable 131 * \param SPSStatus - Mac address of: SA as receiver / RA as initiator 132 * \return void 133 * 134 * \par Description 135 * Defines the function prototype for the scan result callback 136 * (notification by the scan concentrator to a client of either a scan termination or a result frame received) 137 * This CB is egistered by each client and invoked by the scan concentrator, passes scan results to the caller. 138 * 139 * \sa 140 */ 141 typedef void (*TScanResultCB) (TI_HANDLE clientObj, EScanCncnResultStatus status, 142 TScanFrameInfo* frameInfo, TI_UINT16 SPSStatus); 143 144 145 TI_HANDLE scanCncn_Create (TI_HANDLE hOS); 146 void scanCncn_Destroy (TI_HANDLE hScanCncn); 147 void scanCncn_Init (TStadHandlesList *pStadHandles); 148 void scanCncn_SetDefaults (TI_HANDLE hScanCncn, TScanCncnInitParams* pScanCncnInitParams); 149 void scanCncn_SwitchToConnected (TI_HANDLE hScanCncn); 150 void scanCncn_SwitchToNotConnected (TI_HANDLE hScanCncn); 151 void scanCncn_SwitchToIBSS (TI_HANDLE hScanCncn); 152 /** 153 * \brief Starts a one-shot scan operation 154 * 155 * \param hScanCncn - Handle to the scan concentrator object 156 * \param eClient - The client requesting the scan operation 157 * \param pScanParams - Parameters for the requested scan 158 * \return Scan Concentrator Result Status: 159 * SCAN_CRS_SCAN_RUNNING - scan started successfully and is now running 160 * SCAN_CRS_SCAN_FAILED - scan failed to start due to an unexpected error 161 * 162 * \par Description 163 * Starts a one-shot scan operation: 164 * - copies scan params to scan concentrator object 165 * - copies current SSID for roaming scans 166 * - verifies the requested channels with the reg doamin 167 * - if needed, adjust to SG compensation values 168 * - send an event to the client SM 169 * 170 * \sa scanCncn_StopScan 171 */ 172 EScanCncnResultStatus scanCncn_Start1ShotScan (TI_HANDLE hScanCncn, EScanCncnClient eClient, TScanParams* pScanParams); 173 /** 174 * \brief Stop an on-going one-shot scan operation 175 * 176 * \param hScanCncn - Handle to the scan concentrator object 177 * \param eClient - The client requesting to stop the scan operation 178 * \return void 179 * 180 * \par Description 181 * Set necessary flags and send a stop scan event to the client SM 182 * 183 * \sa scanCncn_Start1ShotScan 184 */ 185 void scanCncn_StopScan (TI_HANDLE hScanCncn, EScanCncnClient eClient); 186 EScanCncnResultStatus scanCncn_StartPeriodicScan (TI_HANDLE hScanCncn, EScanCncnClient eClient, 187 TPeriodicScanParams *pScanParams); 188 void scanCncn_StopPeriodicScan (TI_HANDLE hScanCncn, EScanCncnClient eClient); 189 /** 190 * \brief Registers a scan complete object 191 * 192 * \param hScanCncn - Handle to the scan concentrator object 193 * \param eClient - The client requesting to stop the scan operation 194 * \param scanResultCBFunc - Pointer to the resulting callback function 195 * \param scanResultCBObj - Object passed to the scan resulting callback function 196 * \return void 197 * 198 * \par Description 199 * Registers a callback function for a client that is called for every scan result and scan complete event. 200 * It is called by each client one time before issuing a scan request. 201 * 202 * \sa 203 */ 204 void scanCncn_RegisterScanResultCB (TI_HANDLE hScanCncn, EScanCncnClient eClient, 205 TScanResultCB scanResultCBFunc, TI_HANDLE scanResultCBObj); 206 void scanCncn_ScanCompleteNotificationCB (TI_HANDLE hScanCncn, EScanResultTag eTag, 207 TI_UINT32 uResultCount, TI_UINT16 SPSStatus, 208 TI_BOOL bTSFError, TI_STATUS scanStatus, 209 TI_STATUS PSMode); 210 void scanCncn_MlmeResultCB (TI_HANDLE hScanCncn, TMacAddr* bssid, mlmeFrameInfo_t* frameInfo, 211 TRxAttr* pRxAttr, TI_UINT8* buffer, TI_UINT16 bufferLength); 212 void scanCncn_ScrRoamingImmedCB (TI_HANDLE hScanCncn, EScrClientRequestStatus eRequestStatus, 213 EScrResourceId eResource, EScePendReason ePendReason); 214 void scanCncn_ScrRoamingContCB (TI_HANDLE hScanCncn, EScrClientRequestStatus eRequestStatus, 215 EScrResourceId eResource, EScePendReason ePendReason); 216 void scanCncn_ScrAppCB (TI_HANDLE hScanCncn, EScrClientRequestStatus eRequestStatus, 217 EScrResourceId eResource, EScePendReason ePendReason ); 218 void scanCncn_ScrDriverCB (TI_HANDLE hScanCncn, EScrClientRequestStatus eRequestStatus, 219 EScrResourceId eResource, EScePendReason ePendReason); 220 void scanCncn_SGconfigureScanParams (TI_HANDLE hScanCncn, TI_BOOL bUseSGParams, 221 TI_UINT8 probeReqPercent, TI_UINT32 SGcompensationMaxTime, 222 TI_UINT32 SGcompensationPercent); 223 /* Scan concentrator application functions */ 224 TI_STATUS scanCncnApp_SetParam (TI_HANDLE hScanCncn, paramInfo_t *pParam); 225 TI_STATUS scanCncnApp_GetParam (TI_HANDLE hScanCncn, paramInfo_t *pParam); 226 void scanCncn_AppScanResultCB (TI_HANDLE hScanCncn, EScanCncnResultStatus status, 227 TScanFrameInfo* frameInfo, TI_UINT16 SPSStatus); 228 void scanCncn_PeriodicScanCompleteCB (TI_HANDLE hScanCncn, char* str, TI_UINT32 strLen); 229 void scanCncn_PeriodicScanReportCB (TI_HANDLE hScanCncn, char* str, TI_UINT32 strLen); 230 231 #endif /* __SCANCNCN_H__ */ 232 233
