UrlRequest.Builder

public abstract class UrlRequest.Builder

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

ملخّص

الثوابت
static final int

أعلى أولوية للطلبات
static final int

أدنى أولوية للطلبات
static final int

أولوية الطلب منخفضة.
static final int

أولوية الطلب منخفضة جدًا.
static final int

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

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

الإجراءات العامة
abstract UrlRequest.Builder
addHeader(String header, String value)

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

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

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

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

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

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

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

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

تسمح هذه السمة لـ 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

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.Listener مع RequestFinishedInfo
المرتجعات
UrlRequest.Builder

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

allowDirectExecutor

public abstract UrlRequest.Builder allowDirectExecutor()

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

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

bindToNetwork

public UrlRequest.Builder bindToNetwork(long networkHandle)

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

المعلَمات
long networkHandle

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

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

إنشاء

public abstract UrlRequest build()

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

المرتجعات
UrlRequest

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

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

المعلَمات
byte[] dictionarySha256Hash

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

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

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

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

setRequestFinishedListener

public UrlRequest.Builder setRequestFinishedListener(RequestFinishedInfo.Listener listener)

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

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

المعلَمات
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. يتمّ تلقائيًا تحديد مصدر الزيارات على أنّه رقم تعريف المتّصل.

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

المعلَمات
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

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