為配合主幹穩定開發模型，並確保生態系統的平台穩定性，我們將自 2026 年起，在第 2 季和第 4 季將原始碼發布至 AOSP。如要建構及貢獻 AOSP，請使用 android-latest-release。android-latest-release 資訊清單分支版本一律會參照推送至 Android 開放原始碼計畫的最新版本。詳情請參閱「Android 開放原始碼計畫變更」。

Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

WifiHelper

public class WifiHelper
extends Object implements IWifiHelper

java.lang.Object
↳	com.android.tradefed.device.WifiHelper

用於操控裝置上 Wi-Fi 服務的輔助類別。

摘要

常數
`String`	`INSTRUMENTATION_PKG`

公用建構函式
`WifiHelper(ITestDevice device)`
`WifiHelper(ITestDevice device, String wifiUtilApkPath)`
`WifiHelper(ITestDevice device, String wifiUtilApkPath, boolean doSetup)` Alternative constructor that can skip the setup of the wifi apk.
`WifiHelper(ITestDevice device, String wifiUtilApkPath, boolean doSetup, boolean useV2)` 建構函式，用於指定是否使用新的 Wi-Fi 輔助程式 v2。

公用方法
`boolean`	`addOpenNetwork(String ssid)` 新增由 SSID 識別的開放式安全網路。
`boolean`	`addOpenNetwork(String ssid, boolean scanSsid)` 新增由 SSID 識別的開放式安全網路。
`boolean`	`addWpaPskNetwork(String ssid, String psk)` 新增由 ssid 識別的 WPA-PSK 安全網路。
`boolean`	`addWpaPskNetwork(String ssid, String psk, boolean scanSsid)` 新增由 ssid 識別的 WPA-PSK 安全網路。
`boolean`	`checkConnectivity(String urlToCheck)` 向指定網址傳送 HTTP 要求，檢查連線狀態。
`void`	`cleanUp()` 清理資源和 Wi-Fi 輔助程式套件安裝。
`boolean`	`connectToNetwork(String ssid, String psk, String urlToCheck)` 連線至 Wi-Fi 網路並檢查連線狀態。
`IWifiHelper.WifiConnectionResult`	`connectToNetwork(String ssid, String psk, String urlToCheck, boolean scanSsid, String defaultType)` 連線至 Wi-Fi 網路並檢查連線狀態。
`IWifiHelper.WifiConnectionResult`	`connectToNetwork(String ssid, String psk, String urlToCheck, boolean scanSsid)` 連線至 Wi-Fi 網路並檢查連線狀態。
`boolean`	`disableWifi()` 停用裝置的 Wi-Fi 狀態。
`boolean`	`disconnectFromNetwork()` 中斷目前的 Wi-Fi 網路連線，並停用 Wi-Fi。
`boolean`	`enableWifi()` 在裝置上啟用 Wi-Fi 狀態。
`static File`	`extractWifiUtilApk()` Helper method to extract the wifi util apk from the classpath
`String`	`getBSSID()` 取得目前存取點的基本服務集 ID (BSSID)。
`String`	`getIpAddress()` 取得與 Wi-Fi 介面相關聯的 IP 位址。
`String`	`getSSID()` 取得目前連線網路的服務集識別碼。
`Map<String, String>`	`getWifiInfo()` 取得目前的 Wi-Fi 連線資訊。
`boolean`	`hasValidIp()`
`boolean`	`isWifiEnabled()` 檢查目前是否已啟用 Wi-Fi。
`boolean`	`removeAllNetworks()` 移除所有已知網路。
`boolean`	`startMonitor(long interval, String urlToCheck)` 開始監控網路連線。
`List<Long>`	`stopMonitor()` 停止監控網路連線。
`boolean`	`waitForIp(long timeout)` 等待系統將 IP 位址指派給 Wi-Fi 介面卡。
`boolean`	`waitForWifiDisabled(long timeout)` 等待 `isWifiEnabled()` 變成 false。
`boolean`	`waitForWifiDisabled()` 等待 `isWifiEnabled()` 變成 false，並使用預設逾時。
`boolean`	`waitForWifiEnabled(long timeout)` 等待 `isWifiEnabled()` 變成 true。
`boolean`	`waitForWifiEnabled()` 等待 `isWifiEnabled()` 成為 true，並使用預設逾時。
`boolean`	`waitForWifiState(WifiState... expectedStates)` 等待預期的 Wi-Fi 狀態發生。

