CronetEngine

public abstract class CronetEngine extends Object

用于处理 UrlRequest 的引擎，它使用当前平台上的最佳 HTTP 堆栈。可以使用 CronetEngine.Builder 创建此类的一个实例。

嵌套类摘要

类 CronetEngine.Builder CronetEngine 的构建器，允许对 CronetEngine 进行运行时配置。

常量摘要

int	ACTIVE_REQUEST_COUNT_UNKNOWN	活动请求计数的值未知
int	CONNECTION_METRIC_UNKNOWN	连接指标的值未知。
int	EFFECTIVE_CONNECTION_TYPE_2G	有效连接类型的估计值为 2G。
int	EFFECTIVE_CONNECTION_TYPE_3G	有效连接类型的估计值为 3G。
int	EFFECTIVE_CONNECTION_TYPE_4G	有效连接类型的估计值为 4G。
int	EFFECTIVE_CONNECTION_TYPE_OFFLINE	设备处于离线状态。
int	EFFECTIVE_CONNECTION_TYPE_SLOW_2G	有效连接类型的估计值为慢速 2G。
int	EFFECTIVE_CONNECTION_TYPE_UNKNOWN	有效连接类型的估计值未知。

公共构造函数摘要

CronetEngine()

公共方法摘要

void	addRequestFinishedListener(RequestFinishedInfo.Listener listener) 注册一个监听器，在每次请求结束并附带请求信息后会调用该监听器。
void	addRttListener(NetworkQualityRttListener listener) 注册一个监听器，当网络质量评估器监测到样本往返时间时会调用该监听器。
void	addThroughputListener(NetworkQualityThroughputListener listener) 注册一个监听器，当网络质量评估器监测到样本吞吐量测量时会调用该监听器。
void	configureNetworkQualityEstimatorForTesting(boolean useLocalHostRequests, boolean useSmallerResponses, boolean disableOfflineCheck) 配置网络质量评估器用于测试。
abstract URLStreamHandlerFactory	createURLStreamHandlerFactory() 创建一个 `URLStreamHandlerFactory` 来处理 HTTP 和 HTTPS 流量。
int	getActiveRequestCount() 返回正在进行中的请求数量。
int	getDownstreamThroughputKbps() 返回网络质量评估器计算出的下行吞吐量估计值（单位：千位/秒）。
int	getEffectiveConnectionType() 返回网络质量评估器计算出的有效连接类型估计值。
abstract byte[]	getGlobalMetricsDeltas() 返回自上次调用此方法以来 Cronet 收集的指标差异。
int	getHttpRttMs() 返回网络质量评估器计算出的 HTTP RTT 估计值（单位：毫秒）。
int	getTransportRttMs() 返回网络质量评估器计算出的传输层 RTT 估计值（单位：毫秒）。
abstract String	getVersionString()
abstract UrlRequest.Builder	newUrlRequestBuilder(String url, UrlRequest.Callback callback, Executor executor) 创建一个 `UrlRequest` 的构建器。
abstract URLConnection	openConnection(URL url) 建立与 `URL` `url` 指定资源的连接。
void	removeRequestFinishedListener(RequestFinishedInfo.Listener listener) 移除一个已完成请求的监听器。
void	removeRttListener(NetworkQualityRttListener listener) 如果之前已通过 `addRttListener(NetworkQualityRttListener)` 注册，则移除一个往返时间的监听器。
void	removeThroughputListener(NetworkQualityThroughputListener listener) 移除一个吞吐量的监听器。
abstract void	shutdown() 如果不存在活动请求，则关闭 `CronetEngine`，否则抛出异常。
void	startNetLogToDisk(String dirPath, boolean logAll, int maxSize) 开始将 NetLog 记录到指定目录，具有固定大小。
abstract void	startNetLogToFile(String fileName, boolean logAll) 开始将 NetLog 记录到文件。
abstract void	stopNetLog() 停止 NetLog 记录并将文件刷新到磁盘。

继承方法摘要

来自类 java.lang.Object

Object	clone()
boolean	equals(Object arg0)
void	finalize()
final Class<?>	getClass()
int	hashCode()
final void	notify()
final void	notifyAll()
String	toString()
final void	wait(long arg0, int arg1)
final void	wait(long arg0)
final void	wait()

常量

public static final int ACTIVE_REQUEST_COUNT_UNKNOWN

活动请求计数的值未知

常量值: -1

public static final int CONNECTION_METRIC_UNKNOWN

连接指标的值未知。

常量值: -1

