Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

CronetEngine

public abstract class CronetEngine

已知的直接子類別

CronetEngineBase

CronetEngineBase

已知間接子類別

JavaCronetEngine

JavaCronetEngine

java.net.HttpURLConnection支援的 CronetEngine。

處理 UrlRequest 的引擎，會使用目前平台提供的最佳 HTTP 堆疊。這個類別的例項可以使用 Builder 建立。

摘要

巢狀型別
`public class CronetEngine.Builder` `CronetEngine` 的建構工具，可讓您在執行階段設定 `CronetEngine`。
`public abstract class CronetEngine.Builder.LibraryLoader` 這個類別已淘汰。在 minSDK <= 23 上，System.loadLibrary 不可靠，因此這個方法用於提供替代的更可靠載入器。

巢狀型別

public class CronetEngine.Builder

CronetEngine 的建構工具，可讓您在執行階段設定 CronetEngine。

public abstract class CronetEngine.Builder.LibraryLoader

這個類別已淘汰。

在 minSDK <= 23 上，System.loadLibrary 不可靠，因此這個方法用於提供替代的更可靠載入器。

常數
`static final int`	`ACTIVE_REQUEST_COUNT_UNKNOWN = -1` 有效要求計數值不明
`static final int`	`CONNECTION_METRIC_UNKNOWN = -1` 連線指標的值不明。
`static final int`	`EFFECTIVE_CONNECTION_TYPE_2G = 3` 有效連線類型預估為 2G。
`static final int`	`EFFECTIVE_CONNECTION_TYPE_3G = 4` 預估有效連線類型為 3G。
`static final int`	`EFFECTIVE_CONNECTION_TYPE_4G = 5` 預估有效連線類型為 4G。
`static final int`	`EFFECTIVE_CONNECTION_TYPE_OFFLINE = 1` 裝置處於離線狀態。
`static final int`	`EFFECTIVE_CONNECTION_TYPE_SLOW_2G = 2` 有效連線類型估算值為緩慢的 2G。
`static final int`	`EFFECTIVE_CONNECTION_TYPE_UNKNOWN = 0` 有效連線類型估算值不明。
`static final long`	`UNBIND_NETWORK_HANDLE = -1` 用於還原先前網路繫結的值。

公用建構函式
`CronetEngine()`

公用方法
`void`	`addRequestFinishedListener(RequestFinishedInfo.Listener listener)` 註冊事件監聽器，在每個要求結束後呼叫，並提供要求資訊。
`void`	`addRttListener(NetworkQualityRttListener listener)` 註冊監聽器，每當網路品質估算器觀察到樣本來回時間時，就會呼叫該監聽器。
`void`	`addThroughputListener(NetworkQualityThroughputListener listener)` 註冊監聽器，每當網路品質估算器觀察到樣本輸送量測量時，就會呼叫該監聽器。
`void`	`bindToNetwork(long networkHandle)` 將引擎繫結至指定的網路控制代碼。
`void`	`configureNetworkQualityEstimatorForTesting( boolean useLocalHostRequests, boolean useSmallerResponses, boolean disableOfflineCheck )` 設定網路品質估算器以進行測試。
`abstract URLStreamHandlerFactory`	`createURLStreamHandlerFactory()` 建立 `URLStreamHandlerFactory` 來處理 HTTP 和 HTTPS 流量。
`int`	`getActiveRequestCount()` 傳回有效要求的數量。
`int`	`getDownstreamThroughputKbps()` 傳回網路品質估算器計算的下行吞吐量估計值 (以每秒千位元為單位)。
`int`	`getEffectiveConnectionType()` 傳回網路品質估算器計算的有效連線類型估算值。
`abstract byte[]`	`getGlobalMetricsDeltas()` 這個方法已淘汰。在 Cronet 的新版中，這項設定一律會傳回空陣列。
`int`	`getHttpRttMs()` 傳回網路品質估算器計算出的 HTTP 封包往返時間估計值 (以毫秒為單位)。
`int`	`getTransportRttMs()` 傳回網路品質估算器計算出的傳輸封包往返時間估計值 (以毫秒為單位)。
`abstract String`	`getVersionString()`
`abstract UrlRequest.Builder`	`newUrlRequestBuilder( String url, UrlRequest.Callback callback, Executor executor )` 建立 `UrlRequest` 的建構工具。
`abstract URLConnection`	`openConnection(URL url)` 建立與 `URLurl` 指定資源的新連線。
`void`	`removeRequestFinishedListener(RequestFinishedInfo.Listener listener)` 移除已完成的要求監聽器。
`void`	`removeRttListener(NetworkQualityRttListener listener)` 如果先前已透過 `addRttListener` 註冊，則移除往返時間的監聽器。
`void`	`removeThroughputListener(NetworkQualityThroughputListener listener)` 移除處理量的監聽器。
`abstract void`	`shutdown()` 如果沒有任何有效要求，則會關閉 `CronetEngine`，否則會擲回例外狀況。
`void`	`startNetLogToDisk(String dirPath, boolean logAll, int maxSize)` 開始將 NetLog 記錄檔記錄到指定目錄，並限制大小。
`abstract void`	`startNetLogToFile(String fileName, boolean logAll)` 開始將 NetLog 記錄寫入檔案。
`abstract void`	`stopNetLog()` 停止 NetLog 記錄並將檔案排清至磁碟。

