wlanScan 函数 (wlanapi.h)

项目
10/19/2023

注意

一些信息与预发行产品相关，相应产品在商业发行之前可能会进行重大修改。对于此处提供的信息，Microsoft 不作任何明示或暗示的担保。

重要

此 API 将受到即将于 2024 年秋季进行的操作系统行为更改的影响。有关详细信息，请参阅更改 api 行为的 Wi-Fi 访问和位置。

WlanScan 函数请求扫描指示的接口上的可用网络。

语法

DWORD WlanScan(
  [in]           HANDLE               hClientHandle,
  [in]           const GUID           *pInterfaceGuid,
  [in, optional] const PDOT11_SSID    pDot11Ssid,
  [in, optional] const PWLAN_RAW_DATA pIeData,
                 PVOID                pReserved
);

参数

[in] hClientHandle

客户端的会话句柄，由上一次对 WlanOpenHandle 函数的调用获取。

[in] pInterfaceGuid

要查询的接口的 GUID。

可以使用 WlanEnumInterfaces 函数确定在本地计算机上启用的每个无线 LAN 接口的 GUID。

[in, optional] pDot11Ssid

指向 DOT11_SSID 结构的指针，该结构指定要扫描的网络的 SSID。此参数是可选的。如果设置为 NULL，则返回的列表包含所有可用网络。 具有 SP3 的 Windows XP 和适用于 SP2 的 Windows XP 的无线 LAN API： 此参数必须为 NULL。

[in, optional] pIeData

指向要包含在探测请求中的信息元素的指针。此参数指向一个WLAN_RAW_DATA 结构，其中可能包括客户端预配可用性信息和 802.1X 身份验证要求。具有 SP3 的 Windows XP 和适用于 SP2 的 Windows XP 的无线 LAN API： 此参数必须为 NULL。

pReserved

保留供将来使用。必须设置为 NULL。

返回值

如果函数成功，则返回值为 ERROR_SUCCESS。

如果函数失败，则返回值可能是以下返回代码之一。

返回代码	说明
ERROR_INVALID_PARAMETER	hClientHandle 为 NULL 或无效， pInterfaceGuid 为 NULL，或 pReserved 不为 NULL。
ERROR_INVALID_HANDLE	在句柄表中找不到句柄 hClientHandle 。
RPC_STATUS	各种错误代码。
ERROR_NOT_ENOUGH_MEMORY	未能为查询结果分配内存。

注解

WlanScan 函数请求本机 802.11 无线 LAN 驱动程序扫描可用的无线网络。驱动程序可能 (活动扫描) 发送探测请求，具体取决于其实现以及 pDot11Ssid 和 pIeData 参数中传递的值。

如果 pIeData 参数不为 NULL，驱动程序将在扫描期间发送探测请求。探测请求包括 pIeData 参数指向 (IE) 的信息元素。例如，Wi-Fi 受保护的安装程序 (WPS) IE 可以包含在探测请求中，以发现支持 WPS 的接入点。 pIeData 参数指向的缓冲区必须包含从元素 ID 开始的完整 IE。

传递给 WlanScan 函数的 pIeData 参数可以包含指向可选WLAN_RAW_DATA结构的指针，该结构包含邻近服务发现 (PSD) IE 数据条目。

用于存储 PSD IE 时，在 Wlanapi.h 头文件中定义的DOT11_PSD_IE_MAX_DATA_SIZE常量是 dwDataSize 成员的最大值。

常数	Value	说明
DOT11_PSD_IE_MAX_DATA_SIZE	240	PSD IE 数据条目的最大数据大小（以字节为单位）。

有关 PSD IE 的详细信息（包括 PSD IE 格式的讨论），请参阅 WlanSetPsdIEDataList 函数。

调用 WlanScan 函数时，本机 802.11 无线 LAN 驱动程序可能会在启动扫描之前刷新可用无线网络的当前列表。应用程序不应假定调用 WlanScan 函数会将添加到现有可用无线网络列表中，这些无线网络由 WlanGetNetworkBssList 或 WlanGetAvailableNetworkList 函数从以前的扫描返回。

WlanScan 函数会立即返回。若要在网络扫描完成时收到通知，Windows Vista 和更高版本的客户端必须通过调用 WlanRegisterNotification 注册通知。传递给 WlanRegisterNotification 函数的 dwNotifSource 参数必须设置 WLAN_NOTIFICATION_SOURCE_ACM 位，以便注册自动配置模块生成的通知。满足 Windows 徽标要求的无线网络驱动程序需要在 4 秒内完成 WlanScan 函数请求。

当可用的无线网络发生更改时，无线 LAN 服务不会发送通知。无线 LAN 服务不会跟踪多个扫描中对可用网络列表的更改。当前的默认行为是，无线 LAN 服务仅要求无线接口驱动程序每 60 秒扫描一次无线网络，在某些情况下，如果已连接到无线网络，) 无线 LAN 服务根本不要求扫描，则 (。 应用程序可以使用 WlanScan 函数来跟踪无线网络更改。应用程序应首先注册WLAN_NOTIFICATION_SOURCE_ACM通知。然后，可以调用 WlanScan 函数来启动扫描。然后，应用程序应等待 4 秒后收到wlan_notification_acm_scan_complete通知或超时。然后，应用程序可以调用 WlanGetNetworkBssList 或 WlanGetAvailableNetworkList 函数来检索可用无线网络的列表。此过程可以定期重复，应用程序会跟踪对可用无线网络的更改。

WlanScan 函数会立即返回，并且不会在具有 SP3 的 Windows XP 或具有 SP2 的 Windows XP 无线 LAN API 上完成扫描时提供通知。

由于无线接口在扫描时发送和接收数据包变得更加困难， 因此 WlanScan 函数可能会增加延迟，直到网络扫描完成。

要求

要求	值
最低受支持的客户端	Windows Vista、Windows XP 和 SP3 [仅限桌面应用]
最低受支持的服务器	Windows Server 2008 [仅限桌面应用]
目标平台	Windows
标头	wlanapi.h (包括 Wlanapi.h)
Library	Wlanapi.lib
DLL	Wlanapi.dll
可再发行组件	适用于 Windows XP 的无线 LAN API SP2