public static final int EFFECTIVE_CONNECTION_TYPE_2G

有效连接类型的估计值为 2G。

另请参阅

getEffectiveConnectionType()

常量值: 3

public static final int EFFECTIVE_CONNECTION_TYPE_3G

有效连接类型的估计值为 3G。

另请参阅

getEffectiveConnectionType()

常量值: 4

public static final int EFFECTIVE_CONNECTION_TYPE_4G

有效连接类型的估计值为 4G。

另请参阅

getEffectiveConnectionType()

常量值: 5

public static final int EFFECTIVE_CONNECTION_TYPE_OFFLINE

设备处于离线状态。

另请参阅

getEffectiveConnectionType()

常量值: 1

public static final int EFFECTIVE_CONNECTION_TYPE_SLOW_2G

有效连接类型的估计值为慢速 2G。

另请参阅

getEffectiveConnectionType()

常量值: 2

public static final int EFFECTIVE_CONNECTION_TYPE_UNKNOWN

有效连接类型的估计值未知。

另请参阅

getEffectiveConnectionType()

常量值: 0

公共构造函数

public CronetEngine ()

公共方法

public void addRequestFinishedListener (RequestFinishedInfo.Listener listener)

注册一个监听器，在每次请求结束并附带请求信息后会调用该监听器。

监听器在监听器提供的 Executor 上调用。

参数

listener	已完成请求的监听器。

public void addRttListener (NetworkQualityRttListener listener)

注册一个监听器，当网络质量评估器监测到样本往返时间时会调用该监听器。必须在调用 CronetEngine.Builder.enableNetworkQualityEstimator(boolean) 之后调用此方法，否则将抛出异常。往返时间可能在网络堆栈的不同层记录，包括 TCP、QUIC 以及 URL 请求层。监听器会在传递给 Executor 的 CronetEngine.Builder.enableNetworkQualityEstimator(boolean) 上调用。

参数

listener	往返时间的监听器。

public void addThroughputListener (NetworkQualityThroughputListener listener)

注册一个监听器，当网络质量评估器监测到样本吞吐量测量时会调用该监听器。必须在调用 CronetEngine.Builder.enableNetworkQualityEstimator(boolean) 之后调用此方法。吞吐量观测值是在接收至少一个 URL 响应时，通过测量活动网络接口读取的字节数来计算的。监听器会在传递给 Executor 的 CronetEngine.Builder.enableNetworkQualityEstimator(boolean) 上调用。

参数

listener	吞吐量的监听器。

public void configureNetworkQualityEstimatorForTesting (boolean useLocalHostRequests, boolean useSmallerResponses, boolean disableOfflineCheck)

配置网络质量评估器用于测试。必须在添加往返时间和吞吐量监听器之前，并在网络质量评估器已启用之后调用此方法。

参数

useLocalHostRequests	在估计中包含对 localhost 的请求。
useSmallerResponses	在吞吐量估计中包含小型响应。
disableOfflineCheck	设置为 true 时，禁用设备离线检查，无论是在计算有效连接类型时还是在写入偏好设置时。

public abstract URLStreamHandlerFactory createURLStreamHandlerFactory ()

创建一个 URLStreamHandlerFactory 来处理 HTTP 和 HTTPS 流量。可以通过 URL.setURLStreamHandlerFactory(URLStreamHandlerFactory) 安装此类的一个实例，从而默认使用此 CronetEngine 处理通过 URL.openConnection() 创建的所有请求。

Cronet 不使用系统提供的一些 HTTP 特性

通过 HttpResponseCache.install() 安装的 HTTP 缓存
通过 Authenticator.setDefault(Authenticator) 安装的 HTTP 身份验证方法
通过 CookieHandler.setDefault(CookieHandler) 安装的 HTTP Cookie 存储

虽然 Cronet 支持并鼓励使用 HTTPS 协议的请求，但 Cronet 不支持 HttpsURLConnection API。这种不支持也包括不使用系统提供的一些 HTTPS 特性

通过 HttpsURLConnection.setDefaultHostnameVerifier() 安装的 HTTPS 主机名验证器
通过 HttpsURLConnection.setDefaultSSLSocketFactory() 安装的 HTTPS 套接字工厂

此 CronetEngine 实现的 URLStreamHandlerFactory 实例。

public int getActiveRequestCount ()

返回正在进行中的请求数量。

如果请求已调用其 start() 方法但尚未达到最终状态，则该请求处于进行中状态。请求在调用以下回调之一时达到最终状态

