1 /** \file ScanCncnApi.h 2 * \brief This file include public definitions for the scan concentrator module, comprising its API. 3 * \author Ronen Kalish 4 * \date 30-Dec-2004 5 */ 6 /**************************************************************************** 7 **+-----------------------------------------------------------------------+** 8 **| |** 9 **| Copyright(c) 1998 - 2008 Texas Instruments. All rights reserved. |** 10 **| All rights reserved. |** 11 **| |** 12 **| Redistribution and use in source and binary forms, with or without |** 13 **| modification, are permitted provided that the following conditions |** 14 **| are met: |** 15 **| |** 16 **| * Redistributions of source code must retain the above copyright |** 17 **| notice, this list of conditions and the following disclaimer. |** 18 **| * Redistributions in binary form must reproduce the above copyright |** 19 **| notice, this list of conditions and the following disclaimer in |** 20 **| the documentation and/or other materials provided with the |** 21 **| distribution. |** 22 **| * Neither the name Texas Instruments nor the names of its |** 23 **| contributors may be used to endorse or promote products derived |** 24 **| from this software without specific prior written permission. |** 25 **| |** 26 **| THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS |** 27 **| "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT |** 28 **| LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR |** 29 **| A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT |** 30 **| OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, |** 31 **| SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT |** 32 **| LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, |** 33 **| DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY |** 34 **| THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT |** 35 **| (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE |** 36 **| OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |** 37 **| |** 38 **+-----------------------------------------------------------------------+** 39 ****************************************************************************/ 40 41 #ifndef __SCANCNCNAPI_H__ 42 #define __SCANCNCNAPI_H__ 43 44 #include "osApi.h" 45 #include "scrApi.h" 46 #include "paramOut.h" 47 #include "mlmeApi.h" 48 #include "MacServices_api.h" 49 50 51 /** \enum connectionStatus_e 52 * \brief enumerates the different connection statuses 53 */ 54 typedef enum 55 { 56 STA_CONNECTED = 0, /**< the station is connected to an infrastructure BSS */ 57 STA_NOT_CONNECTED, /**< the station is not connected to an infrastructure BSS */ 58 STA_IBSS /**< the station is participating in an IBSS */ 59 } connectionStatus_e; 60 61 62 /** \enum scan_CncnClient_e 63 * \brief enumerates the different possible clients requesting scan from the scan concentrator 64 */ 65 typedef enum 66 { 67 SCAN_SCC_ROAMING_IMMED = 0, /**< immediate scan for roaming */ 68 SCAN_SCC_ROAMING_CONT, /**< continuous scan for roaming */ 69 SCAN_SCC_DRIVER, /**< driver (SME) scan */ 70 SCAN_SCC_APP, /**< application (user) scan */ 71 SCAN_SCC_NUM_OF_CLIENTS, /**< number of clients */ 72 SCAN_SCC_NO_CLIENT /**< no client */ 73 } scan_CncnClient_e; 74 75 /** \enum scan_cncnResultStatus_e 76 * \brief enumerates the different scan result statuses 77 */ 78 typedef enum 79 { 80 SCAN_CRS_RECEIVED_FRAME = 0, /**< scan not yet completed, indicating a frame received during scan */ 81 SCAN_CRS_SCAN_COMPLETE_OK, /**< scan completed normally */ 82 SCAN_CRS_SCAN_RUNNING, /**< scan initialized successfully and is now running */ 83 SCAN_CRS_SCAN_FAILED, /**< 84 * scan failed due to unexpected situation (SCR reject, no 85 * channels available, scan SRV returned NOK, etc) 86 */ 87 SCAN_CRS_SCAN_STOPPED, /**< scan stopped by user */ 88 SCAN_CRS_TSF_ERROR, /**< TSF error (AP recovery) occurred (for SPS only */ 89 SCAN_CRS_SCAN_ABORTED_FW_RESET, /**< scan aborted due to FW reset */ 90 SCAN_CRS_SCAN_ABORTED_HIGHER_PRIORITY, /**< scan aborted due to a higher priority client */ 91 SCAN_CRS_NUM_OF_RES_STATUS /**< number of possible result status */ 92 } scan_cncnResultStatus_e; 93 94 /* 95 *********************************************************************** 96 * External data definitions. 97 *********************************************************************** 98 */ 99 100 /** \struct scan_frameInfo_t 101 * \brief contains a single frame information, returned by the result CB when a frame is available 102 */ 103 typedef struct 104 { 105 macAddress_t* bssId; /* MAC address of the AP from which the frame was received */ 106 mlmeFrameInfo_t* parsedIEs; /* parsed frame IEs */ 107 radioBand_e band; /* band on which the frame was received */ 108 UINT8 channel; /* channel on which the frame was received */ 109 UINT32 staTSF; /* TSF of the station when the frame was received */ 110 INT8 rssi; /* RSSI level at which frame was received */ 111 rate_e rate; /* bitrate at which frame was received */ 112 UINT8* buffer; /* frame body */ 113 UINT16 bufferLength; /* frame body length */ 114 } scan_frameInfo_t; 115 116 /* 117 *********************************************************************** 118 * Typedefs. 119 *********************************************************************** 120 */ 121 122 /** \typedef scan_resultCB_t 123 * \brief Defines the function prototype for the scan result callback 124 * (notification by the scan concentrator to a client of either a scan 125 * termination or a result frame received). 126 */ 127 typedef void (*scan_resultCB_t) ( TI_HANDLE clientObj, scan_cncnResultStatus_e status, 128 scan_frameInfo_t* frameInfo, UINT16 SPSStatus ); 129 130 /* 131 *********************************************************************** 132 * External functions definitions 133 *********************************************************************** 134 */ 135 136 /** 137 * \author Ronen Kalish\n 138 * \date 02-Jan-2005\n 139 * \brief Creates the scan concentrator object 140 * 141 * Function Scope \e Public.\n 142 * \param hOS - handle to the OS object.\n 143 * \return a handle to the scan SRV object, NULL if an error occurred.\n 144 */ 145 TI_HANDLE scanConcentrator_create( TI_HANDLE hOS ); 146 147 /** 148 * \author Ronen Kalish\n 149 * \date 02-Jan-2005\n 150 * \brief Finalizes the scan concentrator object (freeing system resources) 151 * 152 * Function Scope \e Public.\n 153 * \param hScanCncn - handle to the scan concentrator object.\n 154 */ 155 void scanConcentrator_release( TI_HANDLE hScanCncn ); 156 157 /** 158 * \author Ronen Kalish\n 159 * \date 02-Jan-2005\n 160 * \brief Initialize the scan concentrator object. 161 * 162 * Function Scope \e Public.\n 163 * \param hScanCncn - handle to the scan concentrator object.\n 164 * \param hHalCtrl - handle to the Hal Ctrl object.\n 165 * \param hReport - handle to the Report object.\n 166 * \param hRegDomain - handle to the regulatory domain object.\n 167 * \param hSiteMngr - handle to the site manager object.\n 168 * \param hSCR - handle to the SCR object.\n 169 * \param hMacServices - handle to the MacServices object.\n 170 * \param hAPConn - handle to the AP connection object.\n 171 * \param hEventSRV - handle to the event SRV object.\n 172 * \param hMlme - handle to the MLME object.\n 173 * \param hCtrlData - handle to the data CTRL object.\n 174 * \param hHealthMonitor - handle to the health monitor object.\n 175 * \param pScanConcentratorInitParams - pointer to the init parameters structure.\n 176 */ 177 void scanConcentrator_init( TI_HANDLE hScanCncn, 178 TI_HANDLE hHalCtrl, 179 TI_HANDLE hReport, 180 TI_HANDLE hRegDomain, 181 TI_HANDLE hSiteMngr, 182 TI_HANDLE hSCR, 183 TI_HANDLE hMacServices, 184 TI_HANDLE hAPConn, 185 TI_HANDLE hEventSRV, 186 TI_HANDLE hMlme, 187 TI_HANDLE hCtrlData, 188 TI_HANDLE hHealthMonitor, 189 scanConcentratorInitParams_t *pScanConcentratorInitParams ); 190 191 /** 192 * \author Ronen Kalish\n 193 * \date 02-Jan-2005\n 194 * \brief switch the connection mode to connected (infrastructure BSS) 195 * 196 * Function Scope \e Public.\n 197 * \param hScanCncn - handle to the scan concentrator object.\n 198 */ 199 void scanConcentrator_switchToConnected( TI_HANDLE hScanCncn ); 200 201 /** 202 * \author Ronen Kalish\n 203 * \date 02-Jan-2005\n 204 * \brief switch the connection mode to not connected 205 * 206 * Function Scope \e Public.\n 207 * \param hScanCncn - handle to the scan concentrator object.\n 208 */ 209 void scanConcentrator_switchToNotConnected( TI_HANDLE hScanCncn ); 210 211 /** 212 * \author Ronen Kalish\n 213 * \date 02-Jan-2005\n 214 * \brief switch the connection mode to IBSS participation 215 * 216 * Function Scope \e Public.\n 217 * \param hScanCncn - handle to the scan concentrator object.\n 218 */ 219 void scanConcentrator_switchToIBSS( TI_HANDLE hScanCncn ); 220 221 /** 222 * \author Ronen Kalish\n 223 * \date 02-Jan-2005\n 224 * \brief Called by a client to request a scan. 225 * 226 * Function Scope \e Public.\n 227 * \param hScanCncn - handle to the scan concentrator object.\n 228 * \param client - the client ID.\n 229 * \return scan operation detailed result status.\n 230 * \retval SCAN_CRS_SCAN_RUNNING - scan started successfully and is now running.\n 231 * \retval SCAN_CRS_SCAN_FAILED - scan failed to start due to an unexpected error.\n 232 */ 233 scan_cncnResultStatus_e scanConcentrator_scan( TI_HANDLE hScanCncn, 234 scan_CncnClient_e client, 235 scan_Params_t* pScanParams ); 236 237 /** 238 * \author Ronen Kalish\n 239 * \date 02-Jan-2005\n 240 * \brief Called by a client to stop a scan request in process. A client should ONLY stop its own request! 241 * 242 * Function Scope \e Public.\n 243 * \param hScanCncn - handle to the scan concentrator object.\n 244 * \param client - the client ID.\n 245 */ 246 void scanConcentrator_stopScan( TI_HANDLE hScanCncn, scan_CncnClient_e client ); 247 248 /** 249 * \author Ronen Kalish\n 250 * \date 02-Jan-2005\n 251 * \brief Registers a scan result function for a specific client. 252 * 253 * Function Scope \e Public.\n 254 * \param hScanCncn - handle to the scan concentrator object.\n 255 * \param client - the client ID.\n 256 * \param scanResultCBFunc - the function to use.\n 257 * \param scanresultCBObj - the object to pass to the scan result CB function.\n 258 */ 259 void scanConcentrator_registerScanResultCB( TI_HANDLE hScanCncn, scan_CncnClient_e client, 260 scan_resultCB_t scanResultCBFunc, TI_HANDLE scanResultCBObj ); 261 262 /** 263 * \author Ronen Kalish\n 264 * \date 02-Jan-2005\n 265 * \brief Called by the scan SRV (after registration) to notify of a scan complete event. 266 * 267 * Function Scope \e Public.\n 268 * \param hScanCncn - handle to the scan concentrator object.\n 269 * \param SPSStatus - which channels were attempted (if SPS scan).\n 270 * \param bTSFError - whether a TSF error occurred (if SPS scan).\n 271 * \param ScanStatus - return the status of the scan . \n 272 */ 273 void scanConcentrator_scanCompleteNotificationCB( TI_HANDLE hScanCncn, UINT16 SPSStatus, BOOLEAN bTSFError , TI_STATUS ScanStatus , TI_STATUS PSMode); 274 275 /** 276 * \author Ronen Kalish\n 277 * \date 02-Jan-2005\n 278 * \brief Called by the MLME parser to pass information received on a beacon or probe response. 279 * 280 * Function Scope \e Public.\n 281 * \param hScanCncn - handle to the scan concentrator object.\n 282 * \param bssid - a pointer to the address of the AP sending this frame.\n 283 * \param frameInfo - the IE in the frame.\n 284 * \param pRxAttr - a pointer to TNET RX attributes struct.\n 285 * \param buffer - a pointer to the frame body.\n 286 * \param byfferLength - the frame body length.\n 287 */ 288 void scanConcentrator_mlmeResultCB( TI_HANDLE hScanCncn, macAddress_t* bssid, mlmeFrameInfo_t* frameInfo, 289 Rx_attr_t* pRxAttr, UINT8* buffer, UINT16 bufferLength ); 290 291 /** 292 * \author Ronen Kalish\n 293 * \date 02-Jan-2005\n 294 * \brief Called by the SCR (after registration) to notify the scan concentrator of a status change 295 * \brief for the immediate scan for roaming client. 296 * 297 * Function Scope \e Public.\n 298 * \param hScanCncn - handle to the scan concentrator object.\n 299 * \param requestStatus - the continuous scan for roaming client status.\n 300 * \param pendReason - the reason for pend status, if the status is pend.\n 301 */ 302 void scanConcentrator_scrRoamingImmedCB( TI_HANDLE hScanCncn, scr_clientRequestStatus_e requestStatus, 303 scr_pendReason_e pendReason ); 304 305 /** 306 * \author Ronen Kalish\n 307 * \date 02-Jan-2005\n 308 * \brief Called by the SCR (after registration) to notify the scan concentrator of a status change 309 * \brief for the continuous scan for roaming client. 310 * 311 * Function Scope \e Public.\n 312 * \param hScanCncn - handle to the scan concentrator object.\n 313 * \param requestStatus - the continuous scan for roaming client status.\n 314 * \param pendReason - the reason for pend status, if the status is pend.\n 315 */ 316 void scanConcentrator_scrRoamingContCB( TI_HANDLE hScanCncn, scr_clientRequestStatus_e requestStatus, 317 scr_pendReason_e pendReason ); 318 319 /** 320 * \author Ronen Kalish\n 321 * \date 02-Jan-2005\n 322 * \brief Called by the SCR (after registration) to notify the scan concentrator of a status change 323 * \brief for the Application scan client. 324 * 325 * Function Scope \e Public.\n 326 * \param hScanCncn - handle to the scan concentrator object.\n 327 * \param requestStatus - the application scan status.\n 328 * \param pendReason - the reason for pend status, if the status is pend.\n 329 */ 330 void scanConcentrator_scrAppCB( TI_HANDLE hScanCncn, scr_clientRequestStatus_e requestStatus, 331 scr_pendReason_e pendReason ); 332 333 /** 334 * \author Ronen Kalish\n 335 * \date 02-Jan-2005\n 336 * \brief Called by the SCR (after registration) to notify the scan concentrator of a status change 337 * \brief for the driver scan client. 338 * 339 * Function Scope \e Public.\n 340 * \param hScanCncn - handle to the scan concentrator object.\n 341 * \param requestStatus - the driver scan status.\n 342 */ 343 void scanConcentrator_scrDriverCB( TI_HANDLE hScanCncn, scr_clientRequestStatus_e requestStatus, 344 scr_pendReason_e pendReason ); 345 346 /** 347 * \author Yuval Adler\n 348 * \date 26-Jan-2006\n 349 * \brief enable/disable the use of SG parameters , and update parameters of next scans 350 * requests for minDwellTime,MaxDwellTime,numProbeReq .\n 351 * this function is called when SG is enabled or disabled 352 * Function Scope \e Private.\n 353 * \param hScanCncn - handle to the scan concentrator object.\n 354 * \param bUseSGParams - whether to use the new parameters (TRUE when SG is enabled) 355 * \param probeReqNumber - 356 * \param SGcompensationMaxTime - max value from which we won't increase dwelling time 357 * \param SGcompensationPercent - increasing dwell time in that percentage 358 */ 359 void scanConcentrator_SGconfigureScanParams( TI_HANDLE hScanCncn, BOOL bUseSGParams , 360 UINT8 probeReqNumber , UINT32 SGcompensationMaxTime, 361 UINT32 SGcompensationPercent); 362 #endif /* __SCANCNCNAPI_H__ */ 363