CronetEngine.Builder

class CronetEngine.Builder

CronetEngine 的建構工具，可讓您在執行階段設定 CronetEngine。設定選項會在建構工具上設定，然後呼叫 build 來建立 CronetEngine。

摘要

巢狀型別

這個類別已淘汰。

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

常數
const Int

設定為停用 HTTP 快取。
const Int

設定為啟用磁碟快取，包括 HTTP 資料。
const Int

設定為啟用磁碟快取，但不包括 HTTP 資料。
const Int

設定為啟用記憶體內 HTTP 快取，包括 HTTP 資料。

公用建構函式
Builder(context: Context!)

建構 Builder 物件，方便建立 CronetEngine。

公開函式
CronetEngine.Builder!
addPublicKeyPins(
    hostName: String!,
    pinsSha256: (Mutable)Set<ByteArray!>!,
    includeSubdomains: Boolean,
    expirationDate: Date!
)

為特定主機釘選一組公開金鑰。
CronetEngine.Builder!
addQuicHint(host: String!, port: Int, alternatePort: Int)

新增 host 支援 QUIC 的提示。
CronetEngine!

使用這個建構工具的設定建構 CronetEngine。
CronetEngine.Builder!

設定是否啟用 Brotli 壓縮。
CronetEngine.Builder!

設定是否啟用 HTTP/2 通訊協定。
CronetEngine.Builder!
enableHttpCache(cacheMode: Int, maxSize: Long)

啟用或停用 HTTP 資料和其他資訊 (例如 QUIC 伺服器資訊) 的快取。
CronetEngine.Builder!

啟用網路品質估算器，收集並回報網路堆疊各層的封包往返時間 (RTT) 和下游處理量測量結果。
CronetEngine.Builder!

啟用或停用本機信任錨點的公開金鑰固定繞過功能。
CronetEngine.Builder!

設定是否啟用 QUIC 通訊協定。
String!

建構 User-Agent 字串，包括應用程式名稱和版本、系統建構版本、型號和 ID，以及 Cronet 版本。
CronetEngine.Builder!
CronetEngine.Builder!

設定連線遷移作業的行為。
CronetEngine.Builder!

設定主機名稱查詢的行為。
CronetEngine.Builder!
CronetEngine.Builder!

這個函式已淘汰。

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

設定 Proxy 行為。
CronetEngine.Builder!
CronetEngine.Builder!

設定使用 QUIC 時的 Cronet 行為。
CronetEngine.Builder!

設定 HTTP 快取和 Cookie 儲存空間的目錄。
CronetEngine.Builder!

這個函式已淘汰。

在最新版 Cronet 中，這個方法不會執行任何動作。
CronetEngine.Builder!
setUserAgent(userAgent: String!)

覆寫所有要求的 User-Agent 標頭。

受保護的房源
JSONObject!

實驗性選項的 JSON 表示法。

常數

HTTP_CACHE_DISABLED

const val HTTP_CACHE_DISABLED = 0: Int

設定為停用 HTTP 快取。部分資料可能仍會暫時儲存在記憶體中。已轉交給「enableHttpCache」。

HTTP_CACHE_DISK

const val HTTP_CACHE_DISK = 3: Int

設定為啟用磁碟快取，包括 HTTP 資料。將這個常數傳遞至 enableHttpCache 之前，必須先呼叫 setStoragePath。

HTTP_CACHE_DISK_NO_HTTP

const val HTTP_CACHE_DISK_NO_HTTP = 2: Int

設定為啟用磁碟快取，但不包括 HTTP 資料。將這個常數傳遞至 enableHttpCache 之前，必須先呼叫 setStoragePath。

HTTP_CACHE_IN_MEMORY

const val HTTP_CACHE_IN_MEMORY = 1: Int

設定為啟用記憶體內 HTTP 快取，包括 HTTP 資料。已轉交給「enableHttpCache」。

公用建構函式

建構工具

Builder(context: Context!)

建構 Builder 物件，方便建立 CronetEngine。預設設定會啟用 HTTP/2 和 QUIC，但停用 HTTP 快取。

