CronetEngine.Builder

public static class CronetEngine.Builder extends Object

用于创建 CronetEngine 对象的构建器,允许运行时配置 CronetEngine。配置选项在构建器上设置,然后调用 build() 来创建 CronetEngine

嵌套类摘要

class CronetEngine.Builder.LibraryLoader 一个提供加载 cronet 原生库的方法的类。 

常量摘要

int HTTP_CACHE_DISABLED 用于禁用 HTTP 缓存的设置。
int HTTP_CACHE_DISK 用于启用磁盘缓存(包括 HTTP 数据)的设置。
int HTTP_CACHE_DISK_NO_HTTP 用于启用磁盘缓存(不包括 HTTP 数据)的设置。
int HTTP_CACHE_IN_MEMORY 用于启用内存 HTTP 缓存(包括 HTTP 数据)的设置。

公共构造函数摘要

Builder(Context context)
构造一个 CronetEngine.Builder 对象,用于创建 CronetEngine

公共方法摘要

CronetEngine.Builder
addPublicKeyPins(String hostName, Set<byte[]> pinsSha256, boolean includeSubdomains, Date expirationDate)
为一个给定主机固定一组公钥。
CronetEngine.Builder
addQuicHint(String host, int port, int alternatePort)
添加提示,表明 host 支持 QUIC。
CronetEngine
build()
使用此构建器的配置构建 CronetEngine
CronetEngine.Builder
enableBrotli(boolean value)
设置是否启用 Brotli 压缩。
CronetEngine.Builder
enableHttp2(boolean value)
设置是否启用 HTTP/2 协议。
CronetEngine.Builder
enableHttpCache(int cacheMode, long maxSize)
启用或禁用 HTTP 数据及其他信息(例如 QUIC 服务器信息)的缓存。
CronetEngine.Builder
enableNetworkQualityEstimator(boolean value)
启用网络质量估算器,该估算器收集并报告网络堆栈不同层面的往返时间 (RTT) 和下游吞吐量测量结果。
CronetEngine.Builder
enablePublicKeyPinningBypassForLocalTrustAnchors(boolean value)
为本地信任锚点启用或禁用公钥固定绕过。
CronetEngine.Builder
enableQuic(boolean value)
设置是否启用 QUIC 协议。
String
getDefaultUserAgent()
构造一个 User-Agent 字符串,包括应用程序名称和版本、系统构建版本、型号和 ID,以及 Cronet 版本。
CronetEngine.Builder
setConnectionMigrationOptions(ConnectionMigrationOptions connectionMigrationOptions)
配置连接迁移的行为。
CronetEngine.Builder
CronetEngine.Builder
CronetEngine.Builder
setDnsOptions(DnsOptions dnsOptions)
配置主机名查找的行为。
CronetEngine.Builder
CronetEngine.Builder
setQuicOptions(QuicOptions.Builder quicOptionsBuilder)
CronetEngine.Builder
setQuicOptions(QuicOptions quicOptions)
配置 Cronet 使用 QUIC 时的行为。
CronetEngine.Builder
setStoragePath(String value)
设置 HTTP 缓存和 Cookie 存储的目录。
CronetEngine.Builder
setThreadPriority(int priority)
设置 Cronet 内部线程的线程优先级。
CronetEngine.Builder
setUserAgent(String userAgent)
覆盖所有请求的 User-Agent 标头。

继承方法摘要

常量

public static final int HTTP_CACHE_DISABLED

用于禁用 HTTP 缓存的设置。一些数据可能仍会临时存储在内存中。传递给 enableHttpCache(int, long)

常量值: 0

public static final int HTTP_CACHE_DISK

用于启用磁盘缓存(包括 HTTP 数据)的设置。setStoragePath(String) 必须在此常量传递给 enableHttpCache(int, long) 之前调用。

常量值: 3

public static final int HTTP_CACHE_DISK_NO_HTTP

用于启用磁盘缓存(不包括 HTTP 数据)的设置。setStoragePath(String) 必须在此常量传递给 enableHttpCache(int, long) 之前调用。

常量值: 2

public static final int HTTP_CACHE_IN_MEMORY

用于启用内存 HTTP 缓存(包括 HTTP 数据)的设置。传递给 enableHttpCache(int, long)

常量值: 1

公共构造函数

public Builder (Context context)

