CronetEngine
abstract class CronetEngine
JavaCronetEngine |
تمت إضافة |
محرك لمعالجة UrlRequest، ويستخدم أفضل حزمة HTTP متاحة على النظام الأساسي الحالي يمكن إنشاء مثيل لهذه الفئة باستخدام Builder.
ملخّص
الأنواع المتداخلة |
|---|
class CronetEngine.Builderأداة إنشاء |
abstract class CronetEngine.Builder.LibraryLoaderفئة توفّر طريقة لتحميل مكتبة مجمّعة من رموز برمجية أصلية لـ Cronet. |
الثوابت |
|
|---|---|
const Int |
قيمة عدد الطلبات النشطة غير معروفة |
const Int |
قيمة مقياس الاتصال غير معروفة. |
const Int |
تقدير نوع الاتصال الفعّال هو 2G. |
const Int |
تقدير نوع الاتصال الفعّال هو 3G. |
const Int |
تقدير نوع الاتصال الفعّال هو 4G. |
const Int |
الجهاز غير متّصل بالإنترنت. |
const Int |
تقدير نوع الاتصال الفعّال هو شبكة الجيل الثاني البطيئة. |
const Int |
تقدير نوع الاتصال الفعّال غير معروف. |
const Long |
القيمة التي سيتم استخدامها للتراجع عن أي ربط سابق بالشبكة |
طُرق وضع التصميم العامة |
|---|
الوظائف العامة |
|
|---|---|
Unit |
تسجّل هذه السمة معالجًا يتم استدعاؤه بعد انتهاء كل طلب مع معلومات الطلب. |
Unit |
addRttListener(listener: NetworkQualityRttListener!)تسجّل هذه الطريقة أداة معالجة يتم استدعاؤها عندما يرصد مقدّر جودة الشبكة وقت نقل البيانات ذهابًا وإيابًا. |
Unit |
تسجّل هذه الطريقة أداة معالجة يتم استدعاؤها عندما يشهد مقدّر جودة الشبكة قياسًا لسرعة معالجة البيانات. |
Unit |
bindToNetwork(networkHandle: Long)يربط المحرّك بمقبض الشبكة المحدّد. |
Unit |
configureNetworkQualityEstimatorForTesting(تضبط هذه السمة أداة تقدير جودة الشبكة لأغراض الاختبار. |
abstract URLStreamHandlerFactory! |
إنشاء |
Int |
تعرض هذه السمة عدد الطلبات النشطة. |
Int |
تعرض هذه السمة تقديرًا لمعدّل نقل البيانات في اتجاه التنزيل (بالكيلوبت في الثانية) الذي يحسبه مقدّر جودة الشبكة. |
Int |
تعرض هذه السمة تقديرًا لنوع الاتصال الفعّال الذي يتم احتسابه بواسطة أداة تقدير جودة الشبكة. |
abstract ByteArray<Byte>! |
تم إيقاف هذه الوظيفة نهائيًا. في الإصدارات الحديثة من Cronet، سيؤدي ذلك دائمًا إلى عرض مصفوفة فارغة. |
Int |
تعرض هذه السمة تقديرًا لوقت الاستجابة الكامل (RTT) لبروتوكول HTTP (بالمللي ثانية) الذي تم احتسابه بواسطة أداة تقدير جودة الشبكة. |
Int |
تعرض هذه السمة تقديرًا لوقت الاستجابة الكامل للنقل (بالمللي ثانية) الذي يتم احتسابه بواسطة أداة تقدير جودة الشبكة. |
abstract String! |
|
abstract UrlRequest.Builder! |
newUrlRequestBuilder(تنشئ هذه الدالة أداة إنشاء لـ |
abstract URLConnection! |
openConnection(url: URL!)تنشئ هذه السمة اتصالاً جديدًا بالمرجع المحدّد بواسطة |
Unit |
تزيل هذه الطريقة أداة معالجة طلب مكتمل. |
Unit |
removeRttListener(listener: NetworkQualityRttListener!)يزيل مستمعًا لأوقات الرحلة ذهابًا وعودة إذا تم تسجيله مسبقًا باستخدام |
Unit |
يزيل أداة معالجة معدل نقل البيانات. |
abstract Unit |
shutdown()يوقف |
Unit |
startNetLogToDisk(dirPath: String!, logAll: Boolean, maxSize: Int)يبدأ تسجيل NetLog في دليل محدّد بحجم محدود. |
abstract Unit |
startNetLogToFile(fileName: String!, logAll: Boolean)يبدأ تسجيل NetLog في ملف. |
abstract Unit |
يوقف تسجيل NetLog ويفرغ الملف إلى القرص. |
الثوابت
ACTIVE_REQUEST_COUNT_UNKNOWN
const val ACTIVE_REQUEST_COUNT_UNKNOWN = -1: Int
قيمة عدد الطلبات النشطة غير معروفة
CONNECTION_METRIC_UNKNOWN
const val CONNECTION_METRIC_UNKNOWN = -1: Int
قيمة مقياس الاتصال غير معروفة.
EFFECTIVE_CONNECTION_TYPE_2G
const val EFFECTIVE_CONNECTION_TYPE_2G = 3: Int
تقدير نوع الاتصال الفعّال هو 2G.
| انظر أيضًا | |
|---|---|
getEffectiveConnectionType |
EFFECTIVE_CONNECTION_TYPE_3G
const val EFFECTIVE_CONNECTION_TYPE_3G = 4: Int
تقدير نوع الاتصال الفعّال هو 3G.
| انظر أيضًا | |
|---|---|
getEffectiveConnectionType |
EFFECTIVE_CONNECTION_TYPE_4G
const val EFFECTIVE_CONNECTION_TYPE_4G = 5: Int
تقدير نوع الاتصال الفعّال هو 4G.
| انظر أيضًا | |
|---|---|
getEffectiveConnectionType |
EFFECTIVE_CONNECTION_TYPE_OFFLINE
const val EFFECTIVE_CONNECTION_TYPE_OFFLINE = 1: Int
الجهاز غير متّصل بالإنترنت.
| انظر أيضًا | |
|---|---|
getEffectiveConnectionType |
EFFECTIVE_CONNECTION_TYPE_SLOW_2G
const val EFFECTIVE_CONNECTION_TYPE_SLOW_2G = 2: Int
تقدير نوع الاتصال الفعّال هو شبكة الجيل الثاني البطيئة.
| انظر أيضًا | |
|---|---|
getEffectiveConnectionType |
EFFECTIVE_CONNECTION_TYPE_UNKNOWN
const val EFFECTIVE_CONNECTION_TYPE_UNKNOWN = 0: Int
تقدير نوع الاتصال الفعّال غير معروف.
| انظر أيضًا | |
|---|---|
getEffectiveConnectionType |
UNBIND_NETWORK_HANDLE
const val UNBIND_NETWORK_HANDLE = -1: Long
القيمة التي سيتم استخدامها للتراجع عن أي ربط سابق بالشبكة
طُرق وضع التصميم العامة
الوظائف العامة
addRequestFinishedListener
fun addRequestFinishedListener(listener: RequestFinishedInfo.Listener!): Unit
تسجّل هذه السمة معالجًا يتم استدعاؤه بعد انتهاء كل طلب مع معلومات الطلب.
يتم الاتصال بالمستمع على java.util.concurrent.Executor يقدّمه المستمع.
| المعلَمات | |
|---|---|
listener: RequestFinishedInfo.Listener! |
المستمع للطلبات المكتملة |
addRttListener
fun addRttListener(listener: NetworkQualityRttListener!): Unit
تسجّل هذه الطريقة أداة معالجة يتم استدعاؤها عندما يرصد مقدّر جودة الشبكة وقت نقل البيانات ذهابًا وإيابًا. يجب استدعاء هذه الدالة بعد enableNetworkQualityEstimator، وإلا سيتم طرح استثناء. يمكن تسجيل أوقات الذهاب والعودة في طبقات مختلفة من حزمة الشبكة، بما في ذلك TCP وQUIC وفي طبقة طلب عنوان URL. يتم استدعاء المستمع على java.util.concurrent.Executor الذي يتم تمريره إلى enableNetworkQualityEstimator.
| المعلَمات | |
|---|---|
listener: NetworkQualityRttListener! |
المستمع إلى مدة الذهاب والعودة |
addThroughputListener
fun addThroughputListener(listener: NetworkQualityThroughputListener!): Unit
تسجّل هذه الطريقة أداة معالجة يتم استدعاؤها عندما يشهد مقدّر جودة الشبكة قياسًا لسرعة معالجة البيانات. يجب استدعاء هذه الطريقة بعد enableNetworkQualityEstimator. يتم احتساب ملاحظات سرعة معالجة البيانات من خلال قياس عدد وحدات البايت التي تمّت قراءتها عبر واجهة الشبكة النشطة في الأوقات التي يتم فيها تلقّي ردّ واحد على الأقل من عنوان URL. يتم استدعاء المستمع على java.util.concurrent.Executor الذي يتم تمريره إلى enableNetworkQualityEstimator.
| المعلَمات | |
|---|---|
listener: NetworkQualityThroughputListener! |
تمثّل المستمع إلى معدل النقل. |
bindToNetwork
fun bindToNetwork(networkHandle: Long): Unit
يربط المحرّك بمقبض الشبكة المحدّد. ستستخدم جميع الطلبات التي يتم إنشاؤها من خلال محرك البحث هذا الشبكة المرتبطة بهذا الاسم المعرِّف. في حال انقطاع الاتصال بالشبكة، ستتعذّر جميع الطلبات، وسيعتمد الخطأ الدقيق على مرحلة معالجة الطلب عند انقطاع الاتصال بالشبكة. يمكن الحصول على أسماء المستخدمين على الشبكة من خلال Network#getNetworkHandle. تتوفّر هذه الميزة على الإصدارات الأحدث من Android Marshmallow فقط.
| المعلَمات | |
|---|---|
networkHandle: Long |
معرّف الشبكة الذي سيتم ربط المحرك به. حدِّد |
configureNetworkQualityEstimatorForTesting
fun configureNetworkQualityEstimatorForTesting(
useLocalHostRequests: Boolean,
useSmallerResponses: Boolean,
disableOfflineCheck: Boolean
): Unit
تضبط هذه السمة أداة تقدير جودة الشبكة لأغراض الاختبار. يجب استدعاء هذه الدالة قبل إضافة أدوات معالجة وقت نقل البيانات ذهابًا وإيابًا وسرعة معالجة البيانات، وبعد تفعيل أداة تقدير جودة الشبكة.
| المعلَمات | |
|---|---|
useLocalHostRequests: Boolean |
تضمين الطلبات المقدَّمة إلى المضيف المحلي في التقديرات |
useSmallerResponses: Boolean |
تضمين الردود الصغيرة في تقديرات معدل النقل |
disableOfflineCheck: Boolean |
عند ضبطها على "صحيح"، يتم إيقاف عمليات التحقّق من حالة الجهاز غير المتصل بالإنترنت عند احتساب نوع الاتصال الفعّال أو عند كتابة الإعدادات المفضّلة. |
createURLStreamHandlerFactory
abstract fun createURLStreamHandlerFactory(): URLStreamHandlerFactory!
إنشاء URLStreamHandlerFactory للتعامل مع زيارات HTTP وHTTPS يمكن تثبيت مثيل من هذه الفئة من خلال setURLStreamHandlerFactory، وبالتالي استخدام CronetEngine تلقائيًا لجميع الطلبات التي يتم إنشاؤها من خلال openConnection.
لا تستخدم Cronet ميزات HTTP معيّنة يتم توفيرها من خلال النظام:
- ذاكرة التخزين المؤقت عبر HTTP المثبَّتة من خلال
HttpResponseCache.install() - طريقة مصادقة HTTP المثبَّتة من خلال
setDefault - مساحة تخزين ملفات تعريف ارتباط HTTP التي تم تثبيتها من خلال
setDefault
مع أنّ Cronet يتيح الطلبات باستخدام بروتوكول HTTPS ويشجّع على ذلك، لا يتيح Cronet استخدام واجهة برمجة التطبيقات HttpsURLConnection. يشمل عدم التوافق أيضًا عدم استخدام بعض ميزات HTTPS التي يوفّرها النظام:
- أداة التحقّق من اسم المضيف HTTPS المثبَّتة من خلال
HttpsURLConnection.setDefaultHostnameVerifier() - مصنع مقابس HTTPS الذي تم تثبيته من خلال
HttpsURLConnection.setDefaultSSLSocketFactory()
| المرتجعات | |
|---|---|
URLStreamHandlerFactory! |
مثيل |
getActiveRequestCount
fun getActiveRequestCount(): Int
تعرض هذه السمة عدد الطلبات النشطة.
يصبح الطلب "نشطًا" في UrlRequest.start()، على افتراض أنّ هذه الطريقة لا تعرض استثناءً. يصبح غير نشط عندما يتم عرض جميع عمليات معاودة الاتصال ولا يمكن بدء أي عمليات معاودة اتصال إضافية في المستقبل. يعني ذلك عمليًا أنّ الطلب يصبح غير نشط بعد أن تعرض الدالة onSucceeded/onCanceled/onFailed القيمة، وبعد أن تعرض جميع أدوات معالجة الطلبات المكتملة القيمة. دورة حياة طلبات Cronet لمزيد من المعلومات
getDownstreamThroughputKbps
fun getDownstreamThroughputKbps(): Int
تعرض هذه السمة تقديرًا لمعدّل نقل البيانات في اتجاه التنزيل (بالكيلوبت في الثانية) الذي يحسبه مقدّر جودة الشبكة. اضبط القيمة على CONNECTION_METRIC_UNKNOWN إذا كانت غير متاحة. يجب استدعاء هذه الدالة بعد enableNetworkQualityEstimator، وإلا سيتم طرح استثناء.
| المرتجعات | |
|---|---|
Int |
تقدير لمعدل نقل البيانات في اتجاه التنزيل بالكيلوبت في الثانية |
getEffectiveConnectionType
fun getEffectiveConnectionType(): Int
تعرض هذه السمة تقديرًا لنوع الاتصال الفعّال الذي يتم احتسابه بواسطة أداة تقدير جودة الشبكة. استدعِ الدالة enableNetworkQualityEstimator لبدء احتساب هذه القيمة.
| المرتجعات | |
|---|---|
Int |
تمثّل هذه السمة نوع الاتصال المقدَّر. القيمة المعروضة هي إحدى القيم |
getHttpRttMs
fun getHttpRttMs(): Int
تعرض هذه السمة تقديرًا لوقت الاستجابة الكامل (RTT) لبروتوكول HTTP (بالمللي ثانية) الذي تم احتسابه بواسطة أداة تقدير جودة الشبكة. اضبط القيمة على CONNECTION_METRIC_UNKNOWN إذا كانت غير متاحة. يجب استدعاء هذه الدالة بعد enableNetworkQualityEstimator، وإلا سيتم طرح استثناء.
| المرتجعات | |
|---|---|
Int |
تقدير لوقت الاستجابة الكامل لبروتوكول HTTP بالمللي ثانية |
getTransportRttMs
fun getTransportRttMs(): Int
تعرض هذه السمة تقديرًا لوقت الاستجابة الكامل للنقل (بالمللي ثانية) الذي يتم احتسابه بواسطة أداة تقدير جودة الشبكة. اضبط القيمة على CONNECTION_METRIC_UNKNOWN إذا كانت غير متاحة. يجب استدعاء هذه الدالة بعد enableNetworkQualityEstimator، وإلا سيتم طرح استثناء.
| المرتجعات | |
|---|---|
Int |
تقدير لمدّة ذهاب وعودة النقل بالمللي ثانية |
getVersionString
abstract fun getVersionString(): String!
| المرتجعات | |
|---|---|
String! |
سلسلة إصدار المحرك يمكن للمستخدمين قراءتها |
newUrlRequestBuilder
abstract fun newUrlRequestBuilder(
url: String!,
callback: UrlRequest.Callback!,
executor: Executor!
): UrlRequest.Builder!
تنشئ هذه الدالة أداة إنشاء لـ UrlRequest. سيتم استدعاء جميع عمليات الرجوع الخاصة بعناصر UrlRequest التي تم إنشاؤها في سلاسل محادثات executor. يجب ألا تنفّذ executor مهامًا على سلسلة التعليمات التي تستدعي execute لمنع حظر عمليات إنشاء الشبكات والتسبّب في حدوث استثناءات أثناء الإيقاف النهائي.
| المعلَمات | |
|---|---|
url: String! |
عنوان URL للطلبات التي تم إنشاؤها |
callback: UrlRequest.Callback! |
كائن دالة ردّ النداء الذي يتم استدعاؤه عند وقوع أحداث مختلفة. |
executor: Executor! |
|
openConnection
abstract fun openConnection(url: URL!): URLConnection!
تنشئ هذه السمة اتصالاً جديدًا بالمرجع المحدّد بواسطة URLurl.
ملاحظة: يخضع تنفيذ java.net.HttpURLConnection في Cronet لقيود معيّنة، يمكنك الاطّلاع على createURLStreamHandlerFactory للحصول على التفاصيل.
| المعلَمات | |
|---|---|
url: URL! |
عنوان URL للمورد المطلوب الاتصال به |
| المرتجعات | |
|---|---|
URLConnection! |
مثيل |
| عمليات الطرح | |
|---|---|
java.io.IOException |
إذا حدث خطأ أثناء فتح الاتصال |
removeRequestFinishedListener
fun removeRequestFinishedListener(listener: RequestFinishedInfo.Listener!): Unit
تزيل هذه الطريقة أداة معالجة طلب مكتمل.
| المعلَمات | |
|---|---|
listener: RequestFinishedInfo.Listener! |
المستمع الذي تريد إزالته |
removeRttListener
fun removeRttListener(listener: NetworkQualityRttListener!): Unit
يزيل مستمعًا لأوقات الرحلة ذهابًا وعودة إذا تم تسجيله مسبقًا باستخدام addRttListener. يجب استدعاء هذا الإجراء بعد إضافة NetworkQualityRttListener لإيقاف تلقّي الملاحظات.
| المعلَمات | |
|---|---|
listener: NetworkQualityRttListener! |
المستمع إلى مدة الذهاب والعودة |
removeThroughputListener
fun removeThroughputListener(listener: NetworkQualityThroughputListener!): Unit
يزيل أداة معالجة معدل نقل البيانات. يجب استدعاء هذا الإجراء بعد إضافة NetworkQualityThroughputListener باستخدام addThroughputListener من أجل التوقّف عن تلقّي الملاحظات.
| المعلَمات | |
|---|---|
listener: NetworkQualityThroughputListener! |
تمثّل المستمع إلى معدل النقل. |
الإيقاف النهائي
abstract fun shutdown(): Unit
يوقف CronetEngine إذا لم تكن هناك طلبات نشطة، وإلا سيتم عرض استثناء.
لا يمكن استدعاؤه في سلسلة محادثات الشبكة، وهي السلسلة التي يستدعي فيها Cronet برنامج Executor (وهي تختلف عن السلسلة التي يستدعي فيها برنامج Executor عمليات رد الاتصال). قد يتم الحظر إلى أن يتم تنظيف جميع موارد
CronetEngine.
startNetLogToDisk
fun startNetLogToDisk(dirPath: String!, logAll: Boolean, maxSize: Int): Unit
يبدأ تسجيل NetLog في دليل محدّد بحجم محدود. سيحتوي NetLog على الأحداث التي تم إصدارها من جميع CronetEngine النشطة. تكون أداة NetLog مفيدة لتصحيح الأخطاء. بعد إيقاف التسجيل stopNetLog، ستتم كتابة البيانات في ملف netlog.json في dirPath. في حال انقطاع التسجيل، يمكنك دمج الملفات التي تم العثور عليها في الدليل الفرعي .inprogress يدويًا باستخدام: https://chromium.googlesource.com/chromium/src/+/main/net/tools/stitch_net_log_files.py. يمكن عرض السجلّ باستخدام متصفّح Chrome من خلال الانتقال إلى chrome://net-internals/#import.
| المعلَمات | |
|---|---|
dirPath: String! |
الدليل الذي سيتم فيه إنشاء ملف netlog.json. يجب أن يكون dirPath متوفّرًا. يجب ألا تكون ملفات NetLog متوفّرة في الدليل. في حال التسجيل النشط، سيتم تجاهل هذا الإجراء. |
logAll: Boolean |
|
maxSize: Int |
الحد الأقصى لإجمالي مساحة القرص بالبايت التي يجب أن يستخدمها NetLog قد يتجاوز استخدام مساحة القرص الفعلية هذا الحد قليلاً. |
startNetLogToFile
abstract fun startNetLogToFile(fileName: String!, logAll: Boolean): Unit
يبدأ تسجيل NetLog في ملف. سيحتوي NetLog على الأحداث التي تم إصدارها من جميع CronetEngine النشطة. تكون أداة NetLog مفيدة لتصحيح الأخطاء. يمكن عرض الملف باستخدام متصفّح Chrome من خلال الانتقال إلى chrome://net-internals/#import
| المعلَمات | |
|---|---|
fileName: String! |
مسار الملف الكامل يجب ألا يكون فارغًا. إذا كان الملف موجودًا، سيتم اقتطاعه قبل البدء. في حال التسجيل النشط، سيتم تجاهل هذا الإجراء. |
logAll: Boolean |
|
stopNetLog
abstract fun stopNetLog(): Unit
يوقف تسجيل NetLog ويفرغ الملف إلى القرص. إذا لم تكن هناك جلسة تسجيل قيد التقدّم، سيتم تجاهل هذا الطلب.