wlanScan 函式 (wlanapi.h)

發行項
03/04/2024

注意

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

重要

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

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 時，傳回的清單會包含所有可用的網路。 Windows XP 搭配 SP3 和適用於 Windows XP 的無線 LAN API 與 SP2： 此參數必須是 NULL。

[in, optional] pIeData

要包含在探查要求中之信息專案的指標。此參數指向可能包含用戶端布建可用性資訊和 802.1X 驗證需求的 WLAN_RAW_DATA 結構。Windows XP 搭配 SP3 和適用於 Windows XP 的無線 LAN API 與 SP2： 此參數必須是 NULL。

pReserved

保留供未來使用。必須設定為 NULL。

傳回值

如果函式成功，傳回值會ERROR_SUCCESS。

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

傳回碼	Description
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 (IE) 資訊元素。例如，Wi-Fi 受保護的設定 (WPS) IE 可以包含在探查要求中，以探索支援 WPS 的存取點。 pIeData 參數所指向的緩衝區必須包含從元素標識元開始的完整 IE。

傳遞至 WlanScan 函式的 pIeData 參數可以包含選擇性WLAN_RAW_DATA結構的指標，其中包含鄰近服務探索 (PSD) IE 數據專案。

用來儲存 PSD IE 時，Wlanapi.h 頭檔中定義的DOT11_PSD_IE_MAX_DATA_SIZE常數是 dwDataSize 成員的最大值。

常數	值	Description
DOT11_PSD_IE_MAX_DATA_SIZE	240	PSD IE 數據輸入的數據大小上限，以位元組為單位。

如需 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 函式來起始掃描。然後，應用程式應該等候在 4 秒後收到wlan_notification_acm_scan_complete通知或逾時。然後應用程式可以呼叫 WlanGetNetworkBssList 或 WlanGetAvailableNetworkList 函式，以擷取可用無線網路的清單。應用程式可以定期重複此程式，以持續追蹤可用無線網路的變更。

WlanScan 函式會立即傳回，而且在 Windows XP 上完成掃描 SP3 或 Windows XP SP2 的無線 LAN API 時，不會提供通知。

由於無線介面在掃描發生時傳送和接收數據封包變得比較困難， 因此 WlanScan 函式可能會增加延遲，直到網路掃描完成為止。

規格需求

需求	值
最低支援的用戶端	Windows Vista、Windows XP 與 SP3 [僅限傳統型應用程式]
最低支援的伺服器	Windows Server 2008 [僅限傳統型應用程式]
目標平台	Windows
標頭	wlanapi.h (包含 Wlanapi.h)
程式庫	Wlanapi.lib
Dll	Wlanapi.dll
可轉散發套件	適用於 Windows XP 與 SP2 的無線 LAN API