onSucceeded
onCanceled
onFailed

Cronet 请求的生命周期了解更多信息。

public int getDownstreamThroughputKbps ()

返回网络质量评估器计算出的下行吞吐量估计值（单位：千位/秒）。如果值不可用，则设为 CONNECTION_METRIC_UNKNOWN。必须在调用 CronetEngine.Builder.enableNetworkQualityEstimator(boolean) 之后调用此方法，否则将抛出异常。

下行吞吐量的估计值，单位为千位/秒。

public int getEffectiveConnectionType ()

返回网络质量评估器计算出的有效连接类型估计值。调用 CronetEngine.Builder.enableNetworkQualityEstimator(boolean) 开始计算此值。

估计的连接类型。返回值为 EFFECTIVE_CONNECTION_TYPE_* 之一。

public abstract byte[] getGlobalMetricsDeltas ()

返回自上次调用此方法以来 Cronet 收集的指标差异。

Cronet 全局收集这些指标。这意味着 getGlobalMetricsDeltas() 返回的差值将包含由其他 CronetEngine 实例处理的请求测量值。由于此函数返回自上次调用以来收集的指标差值，并且这些指标是全局收集的，因此对任何 CronetEngine 实例的 getGlobalMetricsDeltas() 方法的调用将影响任何其他 CronetEngine 实例的 getGlobalMetricsDeltas() 返回的差值。

Cronet 在第一次调用 getGlobalMetricsDeltras() 后开始收集这些指标，因此第一次调用不返回任何有用数据，因为尚未收集任何指标。

自上次调用 getGlobalMetricsDeltas() 以来 Cronet 收集的指标差异，序列化为 protobuf 。

public int getHttpRttMs ()

返回网络质量评估器计算出的 HTTP RTT 估计值（单位：毫秒）。如果值不可用，则设为 CONNECTION_METRIC_UNKNOWN。必须在调用 CronetEngine.Builder.enableNetworkQualityEstimator(boolean) 之后调用此方法，否则将抛出异常。

HTTP RTT 的估计值，单位为毫秒。

public int getTransportRttMs ()

返回网络质量评估器计算出的传输层 RTT 估计值（单位：毫秒）。如果值不可用，则设为 CONNECTION_METRIC_UNKNOWN。必须在调用 CronetEngine.Builder.enableNetworkQualityEstimator(boolean) 之后调用此方法，否则将抛出异常。

传输层 RTT 的估计值，单位为毫秒。

public abstract String getVersionString ()

引擎的人类可读版本字符串。

public abstract UrlRequest.Builder newUrlRequestBuilder (String url, UrlRequest.Callback callback, Executor executor)

创建一个 UrlRequest 的构建器。生成的 UrlRequest 对象的所有回调都将在 executor 的线程上调用。executor 不得在调用 Executor.execute(Runnable) 的线程上运行任务，以防止阻塞网络操作并在关闭期间导致异常。

参数

url	生成请求的 URL。
callback	在不同事件上调用的回调对象。
executor	所有回调将在此 `Executor` 上调用。

public abstract URLConnection openConnection (URL url)

建立与 URL url 指定资源的连接。

注意: Cronet 的 HttpURLConnection 实现受到某些限制，详见 createURLStreamHandlerFactory()。

参数

url	要连接的资源的 URL。

此 CronetEngine 实现的 HttpURLConnection 实例。

抛出

IOException	如果在打开连接时发生错误。

public void removeRequestFinishedListener (RequestFinishedInfo.Listener listener)

移除一个已完成请求的监听器。

参数

listener	要移除的监听器。

public void removeRttListener (NetworkQualityRttListener listener)

如果之前已通过 addRttListener(NetworkQualityRttListener) 注册，则移除一个往返时间的监听器。应在添加 NetworkQualityRttListener 后调用此方法，以停止接收观测值。

参数

listener	往返时间的监听器。

public void removeThroughputListener (NetworkQualityThroughputListener listener)

移除一个吞吐量的监听器。应在使用 NetworkQualityThroughputListener 和 addThroughputListener(NetworkQualityThroughputListener) 添加监听器后调用此方法，以停止接收观测值。

参数

listener	吞吐量的监听器。

public abstract void shutdown ()

如果不存在活动请求，则关闭 CronetEngine，否则抛出异常。

不能在网络线程上调用此方法 - Cronet 调用 Executor 的线程（与 Executor 调用回调的线程不同）。可能会阻塞，直到 CronetEngine 的所有资源都已清理完毕。

