wlanScan 函数 (wlanapi.h)
注意
一些信息与预发行产品相关，相应产品在商业发行之前可能会进行重大修改。 对于此处提供的信息，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。
如果函数失败，则返回值可能是以下返回代码之一。
| 返回代码 | 说明 |
|---|---|
|
hClientHandle 为 NULL 或无效， pInterfaceGuid 为 NULL，或 pReserved 不为 NULL。 |
|
在句柄表中找不到句柄 hClientHandle 。 |
|
各种错误代码。 |
|
未能为查询结果分配内存。 |
注解
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 |