1 /*************************************************************************** 2 **+-----------------------------------------------------------------------+** 3 **| |** 4 **| Copyright(c) 1998 - 2008 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 ****************************************************************************/ 35 /** \file scanMngrApi.h 36 * \brief This file include public definitions for the scan manager module, comprising its API. 37 * \author Ronen Kalish 38 * \date 01-Mar-2005 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 "ScanCncnApi.h" 47 48 /* 49 *********************************************************************** 50 * Constant definitions. 51 *********************************************************************** 52 */ 53 54 /* 55 *********************************************************************** 56 * Enums. 57 *********************************************************************** 58 */ 59 60 /** \enum scan_mngrResultStatus_e 61 * \brief enumerates the different result statuses that the scan manager 62 * \brief can return in response to an immediate scan request. 63 */ 64 typedef enum 65 { 66 SCAN_MRS_SCAN_COMPLETE_OK= 0, /**< Scan was completed successfully */ 67 SCAN_MRS_SCAN_RUNNING, /**< Scan was started successfully and is now running */ 68 SCAN_MRS_SCAN_NOT_ATTEMPTED_ALREADY_RUNNING, /**< scan was not attempted because it is already running */ 69 SCAN_MRS_SCAN_NOT_ATTEMPTED_EMPTY_POLICY, /**< 70 * Scan was not attempted because the policy defines 71 * NULL scan type 72 */ 73 SCAN_MRS_SCAN_NOT_ATTEMPTED_NO_CHANNLES_AVAILABLE, /**< 74 * Scan was not attempted because no channels are 75 * available for scan, according to the defined policy. 76 */ 77 SCAN_MRS_SCAN_FAILED, /**< Scan failed to start */ 78 SCAN_MRS_SCAN_STOPPED, /**< Scan was stopped by caller */ 79 SCAN_MRS_SCAN_ABORTED_FW_RESET, /**< Scan was aborted due to recovery */ 80 SCAN_MRS_SCAN_ABORTED_HIGHER_PRIORITY, /**< Scan was aborted due to a higher priority client */ 81 } scan_mngrResultStatus_e; 82 83 /* 84 *********************************************************************** 85 * Typedefs. 86 *********************************************************************** 87 */ 88 89 /* 90 *********************************************************************** 91 * Structure definitions. 92 *********************************************************************** 93 */ 94 95 /* 96 *********************************************************************** 97 * External data definitions. 98 *********************************************************************** 99 */ 100 101 /* 102 *********************************************************************** 103 * External functions definitions 104 *********************************************************************** 105 */ 106 107 /** 108 * \author Ronen Kalish\n 109 * \date 01-Mar-2005\n 110 * \brief Creates the scan manager object.\n 111 * 112 * Function Scope \e Public.\n 113 * \param hScanMngr - handle to the OS object.\n 114 * \return a pointer to the scan manager object if successful, NULL otherwise.\n 115 */ 116 TI_HANDLE scanMngr_create( TI_HANDLE hOS ); 117 118 /** 119 * \author Ronen Kalish\n 120 * \date 01-Mar-2005\n 121 * \brief Initializes the scan manager.\n 122 * 123 * Function Scope \e Public.\n 124 * \param hScanMngr - handle to the scan manager object.\n 125 * \param hReport - handle to the report object.\n 126 * \param hRegDomain - handle to the regulatory domain object.\n 127 * \param hScanCncn - handle to the scan concentrator object.\n 128 * \param hRoamMngr - handle to the roaming manager object.\n 129 * \param hSiteMngr - handle to the site manager object.\n 130 */ 131 void scanMngr_init( TI_HANDLE hScanMngr, TI_HANDLE hReport, TI_HANDLE hRegDomain, 132 TI_HANDLE hScanCncn, TI_HANDLE hRoamMngr, TI_HANDLE hSiteMngr, 133 TI_HANDLE hHalCtrl); 134 135 /** 136 * \author Ronen Kalish\n 137 * \date 01-Mar-2005\n 138 * \brief unloads the scan manager object.\n 139 * 140 * Function Scope \e Public.\n 141 * \param hScanMngr - handle to the scan manager object.\n 142 */ 143 void scanMngr_unload( TI_HANDLE hScanMngr ); 144 145 /** 146 * \author Ronen Kalish\n 147 * \date 01-Mar-2005\n 148 * \brief Starts an immediate scan operation.\n 149 * 150 * Function Scope \e Public.\n 151 * \param hScanMngr - handle to the scan manager object.\n 152 * \param pNeighborAPsOnly - TRUE if scan for neighbor APs only, FALSE if scan on all channels.\n 153 * \return status indication.\n 154 * \retval SCAN_MRS_SCAN_RUNNING - the scan started successfully and is now running.\n 155 * \retval SCAN_MRS_SCAN_NOT_ATTEMPTED_ALREADY_RUNNING - scan was not attempted because it is already running.\n 156 * \retval SCAN_MRS_SCAN_NOT_ATTEMPTED_EMPTY_POLICY - scan was not attempted because NULL policy defined.\n 157 * \retval SCAN_MRS_SCAN_NOT_ATTEMPTED_NO_CHANNLES_AVAILABLE - scan was not attempted because no channels were available.\n 158 * \retval SCAN_MRS_SCAN_FAILED - scan failed to start at lower levels.\n 159 */ 160 scan_mngrResultStatus_e scanMngr_startImmediateScan( TI_HANDLE hScanMngr, BOOLEAN bNeighborAPsOnly); 161 162 /** 163 * \author Ronen Kalish\n 164 * \date 01-Mar-2005\n 165 * \brief Stops an immediate scan operation.\n 166 * 167 * Function Scope \e Public.\n 168 * \param hScanMngr - handle to the scan manager object.\n 169 */ 170 void scanMngr_stopImmediateScan( TI_HANDLE hScanMngr ); 171 172 /** 173 * \author Ronen Kalish\n 174 * \date 01-Mar-2005\n 175 * \brief Starts the continuous scan timer.\n 176 * 177 * Function Scope \e Public.\n 178 * \param hScanMngr - handle to the scan manager object.\n 179 * \param currentBSS - the AP we are currently connected to.\n 180 * \currentBSSBand - the band of the current BSS.\n 181 */ 182 void scanMngr_startContScan( TI_HANDLE hScanMngr, macAddress_t* currentBSS, radioBand_e currentBSSBand ); 183 184 /** 185 * \author Ronen Kalish\n 186 * \date 01-Mar-2005\n 187 * \brief Stops the continuous scan timer.\n 188 * 189 * Function Scope \e Public.\n 190 * \param hScanMngr - handle to the scan manager object.\n 191 */ 192 void scanMngr_stopContScan( TI_HANDLE hScanMngr ); 193 194 /** 195 * \author Ronen Kalish\n 196 * \date 01-Mar-2005\n 197 * \brief returns the currently available BSS list.\n 198 * 199 * Function Scope \e Public.\n 200 * \param hScanMngr - handle to the scan manager object.\n 201 * \return BSS list structure pointer.\n 202 */ 203 bssList_t *scanMngr_getBSSList( TI_HANDLE hScanMngr ); 204 205 /** 206 * \author Ronen Kalish\n 207 * \date 01-Mar-2005\n 208 * \brief Sets the neighbor APs.\n 209 * 210 * Function Scope \e Public.\n 211 * \param hScanMngr - handle to the scan manager object.\n 212 * \param neighborAPList - the neighbor AP list.\n 213 */ 214 void scanMngr_setNeighborAPs( TI_HANDLE hScanMngr, neighborAPList_t* neighborAPList ); 215 216 /** 217 * \author Ronen Kalish\n 218 * \date 01-Mar-2005\n 219 * \brief change quality level (normal / deteriorating).\n 220 * 221 * Function Scope \e Public.\n 222 * \param hScanMngr - handle to the scan manager object.\n 223 * \param bLowQuality - TRUE if quality is deteriorating, FALSE if quality is normal.\n 224 */ 225 void scanMngr_qualityChangeTrigger( TI_HANDLE hScanMngr, BOOLEAN bLowQuality ); 226 227 /** 228 * \author Ronen Kalish\n 229 * \date 13-Mar-2005\n 230 * \brief Notifies the scan manager of a roaming event. Should be called BEFORE the SCR group 231 * \brief is changed back to connected.\n 232 * 233 * Function Scope \e Public.\n 234 * \param hScanMngr - handle to the scan manager object.\n 235 * \param macAddress - mac address of the new AP.\n 236 * \param band - the band of the new AP.\n 237 */ 238 void scanMngr_handoverDone( TI_HANDLE hScanMngr, macAddress_t* macAddress, radioBand_e band ); 239 240 /** 241 * \author Ronen Kalish\n 242 * \date 01-Mar-2005\n 243 * \brief Callback used by the scan concentrator for immediate scan result.\n 244 * 245 * Function Scope \e Public.\n 246 * \param hScanMngr - handle to the scan manager object.\n 247 * \param resultStatus - reason for calling this function (frame received / scan complete).\n 248 * \param frameInfo - frame related information (in case of a frame reception).\n 249 * \param SPSStatus - bitmap indicating which channels were scan, in case of an SPS scan.\n 250 */ 251 void scanMngr_immedScanCB( TI_HANDLE hScanMngr, scan_cncnResultStatus_e resultStatus, 252 scan_frameInfo_t* frameInfo, UINT16 SPSStatus ); 253 254 /** 255 * \author Ronen Kalish\n 256 * \date 01-Mar-2005\n 257 * \brief Callback used by the scan concentrator for continuous scan result.\n 258 * 259 * Function Scope \e Public.\n 260 * \param hScanMngr - handle to the scan manager object.\n 261 * \param resultStatus - reason for calling this function (frame received / scan complete).\n 262 * \param frameInfo - frame related info (in case of a frame reception).\n 263 * \param SPSStatus - bitmap indicating which channels were scan, in case of an SPS scan.\n 264 */ 265 void scanMngr_contScanCB( TI_HANDLE hScanMngr, scan_cncnResultStatus_e resultStatus, 266 scan_frameInfo_t* frameInfo, UINT16 SPSStatus ); 267 268 /** 269 * \author Ronen Kalish\n 270 * \date 08-Mar-2005\n 271 * \brief Parses and executes a get param command.\n 272 * 273 * Function Scope \e Public.\n 274 * \param hScanMngr - handle to the scan manager object.\n 275 * \param pParam - the param to get.\n 276 * \return OK if the parameter was get successfully, NOK otherwise.\n 277 */ 278 TI_STATUS scanMngr_getParam( TI_HANDLE hScanMngr, paramInfo_t *pParam ); 279 280 /** 281 * \author Ronen Kalish\n 282 * \date 01-Mar-2005\n 283 * \brief Parses and executes a set param command.\n 284 * 285 * Function Scope \e Public.\n 286 * \param hScanMngr - handle to the scan manager object.\n 287 * \param pParam - the param to set.\n 288 * \return OK if the parameter was set successfully, NOK otherwise.\n 289 */ 290 TI_STATUS scanMngr_setParam( TI_HANDLE hScanMngr, paramInfo_t *pParam ); 291 292 /** 293 * \author Ronen Kalish\n 294 * \date 01-Mar-2005\n 295 * \brief Sets the scan policy.\n 296 * 297 * Function Scope \e Public.\n 298 * \param hScanMngr - handle to the scan manager object.\n 299 * \param scanPolicy - a pointer to the policy data.\n 300 */ 301 void scanMngr_setScanPolicy( TI_HANDLE hScanMngr, scan_Policy_t* scanPolicy ); 302 303 /* Clear all candidate BSSList for Roaming */ 304 void scanMngrClearBSSListEntry( TI_HANDLE hScanMngr ); 305 306 #ifdef TI_DBG 307 /** 308 * \author Ronen Kalish\n 309 * \date 09-Mar-2005\n 310 * \brief Print scan policy.\n 311 * 312 * Function Scope \e Private.\n 313 * \param scanPolicy - scan policy to print.\n 314 */ 315 void scanMngrTracePrintScanPolicy( scan_Policy_t* scanPolicy ); 316 317 /** 318 * \author Ronen Kalish\n 319 * \date 26-May-2005\n 320 * \brief Print scan manager statistics.\n 321 * 322 * Function Scope \e Public.\n 323 * \param hScanMngr - handle to the scan manager object.\n 324 */ 325 void scanMngr_statsPrint( TI_HANDLE hScanMngr ); 326 327 /** 328 * \author Ronen Kalish\n 329 * \date 26-May-2005\n 330 * \brief Reset scan manager statistics.\n 331 * 332 * Function Scope \e Public.\n 333 * \param hScanMngr - handle to the scan manager object.\n 334 */ 335 void scanMngr_statsReset( TI_HANDLE hScanMngr ); 336 337 /** 338 * \author Ronen Kalish\n 339 * \date 25-July-2005\n 340 * \brief Print Neighbor AP list.\n 341 * 342 * Function Scope \e Public.\n 343 * \param hScanMngr - Handle to the scan manager object.\n 344 */ 345 void scanMngrDebugPrintNeighborAPList( TI_HANDLE hScanMngr ); 346 347 /** 348 * \author Ronen Kalish\n 349 * \date 25-July-2005\n 350 * \brief Prints all data in the scan manager object.\n 351 * 352 * Function Scope \e Public.\n 353 * \param hScanMngr - handle to the scan manager object.\n 354 */ 355 void scanMngrDebugPrintObject( TI_HANDLE hScanMngr ); 356 357 #endif /* TI_DBG */ 358 359 #endif /* __SCAN_MNGR_API_H__ */ 360
