Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

UrlRequest.Builder

public abstract class UrlRequest.Builder

UrlRequest 的构建器。允许在通过 build 构建请求之前配置请求。可以通过调用 newUrlRequestBuilder 来创建构建器。

摘要

常量
`static final int`	`REQUEST_PRIORITY_HIGHEST = 4` 最高请求优先级。
`static final int`	`REQUEST_PRIORITY_IDLE = 0` 最低请求优先级。
`static final int`	`REQUEST_PRIORITY_LOW = 2` 请求优先级较低。
`static final int`	`REQUEST_PRIORITY_LOWEST = 1` 请求优先级非常低。
`static final int`	`REQUEST_PRIORITY_MEDIUM = 3` 中等请求优先级。

公共构造函数
`Builder()`

公共方法
`abstract UrlRequest.Builder`	`addHeader(String header, String value)` 添加请求标头。
`UrlRequest.Builder`	`addRequestAnnotation(Object annotation)` 将注释对象与此请求相关联。
`abstract UrlRequest.Builder`	`allowDirectExecutor()` 标记相应执行程序将用于通知回调（针对 `UploadDataProvider` 和 `UrlRequest.Callback`）的执行器是否有意执行内嵌执行，例如 Guava 的 directExecutor 或 `java.util.concurrent.ThreadPoolExecutor.CallerRunsPolicy`。
`UrlRequest.Builder`	`bindToNetwork(long networkHandle)` 将请求绑定到指定的网络句柄。
`abstract UrlRequest`	`build()` 使用此 `Builder` 中的配置创建 `UrlRequest`。
`abstract UrlRequest.Builder`	`disableCache()` 为请求停用缓存。
`abstract UrlRequest.Builder`	`setHttpMethod(String method)` 设置要用于此请求的 HTTP 方法谓词。
`abstract UrlRequest.Builder`	`setPriority(int priority)` 设置请求的优先级，该优先级应为 `REQUEST_PRIORITY_*` 值之一。
`UrlRequest.Builder`	`@UrlRequest.Experimental setRawCompressionDictionary( byte[] dictionarySha256Hash, ByteBuffer dictionary, String dictionaryId )` 允许 Cronet 将指定的压缩字典用于此请求。
`UrlRequest.Builder`	`setRequestFinishedListener(RequestFinishedInfo.Listener listener)` 设置在 `onCanceled()`、 `onFailed()` 或 `onSucceeded()` 返回后调用的监听器。
`UrlRequest.Builder`	`setTrafficStatsTag(int tag)` 设置在统计由此请求引起的套接字流量时要使用的 `android.net.TrafficStats` 标记。
`UrlRequest.Builder`	`setTrafficStatsUid(int uid)` 设置在统计此请求引起的套接字流量时要使用的特定 UID。
`abstract UrlRequest.Builder`	`setUploadDataProvider( UploadDataProvider uploadDataProvider, Executor executor )` 设置上传数据提供方。

常量

REQUEST_PRIORITY_HIGHEST

public static final int REQUEST_PRIORITY_HIGHEST = 4

最高请求优先级。已传递给 setPriority。

REQUEST_PRIORITY_IDLE

public static final int REQUEST_PRIORITY_IDLE = 0

最低请求优先级。已传递给 setPriority。

REQUEST_PRIORITY_LOW

public static final int REQUEST_PRIORITY_LOW = 2

低请求优先级。已传递给 setPriority。

REQUEST_PRIORITY_LOWEST

public static final int REQUEST_PRIORITY_LOWEST = 1

请求优先级非常低。已传递给 setPriority。

REQUEST_PRIORITY_MEDIUM

public static final int REQUEST_PRIORITY_MEDIUM = 3

中等请求优先级。已传递给 setPriority。这是分配给请求的默认优先级。

公共构造函数

Builder

public Builder()

公共方法

addHeader

public abstract UrlRequest.Builder addHeader(String header, String value)

添加请求标头。

参数
`String header`	标头名称。
`String value`	标头值。

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

addRequestAnnotation

public UrlRequest.Builder addRequestAnnotation(Object annotation)

将注释对象与此请求相关联。可以添加多个。传递给 RequestFinishedInfo.Listener，请参阅 getAnnotations。

参数
`Object annotation`	要传递给具有 `RequestFinishedInfo` 的 `RequestFinishedInfo.Listener` 的对象。

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

allowDirectExecutor

public abstract UrlRequest.Builder allowDirectExecutor()

标记相应执行器将用于通知回调（针对 UploadDataProvider 和 UrlRequest.Callback）有意执行内嵌执行，例如 Guava 的 directExecutor 或 java.util.concurrent.ThreadPoolExecutor.CallerRunsPolicy。

警告：此选项很容易导致意外阻塞网络线程。如果您的回调执行磁盘 I/O、获取锁或调用您未仔细控制和审核的其他代码，则不应使用此方法。

bindToNetwork

public UrlRequest.Builder bindToNetwork(long networkHandle)

将请求绑定到指定的网络句柄。Cronet 将仅使用与此句柄关联的网络发送此请求。如果此网络断开连接，请求将失败，具体错误将取决于网络断开连接时请求处理的阶段。可以通过 Network#getNetworkHandle 获取网络句柄。仅从 Android Marshmallow 开始提供。

参数
`long networkHandle`	要将请求绑定到的网络句柄。指定 `UNBIND_NETWORK_HANDLE` 可取消绑定。

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

