WlanScan 函數（wlanapi.h）

備註

尚未發布產品的部分資訊在正式上市前可能會進行重大更改。 Microsoft 對於此處提供的資訊，不做任何明確或隱含的保證。

這很重要

此 API 將受到即將於 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。

本機電腦上啟用的每個無線 LAN 介面的 GUID 可以使用 WlanEnumInterfaces 函式來判斷。

[in, optional] pDot11Ssid

指向 DOT11_SSID 結構的指標，指定要掃描的網路的 SSID。此參數可能是 NULL。 Windows XP SP3 和適用於 Windows XP SP2 的無線 LAN API： 此參數必須是 NULL。

[in, optional] pIeData

要併入探測要求中之資訊元素的指標。此參數指向一個WLAN_RAW_DATA結構，其中可能包括客戶端布建可用性資訊和 802.1X 身份驗證要求。Windows XP SP3 和適用於 Windows XP SP2 的無線 LAN API： 此參數必須是 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）。例如，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 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 函式會立即傳回，而且不會在 Windows XP SP3 或 Windows XP SP2 的無線 LAN API 上掃描完成時提供通知。

由於無線介面在掃描過程中發送和接收資料包變得更加困難，因此 WlanScan 功能可能會增加延遲，直到網路掃描完成。

需求

Requirement	價值觀
最低支援的用戶端	Windows Vista、Windows XP 與 SP3 [僅限傳統型應用程式]
支援的最低伺服器	Windows Server 2008 [僅限傳統型應用程式]
目標平臺	窗戶
Header	wlanapi.h（包括 Wlanapi.h）
Library	瓦拉納皮.lib
DLL	Wlanapi.dll
可再發行	Windows XP 與 SP2 的無線 LAN API