CronetEngine

public abstract class CronetEngine extends Object

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

嵌套类摘要

class 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 日志记录并将文件刷新到磁盘。

继承方法摘要

来自 class 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 Socket Factory

此 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() 后开始收集这些指标，因此第一次调用不会返回任何有用数据，因为尚未收集任何指标。

Cronet 收集的指标差异，自上次调用 getGlobalMetricsDeltas() 以来，序列化为 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)

移除吞吐量监听器。为了停止接收观察结果，应该在使用 addThroughputListener(NetworkQualityThroughputListener) 添加 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