CronetEngine

public abstract class CronetEngine

فئات فرعية مباشرة معروفة
فئات فرعية غير مباشرة معروفة
JavaCronetEngine

تمت إضافة java.net.HttpURLConnection إلى CronetEngine.

محرك لمعالجة UrlRequest، ويستخدم أفضل حزمة HTTP متاحة على النظام الأساسي الحالي يمكن إنشاء مثيل لهذه الفئة باستخدام Builder.

ملخّص

الأنواع المتداخلة

أداة إنشاء CronetEngine تتيح ضبط CronetEngine في وقت التشغيل.

فئة توفّر طريقة لتحميل مكتبة مجمّعة من رموز برمجية أصلية لـ Cronet.

الثوابت
static final int

قيمة عدد الطلبات النشطة غير معروفة
static final int

قيمة مقياس الاتصال غير معروفة.
static final int

تقدير نوع الاتصال الفعّال هو 2G.
static final int

تقدير نوع الاتصال الفعّال هو 3G.
static final int

تقدير نوع الاتصال الفعّال هو 4G.
static final int

الجهاز غير متّصل بالإنترنت.
static final int

تقدير نوع الاتصال الفعّال هو شبكة الجيل الثاني البطيئة.
static final int

تقدير نوع الاتصال الفعّال غير معروف.
static final long

القيمة التي سيتم استخدامها للتراجع عن أي ربط سابق بالشبكة

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

الإجراءات العامة
void

تسجّل هذه السمة معالجًا يتم استدعاؤه بعد انتهاء كل طلب مع معلومات الطلب.
void

تسجّل هذه الطريقة أداة معالجة يتم استدعاؤها عندما يرصد مقدّر جودة الشبكة وقت نقل البيانات ذهابًا وإيابًا.
void

تسجّل هذه الطريقة أداة معالجة يتم استدعاؤها عندما يشهد مقدّر جودة الشبكة قياسًا لسرعة معالجة البيانات.
void
bindToNetwork(long networkHandle)

يربط المحرّك بمقبض الشبكة المحدّد.
void
configureNetworkQualityEstimatorForTesting(
    boolean useLocalHostRequests,
    boolean useSmallerResponses,
    boolean disableOfflineCheck
)

تضبط هذه السمة أداة تقدير جودة الشبكة لأغراض الاختبار.
abstract URLStreamHandlerFactory

إنشاء URLStreamHandlerFactory للتعامل مع زيارات HTTP وHTTPS
int

تعرض هذه السمة عدد الطلبات النشطة.
int

تعرض هذه السمة تقديرًا لمعدّل نقل البيانات في اتجاه التنزيل (بالكيلوبت في الثانية) الذي يحسبه مقدّر جودة الشبكة.
int

تعرض هذه السمة تقديرًا لنوع الاتصال الفعّال الذي يتم احتسابه بواسطة أداة تقدير جودة الشبكة.
abstract byte[]

تم إيقاف هذا الإجراء نهائيًا.

في الإصدارات الحديثة من Cronet، سيؤدي ذلك دائمًا إلى عرض مصفوفة فارغة.
int

تعرض هذه السمة تقديرًا لوقت الاستجابة الكامل (RTT) لبروتوكول HTTP (بالمللي ثانية) الذي تم احتسابه بواسطة أداة تقدير جودة الشبكة.
int

تعرض هذه السمة تقديرًا لوقت الاستجابة الكامل للنقل (بالمللي ثانية) الذي يتم احتسابه بواسطة أداة تقدير جودة الشبكة.
abstract String
abstract UrlRequest.Builder
newUrlRequestBuilder(
    String url,
    UrlRequest.Callback callback,
    Executor executor
)

تنشئ هذه الدالة أداة إنشاء لـ UrlRequest.
abstract URLConnection

تنشئ هذه السمة اتصالاً جديدًا بالمرجع المحدّد بواسطة URLurl.
void

تزيل هذه الطريقة أداة معالجة طلب مكتمل.
void

يزيل مستمعًا لأوقات الرحلة ذهابًا وعودة إذا تم تسجيله مسبقًا باستخدام addRttListener.
void