build

public abstract UrlRequest build()

使用此 Builder 中的配置创建 UrlRequest。然后，可以通过调用 start 来启动返回的 UrlRequest。

返回
`UrlRequest`	使用此 `Builder` 中的配置构建的 `UrlRequest`。

disableCache

public abstract UrlRequest.Builder disableCache()

为请求停用缓存。如果上下文未设置为使用缓存，则此调用无效。

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

setHttpMethod

public abstract UrlRequest.Builder setHttpMethod(String method)

设置要用于此请求的 HTTP 方法谓词。

如果未调用此方法，则默认值为“GET”（如果请求没有正文）或“POST”（如果请求有正文）。

参数
`String method`	“GET”“HEAD”“DELETE”“POST”或“PUT”。

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

setPriority

public abstract UrlRequest.Builder setPriority(int priority)

设置请求的优先级，该优先级应为 REQUEST_PRIORITY_* 值之一。如果未调用此方法，则请求的优先级为 REQUEST_PRIORITY_MEDIUM。

参数
`int priority`	请求的优先级，应为 `REQUEST_PRIORITY_*` 值之一。

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

setRawCompressionDictionary

@UrlRequest.Experimental
public UrlRequest.Builder setRawCompressionDictionary(
    byte[] dictionarySha256Hash,
    ByteBuffer dictionary,
    String dictionaryId
)

允许 Cronet 为此请求使用指定的压缩字典。如果指定，Cronet 可能会向服务器发出信号，表明相应压缩字典是否可用。如需使此设置生效，必须已将将执行此请求的 CronetEngine 配置为启用支持外部字典的压缩方案。此功能在 Cronet 中部分实现了 draft-ietf-httpbis-compression-dictionary。Cronet 不会直接处理“Use-As-Dictionary”响应标头，而是会依赖嵌入器来处理这些标头，并针对符合“Use-As-Dictionary”规则的请求调用 UrlRequest.Builder#setCompressionDictionary；或者通过其他带外机制提取压缩字典，然后调用 UrlRequest.Builder#setCompressionDictionary。Cronet 会将该字典解读为仅与此 UrlRequest 相匹配。如果上述请求被重定向，并且嵌入者决定遵循重定向，则该字典也会与新网址匹配。

参数
`byte[] dictionarySha256Hash`	指定压缩字典的 SHA-256。
`ByteBuffer dictionary`	Cronet 可用于相应 UrlRequest 的压缩字典。这必须是直接 ByteBuffer。
`String dictionaryId`	与此字典关联的可选 ID，如果缺少，则必须为空字符串。如果存在，则会通过 Dictionary-ID 标头发送。如果服务器在其“Use-As-Dictionary”响应中指定了 ID，您就需要指定此属性。

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

setRequestFinishedListener

public UrlRequest.Builder setRequestFinishedListener(RequestFinishedInfo.Listener listener)

设置在 onCanceled()、 onFailed() 或 onSucceeded() 返回后调用的监听器。

监听器会通过 getExecutor() 提供的 java.util.concurrent.Executor 调用，并提供请求完成信息。

参数
`RequestFinishedInfo.Listener listener`	用于监听已完成请求的监听器。

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

setTrafficStatsTag

public UrlRequest.Builder setTrafficStatsTag(int tag)

设置在统计由此请求引起的套接字流量时要使用的 android.net.TrafficStats 标记。如需了解详情，请参阅 android.net.TrafficStats。如果未设置标记（例如，未调用此方法），Android 会将此请求造成的套接字流量视为标记值设置为 0。

注意：设置标记会禁止与其他标记的请求共享套接字，这可能会禁止连接共享，从而对性能产生不利影响。换句话说，只有当所有请求都具有相同的套接字标记时，才允许使用多路复用套接字（例如 HTTP/2 和 QUIC）。

参数
`int tag`	用于统计此请求造成的套接字流量的标记值。介于 0xFFFFFF00 和 0xFFFFFFFF 之间的标记已预留，供系统服务（例如 `android.app.DownloadManager`）在代表应用执行流量操作时在内部使用。

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

setTrafficStatsUid

public UrlRequest.Builder setTrafficStatsUid(int uid)

设置在统计此请求引起的套接字流量时要使用的特定 UID。如需了解详情，请访问 android.net.TrafficStats。旨在用于代表其他应用执行操作时。调用方必须持有 MODIFY_NETWORK_ACCOUNTING 权限。默认情况下，流量归因于调用方的 UID。

注意：设置 UID 会禁止与其他 UID 的请求共享套接字，这可能会禁止连接共享，从而对性能产生不利影响。换句话说，只有当所有请求都设置了相同的 UID 时，才允许使用多路复用套接字（例如 HTTP/2 和 QUIC）。

参数
`int uid`	用于归因于此请求所致套接字流量的 UID。

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

setUploadDataProvider

public abstract UrlRequest.Builder setUploadDataProvider(
    UploadDataProvider uploadDataProvider,
    Executor executor
)

设置上传数据提供方。如果未明确设置，则将方法切换为“POST”。如果未设置 Content-Type 标头，启动请求将抛出异常。

参数
`UploadDataProvider uploadDataProvider`	负责提供上传数据。
`Executor executor`	所有 `uploadDataProvider` 方法都将使用此 `Executor` 进行调用。可以选择性地与请求本身使用的 `Executor` 相同。

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