public void startNetLogToDisk (String dirPath, boolean logAll, int maxSize)

开始将 NetLog 记录到指定目录，具有固定大小。NetLog 将包含所有活动的 CronetEngine 发出的事件。NetLog 对于调试非常有用。一旦日志记录停止 stopNetLog()，数据将写入 dirPath 中的 netlog.json 文件。如果日志记录中断，可以使用以下工具手动拼接 .inprogress 子目录中的文件：https://chromium.googlesource.com/chromium/src/+/main/net/tools/stitch_net_log_files.py。可以使用 Chrome 浏览器导航到 chrome://net-internals/#import 来查看日志。

参数

dirPath	将创建 netlog.json 文件的目录。dirPath 必须已存在。目录中不得存在 NetLog 文件。如果正在进行日志记录，此方法将被忽略。
logAll	`true` 表示在日志中包含基本事件、用户 Cookie、凭据和所有传输的字节。此选项存在隐私风险，因为它会暴露用户的凭据，因此仅应在用户同意并在日志不会公开的情况下使用。`false` 表示仅包含基本事件。
maxSize	NetLog 应使用的最大总磁盘空间（单位：字节）。实际磁盘空间使用量可能略微超出此限制。

public abstract void startNetLogToFile (String fileName, boolean logAll)

开始将 NetLog 记录到文件。NetLog 将包含所有活动的 CronetEngine 发出的事件。NetLog 对于调试非常有用。可以使用 Chrome 浏览器导航到 chrome://net-internals/#import 来查看文件。

参数

fileName	完整的文件路径。不能为空。如果文件存在，将在开始前截断。如果正在进行日志记录，此方法将被忽略。
logAll	`true` 表示在日志中包含基本事件、用户 Cookie、凭据和所有传输的字节。此选项存在隐私风险，因为它会暴露用户的凭据，因此仅应在用户同意并在日志不会公开的情况下使用。`false` 表示仅包含基本事件。

public abstract void stopNetLog ()

停止 NetLog 记录并将文件刷新到磁盘。如果日志记录会话未在进行中，此调用将被忽略。

CronetEngine 使用收藏集保持井井有条 根据您的偏好保存和分类内容。

嵌套类摘要

常量摘要

公共构造函数摘要

公共方法摘要

继承方法摘要

常量

public static final int ACTIVE_REQUEST_COUNT_UNKNOWN

public static final int CONNECTION_METRIC_UNKNOWN

public static final int EFFECTIVE_CONNECTION_TYPE_2G

另请参阅

public static final int EFFECTIVE_CONNECTION_TYPE_3G

另请参阅

public static final int EFFECTIVE_CONNECTION_TYPE_4G

另请参阅

public static final int EFFECTIVE_CONNECTION_TYPE_OFFLINE

另请参阅

public static final int EFFECTIVE_CONNECTION_TYPE_SLOW_2G

另请参阅

public static final int EFFECTIVE_CONNECTION_TYPE_UNKNOWN

另请参阅

公共构造函数

public CronetEngine ()

公共方法

public void addRequestFinishedListener (RequestFinishedInfo.Listener listener)

参数

public void addRttListener (NetworkQualityRttListener listener)

参数

public void addThroughputListener (NetworkQualityThroughputListener listener)

参数

public void configureNetworkQualityEstimatorForTesting (boolean useLocalHostRequests, boolean useSmallerResponses, boolean disableOfflineCheck)

参数

public abstract URLStreamHandlerFactory createURLStreamHandlerFactory ()

返回

public int getActiveRequestCount ()

public int getDownstreamThroughputKbps ()

返回

public int getEffectiveConnectionType ()

返回

public abstract byte[] getGlobalMetricsDeltas ()

返回

public int getHttpRttMs ()

返回

public int getTransportRttMs ()

返回

public abstract String getVersionString ()

返回

public abstract UrlRequest.Builder newUrlRequestBuilder (String url, UrlRequest.Callback callback, Executor executor)

参数

public abstract URLConnection openConnection (URL url)

参数

返回

抛出

public void removeRequestFinishedListener (RequestFinishedInfo.Listener listener)

参数

public void removeRttListener (NetworkQualityRttListener listener)

参数

public void removeThroughputListener (NetworkQualityThroughputListener listener)

参数

public abstract void shutdown ()

public void startNetLogToDisk (String dirPath, boolean logAll, int maxSize)

参数

public abstract void startNetLogToFile (String fileName, boolean logAll)

参数

public abstract void stopNetLog ()

CronetEngine