常數

INSTRUMENTATION_PKG

public static final String INSTRUMENTATION_PKG

常數值： "com.android.tradefed.utils.wifi"

公用建構函式

WifiHelper

public WifiHelper (ITestDevice device)

參數
`device`	`ITestDevice`

擲回
`DeviceNotAvailableException`

WifiHelper

public WifiHelper (ITestDevice device, 
                String wifiUtilApkPath)

參數
`device`	`ITestDevice`
`wifiUtilApkPath`	`String`

擲回
`DeviceNotAvailableException`

WifiHelper

public WifiHelper (ITestDevice device, 
                String wifiUtilApkPath, 
                boolean doSetup)

可略過 Wi-Fi APK 設定的替代建構函式。

參數
`device`	`ITestDevice`
`wifiUtilApkPath`	`String`
`doSetup`	`boolean`

擲回
`DeviceNotAvailableException`

WifiHelper

public WifiHelper (ITestDevice device, 
                String wifiUtilApkPath, 
                boolean doSetup, 
                boolean useV2)

建構函式，用於指定是否使用新的 Wi-Fi 輔助程式 v2。v2 作業不需要安裝 Wi-Fi 應用程式 APK。

參數
`device`	`ITestDevice`
`wifiUtilApkPath`	`String`
`doSetup`	`boolean`
`useV2`	`boolean`

擲回
`DeviceNotAvailableException`

公用方法

addOpenNetwork

public boolean addOpenNetwork (String ssid)

新增由 SSID 識別的開放式安全網路。

如要連上任何 Wi-Fi 網路，必須先在 wpa_supplicant 設定中建立網路設定檔。這會呼叫 wpa_cli，以新增由 ssid 識別的開放式安全網路。

參數
`ssid`	`String`：要新增的網路 SSID。

傳回
`boolean`	如果成功新增聯播網，則為 `true`，否則為 `false`。

擲回
`DeviceNotAvailableException`

addOpenNetwork

public boolean addOpenNetwork (String ssid, 
                boolean scanSsid)

新增由 SSID 識別的開放式安全網路。

如要連上任何 Wi-Fi 網路，必須先在 wpa_supplicant 設定中建立網路設定檔。這會呼叫 wpa_cli，以新增由 ssid 識別的開放式安全網路。

參數
`ssid`	`String`：要新增的網路 SSID。
`scanSsid`	`boolean`：是否掃描這個網路的隱藏 SSID。

傳回
`boolean`	如果成功新增聯播網，則為 `true`，否則為 `false`。

擲回
`DeviceNotAvailableException`

addWpaPskNetwork

public boolean addWpaPskNetwork (String ssid, 
                String psk)

新增由 ssid 識別的 WPA-PSK 安全網路。

參數
`ssid`	`String`：要新增的網路 SSID。
`psk`	`String`：要使用的 WPA-PSK 密碼

傳回
`boolean`	如果成功新增聯播網，則為 `true`，否則為 `false`。

擲回
`DeviceNotAvailableException`

addWpaPskNetwork

public boolean addWpaPskNetwork (String ssid, 
                String psk, 
                boolean scanSsid)

新增由 ssid 識別的 WPA-PSK 安全網路。

參數
`ssid`	`String`：要新增的網路 SSID。
`psk`	`String`：要使用的 WPA-PSK 密碼
`scanSsid`	`boolean`：是否掃描這個網路的隱藏 SSID。