构造一个 CronetEngine.Builder 对象,用于创建 CronetEngine。默认配置启用 HTTP/2 和 QUIC,但禁用 HTTP 缓存。

参数
context Android ContextCronetEngine.Builder 使用它来获取应用上下文。只会保留对应用上下文的引用,以避免不必要地延长 context 的生命周期。

公共方法

public CronetEngine.Builder addPublicKeyPins (String hostName, Set<byte[]> pinsSha256, boolean includeSubdomains, Date expirationDate)

为一个给定主机固定一组公钥。通过固定一组公钥 pinsSha256,要求与 hostName 的通信使用一组固定公钥中的公钥进行证书身份验证。应用可以固定根证书、任何中间证书或末端证书的公钥。即使主机尝试使用设备信任证书存储允许的证书进行身份验证,如果主机的证书链中不存在任何固定公钥,身份验证也将失败,无法建立安全通信。

多次使用相同主机名调用此方法会覆盖之前为该主机设置的固定。

有关公钥固定的更多信息,请参阅 RFC 7469

参数
hostName 应固定公钥的主机名。仅由数字和点字符组成的主机被视为无效。
pinsSha256 一组固定。每个固定都是主机 X.509 证书的主题公钥信息 (SPKI) 的 DER 编码 ASN.1 表示的 SHA-256 加密哈希值。使用 Certificate.getPublicKey()Key.getEncoded() 获取 SPKI 的 DER 编码 ASN.1 表示。尽管此方法并未强制要求存在用于在主私钥失控时使用的备份固定,但强烈建议提供一个。
includeSubdomains 指示固定策略是否应用于 hostName 的子域。
expirationDate 指定固定的到期日期。
返回
  • 构建器,以便于链式调用。
抛出
NullPointerException 如果任何输入参数为 null
IllegalArgumentException 如果给定主机名无效,或 pinsSha256 包含不代表有效 SHA-256 哈希值的字节数组。

public CronetEngine.Builder addQuicHint (String host, int port, int alternatePort)

添加提示,表明 host 支持 QUIC。请注意,需要 enableHttpCache (HTTP_CACHE_DISK) 才能利用会话间的 0-RTT 连接建立。

参数
host 支持 QUIC 的服务器的主机名。
port 支持 QUIC 的服务器主机。
alternatePort 用于 QUIC 的备用端口。
返回
  • 构建器,以便于链式调用。

public CronetEngine build ()

使用此构建器的配置构建 CronetEngine

返回

public CronetEngine.Builder enableBrotli (boolean value)

设置是否启用 Brotli 压缩。如果启用,Accept-Encoding 请求头中将声明 Brotli。默认为禁用。

参数
value 如果为 true,则启用 Brotli;如果为 false,则禁用。
返回
  • 构建器,以便于链式调用。

public CronetEngine.Builder enableHttp2 (boolean value)

设置是否启用 HTTP/2 协议。默认为启用。

参数
value 如果为 true,则启用 HTTP/2;如果为 false,则禁用。
返回
  • 构建器,以便于链式调用。

public CronetEngine.Builder enableHttpCache (int cacheMode, long maxSize)

启用或禁用 HTTP 数据及其他信息(例如 QUIC 服务器信息)的缓存。

参数
cacheMode 控制缓存数据的位置和类型。必须是 HTTP_CACHE_* 之一。
maxSize 用于缓存数据的最大大小(以字节为单位,建议值,有时可能会超过)。
返回
  • 构建器,以便于链式调用。

public CronetEngine.Builder enableNetworkQualityEstimator (boolean value)

启用网络质量估算器,该估算器收集并报告网络堆栈不同层面的往返时间 (RTT) 和下游吞吐量测量结果。启用估算器后,可以使用 CronetEngine.addRttListener(NetworkQualityRttListener)CronetEngine.addThroughputListener(NetworkQualityThroughputListener) 添加 RTT 和吞吐量监听器,并使用 CronetEngine.removeRttListener(NetworkQualityRttListener)CronetEngine.removeThroughputListener(NetworkQualityThroughputListener) 删除。估算器仅在启用时使用内存和 CPU。

参数
value 如果为 true,则启用网络质量估算器;如果为 false,则禁用。
返回
  • 构建器,以便于链式调用。

public CronetEngine.Builder enablePublicKeyPinningBypassForLocalTrustAnchors (boolean value)