常數

ACTIVE_REQUEST_COUNT_UNKNOWN

public static final int ACTIVE_REQUEST_COUNT_UNKNOWN = -1

有效要求計數值不明

CONNECTION_METRIC_UNKNOWN

public static final int CONNECTION_METRIC_UNKNOWN = -1

連線指標的值不明。

EFFECTIVE_CONNECTION_TYPE_2G

public static final int EFFECTIVE_CONNECTION_TYPE_2G = 3

有效連線類型預估為 2G。

另請參閱
`getEffectiveConnectionType`

EFFECTIVE_CONNECTION_TYPE_3G

public static final int EFFECTIVE_CONNECTION_TYPE_3G = 4

預估有效連線類型為 3G。

另請參閱
`getEffectiveConnectionType`

EFFECTIVE_CONNECTION_TYPE_4G

public static final int EFFECTIVE_CONNECTION_TYPE_4G = 5

預估有效連線類型為 4G。

另請參閱
`getEffectiveConnectionType`

EFFECTIVE_CONNECTION_TYPE_OFFLINE

public static final int EFFECTIVE_CONNECTION_TYPE_OFFLINE = 1

裝置處於離線狀態。

另請參閱
`getEffectiveConnectionType`

EFFECTIVE_CONNECTION_TYPE_SLOW_2G

public static final int EFFECTIVE_CONNECTION_TYPE_SLOW_2G = 2

有效連線類型估算值為緩慢的 2G。

另請參閱
`getEffectiveConnectionType`

EFFECTIVE_CONNECTION_TYPE_UNKNOWN

public static final int EFFECTIVE_CONNECTION_TYPE_UNKNOWN = 0

有效連線類型估算值不明。

另請參閱
`getEffectiveConnectionType`

UNBIND_NETWORK_HANDLE

public static final long UNBIND_NETWORK_HANDLE = -1

用於還原先前網路繫結的值。

公用建構函式

CronetEngine

public CronetEngine()

公用方法

addRequestFinishedListener

public void addRequestFinishedListener(RequestFinishedInfo.Listener listener)

註冊事件監聽器，在每個要求結束後呼叫，並提供要求資訊。

系統會在事件監聽器提供的 java.util.concurrent.Executor 上呼叫事件監聽器。

參數
`RequestFinishedInfo.Listener listener`	已完成要求的接聽器。

addRttListener

public void addRttListener(NetworkQualityRttListener listener)

註冊監聽器，每當網路品質估算器觀察到樣本來回時間時，就會呼叫該監聽器。這個方法必須在 enableNetworkQualityEstimator 之後呼叫，否則會擲回例外狀況。往返時間可能會記錄在網路堆疊的各個層，包括 TCP、QUIC 和網址要求層。系統會在傳遞至 enableNetworkQualityEstimator 的 java.util.concurrent.Executor 上呼叫事件監聽器。

參數
`NetworkQualityRttListener listener`	封包往返時間的接聽程式。

addThroughputListener

public void addThroughputListener(NetworkQualityThroughputListener listener)

註冊監聽器，每當網路品質估算器觀察到樣本輸送量測量結果時，就會呼叫該監聽器。這個方法必須在 enableNetworkQualityEstimator 之後呼叫。系統會測量至少收到一個網址回應時，透過有效網路介面讀取的位元組數，藉此計算輸送量觀察結果。系統會在傳遞至 enableNetworkQualityEstimator 的 java.util.concurrent.Executor 上呼叫事件監聽器。

參數
`NetworkQualityThroughputListener listener`	處理量監聽器。

bindToNetwork

public void bindToNetwork(long networkHandle)

將引擎繫結至指定的網路控制代碼。透過這個引擎建立的所有要求都會使用與這個控制代碼相關聯的網路。如果這個網路中斷連線，所有要求都會失敗，確切錯誤取決於網路中斷時的要求處理階段。網路控制代碼可透過 Network#getNetworkHandle 取得。僅適用於 Android Marshmallow 以上版本。