傳回
`boolean`	如果成功新增聯播網，則為 `true`，否則為 `false`。

擲回
`DeviceNotAvailableException`

checkConnectivity

public boolean checkConnectivity (String urlToCheck)

透過向指定網址傳送 HTTP 要求，檢查連線狀態。

參數
`urlToCheck`	`String`：HTTP 要求檢查的目的地網址

傳回
`boolean`	`true` 裝置是否通過連線檢查。

擲回
`DeviceNotAvailableException`

cleanUp

public void cleanUp ()

清理資源並安裝 Wi-Fi 輔助程式套件。如果呼叫不再需要 Wi-Fi，就應呼叫這個方法，因為解除安裝輔助程式時，裝置會失去 Wi-Fi 連線。

擲回
`DeviceNotAvailableException`

connectToNetwork

public boolean connectToNetwork (String ssid, 
                String psk, 
                String urlToCheck)

連線至 Wi-Fi 網路並檢查連線狀態。

參數
`ssid`	`String`：要連線的網路 SSID
`psk`	`String`：要使用的 WPA-PSK 密碼片語。這個值可以為空值。
`urlToCheck`	`String`：HTTP 要求檢查的目的地網址

傳回
`boolean`	`true` 裝置是否通過連線檢查。

擲回
`DeviceNotAvailableException`

connectToNetwork

public IWifiHelper.WifiConnectionResult connectToNetwork (String ssid, 
                String psk, 
                String urlToCheck, 
                boolean scanSsid, 
                String defaultType)

連線至 Wi-Fi 網路並檢查連線狀態。

參數
`ssid`	`String`：要連線的網路 SSID
`psk`	`String`：要使用的 WPA-PSK 密碼片語。這個值可以為空值。
`urlToCheck`	`String`：HTTP 要求檢查的目的地網址
`scanSsid`	`boolean`：是否掃描這個網路的隱藏 SSID
`defaultType`	`String`：如果無法判斷 SSID 的網路類型，則會改用這個預設網路類型

傳回
`IWifiHelper.WifiConnectionResult`	WifiConnectionResult，代表 Wi-Fi 連線結果

擲回
`DeviceNotAvailableException`

connectToNetwork

public IWifiHelper.WifiConnectionResult connectToNetwork (String ssid, 
                String psk, 
                String urlToCheck, 
                boolean scanSsid)

連線至 Wi-Fi 網路並檢查連線狀態。

參數
`ssid`	`String`：要連線的網路 SSID
`psk`	`String`：要使用的 WPA-PSK 密碼片語。這個值可以為空值。
`urlToCheck`	`String`：HTTP 要求檢查的目的地網址
`scanSsid`	`boolean`：是否掃描這個網路的隱藏 SSID

傳回
`IWifiHelper.WifiConnectionResult`	WifiConnectionResult，代表 Wi-Fi 連線結果

擲回
`DeviceNotAvailableException`

disableWifi

public boolean disableWifi ()

停用裝置的 Wi-Fi 狀態。

傳回
`boolean`	`true` (如果 Wi-Fi 已成功停用)

擲回
`DeviceNotAvailableException`

disconnectFromNetwork

public boolean disconnectFromNetwork ()

中斷目前的 Wi-Fi 網路連線，並停用 Wi-Fi。

傳回
`boolean`	如果作業成功，則為 `true`。

擲回
`DeviceNotAvailableException`

enableWifi

public boolean enableWifi ()

在裝置上啟用 Wi-Fi 狀態。

傳回
`boolean`	`true` (如果 Wi-Fi 已成功啟用)

擲回
`DeviceNotAvailableException`

extractWifiUtilApk

public static File extractWifiUtilApk ()

從類別路徑擷取 Wi-Fi 實用工具 APK 的輔助方法

傳回
`File`

擲回
`IOException`

getBSSID

public String getBSSID ()

取得目前存取點的基本服務集 ID (BSSID)。