为本地信任锚点启用或禁用公钥固定绕过。强烈建议不要禁用本地信任锚点的绕过,因为它可能会阻止应用与固定主机通信。例如,用户可能希望通过更改设备代理设置并将代理证书添加到本地信任锚点列表,以便通过启用了 SSL 的代理发送所有流量。禁用此绕过最有可能阻止应用向固定主机发送任何流量。有关更多信息,请参阅 https://www.chromium.org/Home/chromium-security/security-faq 中的“密钥固定如何与本地代理和过滤器交互?”。

参数
value 如果为 true,则启用绕过;如果为 false,则禁用。
返回
  • 构建器,以便于链式调用。

public CronetEngine.Builder enableQuic (boolean value)

设置是否启用 QUIC 协议。默认为启用。如果启用 QUIC,则会将包含应用程序名称和 Cronet 版本的 QUIC User Agent ID 发送到服务器。

参数
value 如果为 true,则启用 QUIC;如果为 false,则禁用。
返回
  • 构建器,以便于链式调用。

public String getDefaultUserAgent ()

构造一个 User-Agent 字符串,包括应用程序名称和版本、系统构建版本、型号和 ID,以及 Cronet 版本。

返回
  • User-Agent 字符串。

public CronetEngine.Builder setConnectionMigrationOptions (ConnectionMigrationOptions connectionMigrationOptions)

配置连接迁移的行为。有关更多详细信息,请参阅 ConnectionMigrationOptions 的文档和 ConnectionMigrationOptions.Builder 的各个方法。

仅在 enableQuic(boolean) 启用时相关。

参数
connectionMigrationOptions
返回
  • 构建器,以便于链式调用。

public CronetEngine.Builder setConnectionMigrationOptions (ConnectionMigrationOptions.Builder connectionMigrationOptionsBuilder)

参数
connectionMigrationOptionsBuilder

public CronetEngine.Builder setDnsOptions (DnsOptions.Builder dnsOptions)

参数
dnsOptions

public CronetEngine.Builder setDnsOptions (DnsOptions dnsOptions)

配置主机名查找的行为。有关更多详细信息,请参阅 DnsOptions 的文档和 DnsOptions.Builder 的各个方法。

仅在 enableQuic(boolean) 启用时相关。

参数
dnsOptions
返回
  • 构建器,以便于链式调用。

dnsOptions

设置要用于加载原生库的 CronetEngine.Builder.LibraryLoader。如果未设置,将使用 System.loadLibrary(String) 加载库。

参数
loader 用于加载原生库的 LibraryLoader
返回
  • 构建器,以便于链式调用。

public CronetEngine.Builder setQuicOptions (QuicOptions.Builder quicOptionsBuilder)

参数
quicOptionsBuilder

public CronetEngine.Builder setQuicOptions (QuicOptions quicOptions)

配置 Cronet 使用 QUIC 时的行为。有关更多详细信息,请参阅 QuicOptions 的文档和 QuicOptions.Builder 的各个方法。

仅在 enableQuic(boolean) 启用时相关。

参数
quicOptions
返回
  • 构建器,以便于链式调用。

public CronetEngine.Builder setStoragePath (String value)

设置 HTTP 缓存和 Cookie 存储的目录。该目录必须存在。

注意:请勿同时将多个 CronetEngine 使用同一存储目录。对存储目录的访问不支持多个 CronetEngine 的并发访问。

参数
value 现有目录的路径。
返回
  • 构建器,以便于链式调用。

public CronetEngine.Builder setThreadPriority (int priority)

设置 Cronet 内部线程的线程优先级。

参数
priority Cronet 内部线程的线程优先级。一个 Linux 优先级级别,从 -20(最高调度优先级)到 19(最低调度优先级)。有关值的更多信息,请参阅 Process.setThreadPriority(int, int)THREAD_PRIORITY_* 值。
返回
  • 构建器,以便于链式调用。

public CronetEngine.Builder setUserAgent (String userAgent)

覆盖所有请求的 User-Agent 标头。使用此函数设置的值将被显式设置的 User-Agent 标头(使用 UrlRequest.Builder.addHeader(String, String) 设置)覆盖。

参数
userAgent 要用于所有请求的 User-Agent 字符串。
返回
  • 构建器,以便于链式调用。