CronetEngine

const val ACTIVE_REQUEST_COUNT_UNKNOWN = -1: Int

有效要求計數值不明

const val CONNECTION_METRIC_UNKNOWN = -1: Int

連線指標的值不明。

const val EFFECTIVE_CONNECTION_TYPE_2G = 3: Int

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

const val EFFECTIVE_CONNECTION_TYPE_3G = 4: Int

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

const val EFFECTIVE_CONNECTION_TYPE_4G = 5: Int

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

const val EFFECTIVE_CONNECTION_TYPE_OFFLINE = 1: Int

裝置處於離線狀態。

const val EFFECTIVE_CONNECTION_TYPE_SLOW_2G = 2: Int

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

const val EFFECTIVE_CONNECTION_TYPE_UNKNOWN = 0: Int

無法估算有效連線類型。

const val UNBIND_NETWORK_HANDLE = -1: Long

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

fun addRequestFinishedListener(listener: RequestFinishedInfo.Listener!): Unit

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

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

fun addRttListener(listener: NetworkQualityRttListener!): Unit

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

fun addThroughputListener(listener: NetworkQualityThroughputListener!): Unit

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

fun bindToNetwork(networkHandle: Long): Unit

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

fun configureNetworkQualityEstimatorForTesting(
    useLocalHostRequests: Boolean,
    useSmallerResponses: Boolean,
    disableOfflineCheck: Boolean
): Unit

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

abstract fun createURLStreamHandlerFactory(): URLStreamHandlerFactory!

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

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

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

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

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

fun getActiveRequestCount(): Int

傳回有效要求數。

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

fun getDownstreamThroughputKbps(): Int

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

fun getEffectiveConnectionType(): Int

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

fun getHttpRttMs(): Int

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

fun getTransportRttMs(): Int

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

abstract fun newUrlRequestBuilder(
    url: String!,
    callback: UrlRequest.Callback!,
    executor: Executor!
): UrlRequest.Builder!

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

abstract fun openConnection(url: URL!): URLConnection!

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

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

fun removeRequestFinishedListener(listener: RequestFinishedInfo.Listener!): Unit

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

fun removeRttListener(listener: NetworkQualityRttListener!): Unit

如果先前已使用 addRttListener 註冊，則移除往返時間的監聽器。加入 NetworkQualityRttListener 後，應呼叫這個方法，停止接收觀察項目。

fun removeThroughputListener(listener: NetworkQualityThroughputListener!): Unit

移除處理量的監聽器。加入 NetworkQualityThroughputListener 和 addThroughputListener 後，應呼叫這個方法，停止接收觀察項目。

abstract fun shutdown(): Unit

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

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

fun startNetLogToDisk(dirPath: String!, logAll: Boolean, maxSize: Int): Unit

開始將 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，查看記錄。

abstract fun startNetLogToFile(fileName: String!, logAll: Boolean): Unit

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

abstract fun stopNetLog(): Unit

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