參數
`long networkHandle`	要將引擎繫結至的網路控制代碼。指定 `UNBIND_NETWORK_HANDLE` 即可取消繫結。

configureNetworkQualityEstimatorForTesting

public void configureNetworkQualityEstimatorForTesting(
    boolean useLocalHostRequests,
    boolean useSmallerResponses,
    boolean disableOfflineCheck
)

設定網路品質估算器以進行測試。必須先呼叫此函式，才能新增封包往返時間和處理量事件監聽器，且必須在啟用網路品質估算器後呼叫。

參數
`boolean useLocalHostRequests`	在預估值中納入對 localhost 的要求。
`boolean useSmallerResponses`	在處理量預估中納入小型回應。
`boolean disableOfflineCheck`	如果設為 true，計算有效連線類型或寫入偏好設定時，系統會停用裝置離線檢查。

createURLStreamHandlerFactory

public abstract URLStreamHandlerFactory createURLStreamHandlerFactory()

建立 URLStreamHandlerFactory 來處理 HTTP 和 HTTPS 流量。這個類別的執行個體可透過 setURLStreamHandlerFactory 安裝，因此系統預設會將這個 CronetEngine 用於透過 openConnection 建立的所有要求。

Cronet 不會使用系統提供的特定 HTTP 功能：

透過 HttpResponseCache.install() 安裝的 HTTP 快取
透過 setDefault 安裝的 HTTP 驗證方法
透過 setDefault 安裝的 HTTP Cookie 儲存空間

雖然 Cronet 支援並鼓勵使用 HTTPS 通訊協定發出要求，但 Cronet 不支援 HttpsURLConnection API。這項不支援也包括不使用系統提供的特定 HTTPS 功能：

透過 HttpsURLConnection.setDefaultHostnameVerifier() 安裝的 HTTPS 主機名稱驗證程式
透過 HttpsURLConnection.setDefaultSSLSocketFactory() 安裝的 HTTPS Socket Factory

傳回
`URLStreamHandlerFactory`	這個 CronetEngine 實作的 `URLStreamHandlerFactory` 例項。

getActiveRequestCount

public int getActiveRequestCount()

傳回有效要求的數量。

假設 UrlRequest.start() 方法不會擲回例外狀況，要求就會在該方法中變成「有效」。當所有回呼都已傳回，且日後無法再觸發其他回呼時，就會變成非使用中狀態。實際上，這表示 onSucceeded/onCanceled/onFailed 傳回後，且所有要求完成監聽器都已傳回，要求就會處於非使用中狀態。詳情請參閱 Cronet 要求的生命週期。

getDownstreamThroughputKbps

public int getDownstreamThroughputKbps()

傳回網路品質估算器計算的下行處理量估計值 (以每秒千位元為單位)。如果值無法使用，請設為 CONNECTION_METRIC_UNKNOWN。這必須在 enableNetworkQualityEstimator 之後呼叫，否則會擲回例外狀況。

傳回
`int`	預估下行處理量 (以每秒千位元為單位)。

getEffectiveConnectionType

public int getEffectiveConnectionType()

傳回網路品質估算器計算的有效連線類型估算值。呼叫 enableNetworkQualityEstimator 開始計算這個值。

傳回
`int`	預估連線類型。傳回值為 `EFFECTIVE_CONNECTION_TYPE_*` 的其中一個值。

getGlobalMetricsDeltas

public abstract byte[] getGlobalMetricsDeltas()

getHttpRttMs

public int getHttpRttMs()

傳回網路品質估算器計算出的 HTTP 封包往返時間估計值 (以毫秒為單位)。如果值無法使用，請設為 CONNECTION_METRIC_UNKNOWN。這必須在 enableNetworkQualityEstimator 之後呼叫，否則會擲回例外狀況。

傳回
`int`	HTTP RTT 的估計值 (以毫秒為單位)。

getTransportRttMs

public int getTransportRttMs()

傳回網路品質估算器計算出的傳輸封包往返時間估計值 (以毫秒為單位)。如果值無法使用，請設為 CONNECTION_METRIC_UNKNOWN。這必須在 enableNetworkQualityEstimator 之後呼叫，否則會擲回例外狀況。

傳回
`int`	預估的傳輸 RTT (以毫秒為單位)。

getVersionString

public abstract String getVersionString()

傳回
`String`	引擎的人類可讀版本字串。

newUrlRequestBuilder

