CronetEngine.Builder

class CronetEngine.Builder

‫Builder של CronetEngine, שמאפשר הגדרה של CronetEngine בזמן ריצה. אפשרויות ההגדרה מוגדרות ב-builder ואז מתבצעת קריאה ל-build כדי ליצור את CronetEngine.

סיכום

סוגי רכיבים שהוצבו בתוך רכיבים אחרים

הכיתה הזו הוצאה משימוש.

השיטה System.loadLibrary לא הייתה אמינה ב-minSDK <= 23, והשתמשנו בה כדי לספק טוענים חלופיים ואמינים יותר.

ערכים קבועים
const Int

הגדרה להשבתת מטמון HTTP.
const Int

הגדרה להפעלת מטמון בדיסק, כולל נתוני HTTP.
const Int

הגדרה להפעלת מטמון בדיסק, לא כולל נתוני HTTP.
const Int

הגדרה להפעלת מטמון HTTP בזיכרון, כולל נתוני HTTP.

‫constructors ציבוריים
Builder(context: Context!)

בונה אובייקט Builder שמקל על יצירת CronetEngine.

פונקציות ציבוריות
CronetEngine.Builder!
addPublicKeyPins(
    hostName: String!,
    pinsSha256: (Mutable)Set<ByteArray!>!,
    includeSubdomains: Boolean,
    expirationDate: Date!
)

הצמדה של קבוצת מפתחות ציבוריים למארח נתון.
CronetEngine.Builder!
addQuicHint(host: String!, port: Int, alternatePort: Int)

הוספנו רמז לכך ש-host תומך ב-QUIC.
CronetEngine!

בניית CronetEngine באמצעות ההגדרה של ה-builder הזה.
CronetEngine.Builder!

קובעת אם הדחיסה Brotli מופעלת.
CronetEngine.Builder!

ההגדרה הזו קובעת אם הפרוטוקול HTTP/2 מופעל.
CronetEngine.Builder!
enableHttpCache(cacheMode: Int, maxSize: Long)

הפעלה או השבתה של שמירת נתונים במטמון של HTTP ומידע אחר, כמו פרטי שרת QUIC.
CronetEngine.Builder!

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

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

המדיניות הזו קובעת אם פרוטוקול QUIC מופעל.
String!

יוצר מחרוזת User-Agent שכוללת את שם האפליקציה והגרסה שלה, את גרסת ה-build של המערכת, את המודל והמזהה ואת גרסת Cronet.
CronetEngine.Builder!
CronetEngine.Builder!

הגדרת אופן הפעולה של העברת חיבורים.
CronetEngine.Builder!

ההגדרה קובעת את אופן הפעולה של חיפוש שם המארח.
CronetEngine.Builder!
CronetEngine.Builder!

הפונקציה הזו הוצאה משימוש.

השיטה System.loadLibrary לא הייתה אמינה ב-minSDK <= 23, והשתמשנו בה כדי לספק טוענים חלופיים ואמינים יותר.
CronetEngine.Builder!

ההגדרה קובעת את התנהגות ה-proxy.
CronetEngine.Builder!
CronetEngine.Builder!

הגדרה של אופן הפעולה של Cronet כשמשתמשים ב-QUIC.
CronetEngine.Builder!

מגדירה את הספרייה לאחסון מטמון HTTP וקובצי Cookie.
CronetEngine.Builder!

הפונקציה הזו הוצאה משימוש.

בגרסאות מודרניות של Cronet, השיטה הזו לא עושה כלום.
CronetEngine.Builder!
setUserAgent(userAgent: String!)

מחליף את כותרת סוכן המשתמש לכל הבקשות.

נכסים מוגנים
JSONObject!

ייצוג ב-JSON של האפשרויות הניסיוניות.

ערכים קבועים

HTTP_CACHE_DISABLED

const val HTTP_CACHE_DISABLED = 0: Int

הגדרה להשבתת מטמון HTTP. יכול להיות שחלק מהנתונים עדיין יישמרו באופן זמני בזיכרון. הועבר אל enableHttpCache.

