CronetEngine.Builder

public class CronetEngine.Builder

---

CronetEngine 的构建器，允许对 CronetEngine 进行运行时配置。配置选项在构建器上设置，然后调用 build 以创建 CronetEngine。

摘要

嵌套类型
public abstract class CronetEngine.Builder.LibraryLoader 一个类，提供用于加载 Cronet 原生库的方法。

常量
static final int	HTTP_CACHE_DISABLED = 0 用于停用 HTTP 缓存的设置。
static final int	HTTP_CACHE_DISK = 3 用于启用磁盘缓存的设置，包括 HTTP 数据。
static final int	HTTP_CACHE_DISK_NO_HTTP = 2 设置以启用磁盘缓存，但不包括 HTTP 数据。
static final int	HTTP_CACHE_IN_MEMORY = 1 用于启用内存中 HTTP 缓存（包括 HTTP 数据）的设置。

受保护的字段
JSONObject	mParsedExperimentalOptions 实验性选项的 JSON 表示形式。

公共构造函数
Builder(Context context) 构建一个 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 字符串，其中包含应用名称和版本、系统 build 版本、型号和 ID 以及 Cronet 版本。
CronetEngine.Builder	@ConnectionMigrationOptions.Experimental setConnectionMigrationOptions(     ConnectionMigrationOptions.Builder connectionMigrationOptionsBuilder )
CronetEngine.Builder	@ConnectionMigrationOptions.Experimental setConnectionMigrationOptions(     ConnectionMigrationOptions connectionMigrationOptions ) 配置连接迁移的行为。
CronetEngine.Builder	@DnsOptions.Experimental setDnsOptions(DnsOptions dnsOptions) 配置主机名查找的行为。
CronetEngine.Builder	@DnsOptions.Experimental setDnsOptions(DnsOptions.Builder dnsOptions)
CronetEngine.Builder	setLibraryLoader(CronetEngine.Builder.LibraryLoader loader) 设置用于加载原生库的 LibraryLoader。
CronetEngine.Builder	setProxyOptions(@NonNull ProxyOptions proxyOptions) 配置代理行为。
CronetEngine.Builder	@QuicOptions.Experimental setQuicOptions(QuicOptions.Builder quicOptionsBuilder)
CronetEngine.Builder	@QuicOptions.Experimental setQuicOptions(QuicOptions quicOptions) 配置使用 QUIC 时 Cronet 的行为。
CronetEngine.Builder	setStoragePath(String value) 设置 HTTP 缓存和 Cookie 存储的目录。
CronetEngine.Builder	setThreadPriority(int priority) 此方法已弃用。 在 Cronet 的新版本中，此方法不执行任何操作。
CronetEngine.Builder	setUserAgent(String userAgent) 替换所有请求的 User-Agent 标头。

常量

HTTP_CACHE_DISABLED

public static final int HTTP_CACHE_DISABLED = 0

用于停用 HTTP 缓存的设置。有些数据可能仍会暂时存储在内存中。已传递给 enableHttpCache。

HTTP_CACHE_DISK

public static final int HTTP_CACHE_DISK = 3

用于启用磁盘缓存的设置，包括 HTTP 数据。必须先调用 setStoragePath，然后才能将此常量传递给 enableHttpCache。

HTTP_CACHE_DISK_NO_HTTP

public static final int HTTP_CACHE_DISK_NO_HTTP = 2

设置为启用磁盘缓存，但不包括 HTTP 数据。必须先调用 setStoragePath，然后才能将此常量传递给 enableHttpCache。

HTTP_CACHE_IN_MEMORY

public static final int HTTP_CACHE_IN_MEMORY = 1

用于启用内存中 HTTP 缓存（包括 HTTP 数据）的设置。已传递给 enableHttpCache。

受保护的字段

mParsedExperimentalOptions

protected JSONObject mParsedExperimentalOptions

实验性选项的 JSON 表示形式。

公共构造函数

Builder

public Builder(Context context)

构建一个 Builder 对象，以便于创建 CronetEngine。默认配置会启用 HTTP/2 和 QUIC，但停用 HTTP 缓存。

参数
Context context	Android Context，Builder 使用它来检索应用上下文。系统将仅保留对应用上下文的引用，以避免不必要地延长 context 的生命周期。

公共方法

addPublicKeyPins

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

为给定主机固定一组公钥。通过固定一组公钥 pinsSha256，与 hostName 的通信需要使用公钥来自固定组的证书进行身份验证。应用可以固定根证书、任何中间证书或最终实体证书的公钥。如果主机证书链中不存在任何公钥，即使主机尝试使用设备的可信证书存储区中允许的证书进行身份验证，身份验证也会失败，并且无法建立安全通信。