يزيل أداة معالجة معدل نقل البيانات.
abstract void

يوقف CronetEngine إذا لم تكن هناك طلبات نشطة، وإلا سيتم عرض استثناء.
void
startNetLogToDisk(String dirPath, boolean logAll, int maxSize)

يبدأ تسجيل NetLog في دليل محدّد بحجم محدود.
abstract void
startNetLogToFile(String fileName, boolean logAll)

يبدأ تسجيل NetLog في ملف.
abstract void

يوقف تسجيل NetLog ويفرغ الملف إلى القرص.

الثوابت

ACTIVE_REQUEST_COUNT_UNKNOWN

public static final int ACTIVE_REQUEST_COUNT_UNKNOWN = -1

قيمة عدد الطلبات النشطة غير معروفة

CONNECTION_METRIC_UNKNOWN

public static final int CONNECTION_METRIC_UNKNOWN = -1

قيمة مقياس الاتصال غير معروفة.

EFFECTIVE_CONNECTION_TYPE_2G

public static final int EFFECTIVE_CONNECTION_TYPE_2G = 3

تقدير نوع الاتصال الفعّال هو 2G.

انظر أيضًا
getEffectiveConnectionType

EFFECTIVE_CONNECTION_TYPE_3G

public static final int EFFECTIVE_CONNECTION_TYPE_3G = 4

تقدير نوع الاتصال الفعّال هو 3G.

انظر أيضًا
getEffectiveConnectionType

EFFECTIVE_CONNECTION_TYPE_4G

public static final int EFFECTIVE_CONNECTION_TYPE_4G = 5

تقدير نوع الاتصال الفعّال هو 4G.

انظر أيضًا
getEffectiveConnectionType

EFFECTIVE_CONNECTION_TYPE_OFFLINE

public static final int EFFECTIVE_CONNECTION_TYPE_OFFLINE = 1

الجهاز غير متّصل بالإنترنت.

انظر أيضًا
getEffectiveConnectionType

EFFECTIVE_CONNECTION_TYPE_SLOW_2G

public static final int EFFECTIVE_CONNECTION_TYPE_SLOW_2G = 2

تقدير نوع الاتصال الفعّال هو شبكة الجيل الثاني البطيئة.

انظر أيضًا
getEffectiveConnectionType

EFFECTIVE_CONNECTION_TYPE_UNKNOWN

public static final int EFFECTIVE_CONNECTION_TYPE_UNKNOWN = 0

تقدير نوع الاتصال الفعّال غير معروف.

انظر أيضًا
getEffectiveConnectionType

UNBIND_NETWORK_HANDLE

public static final long UNBIND_NETWORK_HANDLE = -1

القيمة التي سيتم استخدامها للتراجع عن أي ربط سابق بالشبكة

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

CronetEngine

public CronetEngine()

الإجراءات العامة

addRequestFinishedListener

public void addRequestFinishedListener(RequestFinishedInfo.Listener listener)

تسجّل هذه السمة معالجًا يتم استدعاؤه بعد انتهاء كل طلب مع معلومات الطلب.

يتم الاتصال بالمستمع على java.util.concurrent.Executor يقدّمه المستمع.

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

المستمع للطلبات المكتملة

addRttListener

public void addRttListener(NetworkQualityRttListener listener)

تسجّل هذه الطريقة أداة معالجة يتم استدعاؤها عندما يرصد مقدّر جودة الشبكة وقت نقل البيانات ذهابًا وإيابًا. يجب استدعاء هذه الدالة بعد enableNetworkQualityEstimator، وإلا سيتم طرح استثناء. يمكن تسجيل أوقات الذهاب والعودة في طبقات مختلفة من حزمة الشبكة، بما في ذلك TCP وQUIC وفي طبقة طلب عنوان URL. يتم استدعاء المستمع على java.util.concurrent.Executor الذي يتم تمريره إلى enableNetworkQualityEstimator.

المعلَمات
NetworkQualityRttListener listener

المستمع إلى مدة الذهاب والعودة

addThroughputListener

public void addThroughputListener(NetworkQualityThroughputListener listener)