HTTP_CACHE_DISK

const val HTTP_CACHE_DISK = 3: Int

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

HTTP_CACHE_DISK_NO_HTTP

const val HTTP_CACHE_DISK_NO_HTTP = 2: Int

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

HTTP_CACHE_IN_MEMORY

const val HTTP_CACHE_IN_MEMORY = 1: Int

הגדרה להפעלת מטמון HTTP בזיכרון, כולל נתוני HTTP. הועבר אל enableHttpCache.

‫constructors ציבוריים

בנאי

Builder(context: Context!)

בונה אובייקט Builder שמקל על יצירת CronetEngine. בהגדרות האישיות שקובעים כברירת מחדל, פרוטוקולים HTTP/2 ו-QUIC מופעלים, אבל מטמון ה-HTTP מושבת.

פרמטרים
context: Context!

‫Android Context, שמשמש את Builder לאחזור הקשר האפליקציה. תישמר הפניה רק להקשר של האפליקציה, כדי למנוע הארכה מיותרת של משך החיים של context.

פונקציות ציבוריות

addPublicKeyPins

fun addPublicKeyPins(
    hostName: String!,
    pinsSha256: (Mutable)Set<ByteArray!>!,
    includeSubdomains: Boolean,
    expirationDate: Date!
): CronetEngine.Builder!

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

אם מפעילים את ה-method הזו כמה פעמים עם אותו שם מארח, ההצמדות שהוגדרו קודם למארח מוחלפות.

מידע נוסף על הצמדת מפתח ציבורי זמין ב-RFC 7469.

פרמטרים
hostName: String!

שם המארח שאליו צריך להצמיד את המפתחות הציבוריים. מארח שמורכב רק מספרות והתו נקודה נחשב לא חוקי.
pinsSha256: (Mutable)Set<ByteArray!>!

קבוצה של סיכות. כל פין הוא גיבוב קריפטוגרפי SHA-256 של ייצוג ASN.1 עם קידוד DER של פרטי המפתח הציבורי של הנושא (SPKI) באישור X.509 של המארח. משתמשים ב-Certificate.getPublicKey() וב-Key.getEncoded() כדי לקבל ייצוג של SPKI בפורמט ASN.1 עם קידוד DER. למרות שהשיטה לא מחייבת להזין את קוד ה-PIN לגיבוי שאפשר להשתמש בו אם איבדתם את השליטה במפתח הפרטי הראשי, מומלץ מאוד להזין אותו.
includeSubdomains: Boolean

מציין אם מדיניות ההצמדה צריכה לחול על תת-דומיינים של hostName.
expirationDate: Date!

מציין את תאריך התפוגה של הפינים.
החזרות
CronetEngine.Builder!

הכלי ליצירת שרשורים כדי להקל על יצירת שרשורים.
הקפצת הודעות שגיאה (throw)
java.lang.NullPointerException

אם אחד מפרמטרי הקלט הוא null.
java.lang.IllegalArgumentException

אם שם המארח שצוין לא תקין או אם pinsSha256 מכיל מערך בייטים שלא מייצג גיבוב (hash) תקין באלגוריתם SHA-256.

addQuicHint

fun addQuicHint(host: String!, port: Int, alternatePort: Int): CronetEngine.Builder!

הוספנו רמז לכך ש-host תומך ב-QUIC. שימו לב: צריך להשתמש ב-enableHttpCache (HTTP_CACHE_DISK) כדי ליהנות מיתרון ההתחברות בין סשנים ללא זמן הקמה (0-RTT).

פרמטרים
host: String!

שם המארח של השרת שתומך ב-QUIC.
port: Int

המארח של השרת שתומך ב-QUIC.
alternatePort: Int

יציאה חלופית לשימוש בפרוטוקול QUIC.
החזרות
CronetEngine.Builder!

הכלי ליצירת שרשורים כדי להקל על יצירת שרשורים.

לבנות גרסת build

fun build(): CronetEngine!

בניית CronetEngine באמצעות ההגדרה של ה-builder הזה.

