CronetEngine

const val ACTIVE_REQUEST_COUNT_UNKNOWN = -1: Int

הערך של מספר הבקשות הפעילות לא ידוע

const val CONNECTION_METRIC_UNKNOWN = -1: Int

הערך של מדד החיבור לא ידוע.

const val EFFECTIVE_CONNECTION_TYPE_2G = 3: Int

ההערכה של סוג החיבור בפועל היא 2G.

const val EFFECTIVE_CONNECTION_TYPE_3G = 4: Int

ההערכה של סוג החיבור בפועל היא 3G.

const val EFFECTIVE_CONNECTION_TYPE_4G = 5: Int

ההערכה של סוג החיבור בפועל היא 4G.

const val EFFECTIVE_CONNECTION_TYPE_OFFLINE = 1: Int

המכשיר במצב אופליין.

const val EFFECTIVE_CONNECTION_TYPE_SLOW_2G = 2: Int

ההערכה של סוג החיבור בפועל היא 2G איטי.

const val EFFECTIVE_CONNECTION_TYPE_UNKNOWN = 0: Int

הערכה של סוג החיבור האפקטיבי לא ידועה.

const val UNBIND_NETWORK_HANDLE = -1: Long

הערך שבו יש להשתמש כדי לבטל כל קשירה קודמת לרשת.

fun addRequestFinishedListener(listener: RequestFinishedInfo.Listener!): Unit

רושם מאזין שמופעל אחרי סיום כל בקשה עם פרטי הבקשה.

השיחה למאזין מתבצעת במספר java.util.concurrent.Executor שסופק על ידי המאזין.

fun addRttListener(listener: NetworkQualityRttListener!): Unit

רושמת מאזין שמופעל בכל פעם שהכלי להערכת איכות הרשת מזהה זמן הלוך ושוב לדוגמה. חובה להפעיל את הפונקציה הזו אחרי enableNetworkQualityEstimator, אחרת תופעל חריגה. יכול להיות שזמני הלוך ושוב יתועדו בשכבות שונות של מחסנית הרשת, כולל TCP,‏ QUIC ובשכבת בקשת כתובת ה-URL. המאזין מקבל שיחה ב-java.util.concurrent.Executor שמועבר אל enableNetworkQualityEstimator.

fun addThroughputListener(listener: NetworkQualityThroughputListener!): Unit

רושמת מאזין שמופעל בכל פעם שהמערכת להערכת איכות הרשת מזהה מדידה של קצב העברת נתונים לדוגמה. חובה להפעיל את הפונקציה הזו אחרי enableNetworkQualityEstimator. התפוקה מחושבת על ידי מדידת בייטים שנקראו בממשק הרשת הפעיל בזמנים שבהם מתקבלת תגובה של כתובת URL אחת לפחות. המאזין מקבל שיחה ב-java.util.concurrent.Executor שמועבר אל enableNetworkQualityEstimator.

fun bindToNetwork(networkHandle: Long): Unit

קושר את המנוע לטיפול ברשת שצוין. כל הבקשות שנוצרו דרך המנוע הזה ישתמשו ברשת שמשויכת לכינוי הזה. אם הרשת הזו מתנתקת, כל הבקשות ייכשלו. השגיאה המדויקת תלויה בשלב העיבוד של הבקשה בזמן שהרשת מתנתקת. אפשר לקבל כינויים לרשת דרך Network#getNetworkHandle. התכונה זמינה רק החל מ-Android Marshmallow.

fun configureNetworkQualityEstimatorForTesting(
    useLocalHostRequests: Boolean,
    useSmallerResponses: Boolean,
    disableOfflineCheck: Boolean
): Unit

הגדרת אומדן איכות הרשת לבדיקה. צריך להפעיל את הפונקציה הזו לפני שמוסיפים את מאזיני הזמן הלוך ושוב ואת מאזיני קצב העברת הנתונים, ואחרי שמפעילים את כלי ההערכה של איכות הרשת.

abstract fun createURLStreamHandlerFactory(): URLStreamHandlerFactory!

יוצר URLStreamHandlerFactory לטיפול בתנועת HTTP ו-HTTPS. אפשר להתקין מופע של המחלקה הזו באמצעות setURLStreamHandlerFactory, וכך להשתמש ב-CronetEngine כברירת מחדל לכל הבקשות שנוצרו באמצעות openConnection.

‫Cronet לא משתמש בתכונות מסוימות של HTTP שזמינות דרך המערכת:

• מטמון ה-HTTP שהותקן דרך HttpResponseCache.install()
• שיטת האימות של HTTP שהותקנה דרך setDefault
• אחסון קובצי ה-cookie של HTTP שהותקן דרך setDefault

למרות ש-Cronet תומך בבקשות באמצעות פרוטוקול HTTPS ומעודד שימוש בו, הוא לא תומך ב-API של HttpsURLConnection. היעדר התמיכה כולל גם אי שימוש בתכונות מסוימות של HTTPS שזמינות דרך המערכת:

• הכלי לאימות שם המארח ב-HTTPS שהותקן באמצעות HttpsURLConnection.setDefaultHostnameVerifier()
• ה-HTTPS socket factory שהותקן דרך HttpsURLConnection.setDefaultSSLSocketFactory()

