wlanScan 函式 (wlanapi.h)
注意
針對發行前產品的部分相關資訊，在產品正式發行時可能會有大幅修改。 針對此處提供的資訊，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 |
|---|---|
|
hClientHandle 為 NULL 或無效， pInterfaceGuid 為 NULL，或 pReserved 不是 NULL。 |
|
句柄數據表中找不到句柄 hClientHandle 。 |
|
各種錯誤碼。 |
|
無法為查詢結果配置記憶體。 |
備註
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 |