wlanapi.h) (WlanGetNetworkBssList 函数

项目
03/09/2024

注意

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

重要

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

WlanGetNetworkBssList 函数检索 (BSS) 给定无线 LAN 接口上无线网络或网络的条目的基本服务集的列表。

语法

DWORD WlanGetNetworkBssList(
  [in]       HANDLE            hClientHandle,
  [in]       const GUID        *pInterfaceGuid,
  [optional] const PDOT11_SSID pDot11Ssid,
  [in]       DOT11_BSS_TYPE    dot11BssType,
  [in]       BOOL              bSecurityEnabled,
             PVOID             pReserved,
  [out]      PWLAN_BSS_LIST    *ppWlanBssList
);

参数

[in] hClientHandle

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

[in] pInterfaceGuid

指向要查询的无线 LAN 接口 GUID 的指针。

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

[optional] pDot11Ssid

指向 DOT11_SSID 结构的指针，该结构指定从中请求 BSS 列表的网络的 SSID。此参数是可选的。如果设置为 NULL，则返回的列表包含无线 LAN 接口上的所有可用 BSS 条目。

如果指定了指向 DOT11_SSID 结构的指针，则DOT11_SSID 结构的 uSSIDLength 成员中指定的 SSID 长度必须小于或等于 wlantypes.h 头文件中定义的DOT11_SSID_MAX_LENGTH。此外，必须将 dot11BssType 参数设置为 dot11_BSS_type_infrastructure 或 dot11_BSS_type_independent 并且必须指定 bSecurityEnabled 参数。

[in] dot11BssType

网络的 BSS 类型。如果未指定 BSS 列表的网络 SSID， (pDot11Ssid 参数为 NULL) ，则忽略此参数。

此参数可以是在 wlantypes.h 头文件中定义的 DOT11_BSS_TYPE 枚举中定义的以下值之一。

值	含义
dot11_BSS_type_infrastructure	基础结构 BSS 网络。
dot11_BSS_type_independent	独立 BSS (IBSS) 网络 (临时网络) 。
dot11_BSS_type_any	任何 BSS 网络。

[in] bSecurityEnabled

一个值，该值指示是否在网络上启用安全性。仅当为 BSS 列表指定了网络的 SSID (pDot11Ssid 参数不为 NULL) 时，此参数才有效。

pReserved

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

[out] ppWlanBssList

指向存储的指针，用于接收 WLAN_BSS_LIST 结构中返回的 BSS 条目列表。

如果调用成功，则由 WlanGetNetworkBssList 函数分配返回WLAN_BSS_LIST的缓冲区。

返回值

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

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

返回代码	说明
ERROR_INVALID_HANDLE	在句柄表中找不到句柄 hClientHandle 。
ERROR_INVALID_PARAMETER	参数不正确。如果 hClientHandle、 pInterfaceGuid 或 ppWlanBssList 参数为 NULL，则返回此错误。如果 pReserved 不为 NULL，则返回此错误。如果 hClientHandle、pDot11Ssid 参数中指定的 SSID 或 dot11BssType 参数中指定的 BSS 类型无效，也会返回此错误。
ERROR_NDIS_DOT11_POWER_STATE_INVALID	与接口关联的无线电已关闭。当无线电关闭时，BSS 列表不可用。
ERROR_NOT_ENOUGH_MEMORY	没有足够的内存可用于处理此请求并为查询结果分配内存。
ERROR_NOT_FOUND	找不到该元素。如果找不到 pInterfaceGuid 参数中指定的要查询的接口的 GUID，则返回此错误。
ERROR_NOT_SUPPORTED	不支持该请求。如果从具有 SP3 的 Windows XP 或具有 SP2 客户端的 Windows XP 无线 LAN API 调用此函数，则返回此错误。如果禁用 WLAN 自动配置服务，也会返回此错误。
ERROR_SERVICE_NOT_ACTIVE	WLAN 自动配置服务尚未启动。
RPC_STATUS	各种错误代码。

注解

WlanGetNetworkBssList 函数检索给定接口上可访问的每个无线网络或网络的基本服务集列表。为每个无线网络返回的信息列表还包含基础结构 BSS 网络的每个接入点或独立 BSS 网络的网络对等方返回的信息元素列表， (即席网络) 。信息作为指向 ppWlanBssList 参数中的 WLAN_BSS_LIST 结构的指针返回。 WLAN_BSS_LIST 结构包含项计数，后跟WLAN_BSS_ENTRY结构条目数组。

由于 WlanGetNetworkBssList 函数返回的信息是由基础结构 BSS 网络的接入点或独立 BSS 网络 (即席网络) 的网络对等方发送的，因此返回的信息不应受信任。应使用 WLAN_BSS_ENTRY 结构中的 ulIeOffset 和 ulIeSize 成员来确定WLAN_BSS_ENTRY结构中的信息元素数据 blob 的大小，而不是信息元素数据 blob 本身中的数据。 WlanGetNetworkBssList 函数不会验证 ulIeOffset 成员指向的信息元素数据 Blob 中返回的任何信息是否为无线 LAN 的 IEEE 802.11 标准定义的有效信息元素。

如果指定了 pDot11Ssid 参数 (非 NULL) ，则必须将指定的 dot11BssType 参数设置为基础结构 BSS 网络的dot11_BSS_type_infrastructure或独立 BSS 网络 (即席网络) dot11_BSS_type_independent。如果将 dot11BssType 参数设置为 dot11_BSS_type_any，则 WlanGetNetworkBssList 函数将返回ERROR_SUCCESS但不返回 BSS 条目。

若要返回无线 LAN 接口上) 的所有基础结构 BSS 网络和独立 BSS 网络 (即席网络的列表，请将 pDot11Ssid 参数设置为 NULL。当无线 LAN 接口也作为无线托管网络运行时，BSS 列表将包含为无线托管网络创建的 BSS 条目。

WLAN 自动配置服务返回空 BSS 列表时， WlanGetNetworkBssList 函数返回ERROR_SUCCESS。调用 WlanGetNetworkBssList 函数的应用程序必须检查 ppWlanBssList 参数指向的WLAN_BSS_LIST的 dwNumberOfItems 成员不是零，然后才能访问WLAN_BSS_LIST结构中的 wlanBssEntries[0] 成员。

当函数成功时， WlanGetNetworkBssList 函数为 在 ppWlanBssList 参数指向的缓冲区中返回的基本服务集列表分配内存。不再需要缓冲区后，应通过调用 WlanFreeMemory 函数释放 ppWlanBssList 参数指向的缓冲区所用的内存。

要求

要求	值
最低受支持的客户端	Windows Vista [仅限桌面应用]
最低受支持的服务器	Windows Server 2008 [仅限桌面应用]
目标平台	Windows
标头	wlanapi.h (包括 Wlanapi.h)
Library	Wlanapi.lib
DLL	Wlanapi.dll