WlanScan function (wlanapi.h)
Note
Some information relates to pre-released product, which may be substantially modified before it's commercially released. Microsoft makes no warranties, express or implied, with respect to the information provided here.
Important
This API will be affected by upcoming changes to operating system behavior, planned for fall 2024. For more info, see Changes to API behavior for Wi-Fi access and location.
The WlanScan function requests a scan for available networks on the indicated interface.
Syntax
DWORD WlanScan(
[in] HANDLE hClientHandle,
[in] const GUID *pInterfaceGuid,
[in, optional] const PDOT11_SSID pDot11Ssid,
[in, optional] const PWLAN_RAW_DATA pIeData,
PVOID pReserved
);
Parameters
[in] hClientHandle
The client's session handle, obtained by a previous call to the WlanOpenHandle function.
[in] pInterfaceGuid
The GUID of the interface to be queried.
The GUID of each wireless LAN interface enabled on a local computer can be determined using the WlanEnumInterfaces function.
[in, optional] pDot11Ssid
A pointer to a DOT11_SSID structure that specifies the SSID of the network to be scanned. This parameter is optional. When set to NULL, the returned list contains all available networks. Windows XP with SP3 and Wireless LAN API for Windows XP with SP2: This parameter must be NULL.
[in, optional] pIeData
A pointer to an information element to include in probe requests. This parameter points to a WLAN_RAW_DATA structure that may include client provisioning availability information and 802.1X authentication requirements.Windows XP with SP3 and Wireless LAN API for Windows XP with SP2: This parameter must be NULL.
pReserved
Reserved for future use. Must be set to NULL.
Return value
If the function succeeds, the return value is ERROR_SUCCESS.
If the function fails, the return value may be one of the following return codes.
| Return code | Description |
|---|---|
|
hClientHandle is NULL or invalid, pInterfaceGuid is NULL, or pReserved is not NULL. |
|
The handle hClientHandle was not found in the handle table. |
|
Various error codes. |
|
Failed to allocate memory for the query results. |
Remarks
The WlanScan function requests that the native 802.11 Wireless LAN driver scan for available wireless networks. The driver may or may not send probe requests (an active scan) depending on its implementation and the values passed in the pDot11Ssid and pIeData parameters.
If the pIeData parameter is not NULL, the driver will send probe requests during the scan. The probe requests include the information element (IE) pointed to by the pIeData parameter. For instance, the Wi-Fi Protected Setup (WPS) IE can be included in the probe requests to discover WPS-capable access points. The buffer pointed to by the pIeData parameter must contain the complete IE starting from the Element ID.
The pIeData parameter passed to the WlanScan function can contain a pointer to an optional WLAN_RAW_DATA structure that contains a proximity service discovery (PSD) IE data entry.
When used to store a PSD IE, the DOT11_PSD_IE_MAX_DATA_SIZE constant defined in the Wlanapi.h header file is the maximum value of the dwDataSize member.
| Constant | Value | Description |
|---|---|---|
| DOT11_PSD_IE_MAX_DATA_SIZE | 240 | The maximum data size, in bytes, of a PSD IE data entry. |
For more information about PSD IEs, including a discussion of the format of a PSD IE, see the WlanSetPsdIEDataList function.
When the WlanScan function is called, the native 802.11 Wireless LAN driver may flush the current list of available wireless networks before the scan is initiated. Applications should not assume that calling the WlanScan function will add to the existing list of available wireless networks returned by the WlanGetNetworkBssList or WlanGetAvailableNetworkList functions from previous scans.
The WlanScan function returns immediately. To be notified when the network scan is complete, a client on Windows Vista and later must register for notifications by calling WlanRegisterNotification. The dwNotifSource parameter passed to the WlanRegisterNotification function must have the WLAN_NOTIFICATION_SOURCE_ACM bit set to register for notifications generated by the auto configuration module. Wireless network drivers that meet Windows logo requirements are required to complete a WlanScan function request in 4 seconds.
The Wireless LAN Service does not send notifications when available wireless networks change. The Wireless LAN Service does not track changes to the list of available networks across multiple scans. The current default behavior is that the Wireless LAN Service only asks the wireless interface driver to scan for wireless networks every 60 seconds, and in some cases (when already connected to wireless network) the Wireless LAN Service does not ask for scans at all. The WlanScan function can be used by an application to track wireless network changes. The application should first register for WLAN_NOTIFICATION_SOURCE_ACM notifications. The WlanScan function can then be called to initiate a scan. The application should then wait to receive the wlan_notification_acm_scan_complete notification or timeout after 4 seconds. Then the application can call the WlanGetNetworkBssList or WlanGetAvailableNetworkList function to retrieve a list of available wireless networks. This process can be repeated periodically with the application keeping tracking of changes to available wireless networks.
The WlanScan function returns immediately and does not provide a notification when the scan is complete on Windows XP with SP3 or the Wireless LAN API for Windows XP with SP2.
Since it becomes more difficult for a wireless interface to send and receive data packets while a scan is occurring, the WlanScan function may increase latency until the network scan is complete.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows Vista, Windows XP with SP3 [desktop apps only] |
| Minimum supported server | Windows Server 2008 [desktop apps only] |
| Target Platform | Windows |
| Header | wlanapi.h (include Wlanapi.h) |
| Library | Wlanapi.lib |
| DLL | Wlanapi.dll |
| Redistributable | Wireless LAN API for Windows XP with SP2 |