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 */
64typedef 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 */
116TI_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 */
131void 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 */
143void 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 */
160scan_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 */
170void 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 */
182void 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 */
192void 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 */
203bssList_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 */
214void 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 */
225void 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 */
238void 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 */
251void 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 */
265void 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 */
278TI_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 */
290TI_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 */
301void scanMngr_setScanPolicy( TI_HANDLE hScanMngr, scan_Policy_t* scanPolicy );
302
303/* Clear all candidate BSSList for Roaming */
304void 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 */
315void 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 */
325void 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 */
335void 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 */
345void 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 */
355void scanMngrDebugPrintObject( TI_HANDLE hScanMngr );
356
357#endif /* TI_DBG */
358
359#endif /* __SCAN_MNGR_API_H__ */
360