UrlRequest.Builder

abstract class UrlRequest.Builder

أداة إنشاء لـ UrlRequest تتيح إعداد الطلبات قبل إنشائها باستخدام build. يمكن إنشاء أداة الإنشاء من خلال استدعاء newUrlRequestBuilder.

ملخّص

الثوابت
const Int

أعلى أولوية للطلبات
const Int

أدنى أولوية للطلبات
const Int

أولوية الطلب منخفضة.
const Int

أولوية الطلب منخفضة جدًا.
const Int

أولوية الطلب المتوسطة

طُرق وضع التصميم العامة

الوظائف العامة
abstract UrlRequest.Builder!
addHeader(header: String!, value: String!)

تضيف هذه السمة عنوان طلب.
UrlRequest.Builder!
addRequestAnnotation(annotation: Any!)

يربط عنصر التعليق التوضيحي بهذا الطلب.
abstract UrlRequest.Builder!

تشير هذه العلامة إلى أنّ المنفّذين الذين سيستخدمهم هذا الطلب لإرسال إشعارات إلى الدوال البرمجية (بالنسبة إلى UploadDataProvider وUrlRequest.Callback) ينفّذون التعليمات البرمجية المضمّنة بشكلٍ متعمّد، مثل directExecutor في Guava أو java.util.concurrent.ThreadPoolExecutor.CallerRunsPolicy.
UrlRequest.Builder!
bindToNetwork(networkHandle: Long)

يربط الطلب بمقبض الشبكة المحدّد.
abstract UrlRequest!

تُنشئ UrlRequest باستخدام الإعدادات ضمن Builder.
abstract UrlRequest.Builder!

يؤدي ذلك إلى إيقاف ذاكرة التخزين المؤقت للطلب.
abstract UrlRequest.Builder!

تضبط هذه السمة فعل طريقة HTTP المطلوب استخدامه لهذا الطلب.
abstract UrlRequest.Builder!
setPriority(priority: Int)

تضبط هذه السمة أولوية الطلب التي يجب أن تكون إحدى قيم REQUEST_PRIORITY_*.
UrlRequest.Builder!
@UrlRequest.Experimental
setRawCompressionDictionary(
    dictionarySha256Hash: ByteArray!,
    dictionary: ByteBuffer!,
    dictionaryId: String!
)

تسمح هذه السمة لـ Cronet باستخدام قاموس الضغط المحدّد لهذا الطلب.
UrlRequest.Builder!

تضبط هذه السمة أداة معالجة يتم استدعاؤها بعد عرض onCanceled() أو onFailed() أو onSucceeded().
UrlRequest.Builder!

يضبط العلامة android.net.TrafficStats التي سيتم استخدامها عند تدوين سجلات الاستخدام لحركة بيانات المقبس الناتجة عن هذا الطلب.
UrlRequest.Builder!

يضبط معرّف UID معيّنًا لاستخدامه عند احتساب عدد زيارات المقبس الناتجة عن هذا الطلب.
abstract UrlRequest.Builder!
setUploadDataProvider(
    uploadDataProvider: UploadDataProvider!,
    executor: Executor!
)

تضبط هذه السمة مزوّد بيانات التحميل.

الثوابت

REQUEST_PRIORITY_HIGHEST

const val REQUEST_PRIORITY_HIGHEST = 4: Int

أعلى أولوية للطلبات تمت الموافقة على الطلب من خلال setPriority.

REQUEST_PRIORITY_IDLE

const val REQUEST_PRIORITY_IDLE = 0: Int

أدنى أولوية للطلبات تمت الموافقة على الطلب من خلال setPriority.

REQUEST_PRIORITY_LOW

const val REQUEST_PRIORITY_LOW = 2: Int

أولوية الطلب منخفضة. تمت الموافقة على الطلب من خلال setPriority.

REQUEST_PRIORITY_LOWEST

const val REQUEST_PRIORITY_LOWEST = 1: Int

أولوية الطلب منخفضة جدًا. تمت الموافقة على الطلب من خلال setPriority.

REQUEST_PRIORITY_MEDIUM

const val REQUEST_PRIORITY_MEDIUM = 3: Int

أولوية الطلب المتوسطة تمت الموافقة على الطلب من خلال setPriority. هذه هي الأولوية التلقائية الممنوحة للطلب.

طُرق وضع التصميم العامة

"البنّاء" (Builder)

Builder()

الوظائف العامة

addHeader

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

تضيف هذه السمة عنوان طلب.

المعلَمات
header: String!

اسم العنوان
value: String!

قيمة العنوان.
المرتجعات
UrlRequest.Builder!

تسهيل ربط السلاسل

addRequestAnnotation

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

يربط عنصر التعليق التوضيحي بهذا الطلب. يمكنك إضافة أكثر من واحد. تم تمريرها إلى RequestFinishedInfo.Listener، يمكنك الاطّلاع على getAnnotations.

المعلَمات
annotation: Any!

عنصر يتم تمريره إلى RequestFinishedInfo.Listener مع RequestFinishedInfo
المرتجعات
UrlRequest.Builder!

