WlanScan 函数 （wlanapi.h）

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

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
);

参数

[in] hClientHandle

客户端的会话句柄，由先前对 WlanOpenHandle 函数的调用获取。

[in] pInterfaceGuid

要查询的接口的 GUID。

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

[in, optional] pDot11Ssid

指向 DOT11_SSID 结构的指针，该结构指定要扫描的网络的 SSID。 此参数可以为 NULL。 带有 SP3 和 Windows XP 的无线 LAN API 的 Windows XP 和 SP2： 此参数必须为 NULL。

[in, optional] pIeData

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

pReserved

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

返回值

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

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

注解

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 成员的最大值。

有关 PSD IDE 的详细信息（包括有关 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 函数来启动扫描。 然后，应用程序应等待接收wlan_notification_acm_scan_complete通知或在 4 秒后超时。 然后，应用程序可以调用 WlanGetNetworkBssList 或 WlanGetAvailableNetworkList 函数来检索可用无线网络的列表。 此过程可以定期重复，应用程序会跟踪对可用无线网络的更改。

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

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

要求

另请参阅

DOT11_SSID

WLAN_RAW_DATA

WlanEnumInterfaces

WlanGetAvailableNetworkList

WlanGetNetworkBssList

WlanRegisterNotification

WlanSetPsdIEDataList