UrlRequest.Builder

const val REQUEST_PRIORITY_HIGHEST = 4: Int

最高要求優先順序。已轉交給「setPriority」。

const val REQUEST_PRIORITY_IDLE = 0: Int

要求優先順序最低。已轉交給「setPriority」。

const val REQUEST_PRIORITY_LOW = 2: Int

要求優先順序較低。已轉交給「setPriority」。

const val REQUEST_PRIORITY_LOWEST = 1: Int

要求優先順序極低。已轉交給「setPriority」。

const val REQUEST_PRIORITY_MEDIUM = 3: Int

中等優先順序的請求。已轉交給「setPriority」。這是系統預設的請求優先順序。

abstract fun addHeader(header: String!, value: String!): UrlRequest.Builder!

新增要求標頭。

fun addRequestAnnotation(annotation: Any!): UrlRequest.Builder!

將註解物件與這項要求建立關聯。可以新增多個。傳遞至 RequestFinishedInfo.Listener，請參閱 getAnnotations。

abstract fun allowDirectExecutor(): UrlRequest.Builder!

標記執行器，這個要求會用來通知回呼 (適用於 UploadDataProvider 和 UrlRequest.Callback)，表示執行器會刻意執行內嵌執行作業，例如 Guava 的 directExecutor 或 java.util.concurrent.ThreadPoolExecutor.CallerRunsPolicy。

警告：這個選項很容易導致網路執行緒遭到封鎖。如果回呼會執行磁碟 I/O、取得鎖定或呼叫您未仔細控管及稽核的其他程式碼，則不應使用此方法。

fun bindToNetwork(networkHandle: Long): UrlRequest.Builder!

將要求繫結至指定的網路控制代碼。Cronet 只會使用與這個控制代碼相關聯的網路傳送這項要求。如果這個網路中斷連線，要求就會失敗，確切的錯誤會取決於網路中斷連線時的要求處理階段。網路控制代碼可透過 Network#getNetworkHandle 取得。僅適用於 Android Marshmallow 以上版本。

abstract fun build(): UrlRequest!

使用這個 Builder 內的設定建立 UrlRequest。然後呼叫 start 即可啟動傳回的 UrlRequest。

abstract fun disableCache(): UrlRequest.Builder!

停用要求快取。如果未設定使用快取的環境，這個呼叫就不會生效。

abstract fun setHttpMethod(method: String!): UrlRequest.Builder!

設定要用於這項要求的 HTTP 方法動詞。

如果要求沒有主體，且未呼叫這個方法，預設值為「GET」；如果要求有主體，預設值則為「POST」。

abstract fun setPriority(priority: Int): UrlRequest.Builder!

設定要求優先順序，應為 REQUEST_PRIORITY_* 值之一。如果未呼叫這個方法，要求會獲得 REQUEST_PRIORITY_MEDIUM 優先順序。

@UrlRequest.Experimental
fun setRawCompressionDictionary(
    dictionarySha256Hash: ByteArray!,
    dictionary: ByteBuffer!,
    dictionaryId: String!
): UrlRequest.Builder!

允許 Cronet 對這項要求使用指定的壓縮字典。指定後，Cronet 可能會向伺服器發出信號，表示有可用的壓縮字典。如要讓這項設定生效，執行這項要求的 CronetEngine 必須已設定為啟用支援外部字典的壓縮配置。這會在 Cronet 中部分實作 draft-ietf-httpbis-compression-dictionary。Cronet 不會直接處理「Use-As-Dictionary」回應標頭，而是會依賴嵌入器：處理這些標頭，然後針對符合 Use-As-Dictionary 規則的要求呼叫 UrlRequest.Builder#setCompressionDictionary；或透過其他頻外機制擷取壓縮字典，然後呼叫 UrlRequest.Builder#setCompressionDictionary。Cronet 會將字典解讀為只符合這個 UrlRequest。如果該要求遭到重新導向，且嵌入器決定追蹤重新導向，字典也會比對新網址。

fun setRequestFinishedListener(listener: RequestFinishedInfo.Listener!): UrlRequest.Builder!

設定在 onCanceled()、 onFailed() 或 onSucceeded() 傳回後叫用的監聽器。

系統會在 getExecutor() 提供的 java.util.concurrent.Executor 上，使用要求完成資訊叫用事件監聽器。

fun setTrafficStatsTag(tag: Int): UrlRequest.Builder!

設定 android.net.TrafficStats 標記，用於計算這項要求造成的通訊端流量。詳情請參閱 android.net.TrafficStats。如果未設定標記 (例如未呼叫這個方法)，Android 會將這項要求造成的通訊端流量視為標記值設為 0。

注意：設定標記會禁止與其他標記的要求共用通訊端，這可能會禁止共用連線，進而對效能造成負面影響。換句話說，只有在所有要求都有相同的通訊端標記時，才能使用多路複用通訊端 (例如 HTTP/2 和 QUIC)。

fun setTrafficStatsUid(uid: Int): UrlRequest.Builder!

設定特定 UID，用於計算這項要求造成的通訊端流量。詳情請參閱 android.net.TrafficStats。專為代表其他應用程式執行作業時使用。呼叫者必須擁有 MODIFY_NETWORK_ACCOUNTING 權限。根據預設，流量會歸因於呼叫端的 UID。

注意：設定 UID 會禁止與其他 UID 的要求共用通訊端，這可能會禁止共用連線，進而對效能造成負面影響。換句話說，只有在所有要求都設定相同的 UID 時，才能使用多路複用通訊端 (例如 HTTP/2 和 QUIC)。

abstract fun setUploadDataProvider(
    uploadDataProvider: UploadDataProvider!,
    executor: Executor!
): UrlRequest.Builder!

設定上傳資料供應商。如果未明確設定，則會將方法切換為「POST」。如果未設定 Content-Type 標頭，啟動要求時會擲回例外狀況。