1 /* 2 * ScanCncn.h 3 * 4 * Copyright(c) 1998 - 2009 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 /** \enum EScanCncnClient 49 * \brief Scan Concentrator Client 50 * 51 * \par Description 52 * Enumerates the different possible clients requesting scan from the scan concentrator 53 * 54 * \sa 55 */ 56 typedef enum 57 { 58 /* 0 */ SCAN_SCC_ROAMING_IMMED, /**< Indicates a scan from the immediate scan for a roaming client */ 59 /* 1 */ SCAN_SCC_ROAMING_CONT, /**< Indicates a scan from the continuous scan for a roaming client */ 60 /* 2 */ SCAN_SCC_DRIVER, /**< Indicates a scan from the driver client (SME scan) */ 61 /* 3 */ SCAN_SCC_APP_PERIODIC, /**< Indicates application (user) periodic scan */ 62 /* 4 */ SCAN_SCC_APP_ONE_SHOT, /**< Indicates application (user) one shot scan */ 63 /* 5 */ SCAN_SCC_NUM_OF_CLIENTS, /**< Number of scan clients (used internally) */ 64 /* 6 */ SCAN_SCC_NO_CLIENT /**< No valid scan clients (used internally) */ 65 66 } EScanCncnClient; 67 68 /** \enum EScanCncnResultStatus 69 * \brief Scan Concentrator Result Status 70 * 71 * \par Description 72 * Enumerates the possible scan result statuses 73 * 74 * \sa 75 */ 76 typedef enum 77 { 78 /* 0 */ SCAN_CRS_RECEIVED_FRAME = 0, /**< Scan is still running; management frame information is passed. */ 79 /* 1 */ SCAN_CRS_SCAN_COMPLETE_OK, /**< Scan completed successfully */ 80 /* 2 */ SCAN_CRS_SCAN_RUNNING, /**< Scan started successfully and now is running */ 81 /* 3 */ SCAN_CRS_SCAN_FAILED, /**< 82 * scan failed due to unexpected situation (SCR reject, no 83 * channels available, scan SRV returned TI_NOK, etc) 84 */ 85 /* 4 */ SCAN_CRS_SCAN_STOPPED, /**< scan stopped by user */ 86 /* 5 */ SCAN_CRS_TSF_ERROR, /**< TSF error (AP recovery) occurred (for SPS only): 87 * SPS was not performed because current TSF value is less than designated TSF value. 88 */ 89 /* 6 */ SCAN_CRS_SCAN_ABORTED_FW_RESET, /**< scan aborted due to FW reset */ 90 /* 7 */ SCAN_CRS_SCAN_ABORTED_HIGHER_PRIORITY, /**< Scan was aborted because of a higher priority client request of the channel (switched channel) */ 91 /* 8 */ SCAN_CRS_NUM_OF_RES_STATUS /**< number of possible result status */ 92 93 } EScanCncnResultStatus; 94 95 /** \struct TScanFrameInfo 96 * \brief Scan Fram Information 97 * 98 * \par Description 99 * This structure contains a single frame information, returned by the result CB when a frame is available. 100 * It is used to pass scan results (beacons and probe responses). 101 * 102 * \sa 103 */ 104 typedef struct 105 { 106 TMacAddr* bssId; /* BSSID (MAC address) of the AP from which the frame was received */ 107 mlmeFrameInfo_t* parsedIEs; /* Information elements in the frame, which is parsed */ 108 ERadioBand band; /* Band on which the frame was received */ 109 TI_UINT8 channel; /* Channel on which the frame was received */ 110 TI_UINT32 staTSF; /* TSF of the station when the frame was received */ 111 TI_INT8 rssi; /* RSSI level at which frame was received */ 112 TI_INT8 snr; /* SNR level at which frame was received */ 113 ERate rate; /* Bitrate at which frame was received */ 114 TI_UINT8* buffer; /* Frame information elements, unparsed */ 115 TI_UINT16 bufferLength; /* Length of the frame unparsed information elements */ 116 } TScanFrameInfo; 117 118 /** \typedef TScanResultCB 119 * \brief Defines the function prototype for the scan result callback 120 * (notification by the scan concentrator to a client of either a scan 121 * termination or a result frame received). 122 */ 123 /** 124 * \brief Scan Result CB 125 * 126 * \param clientObj - TWD module object handle 127 * \param status - TID number 128 * \param frameInfo - Policy : Enable / Disable 129 * \param SPSStatus - Mac address of: SA as receiver / RA as initiator 130 * \return void 131 * 132 * \par Description 133 * Defines the function prototype for the scan result callback 134 * (notification by the scan concentrator to a client of either a scan termination or a result frame received) 135 * This CB is egistered by each client and invoked by the scan concentrator, passes scan results to the caller. 136 * 137 * \sa 138 */ 139 typedef void (*TScanResultCB) (TI_HANDLE clientObj, EScanCncnResultStatus status, 140 TScanFrameInfo* frameInfo, TI_UINT16 SPSStatus); 141 142 143 TI_HANDLE scanCncn_Create (TI_HANDLE hOS); 144 void scanCncn_Destroy (TI_HANDLE hScanCncn); 145 void scanCncn_Init (TStadHandlesList *pStadHandles); 146 void scanCncn_SetDefaults (TI_HANDLE hScanCncn, TScanCncnInitParams* pScanCncnInitParams); 147 void scanCncn_SwitchToConnected (TI_HANDLE hScanCncn); 148 void scanCncn_SwitchToNotConnected (TI_HANDLE hScanCncn); 149 void scanCncn_SwitchToIBSS (TI_HANDLE hScanCncn); 150 /** 151 * \brief Starts a one-shot scan operation 152 * 153 * \param hScanCncn - Handle to the scan concentrator object 154 * \param eClient - The client requesting the scan operation 155 * \param pScanParams - Parameters for the requested scan 156 * \return Scan Concentrator Result Status: 157 * SCAN_CRS_SCAN_RUNNING - scan started successfully and is now running 158 * SCAN_CRS_SCAN_FAILED - scan failed to start due to an unexpected error 159 * 160 * \par Description 161 * Starts a one-shot scan operation: 162 * - copies scan params to scan concentrator object 163 * - copies current SSID for roaming scans 164 * - verifies the requested channels with the reg doamin 165 * - if needed, adjust to SG compensation values 166 * - send an event to the client SM 167 * 168 * \sa scanCncn_StopScan 169 */ 170 EScanCncnResultStatus scanCncn_Start1ShotScan (TI_HANDLE hScanCncn, EScanCncnClient eClient, TScanParams* pScanParams); 171 /** 172 * \brief Stop an on-going one-shot scan operation 173 * 174 * \param hScanCncn - Handle to the scan concentrator object 175 * \param eClient - The client requesting to stop the scan operation 176 * \return void 177 * 178 * \par Description 179 * Set necessary flags and send a stop scan event to the client SM 180 * 181 * \sa scanCncn_Start1ShotScan 182 */ 183 void scanCncn_StopScan (TI_HANDLE hScanCncn, EScanCncnClient eClient); 184 EScanCncnResultStatus scanCncn_StartPeriodicScan (TI_HANDLE hScanCncn, EScanCncnClient eClient, 185 TPeriodicScanParams *pScanParams); 186 void scanCncn_StopPeriodicScan (TI_HANDLE hScanCncn, EScanCncnClient eClient); 187 /** 188 * \brief Registers a scan complete object 189 * 190 * \param hScanCncn - Handle to the scan concentrator object 191 * \param eClient - The client requesting to stop the scan operation 192 * \param scanResultCBFunc - Pointer to the resulting callback function 193 * \param scanResultCBObj - Object passed to the scan resulting callback function 194 * \return void 195 * 196 * \par Description 197 * Registers a callback function for a client that is called for every scan result and scan complete event. 198 * It is called by each client one time before issuing a scan request. 199 * 200 * \sa 201 */ 202 void scanCncn_RegisterScanResultCB (TI_HANDLE hScanCncn, EScanCncnClient eClient, 203 TScanResultCB scanResultCBFunc, TI_HANDLE scanResultCBObj); 204 void scanCncn_ScanCompleteNotificationCB (TI_HANDLE hScanCncn, EScanResultTag eTag, 205 TI_UINT32 uResultCount, TI_UINT16 SPSStatus, 206 TI_BOOL bTSFError, TI_STATUS scanStatus, 207 TI_STATUS PSMode); 208 void scanCncn_MlmeResultCB (TI_HANDLE hScanCncn, TMacAddr* bssid, mlmeFrameInfo_t* frameInfo, 209 TRxAttr* pRxAttr, TI_UINT8* buffer, TI_UINT16 bufferLength); 210 void scanCncn_ScrRoamingImmedCB (TI_HANDLE hScanCncn, EScrClientRequestStatus eRequestStatus, 211 EScrResourceId eResource, EScePendReason ePendReason); 212 void scanCncn_ScrRoamingContCB (TI_HANDLE hScanCncn, EScrClientRequestStatus eRequestStatus, 213 EScrResourceId eResource, EScePendReason ePendReason); 214 void scanCncn_ScrAppCB (TI_HANDLE hScanCncn, EScrClientRequestStatus eRequestStatus, 215 EScrResourceId eResource, EScePendReason ePendReason ); 216 void scanCncn_ScrDriverCB (TI_HANDLE hScanCncn, EScrClientRequestStatus eRequestStatus, 217 EScrResourceId eResource, EScePendReason ePendReason); 218 void scanCncn_SGconfigureScanParams (TI_HANDLE hScanCncn, TI_BOOL bUseSGParams, 219 TI_UINT8 probeReqPercent, TI_UINT32 SGcompensationMaxTime, 220 TI_UINT32 SGcompensationPercent); 221 /* Scan concentrator application functions */ 222 TI_STATUS scanCncnApp_SetParam (TI_HANDLE hScanCncn, paramInfo_t *pParam); 223 TI_STATUS scanCncnApp_GetParam (TI_HANDLE hScanCncn, paramInfo_t *pParam); 224 void scanCncn_AppScanResultCB (TI_HANDLE hScanCncn, EScanCncnResultStatus status, 225 TScanFrameInfo* frameInfo, TI_UINT16 SPSStatus); 226 void scanCncn_PeriodicScanCompleteCB (TI_HANDLE hScanCncn, char* str, TI_UINT32 strLen); 227 void scanCncn_PeriodicScanReportCB (TI_HANDLE hScanCncn, char* str, TI_UINT32 strLen); 228 229 #endif /* __SCANCNCN_H__ */ 230 231