使用相同的主机名多次调用此方法会替换之前为主机设置的固定证书。

如需详细了解公钥固定，请参阅 RFC 7469。

参数
String hostName	应固定公钥的主机的名称。仅包含数字和英文句点字符的主机名会被视为无效。
Set<byte[]> pinsSha256	一组固定。每个 pin 都是主机 X.509 证书的 Subject Public Key Info (SPKI) 的 DER 编码 ASN.1 表示形式的 SHA-256 加密哈希。使用 Certificate.getPublicKey() 和 Key.getEncoded() 获取 SPKI 的 DER 编码 ASN.1 表示形式。虽然该方法不强制要求提供在主私钥控制权丢失时可使用的备用 PIN 码，但强烈建议提供一个。
boolean includeSubdomains	表示是否应将固定政策应用于 hostName 的子网域。
Date expirationDate	指定 PIN 码的失效日期。

返回
CronetEngine.Builder	构建器，以方便进行链式调用。

抛出
java.lang.NullPointerException	如果任何输入参数为 null。
java.lang.IllegalArgumentException	如果给定的主机名无效或 pinsSha256 包含的字节数组不表示有效的 SHA-256 哈希值。

addQuicHint

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

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

参数
String host	支持 QUIC 的服务器的主机名。
int port	支持 QUIC 的服务器的主机。
int alternatePort	用于 QUIC 的备用端口。

返回
CronetEngine.Builder	构建器，以方便进行链式调用。

build

public CronetEngine build()

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

返回
CronetEngine	建成年份：CronetEngine。

enableBrotli

public CronetEngine.Builder enableBrotli(boolean value)

设置是否启用 Brotli 压缩。如果启用，则会在 Accept-Encoding 请求标头中宣传 Brotli。默认值为 disabled。

参数
boolean value	true 表示启用 Brotli，false 表示停用。

返回
CronetEngine.Builder	构建器，以方便进行链式调用。

enableHttp2

public CronetEngine.Builder enableHttp2(boolean value)

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

参数
boolean value	true 表示启用 HTTP/2，false 表示停用。

返回
CronetEngine.Builder	构建器，以方便进行链式调用。

enableHttpCache

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

启用或停用 HTTP 数据和其他信息（例如 QUIC 服务器信息）的缓存。

参数
int cacheMode	控制缓存数据的位置和类型。必须为 HTTP_CACHE_* 之一。
long maxSize	用于缓存数据的最大大小（以字节为单位）（建议值，有时可能会超出）。

返回
CronetEngine.Builder	构建器，以方便进行链式调用。

enableNetworkQualityEstimator

public CronetEngine.Builder enableNetworkQualityEstimator(boolean value)

启用网络质量估算器，该估算器会收集并报告网络堆栈各个层级的往返时间 (RTT) 和下游吞吐量测量结果。启用估算器后，可以使用 addRttListener 和 addThroughputListener 添加 RTT 和吞吐量监听器，并使用 removeRttListener 和 removeThroughputListener 移除监听器。估算器仅在启用时使用内存和 CPU。

参数
boolean value	true 可启用网络质量估算器，false 可停用。

返回
CronetEngine.Builder	构建器，以方便进行链式调用。

enablePublicKeyPinningBypassForLocalTrustAnchors

public CronetEngine.Builder enablePublicKeyPinningBypassForLocalTrustAnchors(boolean value)

为本地信任锚启用或停用公钥固定绕过。强烈建议不要停用本地信任锚的绕过功能，因为这可能会禁止应用与固定的主机进行通信。例如，用户可能希望通过更改设备代理设置并将代理证书添加到本地信任锚点列表中，来通过启用 SSL 的代理发送所有流量。停用绕过功能后，应用很可能无法向固定的主机发送任何流量。如需了解详情，请访问 https://www.chromium.org/Home/chromium-security/security-faq，参阅“密钥固定如何与本地代理和过滤器交互？”

参数
boolean value	true 表示启用旁路，false 表示停用旁路。

返回
CronetEngine.Builder	构建器，以方便进行链式调用。

enableQuic

public CronetEngine.Builder enableQuic(boolean value)

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

参数
boolean value	true 表示启用 QUIC，false 表示停用。

返回
CronetEngine.Builder	构建器，以方便进行链式调用。

getDefaultUserAgent

public String getDefaultUserAgent()

构建一个 User-Agent 字符串，其中包含应用名称和版本、系统 build 版本、型号和 ID 以及 Cronet 版本。

返回
String	用户代理字符串。

setConnectionMigrationOptions

@ConnectionMigrationOptions.Experimental
public CronetEngine.Builder setConnectionMigrationOptions(
    ConnectionMigrationOptions.Builder connectionMigrationOptionsBuilder
)