تسجّل هذه الطريقة أداة معالجة يتم استدعاؤها عندما يشهد مقدّر جودة الشبكة قياسًا لسرعة معالجة البيانات. يجب استدعاء هذه الطريقة بعد enableNetworkQualityEstimator. يتم احتساب ملاحظات سرعة معالجة البيانات من خلال قياس عدد وحدات البايت التي تمّت قراءتها عبر واجهة الشبكة النشطة في الأوقات التي يتم فيها تلقّي ردّ واحد على الأقل من عنوان URL. يتم استدعاء المستمع على java.util.concurrent.Executor الذي يتم تمريره إلى enableNetworkQualityEstimator.

المعلَمات
NetworkQualityThroughputListener listener

تمثّل المستمع إلى معدل النقل.

bindToNetwork

public void bindToNetwork(long networkHandle)

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

المعلَمات
long networkHandle

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

configureNetworkQualityEstimatorForTesting

public void configureNetworkQualityEstimatorForTesting(
    boolean useLocalHostRequests,
    boolean useSmallerResponses,
    boolean disableOfflineCheck
)

تضبط هذه السمة أداة تقدير جودة الشبكة لأغراض الاختبار. يجب استدعاء هذه الدالة قبل إضافة أدوات معالجة وقت نقل البيانات ذهابًا وإيابًا وسرعة معالجة البيانات، وبعد تفعيل أداة تقدير جودة الشبكة.

المعلَمات
boolean useLocalHostRequests

تضمين الطلبات المقدَّمة إلى المضيف المحلي في التقديرات
boolean useSmallerResponses

تضمين الردود الصغيرة في تقديرات معدل النقل
boolean disableOfflineCheck

عند ضبطها على "صحيح"، يتم إيقاف عمليات التحقّق من حالة الجهاز غير المتصل بالإنترنت عند احتساب نوع الاتصال الفعّال أو عند كتابة الإعدادات المفضّلة.

createURLStreamHandlerFactory

public abstract URLStreamHandlerFactory createURLStreamHandlerFactory()

إنشاء URLStreamHandlerFactory للتعامل مع زيارات HTTP وHTTPS يمكن تثبيت مثيل من هذه الفئة من خلال setURLStreamHandlerFactory، وبالتالي استخدام CronetEngine تلقائيًا لجميع الطلبات التي يتم إنشاؤها من خلال openConnection.

لا تستخدم Cronet ميزات HTTP معيّنة يتم توفيرها من خلال النظام:

  • ذاكرة التخزين المؤقت عبر HTTP المثبَّتة من خلال HttpResponseCache.install()
  • طريقة مصادقة HTTP المثبَّتة من خلال setDefault
  • مساحة تخزين ملفات تعريف ارتباط HTTP التي تم تثبيتها من خلال setDefault

مع أنّ Cronet يتيح الطلبات باستخدام بروتوكول HTTPS ويشجّع على ذلك، لا يتيح Cronet استخدام واجهة برمجة التطبيقات HttpsURLConnection. يشمل عدم التوافق أيضًا عدم استخدام بعض ميزات HTTPS التي يوفّرها النظام:

المرتجعات
URLStreamHandlerFactory

مثيل URLStreamHandlerFactory تم تنفيذه بواسطة CronetEngine هذا

getActiveRequestCount

public int getActiveRequestCount()

تعرض هذه السمة عدد الطلبات النشطة.

يصبح الطلب "نشطًا" في UrlRequest.start()، على افتراض أنّ هذه الطريقة لا تعرض استثناءً. يصبح غير نشط عندما يتم عرض جميع عمليات معاودة الاتصال ولا يمكن بدء أي عمليات معاودة اتصال إضافية في المستقبل. يعني ذلك عمليًا أنّ الطلب يصبح غير نشط بعد أن تعرض الدالة onSucceeded/onCanceled/onFailed القيمة، وبعد أن تعرض جميع أدوات معالجة الطلبات المكتملة القيمة. دورة حياة طلبات Cronet لمزيد من المعلومات

getDownstreamThroughputKbps

public int getDownstreamThroughputKbps()