החזרות
CronetEngine!

נבנה ב-CronetEngine.

enableBrotli

fun enableBrotli(value: Boolean): CronetEngine.Builder!

קובעת אם הדחיסה Brotli מופעלת. אם ההגדרה הזו מופעלת, המערכת תפרסם את Brotli בכותרות הבקשה Accept-Encoding. ברירת המחדל היא השבתה.

פרמטרים
value: Boolean

‫true כדי להפעיל את Brotli, ‏ false כדי להשבית.
החזרות
CronetEngine.Builder!

הכלי ליצירת שרשורים.

enableHttp2

fun enableHttp2(value: Boolean): CronetEngine.Builder!

ההגדרה הזו קובעת אם הפרוטוקול HTTP/2 מופעל. ברירת המחדל היא enabled.

פרמטרים
value: Boolean

‫true כדי להפעיל את HTTP/2, ‏ false כדי להשבית.
החזרות
CronetEngine.Builder!

הכלי ליצירת שרשורים.

enableHttpCache

fun enableHttpCache(cacheMode: Int, maxSize: Long): CronetEngine.Builder!

הפעלה או השבתה של שמירת נתונים במטמון של HTTP ומידע אחר, כמו פרטי שרת QUIC.

פרמטרים
cacheMode: Int

לשלוט במיקום ובסוג של הנתונים שנשמרים במטמון. הערך חייב להיות אחד מהערכים הבאים: HTTP_CACHE_*.
maxSize: Long

הגודל המקסימלי בבייטים שמשמש לשמירת נתונים במטמון (המלצה, יכול להיות שיהיו חריגות מדי פעם).
החזרות
CronetEngine.Builder!

הכלי ליצירת שרשורים.

enableNetworkQualityEstimator

fun enableNetworkQualityEstimator(value: Boolean): CronetEngine.Builder!

ההגדרה הזו מפעילה את כלי ההערכה של איכות הרשת, שאוסף ומדווח על מדידות של זמן הלוך ושוב (RTT) ושל קצב העברת הנתונים במורד הזרם בשכבות שונות של מחסנית הרשת. אחרי שמפעילים את כלי ההערכה, אפשר להוסיף מאזינים של RTT ושל קצב העברת נתונים באמצעות addRttListener ו-addThroughputListener, ולהסיר אותם באמצעות removeRttListener ו-removeThroughputListener. הכלי להערכת נפח הזיכרון והמעבד משתמש בזיכרון ובמעבד רק כשהוא מופעל.

פרמטרים
value: Boolean

‫true כדי להפעיל את כלי ההערכה של איכות הרשת, false כדי להשבית אותו.
החזרות
CronetEngine.Builder!

הכלי ליצירת שרשורים.

enablePublicKeyPinningBypassForLocalTrustAnchors

fun enablePublicKeyPinningBypassForLocalTrustAnchors(value: Boolean): CronetEngine.Builder!

ההגדרה הזו מפעילה או משביתה את העקיפה של הצמדת מפתחות ציבוריים לישויות עוגן אמינות מקומיות. לא מומלץ להשבית את העקיפה של ישויות עוגן אמינות מקומיות, כי היא עלולה למנוע מהאפליקציה לתקשר עם המארחים המוצמדים. לדוגמה, משתמש יכול לשלוח את כלל התנועה דרך שרת proxy עם SSL על ידי שינוי הגדרות לשרת proxy במכשיר והוספת אישור ה-proxy לרשימת ישויות עוגן אמינות מקומיות. אם תשביתו את העקיפה, סביר להניח שהאפליקציה לא תוכל לשלוח תעבורת נתונים למארחים המוצמדים. מידע נוסף זמין במאמר 'איך הצמדת מפתחות פועלת עם פרוקסי ומסננים מקומיים?' בכתובת https://www.chromium.org/Home/chromium-security/security-faq

פרמטרים
value: Boolean

‫true כדי להפעיל את העקיפה, false כדי להשבית אותה.
החזרות
CronetEngine.Builder!