fun getActiveRequestCount(): Int

הפונקציה מחזירה את מספר הבקשות הפעילות.

בקשה הופכת ל'פעילה' ב-UrlRequest.start(), בהנחה שהשיטה הזו לא יוצרת חריגה. היא הופכת ללא פעילה כשכל הקריאות החוזרות (callback) מסתיימות ואי אפשר להפעיל קריאות חוזרות נוספות בעתיד. בפועל, המשמעות היא שהבקשה לא פעילה אחרי שהפונקציה onSucceeded/onCanceled/onFailed מחזירה ערך וכל מאזיני הבקשות סיימו להחזיר ערך. מידע נוסף זמין במאמר מחזור החיים של בקשות Cronet.

fun getDownstreamThroughputKbps(): Int

הפונקציה מחזירה את האומדן של קצב העברת הנתונים (בקילובייט לשנייה) שחושב על ידי כלי ההערכה של איכות הרשת. אם הערך לא זמין, מגדירים את הערך CONNECTION_METRIC_UNKNOWN. חובה להפעיל את הפונקציה הזו אחרי enableNetworkQualityEstimator, אחרת תופעל חריגה.

fun getEffectiveConnectionType(): Int

הפונקציה מחזירה אומדן של סוג החיבור האפקטיבי שחושב על ידי כלי האומדן של איכות הרשת. מתקשרים אל enableNetworkQualityEstimator כדי להתחיל לחשב את הערך הזה.

fun getHttpRttMs(): Int

הפונקציה מחזירה את האומדן של זמן הלוך ושוב (RTT) של HTTP (באלפיות השנייה) שחושב על ידי כלי ההערכה של איכות הרשת. אם הערך לא זמין, מגדירים את הערך CONNECTION_METRIC_UNKNOWN. חובה להפעיל את הפונקציה הזו אחרי enableNetworkQualityEstimator, אחרת תופעל חריגה.

fun getTransportRttMs(): Int

הפונקציה מחזירה את האומדן של זמן הלוך ושוב (RTT) של התעבורה (באלפיות השנייה) שחושב על ידי כלי ההערכה של איכות הרשת. אם הערך לא זמין, מגדירים את הערך CONNECTION_METRIC_UNKNOWN. חובה להפעיל את הפונקציה הזו אחרי enableNetworkQualityEstimator, אחרת תופעל חריגה.

abstract fun newUrlRequestBuilder(
    url: String!,
    callback: UrlRequest.Callback!,
    executor: Executor!
): UrlRequest.Builder!

יוצרת builder של UrlRequest. כל הקריאות החוזרות לאובייקטים שנוצרו ב-UrlRequest יופעלו בשרשורים של executor. אסור לאפליקציית executor להריץ משימות בשרשור שקורא ל-execute כדי למנוע חסימה של פעולות ברשת וגרימה של חריגים במהלך כיבוי.

abstract fun openConnection(url: URL!): URLConnection!

יוצר חיבור חדש למשאב שצוין על ידי URLurl.

הערה: ההטמעה של Cronet‏ java.net.HttpURLConnection כפופה למגבלות מסוימות. פרטים נוספים זמינים במאמר createURLStreamHandlerFactory.

fun removeRequestFinishedListener(listener: RequestFinishedInfo.Listener!): Unit

הסרה של מאזין בקשות שהסתיימו.

fun removeRttListener(listener: NetworkQualityRttListener!): Unit

מסיר מאזין של זמני הלוך ושוב אם הוא נרשם קודם באמצעות addRttListener. צריך להפעיל את הפונקציה הזו אחרי שמוסיפים NetworkQualityRttListener כדי להפסיק לקבל תצפיות.

fun removeThroughputListener(listener: NetworkQualityThroughputListener!): Unit

מסירה מאזין של קצב העברת הנתונים. צריך להפעיל את הפונקציה הזו אחרי שמוסיפים NetworkQualityThroughputListener באמצעות addThroughputListener כדי להפסיק לקבל תצפיות.

abstract fun shutdown(): Unit

הפונקציה משביתה את CronetEngine אם אין בקשות פעילות, אחרת היא מחזירה חריגה.

אי אפשר לקרוא לשיטה הזו בשרשור של הרשת – השרשור ש-Cronet קורא ל-Executor (ששונה מהשרשור שבו Executor מפעיל קריאות חוזרות). יכול להיות שהפונקציה תיחסם עד שכל המשאבים של CronetEngine ינוקו.

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.

abstract fun startNetLogToFile(fileName: String!, logAll: Boolean): Unit

מתחיל רישום ביומן NetLog לקובץ. הקובץ NetLog יכיל אירועים שנשלחו מכל מנועי CronetEngine הפעילים. ה-NetLog שימושי לניפוי באגים. אפשר לצפות בקובץ באמצעות דפדפן Chrome, על ידי מעבר אל chrome://net-internals/#import

abstract fun stopNetLog(): Unit

מפסיקה את הרישום ביומן NetLog ומרוקנת את הקובץ לדיסק. אם סשן הרישום ביומן לא מתבצע, המערכת מתעלמת מהקריאה הזו.