CronetEngine.Builder

class CronetEngine.Builder

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

סיכום

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

מחלקת Cronet שמספקת שיטה לטעינת ספריית ה-Native.

ערכים קבועים
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!

מגדירה LibraryLoader שישמש לטעינת ספריית Native.
CronetEngine.Builder!

ההגדרה קובעת את אופן הפעולה של שרת proxy.
CronetEngine.Builder!
CronetEngine.Builder!

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

מגדירה את הספרייה לאחסון קובצי Cookie ולמטמון HTTP.
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 בקידוד DER של ASN.1. למרות שהשיטה לא מחייבת להזין את קוד ה-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 מופעל. ברירת המחדל היא מופעל.

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

פרמטרים
value: Boolean

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

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

enableQuic

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

ההגדרה קובעת אם פרוטוקול QUIC מופעל. ברירת המחדל היא מופעל. אם 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

‫ProxyOptions שישמשו עבור 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!

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

הערה: אל תשתמשו באותה ספריית אחסון עם יותר מ- 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!

מחרוזת סוכן המשתמש שבה רוצים להשתמש לכל הבקשות.
החזרות
CronetEngine.Builder!

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

נכסים מוגנים

mParsedExperimentalOptions

protected val mParsedExperimentalOptions: JSONObject!

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