تسهيل ربط السلاسل

allowDirectExecutor

abstract fun allowDirectExecutor(): UrlRequest.Builder!

تشير هذه العلامة إلى أنّ المنفّذين الذين سيستخدمهم هذا الطلب لإرسال إشعارات إلى الدوال البرمجية (بالنسبة إلى UploadDataProvider وUrlRequest.Callback) ينفّذون التعليمات البرمجية المضمّنة بشكلٍ متعمّد، مثل directExecutor في Guava أو java.util.concurrent.ThreadPoolExecutor.CallerRunsPolicy.

تحذير: يسهّل هذا الخيار حظر سلسلة المحادثات على الشبكة عن طريق الخطأ. يجب عدم استخدامها إذا كانت عمليات رد الاتصال تنفّذ عمليات إدخال/إخراج على القرص أو تحصل على أقفال أو تستدعي رمزًا آخر لا يمكنك التحكّم فيه وتدقيقه بعناية.

bindToNetwork

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

يربط الطلب بمقبض الشبكة المحدّد. سيرسل Cronet هذا الطلب فقط باستخدام الشبكة المرتبطة بهذا المعرّف. في حال انقطاع الاتصال بالشبكة، سيتعذّر تنفيذ الطلب، وسيعتمد الخطأ الدقيق على مرحلة معالجة الطلب عند انقطاع الاتصال بالشبكة. يمكن الحصول على أسماء المستخدمين على الشبكة من خلال Network#getNetworkHandle. تتوفّر هذه الميزة على الإصدارات الأحدث من Android Marshmallow فقط.

المعلَمات
networkHandle: Long

مقبض الشبكة الذي سيتم ربط الطلب به. حدِّد UNBIND_NETWORK_HANDLE لإلغاء الربط.
المرتجعات
UrlRequest.Builder!

تسهيل ربط السلاسل

إنشاء

abstract fun build(): UrlRequest!

تُنشئ UrlRequest باستخدام الإعدادات ضمن Builder. يمكن بعد ذلك بدء UrlRequest الذي تم عرضه عن طريق استدعاء start.

المرتجعات
UrlRequest!

تم إنشاء UrlRequest باستخدام الإعدادات ضمن Builder.

disableCache

abstract fun disableCache(): UrlRequest.Builder!

يؤدي ذلك إلى إيقاف ذاكرة التخزين المؤقت للطلب. في حال عدم إعداد السياق لاستخدام ذاكرة التخزين المؤقت، لن يكون لهذا الطلب أي تأثير.

المرتجعات
UrlRequest.Builder!

تسهيل ربط السلاسل

setHttpMethod

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

تضبط هذه السمة فعل طريقة HTTP المطلوب استخدامه لهذا الطلب.

القيمة التلقائية عند عدم استدعاء هذه الطريقة هي "GET" إذا لم يتضمّن الطلب أي نص أساسي أو "POST" إذا كان يتضمّن نصًا أساسيًا.

المعلَمات
method: String!

‫"GET" أو "HEAD" أو "DELETE" أو "POST" أو "PUT"
المرتجعات
UrlRequest.Builder!

تسهيل ربط السلاسل

setPriority

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

تضبط هذه السمة أولوية الطلب التي يجب أن تكون إحدى قيم REQUEST_PRIORITY_*. يتم منح الطلب الأولوية REQUEST_PRIORITY_MEDIUM إذا لم يتم استدعاء هذا الإجراء.

المعلَمات
priority: Int

أولوية الطلب التي يجب أن تكون إحدى قيم REQUEST_PRIORITY_*
المرتجعات
UrlRequest.Builder!

تسهيل ربط السلاسل

setRawCompressionDictionary

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

تسمح هذه السمة لـ Cronet باستخدام قاموس الضغط المحدّد لهذا الطلب. عند تحديدها، قد تشير Cronet إلى الخادم بتوفّر قاموس الضغط المذكور. ولكي يكون لهذا الإعداد أي تأثير، يجب أن يكون قد تم ضبط CronetEngine الذي سينفّذ هذا الطلب لتفعيل نظام ضغط يتوافق مع القواميس الخارجية. يتم تنفيذ مسودة ietf-httpbis-compression-dictionary جزئيًا ضمن Cronet. لن يتعامل Cronet مباشرةً مع عناوين الاستجابة "Use-As-Dictionary"، بل سيعتمد بدلاً من ذلك على برنامج التضمين لتنفيذ أحد الإجراءَين التاليَين: إما التعامل معها ثم استدعاء UrlRequest.Builder#setCompressionDictionary للطلبات التي تتطابق مع قواعد Use-As-Dictionary، أو جلب قواميس الضغط من خلال آلية أخرى خارج النطاق، ثم استدعاء UrlRequest.Builder#setCompressionDictionary. ستفسّر Cronet القاموس على أنّه يطابق طلب UrlRequest هذا فقط. في حال إعادة توجيه الطلب المذكور، وقرّر برنامج التضمين اتّباع عملية إعادة التوجيه، ستتطابق القاموس أيضًا مع عنوان URL الجديد.

