用于创建 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 。 |
公共方法摘要
继承方法摘要
常量
public static final int HTTP_CACHE_DISABLED
用于禁用 HTTP 缓存的设置。一些数据可能仍会临时存储在内存中。传递给 enableHttpCache(int, long)
。
public static final int HTTP_CACHE_DISK
用于启用磁盘缓存(包括 HTTP 数据)的设置。setStoragePath(String)
必须在此常量传递给 enableHttpCache(int, long)
之前调用。
public static final int HTTP_CACHE_DISK_NO_HTTP
用于启用磁盘缓存(不包括 HTTP 数据)的设置。setStoragePath(String)
必须在此常量传递给 enableHttpCache(int, long)
之前调用。
public static final int HTTP_CACHE_IN_MEMORY
用于启用内存 HTTP 缓存(包括 HTTP 数据)的设置。传递给 enableHttpCache(int, long)
。
公共构造函数
public Builder (Context context)
构造一个 CronetEngine.Builder
对象,用于创建 CronetEngine
。默认配置启用 HTTP/2 和 QUIC,但禁用 HTTP 缓存。
参数
context | Android Context ,CronetEngine.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.Builder enableBrotli (boolean value)
设置是否启用 Brotli 压缩。如果启用,Accept-Encoding 请求头中将声明 Brotli。默认为禁用。
参数
value | 如果为 true ,则启用 Brotli;如果为 false ,则禁用。 |
---|
返回
- 构建器,以便于链式调用。
public CronetEngine.Builder enableHttp2 (boolean value)
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)
public CronetEngine.Builder setDnsOptions (DnsOptions.Builder 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)
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 字符串。 |
---|
返回
- 构建器,以便于链式调用。