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 安裝，因此系統預設會將這個 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

fun getActiveRequestCount(): Int

傳回有效要求的數量。

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

fun getDownstreamThroughputKbps(): Int

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

fun getEffectiveConnectionType(): Int

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

fun getHttpRttMs(): Int

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

fun getTransportRttMs(): Int

傳回網路品質估算器計算出的傳輸封包往返時間估算值 (以毫秒為單位)。如果值無法使用，請設為 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 記錄並將檔案排清至磁碟。如果記錄工作階段未進行中，系統會忽略此呼叫。