تعرض هذه السمة تقديرًا لمعدّل نقل البيانات في اتجاه التنزيل (بالكيلوبت في الثانية) الذي يحسبه مقدّر جودة الشبكة. اضبط القيمة على CONNECTION_METRIC_UNKNOWN إذا كانت غير متاحة. يجب استدعاء هذه الدالة بعد enableNetworkQualityEstimator، وإلا سيتم طرح استثناء.

المرتجعات
int

تقدير لمعدل نقل البيانات في اتجاه التنزيل بالكيلوبت في الثانية

getEffectiveConnectionType

public int getEffectiveConnectionType()

تعرض هذه السمة تقديرًا لنوع الاتصال الفعّال الذي يتم احتسابه بواسطة أداة تقدير جودة الشبكة. استدعِ الدالة enableNetworkQualityEstimator لبدء احتساب هذه القيمة.

المرتجعات
int

تمثّل هذه السمة نوع الاتصال المقدَّر. القيمة المعروضة هي إحدى القيم EFFECTIVE_CONNECTION_TYPE_* .

getGlobalMetricsDeltas

public abstract byte[] getGlobalMetricsDeltas()

getHttpRttMs

public int getHttpRttMs()

تعرض هذه السمة تقديرًا لوقت الاستجابة الكامل (RTT) لبروتوكول HTTP (بالمللي ثانية) الذي تم احتسابه بواسطة أداة تقدير جودة الشبكة. اضبط القيمة على CONNECTION_METRIC_UNKNOWN إذا كانت غير متاحة. يجب استدعاء هذه الدالة بعد enableNetworkQualityEstimator، وإلا سيتم طرح استثناء.

المرتجعات
int

تقدير لوقت الاستجابة الكامل لبروتوكول HTTP بالمللي ثانية

getTransportRttMs

public int getTransportRttMs()

تعرض هذه السمة تقديرًا لوقت الاستجابة الكامل للنقل (بالمللي ثانية) الذي يتم احتسابه بواسطة أداة تقدير جودة الشبكة. اضبط القيمة على CONNECTION_METRIC_UNKNOWN إذا كانت غير متاحة. يجب استدعاء هذه الدالة بعد enableNetworkQualityEstimator، وإلا سيتم طرح استثناء.

المرتجعات
int

تقدير لمدّة ذهاب وعودة النقل بالمللي ثانية

getVersionString

public abstract String getVersionString()
المرتجعات
String

سلسلة إصدار المحرك يمكن للمستخدمين قراءتها

newUrlRequestBuilder

public abstract UrlRequest.Builder newUrlRequestBuilder(
    String url,
    UrlRequest.Callback callback,
    Executor executor
)

تنشئ هذه الدالة أداة إنشاء لـ UrlRequest. سيتم استدعاء جميع عمليات الرجوع الخاصة بعناصر UrlRequest التي تم إنشاؤها في سلاسل محادثات executor. يجب ألا تنفّذ executor مهامًا على سلسلة التعليمات التي تستدعي execute لمنع حظر عمليات إنشاء الشبكات والتسبّب في حدوث استثناءات أثناء الإيقاف النهائي.

المعلَمات
String url

عنوان URL للطلبات التي تم إنشاؤها
UrlRequest.Callback callback

كائن دالة ردّ النداء الذي يتم استدعاؤه عند وقوع أحداث مختلفة.
Executor executor

Executor التي سيتم استدعاء جميع عمليات معاودة الاتصال عليها.

openConnection

public abstract URLConnection openConnection(URL url)

تنشئ هذه السمة اتصالاً جديدًا بالمرجع المحدّد بواسطة URLurl.

ملاحظة: يخضع تنفيذ java.net.HttpURLConnection في Cronet لقيود معيّنة، يمكنك الاطّلاع على createURLStreamHandlerFactory للحصول على التفاصيل.

المعلَمات
URL url

عنوان URL للمورد المطلوب الاتصال به
المرتجعات
URLConnection

مثيل java.net.HttpURLConnection تم تنفيذه بواسطة CronetEngine هذا
عمليات الطرح
java.io.IOException

إذا حدث خطأ أثناء فتح الاتصال

removeRequestFinishedListener

public void removeRequestFinishedListener(RequestFinishedInfo.Listener listener)