הכלי ליצירת שרשורים.

enableQuic

fun enableQuic(value: Boolean): CronetEngine.Builder!

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

פרמטרים
value: Boolean

‫true כדי להפעיל את QUIC, ‏ false כדי להשבית אותו.
החזרות
CronetEngine.Builder!

הכלי ליצירת שרשורים.

getDefaultUserAgent

fun getDefaultUserAgent(): String!

יוצר מחרוזת User-Agent שכוללת את שם האפליקציה והגרסה שלה, את גרסת ה-build של המערכת, את המודל והמזהה ואת גרסת Cronet.

החזרות
String!

מחרוזת סוכן המשתמש.

setConnectionMigrationOptions

@ConnectionMigrationOptions.Experimental
fun setConnectionMigrationOptions(
    connectionMigrationOptionsBuilder: ConnectionMigrationOptions.Builder!
): CronetEngine.Builder!
עוד באותו הקשר
setConnectionMigrationOptions

setConnectionMigrationOptions

@ConnectionMigrationOptions.Experimental
fun setConnectionMigrationOptions(
    connectionMigrationOptions: ConnectionMigrationOptions!
): CronetEngine.Builder!

הגדרת אופן הפעולה של העברת חיבורים. פרטים נוספים זמינים במסמכי התיעוד של ConnectionMigrationOptions ובמאמרים על השיטות השונות של ConnectionMigrationOptions.Builder.

ההגדרה רלוונטית רק אם האפשרות enableQuic מופעלת.

החזרות
CronetEngine.Builder!

הכלי ליצירת שרשורים כדי להקל על יצירת שרשורים.

setDnsOptions

@DnsOptions.Experimental
fun setDnsOptions(dnsOptions: DnsOptions!): CronetEngine.Builder!

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

ההגדרה רלוונטית רק אם האפשרות enableQuic מופעלת.

החזרות
CronetEngine.Builder!

הכלי ליצירת שרשורים כדי להקל על יצירת שרשורים.

setDnsOptions

@DnsOptions.Experimental
fun setDnsOptions(dnsOptions: DnsOptions.Builder!): CronetEngine.Builder!
עוד באותו הקשר
setDnsOptions

setLibraryLoader

fun setLibraryLoader(loader: CronetEngine.Builder.LibraryLoader!): CronetEngine.Builder!

מגדירה LibraryLoader שישמש לטעינת ספריית Native. אם לא מגדירים את המדיניות, הספרייה תיטען באמצעות loadLibrary.

פרמטרים
loader: CronetEngine.Builder.LibraryLoader!

‫LibraryLoader ישמש לטעינת ספריית Native.
החזרות
CronetEngine.Builder!

הכלי ליצירת שרשורים כדי להקל על יצירת שרשורים.

setProxyOptions

fun setProxyOptions(proxyOptions: ProxyOptions): CronetEngine.Builder!

ההגדרה קובעת את התנהגות ה-proxy. ההגדרה הזו משפיעה בדרכים שונות על הקמת חיבורים, על UrlRequest ועל BidirectionalStream. פרטים נוספים מופיעים במסמכי התיעוד של Proxy.

לא להתבלבל עם הגדרות proxy שהוגדרו על ידי: המשתמש, הגדרות פרופיל ארגוניות או (ברוב המקרים) הגדרות רשת אוטומטיות (למשל, Web Proxy Auto-Discovery Protocol). ההגדרה הזו נקראת בדרך כלל הגדרת proxy של המערכת. אם הוא קיים, בדרך כלל נדרש לכבד את הגדרת הפרוקסי של המערכת כדי לקבל קישוריות מקומית ו/או לאינטרנט. ‫CronetEngine כבר מטפל בהגדרת שרת ה-proxy של המערכת באופן פנימי.

