WlanGetNetworkBssList 函式 (wlanapi.h)

發行項
03/04/2024

注意

針對發行前產品的部分相關資訊，在產品正式發行時可能會有大幅修改。針對此處提供的資訊，Microsoft 不做任何明示或默許的擔保。

重要

此 API 將受到即將變更操作系統行為所影響，其計劃為 2024 年 2024 年。如需詳細資訊，請參閱 Wi-Fi 存取和位置的 API 行為變更。

WlanGetNetworkBssList 函式會擷取在指定無線 LAN 介面上無線網路或網路上 (BSS) 專案的基本服務集清單。

語法

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。

如果函式失敗，傳回值可能是下列其中一個傳回碼。

傳回碼	Description
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 或 Windows XP 搭配 SP2 用戶端的無線 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 中所傳回的任何資訊，都是由 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)
程式庫	Wlanapi.lib
Dll	Wlanapi.dll