參數
context: Context!

Android Context，Builder 會使用這個類別擷取應用程式內容。系統只會保留應用程式內容的參照，避免不必要地延長 context 的生命週期。

公開函式

addPublicKeyPins

fun addPublicKeyPins(
    hostName: String!,
    pinsSha256: (Mutable)Set<ByteArray!>!,
    includeSubdomains: Boolean,
    expirationDate: Date!
): CronetEngine.Builder!

為特定主機綁定一組公開金鑰。綁定一組公開金鑰 pinsSha256 後，與 hostName 通訊時，必須使用公開金鑰來自綁定金鑰組的憑證進行驗證。應用程式可以釘選根憑證、任何中繼憑證或尾端項目憑證的公開金鑰。如果主機的憑證鏈結中沒有任何公開金鑰，即使主機嘗試使用裝置信任憑證存放區允許的憑證進行驗證，驗證也會失敗，且無法建立安全通訊。

如果使用相同主機名稱多次呼叫這個方法，系統會覆寫先前為該主機設定的固定憑證。

如要進一步瞭解公開金鑰固定，請參閱 RFC 7469。

參數
hostName: String!

要釘選公開金鑰的主機名稱。如果主機名稱只包含數字和半形句號，系統會視為無效。
pinsSha256: (Mutable)Set<ByteArray!>!

一組圖釘。每個固定位元都是主機 X.509 憑證主體公開金鑰資訊 (SPKI) 的 DER 編碼 ASN.1 表示法 SHA-256 密碼編譯雜湊。使用 Certificate.getPublicKey() 和 Key.getEncoded() 取得 SPKI 的 DER 編碼 ASN.1 表示法。雖然這個方法不會強制提供備用 PIN 碼 (如果遺失主要私密金鑰的控制權，可以使用該 PIN 碼)，但強烈建議您提供。
includeSubdomains: Boolean

指出是否應將固定政策套用至 hostName 的子網域。
expirationDate: Date!

指定 PIN 碼的到期日。
傳回
CronetEngine.Builder!

建構工具，方便鏈結。
擲回
java.lang.NullPointerException

如果任何輸入參數為 null。
java.lang.IllegalArgumentException

如果指定的主機名稱無效，或 pinsSha256 包含的位元組陣列並非有效的 SHA-256 雜湊。

addQuicHint

fun addQuicHint(host: String!, port: Int, alternatePort: Int): CronetEngine.Builder!

新增 host 支援 QUIC 的提示。請注意，如要在工作階段之間建立 0-RTT 連線，必須使用 enableHttpCache (HTTP_CACHE_DISK)。

參數
host: String!

支援 QUIC 的伺服器主機名稱。
port: Int

支援 QUIC 的伺服器主機。
alternatePort: Int

QUIC 要使用的替代通訊埠。
傳回
CronetEngine.Builder!

建構工具，方便鏈結。

build

fun build(): CronetEngine!

使用這個建構工具的設定建構 CronetEngine。

傳回
CronetEngine!

建構 CronetEngine。

enableBrotli

fun enableBrotli(value: Boolean): CronetEngine.Builder!

設定是否啟用 Brotli 壓縮功能。啟用後，系統會在 Accept-Encoding 要求標頭中宣傳 Brotli。預設為停用。

參數
value: Boolean

true 啟用 Brotli，false 停用。
傳回
CronetEngine.Builder!

建構工具，方便鏈結。

enableHttp2

fun enableHttp2(value: Boolean): CronetEngine.Builder!

設定是否啟用 HTTP/2 通訊協定。預設為啟用。

參數
value: Boolean

true 啟用 HTTP/2，false 停用。
傳回
CronetEngine.Builder!

建構工具，方便鏈結。

enableHttpCache

fun enableHttpCache(cacheMode: Int, maxSize: Long): CronetEngine.Builder!

啟用或停用 HTTP 資料和其他資訊 (例如 QUIC 伺服器資訊) 的快取。

參數
cacheMode: Int

控管快取資料的位置和類型。必須是 HTTP_CACHE_* 的其中一種格式。
maxSize: Long