傳回
`String`

擲回
`DeviceNotAvailableException`

getIpAddress

public String getIpAddress ()

取得與 Wi-Fi 介面相關聯的 IP 位址。如果無法擷取 IP 位址，則傳回 null。

傳回
`String`

擲回
`DeviceNotAvailableException`

getSSID

public String getSSID ()

取得目前連線網路的服務集 ID。

傳回
`String`

擲回
`DeviceNotAvailableException`

getWifiInfo

public Map<String, String> getWifiInfo ()

取得目前的 Wi-Fi 連線資訊。

包括 SSID、BSSID、IP 位址、連結速度和 RSSI。

傳回
`Map<String, String>`	包含 Wi-Fi 連線資訊的地圖。

擲回
`DeviceNotAvailableException`

hasValidIp

public boolean hasValidIp ()

傳回
`boolean`

擲回
`DeviceNotAvailableException`

isWifiEnabled

public boolean isWifiEnabled ()

確認目前是否已啟用 Wi-Fi。

傳回
`boolean`

擲回
`DeviceNotAvailableException`

removeAllNetworks

public boolean removeAllNetworks ()

移除所有已知網路。

傳回
`boolean`

擲回
`DeviceNotAvailableException`

startMonitor

public boolean startMonitor (long interval, 
                String urlToCheck)

開始監控網路連線。

參數
`interval`	`long`：連線檢查間隔。
`urlToCheck`	`String`：用於檢查連線的網址。

傳回
`boolean`	如果作業成功，則為 `true`。

擲回
`DeviceNotAvailableException`

stopMonitor

public List<Long> stopMonitor ()

停止監控網路連線。

這也會傳回自上次 IWifiHelper.startMonitor(long,String) 呼叫以來的延遲時間記錄。

傳回
`List<Long>`	延遲記錄。

擲回
`DeviceNotAvailableException`

waitForIp

public boolean waitForIp (long timeout)

等待系統將 IP 位址指派給 Wi-Fi 介面卡。

參數
`timeout`	`long`：等待時間長度

傳回
`boolean`	`true` if an ip address is assigned before timeout, `false` otherwise

擲回
`DeviceNotAvailableException`

waitForWifiDisabled

public boolean waitForWifiDisabled (long timeout)

等待 isWifiEnabled() 變成 false。

參數
`timeout`	`long`：等待時間 (以毫秒為單位)

傳回
`boolean`	如果 Wi-Fi 在逾時前已停用，則為 `true`，否則為 `false`。

擲回
`DeviceNotAvailableException`

waitForWifiDisabled

public boolean waitForWifiDisabled ()

等待 isWifiEnabled() 變成 false，並使用預設逾時。

傳回
`boolean`	如果 Wi-Fi 在逾時前已停用，則為 `true`，否則為 `false`。

擲回
`DeviceNotAvailableException`

waitForWifiEnabled

public boolean waitForWifiEnabled (long timeout)

等待 isWifiEnabled() 變成 true。

參數
`timeout`	`long`：等待時間 (以毫秒為單位)

傳回
`boolean`	如果逾時前已啟用 Wi-Fi，則為 `true`，否則為 `false`。

擲回
`DeviceNotAvailableException`

waitForWifiEnabled

public boolean waitForWifiEnabled ()

等待 isWifiEnabled() 成為 true，並使用預設逾時。

傳回
`boolean`	如果逾時前已啟用 Wi-Fi，則為 `true`，否則為 `false`。

擲回
`DeviceNotAvailableException`

waitForWifiState

public boolean waitForWifiState (WifiState... expectedStates)

等待直到出現預期的 Wi-Fi 狀態。

參數
`expectedStates`	`WifiState`：預期的一或多個 Wi-Fi 狀態

傳回
`boolean`	`true` (如果發生其中一個預期狀態)。`false` (如果逾時前未發生任何狀態)

擲回
`DeviceNotAvailableException`