تزيل هذه الطريقة أداة معالجة طلب مكتمل.

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

المستمع الذي تريد إزالته

removeRttListener

public void removeRttListener(NetworkQualityRttListener listener)

يزيل مستمعًا لأوقات الرحلة ذهابًا وعودة إذا تم تسجيله مسبقًا باستخدام addRttListener. يجب استدعاء هذا الإجراء بعد إضافة NetworkQualityRttListener لإيقاف تلقّي الملاحظات.

المعلَمات
NetworkQualityRttListener listener

المستمع إلى مدة الذهاب والعودة

removeThroughputListener

public void removeThroughputListener(NetworkQualityThroughputListener listener)

يزيل أداة معالجة معدل نقل البيانات. يجب استدعاء هذا الإجراء بعد إضافة NetworkQualityThroughputListener باستخدام addThroughputListener من أجل التوقّف عن تلقّي الملاحظات.

المعلَمات
NetworkQualityThroughputListener listener

تمثّل المستمع إلى معدل النقل.

الإيقاف النهائي

public abstract void shutdown()

يوقف CronetEngine إذا لم تكن هناك طلبات نشطة، وإلا سيتم عرض استثناء.

لا يمكن استدعاؤه في سلسلة محادثات الشبكة، وهي السلسلة التي يستدعي فيها Cronet برنامج Executor (وهي تختلف عن السلسلة التي يستدعي فيها برنامج Executor عمليات رد الاتصال). قد يتم الحظر إلى أن يتم تنظيف جميع موارد CronetEngine.

startNetLogToDisk

public void startNetLogToDisk(String dirPath, boolean logAll, int maxSize)

يبدأ تسجيل 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.

المعلَمات
String dirPath

الدليل الذي سيتم فيه إنشاء ملف netlog.json. يجب أن يكون dirPath متوفّرًا. يجب ألا تكون ملفات NetLog متوفّرة في الدليل. في حال التسجيل النشط، سيتم تجاهل هذا الإجراء.
boolean logAll

true لتضمين الأحداث الأساسية وملفات تعريف الارتباط الخاصة بالمستخدم وبيانات الاعتماد وجميع وحدات البايت المنقولة في السجلّ. يمثّل هذا الخيار خطرًا على الخصوصية، لأنّه يعرّض بيانات اعتماد المستخدم، ويجب استخدامه فقط بموافقة المستخدم وفي الحالات التي لن يكون فيها السجلّ متاحًا للجميع. false لتضمين الأحداث الأساسية فقط.
int maxSize

الحد الأقصى لإجمالي مساحة القرص بالبايت التي يجب أن يستخدمها NetLog قد يتجاوز استخدام مساحة القرص الفعلية هذا الحد قليلاً.

startNetLogToFile

public abstract void startNetLogToFile(String fileName, boolean logAll)

يبدأ تسجيل NetLog في ملف. سيحتوي NetLog على الأحداث التي تم إصدارها من جميع CronetEngine النشطة. تكون أداة NetLog مفيدة لتصحيح الأخطاء. يمكن عرض الملف باستخدام متصفّح Chrome من خلال الانتقال إلى chrome://net-internals/#import

المعلَمات
String fileName

مسار الملف الكامل يجب ألا يكون فارغًا. إذا كان الملف موجودًا، سيتم اقتطاعه قبل البدء. في حال التسجيل النشط، سيتم تجاهل هذا الإجراء.
boolean logAll

true لتضمين الأحداث الأساسية وملفات تعريف الارتباط الخاصة بالمستخدم وبيانات الاعتماد وجميع وحدات البايت المنقولة في السجلّ. يمثّل هذا الخيار خطرًا على الخصوصية، لأنّه يعرّض بيانات اعتماد المستخدم، ويجب استخدامه فقط بموافقة المستخدم وفي الحالات التي لن يكون فيها السجلّ متاحًا للجميع. false لتضمين الأحداث الأساسية فقط.

stopNetLog

public abstract void stopNetLog()

يوقف تسجيل NetLog ويفرغ الملف إلى القرص. إذا لم تكن هناك جلسة تسجيل قيد التقدّم، سيتم تجاهل هذا الطلب.