1 /* 2 * scanMngrApi.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 scanMngrApi.h 35 * \brief This file include public definitions for the scan manager module, comprising its API. 36 * 37 * \see scanMngr.c, scanMngr.h, scanMngrTypes.h 38 */ 39 40 41 #ifndef __SCAN_MNGR_API_H__ 42 #define __SCAN_MNGR_API_H__ 43 44 #include "scanMngrTypes.h" 45 #include "bssTypes.h" 46 #include "ScanCncn.h" 47 #include "DrvMainModules.h" 48 49 50 /* 51 *********************************************************************** 52 * Constant definitions. 53 *********************************************************************** 54 */ 55 56 #define SCANNING_OPERATIONAL_MODE_MANUAL 0 57 #define SCANNING_OPERATIONAL_MODE_AUTO 1 58 59 60 /* 61 *********************************************************************** 62 * Enums. 63 *********************************************************************** 64 */ 65 /** \enum scan_mngrResultStatus_e 66 * 67 * \brief Scan Manager Result Status 68 * 69 * \par Description 70 * Enumerates the possible Scan result statuses. 71 * Returned as a response to an immediate scan request. 72 * 73 * \sa 74 */ 75 typedef enum 76 { 77 /* 0 */ SCAN_MRS_SCAN_COMPLETE_OK, /**< Scan was completed successfully */ 78 /* 1 */ SCAN_MRS_SCAN_RUNNING, /**< Scan was started successfully and is now running */ 79 /* 2 */ SCAN_MRS_SCAN_NOT_ATTEMPTED_ALREADY_RUNNING, /**< scan was not attempted because it is already running */ 80 /* 3 */ SCAN_MRS_SCAN_NOT_ATTEMPTED_EMPTY_POLICY, /**< 81 * Scan was not attempted because the policy defines 82 * NULL scan type 83 */ 84 /* 4 */ SCAN_MRS_SCAN_NOT_ATTEMPTED_NO_CHANNLES_AVAILABLE, /**< 85 * Scan was not attempted because no channels are 86 * available for scan, according to the defined policy. 87 */ 88 /* 5 */ SCAN_MRS_SCAN_FAILED, /**< Scan failed to start */ 89 /* 6 */ SCAN_MRS_SCAN_STOPPED, /**< Scan was stopped by caller */ 90 /* 7 */ SCAN_MRS_SCAN_ABORTED_FW_RESET, /**< Scan was aborted due to recovery */ 91 /* 8 */ SCAN_MRS_SCAN_ABORTED_HIGHER_PRIORITY /**< Scan was aborted due to a higher priority client */ 92 93 } scan_mngrResultStatus_e; 94 95 typedef enum { 96 CONNECTION_STATUS_CONNECTED =0, 97 CONNECTION_STATUS_NOT_CONNECTED 98 } scanMngr_connStatus_e; 99 100 101 102 103 /* 104 *********************************************************************** 105 * Typedefs. 106 *********************************************************************** 107 */ 108 109 /* 110 *********************************************************************** 111 * Structure definitions. 112 *********************************************************************** 113 */ 114 115 typedef struct { 116 TI_UINT8 numOfChannels; /**< Number of channels to scan */ 117 TScanChannelEntry channelEntry[ MAX_NUMBER_OF_CHANNELS_PER_SCAN ]; /**< Channel data array, actual size according to the above field. */ 118 } channelList_t; 119 120 typedef struct _BssListEx_t 121 { 122 bssList_t *pListOfAPs; 123 TI_BOOL scanIsRunning; 124 } BssListEx_t; 125 126 127 /* 128 *********************************************************************** 129 * External data definitions. 130 *********************************************************************** 131 */ 132 /* 133 *********************************************************************** 134 * External functions definitions 135 *********************************************************************** 136 */ 137 /** 138 * \brief Creates the scan manager object 139 * 140 * \param hScanMngr - handle to the OS object 141 * \return Handle to the Scan Manager Object on Success, NULL otherwise 142 * 143 * \par Description 144 * Creates (allocates) the scan manager object and its database 145 * 146 * \sa 147 */ 148 TI_HANDLE scanMngr_create( TI_HANDLE hOS ); 149 /** 150 * \brief Initializes the scan manager 151 * 152 * \param pStadHandles - The driver modules handles 153 * \return void 154 * 155 * \par Description 156 * Initializes the scan manager object with other object handlers called by the driver core logic, 157 * and creates Scan Manager Timer 158 * 159 * \sa scanMngr_unload 160 */ 161 void scanMngr_init (TStadHandlesList *pStadHandles); 162 /** 163 * \brief Unloads the scan manager object 164 * 165 * \param hScanMngr - Handle to the scan manager object to unload 166 * \return void 167 * 168 * \par Description 169 * Frees the memory allocated by the scan manager. 170 * The function is called as part of the unloading process of the driver. 171 * 172 * \sa 173 */ 174 void scanMngr_unload( TI_HANDLE hScanMngr ); 175 /** 176 * \brief Starts an immediate scan operation 177 * 178 * \param hScanMngr - handle to the scan manager object 179 * \param pNeighborAPsOnly - Indicates whether to scan only neighbor APs (or all channels defined by the policy) 180 * TI_TRUE if scan for neighbor APs only, TI_FALSE if scan on all channels 181 * \return Scan Result Status 182 * 183 * \par Description 184 * 185 * \sa scanMngr_create 186 */ 187 scan_mngrResultStatus_e scanMngr_startImmediateScan( TI_HANDLE hScanMngr, TI_BOOL bNeighborAPsOnly ); 188 /** 189 * \brief Stops the immediate scan operation 190 * 191 * \param hScanMngr - handle to the scan manager object 192 * \return void 193 * 194 * \par Description 195 * 196 * \sa 197 */ 198 void scanMngr_stopImmediateScan( TI_HANDLE hScanMngr ); 199 /** 200 * \brief Starts the continuous scan timer 201 * 202 * \param hScanMngr - Handle to the scan manager object 203 * \param currentBSS - BSSID of the AP to which the STA is connected 204 * \param currentBSSBand - Band of the AP to which the STA is connected 205 * \return void 206 * 207 * \par Description 208 * Starts the continuous scan process performed by the scan manager. 209 * It is called by the roaming manager when an STA connection is established 210 * 211 * \sa 212 */ 213 void scanMngr_startContScan( TI_HANDLE hScanMngr, TMacAddr* currentBSS, ERadioBand currentBSSBand ); 214 /** 215 * \brief Stops the continuous scan timer 216 * 217 * \param hScanMngr - Handle to the scan manager object 218 * \return void 219 * 220 * \par Description 221 * Stops the continues scan performed by the scan manager. 222 * It is called by the roaming manager when the STA disconnects 223 * 224 * \sa 225 */ 226 void scanMngr_stopContScan( TI_HANDLE hScanMngr ); 227 /** 228 * \brief Returns the currently available BSS list 229 * 230 * \param hScanMngr - Handle to the scan manager object 231 * \return Pointer to BSS list 232 * 233 * \par Description 234 * Used by the roaming manager to obtain the scan manager BSS list. 235 * 236 * \sa 237 */ 238 bssList_t *scanMngr_getBSSList( TI_HANDLE hScanMngr ); 239 /** 240 * \brief Sets the neighbor APs 241 * 242 * \param hScanMngr - Handle to the scan manager object 243 * \param neighborAPList - Pointer to the neighbor AP list 244 * \return void 245 * 246 * \par Description 247 * Used by the roaming manager to set a list of neighbor APs for the scan manager, 248 * which are then given priority over policy channels in the discovery phase 249 * 250 * \sa 251 */ 252 void scanMngr_setNeighborAPs( TI_HANDLE hScanMngr, neighborAPList_t* neighborAPList ); 253 /** 254 * \brief Change quality level (normal / deteriorating) 255 * 256 * \param hScanMngr - Handle to the scan manager object 257 * \param bLowQuality - TI_TRUE if quality is deteriorating, TI_FALSE if quality is normal 258 * \return void 259 * 260 * \par Description 261 * Used by the roaming manager to set the scan interval used by the scan manager, 262 * according to the current AP quality level 263 * 264 * \sa 265 */ 266 void scanMngr_qualityChangeTrigger( TI_HANDLE hScanMngr, TI_BOOL bLowQuality ); 267 /** 268 * \brief Change quality level (normal / deteriorating) 269 * 270 * \param hScanMngr - Handle to the scan manager object 271 * \param macAddress - MAC address of the new AP (to which the STA is currently connected to) 272 * \param band - Band of the new AP (to which the STA is currently connected to) 273 * \return void 274 * 275 * \par Description 276 * Used by the roaming manager to notify the scan manager that roaming is complete. 277 * This is done so that the scan manager does not attempt to discover the current AP, 278 * in case it is also a neighbor AP 279 * 280 * \sa 281 */ 282 void scanMngr_handoverDone( TI_HANDLE hScanMngr, TMacAddr* macAddress, ERadioBand band ); 283 /** 284 * \brief Get Scan Manager Parameters 285 * 286 * \param hScanMngr - Handle to the scan manager object 287 * \param pParam - Pointer to get Parameter 288 * \return TI_OK if the parameter got successfully, TI_NOK otherwise 289 * 290 * \par Description 291 * Parses and executes a get parameter command 292 * 293 * \sa 294 */ 295 TI_STATUS scanMngr_getParam( TI_HANDLE hScanMngr, paramInfo_t *pParam ); 296 /** 297 * \brief Set Scan Manager Parameters 298 * 299 * \param hScanMngr - Handle to the scan manager object 300 * \param pParam - Pointer to set Parameter 301 * \return TI_OK if the parameter was set successfully, TI_NOK otherwise 302 * 303 * \par Description 304 * Called when the user configures scan parameters. It parses and executes a set parameter command 305 * 306 * \sa 307 */ 308 TI_STATUS scanMngr_setParam( TI_HANDLE hScanMngr, paramInfo_t *pParam ); 309 310 311 312 313 314 /********** New APIs added for EMP manual scan support ******/ 315 316 void scanMngr_startManual(TI_HANDLE hScanMngr); 317 318 void scanMngr_stopManual(TI_HANDLE hScanMngr); 319 320 TI_STATUS scanMngr_setManualScanChannelList (TI_HANDLE hScanMngr, channelList_t* pChannelList); 321 322 EScanCncnResultStatus scanMngr_Start1ShotScan (TI_HANDLE hScanMngr, EScanCncnClient eClient); 323 324 TI_STATUS scanMngr_immediateScanComplete(TI_HANDLE hScanMngr, scan_mngrResultStatus_e scanCmpltStatus); 325 326 TI_STATUS scanMngr_reportImmediateScanResults(TI_HANDLE hScanMngr, scan_mngrResultStatus_e scanCmpltStatus); 327 328 TI_STATUS scanMngr_startContinuousScanByApp (TI_HANDLE hScanMngr, channelList_t* pChannelList); 329 330 TI_STATUS scanMngr_stopContinuousScanByApp (TI_HANDLE hScanMngr); 331 332 void scanMngr_SetDefaults (TI_HANDLE hScanMngr, TRoamScanMngrInitParams *pInitParams); 333 334 /********** New APIs added for EMP manual scan support ******/ 335 336 337 #ifdef TI_DBG 338 /** 339 * \brief Print scan policy 340 * 341 * \param scanPolicy - scan policy to print 342 * \return void 343 * 344 * \par Description 345 * 346 * \sa 347 */ 348 void scanMngrTracePrintScanPolicy( TScanPolicy* scanPolicy ); 349 /** 350 * \brief Print scan manager statistics 351 * 352 * \param hScanMngr - handle to the scan manager object.\n 353 * \return void 354 * 355 * \par Description 356 * 357 * \sa 358 */ 359 void scanMngr_statsPrint( TI_HANDLE hScanMngr ); 360 /** 361 * \brief Reset scan manager statistics 362 * 363 * \param hScanMngr - handle to the scan manager object.\n 364 * \return void 365 * 366 * \par Description 367 * 368 * \sa 369 */ 370 void scanMngr_statsReset( TI_HANDLE hScanMngr ); 371 /** 372 * \brief Print Neighbor AP list 373 * 374 * \param hScanMngr - handle to the scan manager object.\n 375 * \return void 376 * 377 * \par Description 378 * 379 * \sa 380 */ 381 void scanMngrDebugPrintNeighborAPList( TI_HANDLE hScanMngr ); 382 /** 383 * \brief Prints all data in the scan manager object 384 * 385 * \param hScanMngr - handle to the scan manager object.\n 386 * \return void 387 * 388 * \par Description 389 * 390 * \sa 391 */ 392 void scanMngrDebugPrintObject( TI_HANDLE hScanMngr ); 393 394 #endif /* TI_DBG */ 395 396 #endif /* __SCAN_MNGR_API_H__ */ 397