المعلَمات
dictionarySha256Hash: ByteArray!

تمثّل هذه السمة تجزئة SHA-256 لقاموس الضغط المحدّد.
dictionary: ByteBuffer!

قاموس الضغط الذي يمكن أن يستخدمه Cronet لطلب UrlRequest هذا. يجب أن يكون هذا المخزن المؤقت من النوع ByteBuffer المباشر.
dictionaryId: String!

المعرّف الاختياري المرتبط بهذا القاموس، ويجب أن يكون سلسلة فارغة في حال عدم توفّره. في حال توفّر هذا المفتاح، سيتم إرساله عبر عنوان Dictionary-ID. عليك تحديد ذلك إذا حدّد الخادم معرّفًا في استجابته "Use-As-Dictionary".
المرتجعات
UrlRequest.Builder!

تسهيل ربط السلاسل

setRequestFinishedListener

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

تضبط هذه السمة أداة معالجة يتم استدعاؤها بعد عرض onCanceled() أو onFailed() أو onSucceeded().

يتم استدعاء أداة الاستماع مع معلومات اكتمال الطلب في java.util.concurrent.Executor المقدَّمة من getExecutor().

المعلَمات
listener: RequestFinishedInfo.Listener!

المستمع للطلبات المكتملة
المرتجعات
UrlRequest.Builder!

تسهيل ربط السلاسل

setTrafficStatsTag

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

يضبط العلامة android.net.TrafficStats التي سيتم استخدامها عند تدوين سجلات الاستخدام لحركة بيانات المقبس الناتجة عن هذا الطلب. يُرجى الاطّلاع على android.net.TrafficStats للحصول على المزيد من المعلومات. في حال عدم ضبط أي علامة (على سبيل المثال، إذا لم يتم استدعاء هذه الطريقة)، سيحتسب نظام التشغيل Android عدد الزيارات الواردة من المقبس الناتجة عن هذا الطلب كما لو تم ضبط قيمة العلامة على 0.

ملاحظة: يؤدي ضبط علامة إلى عدم السماح بمشاركة مآخذ التوصيل مع الطلبات التي تتضمّن علامات أخرى، ما قد يؤثر سلبًا في الأداء من خلال حظر مشاركة الاتصال. بعبارة أخرى، لن يُسمح باستخدام المقابس المتعددة الإرسال (مثل HTTP/2 وQUIC) إلا إذا كانت جميع الطلبات تحمل علامة المقبس نفسها.

المعلَمات
tag: Int

قيمة العلامة المستخدَمة عند احتساب عدد الزيارات التي تم إنشاؤها بسبب هذا الطلب العلامات بين 0xFFFFFF00 و0xFFFFFFFF محجوزة وتستخدم داخليًا من قِبل خدمات النظام، مثل android.app.DownloadManager عند تنفيذ حركة بيانات نيابةً عن أحد التطبيقات.
المرتجعات
UrlRequest.Builder!

تسهيل ربط السلاسل

setTrafficStatsUid

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

يضبط معرّف UID معيّنًا لاستخدامه عند احتساب عدد زيارات المقبس الناتجة عن هذا الطلب. يُرجى الاطّلاع على android.net.TrafficStats لمزيد من المعلومات. تم تصميمها لاستخدامها عند تنفيذ عملية نيابةً عن تطبيق آخر. يجب أن يكون لدى المتصل إذن MODIFY_NETWORK_ACCOUNTING. يتمّ تلقائيًا تحديد مصدر الزيارات على أنّه رقم تعريف المتّصل.

ملاحظة: يؤدي ضبط معرّف فريد إلى عدم السماح بمشاركة مآخذ التوصيل مع الطلبات التي تتضمّن معرّفات فريدة أخرى، ما قد يؤثر سلبًا في الأداء من خلال حظر مشاركة الاتصال. بعبارة أخرى، لن يُسمح باستخدام مآخذ توصيل متعددة الإرسال (مثل HTTP/2 وQUIC) إلا إذا تم ضبط معرّف UID نفسه لجميع الطلبات.

المعلَمات
uid: Int

معرّف المستخدم (UID) الذي سيتمّ ربط عدد الزيارات الواردة إلى المقبس بهذا الطلب
المرتجعات
UrlRequest.Builder!

تسهيل ربط السلاسل

setUploadDataProvider

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

تضبط هذه السمة مزوّد بيانات التحميل. يتم تبديل الطريقة إلى "POST" إذا لم يتم ضبطها بشكل صريح. سيؤدي بدء الطلب إلى طرح استثناء إذا لم يتم ضبط العنوان Content-Type.

المعلَمات
uploadDataProvider: UploadDataProvider!

المسؤول عن تقديم بيانات التحميل
executor: Executor!

سيتم استدعاء جميع طرق uploadDataProvider باستخدام Executor هذا. يمكن أن يكون اختياريًا هو نفسه Executor الذي يستخدمه الطلب نفسه.
المرتجعات
UrlRequest.Builder!

تسهيل ربط السلاسل