הגדרות proxy שמוגדרות באמצעות ה-API הזה נקראות הגדרות proxy של האפליקציה. ההגדרות של שרת ה-Proxy באפליקציה ושל שרת ה-Proxy במערכת הן נפרדות, והכי חשוב, הן שונות. נכון לעכשיו, הגדרות ה-Proxy של האפליקציה והמערכת הן בלעדיות: אם מציינים את ProxyOptions, הוא מבטל את הגדרת ה-Proxy של המערכת, אם היא קיימת. זה עלול לגרום לבעיות בקישוריות בתרחישים מסוימים שבהם קיימת הגדרת proxy של המערכת. בתרחישים כאלה, יכול להיות שלמשתמשים לא תהיה גישה לאינטרנט, אלא אם ProxyOptions הוגדר עם גיבוי סופי, null. אפשר לעיין בProxyOptionsמאמרי העזרה.

פרמטרים
proxyOptions: ProxyOptions

אפשרויות proxy לשימוש ב-UrlRequest, ב-BiridirectionalStream ובחיבורים שנוצרו על ידי CronetEngine שנוצר על ידי ה-builder הזה.
החזרות
CronetEngine.Builder!

הכלי ליצירת שרשורים כדי להקל על יצירת שרשורים.
הקפצת הודעות שגיאה (throw)
java.lang.UnsupportedOperationException

אם ההטמעה של Cronet שנמצאת בשימוש ישנה מדי ולא תומכת ב-ProxyOptions.

setQuicOptions

@QuicOptions.Experimental
fun setQuicOptions(quicOptionsBuilder: QuicOptions.Builder!): CronetEngine.Builder!
עוד באותו הקשר
setQuicOptions

setQuicOptions

@QuicOptions.Experimental
fun setQuicOptions(quicOptions: QuicOptions!): CronetEngine.Builder!

הגדרה של אופן הפעולה של Cronet כשמשתמשים ב-QUIC. פרטים נוספים זמינים במסמכי התיעוד של QuicOptions ובמאמרים על השיטות השונות של QuicOptions.Builder.

ההגדרה רלוונטית רק אם האפשרות enableQuic מופעלת.

החזרות
CronetEngine.Builder!

הכלי ליצירת שרשורים כדי להקל על יצירת שרשורים.

setStoragePath

fun setStoragePath(value: String!): CronetEngine.Builder!

מגדירה את הספרייה לאחסון מטמון HTTP וקובצי Cookie. הספרייה חייבת להתקיים.

הערה: אל תשתמשו באותה תיקיית אחסון עם יותר מ- CronetEngine אחד בכל פעם. הגישה לספריית האחסון לא תומכת בגישה בו-זמנית של כמה CronetEngine.

פרמטרים
value: String!

נתיב לספרייה קיימת.
החזרות
CronetEngine.Builder!

הכלי ליצירת שרשורים.

setThreadPriority

fun setThreadPriority(priority: Int): CronetEngine.Builder!

ההגדרה קובעת את העדיפות של השרשור הפנימי של Cronet.

פרמטרים
priority: Int

העדיפות של השרשור הפנימי של Cronet. רמת עדיפות ב-Linux, מ-‎-20 לעדיפות התזמון הגבוהה ביותר ועד 19 לעדיפות התזמון הנמוכה ביותר. מידע נוסף על ערכים זמין במאמרים בנושא ערכי setThreadPriority וערכי THREAD_PRIORITY_*.
החזרות
CronetEngine.Builder!

הכלי ליצירת שרשורים.

setUserAgent

fun setUserAgent(userAgent: String!): CronetEngine.Builder!

מחליף את כותרת סוכן המשתמש לכל הבקשות. כותרת User-Agent שהוגדרה באופן מפורש (הוגדרה באמצעות addHeader) תבטל ערך שהוגדר באמצעות הפונקציה הזו.

פרמטרים
userAgent: String!

מחרוזת User-Agent לשימוש בכל הבקשות.
החזרות
CronetEngine.Builder!

הכלי ליצירת שרשורים כדי להקל על יצירת שרשורים.

נכסים מוגנים

mParsedExperimentalOptions

protected val mParsedExperimentalOptions: JSONObject!

ייצוג ב-JSON של האפשרויות הניסיוניות.