public abstract UrlRequest.Builder newUrlRequestBuilder(
    String url,
    UrlRequest.Callback callback,
    Executor executor
)

建立 UrlRequest 的建構工具。系統會在 executor 的執行緒上，叫用所產生 UrlRequest 物件的所有回呼。為避免封鎖網路作業，並在關閉期間導致例外狀況，executor 不得在呼叫 execute 的執行緒上執行工作。

參數
`String url`	產生要求的網址。
`UrlRequest.Callback callback`	回呼物件，會在不同事件上叫用。
`Executor executor`	`Executor`，所有回呼都會在該執行緒上叫用。

openConnection

public abstract URLConnection openConnection(URL url)

建立與 URLurl 指定資源的新連線。

注意：Cronet 的 java.net.HttpURLConnection 實作方式設有特定限制，詳情請參閱 createURLStreamHandlerFactory。

參數
`URL url`	要連結的資源網址。

傳回
`URLConnection`	這個 CronetEngine 實作的 `java.net.HttpURLConnection` 例項。

擲回
`java.io.IOException`	如果開啟連線時發生錯誤。

removeRequestFinishedListener

public void removeRequestFinishedListener(RequestFinishedInfo.Listener listener)

移除已完成的要求監聽器。

參數
`RequestFinishedInfo.Listener listener`	要移除的接聽器。

removeRttListener

public void removeRttListener(NetworkQualityRttListener listener)

如果先前已透過 addRttListener 註冊，則移除來回時間的監聽器。加入 NetworkQualityRttListener 後，應呼叫這個方法，停止接收觀察結果。

參數
`NetworkQualityRttListener listener`	封包往返時間的接聽程式。

removeThroughputListener

public void removeThroughputListener(NetworkQualityThroughputListener listener)

移除處理量的監聽器。加入 NetworkQualityThroughputListener 後，應呼叫 addThroughputListener，停止接收觀測結果。

參數
`NetworkQualityThroughputListener listener`	處理量監聽器。

關機

public abstract void shutdown()

如果沒有任何有效要求，就會關閉 CronetEngine，否則會擲回例外狀況。

無法在網路執行緒上呼叫，也就是 Cronet 呼叫 Executor 的執行緒 (與 Executor 叫用回呼的執行緒不同)。可能會封鎖，直到所有 CronetEngine 的資源都已清除為止。

startNetLogToDisk

public void startNetLogToDisk(String dirPath, boolean logAll, int maxSize)

開始將 NetLog 記錄檔記錄到指定目錄，並限制大小。NetLog 會包含所有即時 CronetEngine 發出的事件。NetLog 適用於偵錯。停止記錄後 stopNetLog，資料會寫入 dirPath 中的 netlog.json。如果記錄作業中斷，您可以使用 https://chromium.googlesource.com/chromium/src/+/main/net/tools/stitch_net_log_files.py，手動縫合 .inprogress 子目錄中的檔案。使用 Chrome 瀏覽器前往 chrome://net-internals/#import，即可查看記錄。

參數
`String dirPath`	要建立 netlog.json 檔案的目錄。dirPath 必須已存在。目錄中不得有 NetLog 檔案。如果正在記錄，系統會忽略這個方法。
`boolean logAll`	`true`，將基本事件、使用者 Cookie、憑證和所有傳輸的位元組納入記錄。這個選項會公開使用者的憑證，因此有隱私權風險，請務必取得使用者同意，並確保記錄不會公開，再使用這個選項。`false`，只納入基本事件。
`int maxSize`	NetLog 應使用的磁碟空間總量上限 (以位元組為單位)。實際磁碟空間用量可能會略微超出這個限制。

startNetLogToFile

public abstract void startNetLogToFile(String fileName, boolean logAll)

開始將 NetLog 記錄寫入檔案。NetLog 會包含所有即時 CronetEngine 發出的事件。NetLog 適用於偵錯。使用 Chrome 瀏覽器前往 chrome://net-internals/#import 即可查看檔案

參數
`String fileName`	完整檔案路徑。不得留空。如果檔案存在，系統會先截斷檔案，再開始作業。如果正在記錄，系統會忽略這個方法。
`boolean logAll`	`true`，將基本事件、使用者 Cookie、憑證和所有傳輸的位元組納入記錄。這個選項會公開使用者的憑證，因此有隱私權風險，請務必取得使用者同意，並確保記錄不會公開，再使用這個選項。`false`，只納入基本事件。

stopNetLog

public abstract void stopNetLog()

停止 NetLog 記錄並將檔案排清至磁碟。如果記錄工作階段未進行中，系統會忽略此呼叫。