1.3.3 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_PIC32MZW_BSSFindSetEnabledChannels24.

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

WDRV_PIC32MZW_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 isn’t provided, the application can poll this interface using WDRV_PIC32MZW_BSSFindInProgress to determine if the device is still scanning.

Getting Results – Callback Only

If a callback function was provided to WDRV_PIC32MZW_BSSFindFirst, the Wi-Fi driver will call this callback when the first results are available. The callback is provided with the scan result for a single BSS as well as the index of the results 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 request the next result from the PIC32MZW1 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 request the next set of BSS information from the PIC32MZW1 device.

The foreground task may then call WDRV_PIC32MZW_BSSFindGetInfo with a pointer to a WDRV_PIC32MZW_BSS_INFO structure to receive the BSS information. If the function is called when there is no valid BSS information present in the PIC32MZW driver, the function will return WDRV_PIC32MZW_STATUS_NO_BSS_INFO.

When the application wishes to request the next set of BSS information, it must call WDRV_PIC32MZW_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_PIC32MZW_BSSFindInProgress indicates if the scan operation is currently active and results are not yet available. WDRV_PIC32MZW_BSSFindGetNumBSSResults returns the number of sets of BSS information available as a result of a scan operation. WDRV_PIC32MZW_BSSFindGetInfo can be called to retrieve the BSS information. If the information is not yet available this function will return WDRV_PIC32MZW_STATUS_NO_BSS_INFO.

Terminating a BSS Search

Once a scan operation has been started by calling WDRV_PIC32MZW_BSSFindFirst it must be allowed to complete, once it has 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_PIC32MZW_BSSFindReset.