1.1.9 Client - BSS Find APIs

The application can use this interface to request a scan for local BSSs. Once requested, the device will conduct the search using the configured search parameters and report the results back to the application one BSS at a time. This interface can be used in either a callback mode, a polled mode, or a combination of both callback and polled depending on how the application wishes to receive the BSS information.

How a scan is conducted depends on the parameters and channel lists provided by the application.

The channels which can be scanned may be set by calling WDRV_WINC_BSSFindSetScanChannels24.

When an application wishes to begin a scan operation it must call WDRV_WINC_BSSFindFirst. It is possible to request a scan on only a single channel or on all channels enabled by calling WDRV_WINC_BSSFindSetScanChannels24. The scan can be performed using active mode (where probe requests are transmitted) or passive mode (where beacons are listened for).

WDRV_WINC_BSSFindFirst takes an optional callback function to use for notifying the application when the scan operation is complete, and the first result is available. If this is not provided, the application can poll this interface using WDRV_WINC_BSSFindInProgress to determine if the device is still scanning.

Getting Results – Callback Only

If a callback function was provided to WDRV_WINC_BSSFindFirst, the Wi-Fi driver will call this callback when the first result is available. The callback provides the scan result for a single BSS as well as the index of the result within the full set of BSSs discovered.

If the callback function returns the value true to the Wi-Fi driver, it will cause the driver to fetch the next result from the WINCS02 device. When this result is available, the Wi-Fi driver will again call the callback and provide the BSS information. It is thus possible to receive all the results via the callback.

Getting Results – Callback Notification, Foreground Retrieval

While the application may wish to be notified of a BSS result being available via the callback mechanism, it may be preferable to retrieve the result information from a foreground task. For example, in an OS environment the callback may simply signal a semaphore triggering the main application task to retrieve the BSS information.

In this model the callback called by the Wi-Fi driver should return the value false. The Wi-Fi driver will not fetch the next set of BSS information from the WINCS02 device.

The foreground task may then call WDRV_WINC_BSSFindGetInfo with a pointer to a WDRV_WINC_BSS_INFO structure to receive the BSS information. If the function is called when there is no valid BSS information present in the WINCS02 driver, the function will return WDRV_WINC_STATUS_NO_BSS_INFO.

When the application wishes to request the next set of BSS information, it must call WDRV_WINC_BSSFindNext. It is possible to change the callback function at this time or even turn off callback operation if a NULL pointer is used. Assuming the callback function is again specified the Wi-Fi driver will request the next set of BSS information from the device and inform the application via the callback.

Getting Results – Polled

The operations of the BSS scan can be inferred by polling this interface. WDRV_WINC_BSSFindInProgress indicates if the scan operation is currently active and results are not yet available. WDRV_WINC_BSSFindGetNumBSSResults returns the number of sets of BSS information available as a result of a scan operation. WDRV_WINC_BSSFindGetInfo can be called to retrieve the BSS information. If the information is not yet available this function will return WDRV_WINC_STATUS_NO_BSS_INFO.

Terminating a BSS Search

Once a scan operation has been started by calling WDRV_WINC_BSSFindFirst it must be allowed to complete. Once complete, the application may decide to ignore some or all of the results. To abort the BSS information retrieval and abandon any remaining results the application can call WDRV_WINC_BSSFindReset.