用於快取資料的大小上限 (以位元組為單位，僅供參考，有時可能會超過)。
傳回
CronetEngine.Builder!

建構工具，方便鏈結。

enableNetworkQualityEstimator

fun enableNetworkQualityEstimator(value: Boolean): CronetEngine.Builder!

啟用網路品質估算器，收集並回報網路堆疊各層的封包往返時間 (RTT) 和下游處理量測量結果。啟用估算器後，即可使用 addRttListener 和 addThroughputListener 新增 RTT 和處理量監聽器，並使用 removeRttListener 和 removeThroughputListener 移除監聽器。只有在啟用估算器時，估算器才會使用記憶體和 CPU。

參數
value: Boolean

true 啟用網路品質估算器，false 停用。
傳回
CronetEngine.Builder!

建構工具，方便鏈結。

enablePublicKeyPinningBypassForLocalTrustAnchors

fun enablePublicKeyPinningBypassForLocalTrustAnchors(value: Boolean): CronetEngine.Builder!

啟用或停用本機信任錨點的公開金鑰固定繞過功能。強烈建議不要停用本機信任錨點的繞過功能，因為這可能會禁止應用程式與已釘選的主機通訊。舉例來說，使用者可以變更裝置 Proxy 設定，並將 Proxy 憑證新增至本機信任錨點清單，藉此透過啟用 SSL 的 Proxy 傳送所有流量。停用繞過功能後，應用程式很可能無法將任何流量傳送至已釘選的主機。詳情請參閱 https://www.chromium.org/Home/chromium-security/security-faq 的「How does key pinning interact with local proxies and filters?」(金鑰固定與本機 Proxy 和篩選器如何互動？) 一文。

參數
value: Boolean

true 啟用略過功能，false 停用略過功能。
傳回
CronetEngine.Builder!

建構工具，方便鏈結。

enableQuic

fun enableQuic(value: Boolean): CronetEngine.Builder!

設定是否啟用 QUIC 通訊協定。預設為啟用。如果啟用 QUIC，系統會將包含應用程式名稱和 Cronet 版本的 QUIC 使用者代理程式 ID 傳送至伺服器。

參數
value: Boolean

true 啟用 QUIC，false 停用。
傳回
CronetEngine.Builder!

建構工具，方便鏈結。

getDefaultUserAgent

fun getDefaultUserAgent(): String!

建構 User-Agent 字串，包括應用程式名稱和版本、系統建構版本、型號和 ID，以及 Cronet 版本。

傳回
String!

使用者代理程式字串。

setConnectionMigrationOptions

@ConnectionMigrationOptions.Experimental
fun setConnectionMigrationOptions(
    connectionMigrationOptionsBuilder: ConnectionMigrationOptions.Builder!
): CronetEngine.Builder!
另請參閱
setConnectionMigrationOptions

setConnectionMigrationOptions

@ConnectionMigrationOptions.Experimental
fun setConnectionMigrationOptions(
    connectionMigrationOptions: ConnectionMigrationOptions!
): CronetEngine.Builder!

設定連線遷移作業的行為。詳情請參閱 ConnectionMigrationOptions 和 ConnectionMigrationOptions.Builder 個別方法的說明文件。

只有在啟用 enableQuic 時才適用。

傳回
CronetEngine.Builder!

建構工具，方便鏈結。

setDnsOptions

@DnsOptions.Experimental
fun setDnsOptions(dnsOptions: DnsOptions!): CronetEngine.Builder!

設定主機名稱查詢的行為。詳情請參閱 DnsOptions 和 DnsOptions.Builder 個別方法的說明文件。

只有在啟用 enableQuic 時才適用。

傳回
CronetEngine.Builder!

建構工具，方便鏈結。

setDnsOptions

@DnsOptions.Experimental
fun setDnsOptions(dnsOptions: DnsOptions.Builder!): CronetEngine.Builder!
另請參閱
setDnsOptions

setLibraryLoader

fun setLibraryLoader(loader: CronetEngine.Builder.LibraryLoader!): CronetEngine.Builder!