另请参阅
setConnectionMigrationOptions

setConnectionMigrationOptions

@ConnectionMigrationOptions.Experimental
public CronetEngine.Builder setConnectionMigrationOptions(
    ConnectionMigrationOptions connectionMigrationOptions
)

配置连接迁移的行为。如需了解详情，请参阅 ConnectionMigrationOptions 的文档以及 ConnectionMigrationOptions.Builder 的各个方法。

仅在启用 enableQuic 时相关。

返回
CronetEngine.Builder	构建器，以方便进行链式调用。

setDnsOptions

@DnsOptions.Experimental
public CronetEngine.Builder setDnsOptions(DnsOptions dnsOptions)

配置主机名查找的行为。如需了解详情，请参阅 DnsOptions 的文档以及 DnsOptions.Builder 的各个方法。

仅在启用 enableQuic 时相关。

返回
CronetEngine.Builder	构建器，以方便进行链式调用。

setDnsOptions

@DnsOptions.Experimental
public CronetEngine.Builder setDnsOptions(DnsOptions.Builder dnsOptions)

另请参阅
setDnsOptions

setLibraryLoader

public CronetEngine.Builder setLibraryLoader(CronetEngine.Builder.LibraryLoader loader)

设置用于加载原生库的 LibraryLoader。如果未设置，系统将使用 loadLibrary 加载库。

参数
CronetEngine.Builder.LibraryLoader loader	LibraryLoader 用于加载原生库。

返回
CronetEngine.Builder	构建器，以方便进行链式调用。

setProxyOptions

public CronetEngine.Builder setProxyOptions(@NonNull ProxyOptions proxyOptions)

配置代理行为。这会以不同的方式影响连接建立、UrlRequest 和 BidirectionalStream。如需了解详情，请参阅 Proxy 的文档。

请勿将此与以下情况设置的代理配置混淆：用户；某些企业资料配置；或（最有可能）某些网络自动配置（例如 Web 代理自动发现协议）。这通常称为“系统”代理配置。如果存在，尊重系统代理配置通常是获得本地和/或互联网连接的必要条件。CronetEngine 已在内部处理系统代理配置。

通过此 API 定义的代理配置称为“应用”代理配置。应用代理配置和系统代理配置是分开的，最重要的是，两者不同。目前，应用和系统代理配置是互斥的：如果指定了 ProxyOptions，则会覆盖系统代理配置（如果存在）。在存在系统代理配置的某些情况下，这可能会导致连接问题。在这种情况下，除非 ProxyOptions 已配置为最终的 null 回退，否则用户可能最终无法访问互联网。请参阅 ProxyOptions 文档。

参数
@NonNull ProxyOptions proxyOptions	要用于 UrlRequest、BiridirectionalStream 和由此构建器创建的 CronetEngine 所建立的连接的 ProxyOptions。

返回
CronetEngine.Builder	构建器，以方便进行链式调用。

抛出
java.lang.UnsupportedOperationException	如果所使用的 Cronet 实现版本过旧，不支持 ProxyOptions。

setQuicOptions

@QuicOptions.Experimental
public CronetEngine.Builder setQuicOptions(QuicOptions.Builder quicOptionsBuilder)

另请参阅
setQuicOptions

setQuicOptions

@QuicOptions.Experimental
public CronetEngine.Builder setQuicOptions(QuicOptions quicOptions)

配置使用 QUIC 时 Cronet 的行为。如需了解详情，请参阅 QuicOptions 的文档以及 QuicOptions.Builder 的各个方法。

仅在启用 enableQuic 时相关。

返回
CronetEngine.Builder	构建器，以方便进行链式调用。

setStoragePath

public CronetEngine.Builder setStoragePath(String value)

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

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

参数
String value	现有目录的路径。

返回
CronetEngine.Builder	构建器，以方便进行链式调用。

setThreadPriority

public CronetEngine.Builder setThreadPriority(int priority)

此方法已弃用。

在 Cronet 的新版本中，此方法不执行任何操作。

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

参数
int priority	Cronet 内部线程的线程优先级。一个 Linux 优先级级别，从 -20（最高调度优先级）到 19（最低调度优先级）。如需详细了解这些值，请参阅 setThreadPriority 和 THREAD_PRIORITY_* 值。

返回
CronetEngine.Builder	构建器，以方便进行链式调用。

setUserAgent

public CronetEngine.Builder setUserAgent(String userAgent)

替换所有请求的 User-Agent 标头。使用 addHeader 明确设置的 User-Agent 标头会替换使用此函数设置的值。

参数
String userAgent	要用于所有请求的 User-Agent 字符串。

返回
CronetEngine.Builder	构建器，以方便进行链式调用。