設定用於載入原生程式庫的 LibraryLoader。如未設定，系統會使用 loadLibrary 載入程式庫。

參數
loader: CronetEngine.Builder.LibraryLoader!

LibraryLoader，用於載入原生資料庫。
傳回
CronetEngine.Builder!

建構工具，方便鏈結。

setProxyOptions

fun setProxyOptions(proxyOptions: ProxyOptions): CronetEngine.Builder!

設定 Proxy 行為。這會以不同方式影響連線建立、UrlRequest 和 BidirectionalStream。詳情請參閱 Proxy 的說明文件。

請勿將此與下列情況混淆：使用者設定的 Proxy 設定；某些企業設定檔設定；或 (最有可能) 某些網路自動設定 (例如 Web Proxy Auto-Discovery Protocol)。這通常稱為「系統」Proxy 設定。如果系統有 Proxy 設定，通常必須遵守這項設定，才能取得本機和/或網際網路連線。CronetEngine 會在內部處理系統 Proxy 設定。

透過這個 API 定義的 Proxy 設定稱為「應用程式」Proxy 設定。應用程式和系統的 Proxy 設定是分開的，而且最重要的是，兩者不同。目前應用程式和系統 Proxy 設定互斥：指定 ProxyOptions 會覆寫系統 Proxy 設定 (如有)。在有系統 Proxy 設定的部分情境中，這可能會導致連線問題。在這種情況下，除非 ProxyOptions 已設定最終的 null 回退，否則使用者可能無法存取網際網路。請參閱ProxyOptions說明文件。

參數
proxyOptions: ProxyOptions

用於 UrlRequest、BiridirectionalStream 和這個建構工具建立的 CronetEngine 所建立連線的 ProxyOptions。
傳回
CronetEngine.Builder!

建構工具，方便鏈結。
擲回
java.lang.UnsupportedOperationException

如果使用的 Cronet 實作版本過舊，無法支援 ProxyOptions。

setQuicOptions

@QuicOptions.Experimental
fun setQuicOptions(quicOptionsBuilder: QuicOptions.Builder!): CronetEngine.Builder!
另請參閱
setQuicOptions

setQuicOptions

@QuicOptions.Experimental
fun setQuicOptions(quicOptions: QuicOptions!): CronetEngine.Builder!

設定使用 QUIC 時的 Cronet 行為。詳情請參閱 QuicOptions 和 QuicOptions.Builder 個別方法的說明文件。

只有在啟用 enableQuic 時才適用。

傳回
CronetEngine.Builder!

建構工具，方便鏈結。

setStoragePath

fun setStoragePath(value: String!): CronetEngine.Builder!

設定 HTTP 快取和 Cookie 儲存空間的目錄。目錄必須存在。

注意：請勿同時使用多個 CronetEngine 存取同一個儲存目錄。儲存空間目錄不支援多個 CronetEngine 同時存取。

參數
value: String!

現有目錄的路徑。
傳回
CronetEngine.Builder!

建構工具，方便鏈結。

setThreadPriority

fun setThreadPriority(priority: Int): CronetEngine.Builder!

設定 Cronet 內部執行緒的執行緒優先順序。

參數
priority: Int

Cronet 內部執行緒的執行緒優先順序。Linux 優先順序等級，從 -20 (最高排程優先順序) 到 19 (最低排程優先順序)。如要進一步瞭解值，請參閱 setThreadPriority 和 THREAD_PRIORITY_* 值。
傳回
CronetEngine.Builder!

建構工具，方便鏈結。

setUserAgent

fun setUserAgent(userAgent: String!): CronetEngine.Builder!

覆寫所有要求的 User-Agent 標頭。明確設定的 User-Agent 標頭 (使用 addHeader 設定) 會覆寫使用這個函式設定的值。

參數
userAgent: String!

用於所有要求的使用者代理程式字串。
傳回
CronetEngine.Builder!

建構工具，方便鏈結。

受保護的房源

mParsedExperimentalOptions

protected val mParsedExperimentalOptions: JSONObject!

實驗性選項的 JSON 表示法。