תיאור
שימוש ב-API chrome.vpnProvider
כדי להטמיע לקוח VPN.
הרשאות
vpnProvider
זמינות
מושגים ושימוש
השימוש האופייני ב-chrome.vpnProvider
הוא:
מתקשרים אל
createConfig()
כדי ליצור הגדרות VPN. הגדרת VPN היא רשומה קבועה שמוצגת למשתמש בממשק משתמש של ChromeOS. המשתמש יכול לבחור תצורת VPN מתוך רשימה ולהתחבר אליה או להתנתק ממנה.להוסיף מאזינים לאירועים
onPlatformMessage
,onPacketReceived
ו-onConfigRemoved
.כשהמשתמש יתחבר לתצורת ה-VPN,
onPlatformMessage
יתקבל עם ההודעה"connected"
. פרק הזמן שבין ההודעה"connected"
להודעה"disconnected"
נקרא "סשן VPN". בפרק הזמן הזה, אנחנו אומרים שהתוסף שמקבל את ההודעה הוא הבעלים של הסשן של ה-VPN.יוצרים חיבור לשרת ה-VPN ומפעילים את לקוח ה-VPN.
מגדירים את הפרמטרים של החיבור על ידי קריאה לפונקציה
setParameters()
.מודיעים למצב החיבור בתור
"connected"
על ידי חיוג אלnotifyConnectionStateChanged()
.אחרי שמשלימים את השלבים הקודמים בלי שגיאות, נוצרת מנהרה וירטואלית לסטאק הרשתות של ChromeOS. ניתן לשלוח מנות IP דרך המנהרה על ידי קריאה ל-
sendPacket()
. כל המנות שמקורן במכשיר ChromeOS יתקבלו באמצעות ה-handler של האירועיםonPacketReceived
.כשהמשתמש יתנתק מתצורת ה-VPN,
onPlatformMessage
יופעל עם ההודעה"disconnected"
.אם אין יותר צורך בהגדרת ה-VPN, אפשר להשמיד אותה באמצעות קריאה ל-
destroyConfig()
.
סוגים
Parameters
תכונות
-
כתובת
string
כתובת ה-IP של ממשק ה-VPN בסימון CIDR. בשלב זה, IPv4 הוא המצב היחיד שנתמך.
-
broadcastAddress
מחרוזת אופציונלי
כתובת השידור של ממשק ה-VPN. (ברירת מחדל: נגזר מכתובת IP וממסכה)
-
dnsServers
מחרוזת[]
רשימה של כתובות IP עבור שרתי ה-DNS.
-
domainSearch
string[] אופציונלי
רשימת דומיינים לחיפוש. (ברירת מחדל: אין דומיין חיפוש)
-
exclusionList
מחרוזת[]
החרגת תנועת הרשת מרשימת החסימות של כתובות ה-IP בסימון CIDR מהמנהרה. ניתן להשתמש באפשרות הזו כדי לעקוף תעבורת נתונים אל שרת ה-VPN וממנו. אם יש כללים רבים שתואמים ליעד, הכלל עם הקידומת הארוכה ביותר זוכה. רשומות שתואמות לאותו בלוק CIDR נחשבות לכפילויות. כפילויות כאלה ברשימה המקושרת (exclusionList + IncludeList) מוסרות, והערך הכפול המדויק שיוסר לא מוגדר.
-
inclusionList
מחרוזת[]
הכללה של תעבורת הנתונים ברשת לרשימת החסימות של כתובות ה-IP בסימון CIDR למנהרה. ניתן להשתמש בפרמטר הזה כדי להגדיר מנהרה מפוצלת. כברירת מחדל, אין הפניית תנועה אל המנהרה. הוספת הרשומה "0.0.0.0/0" לרשימה הזו תפנה את כל תנועת המשתמשים למנהרה. אם יש כללים רבים שתואמים ליעד, הכלל עם הקידומת הארוכה ביותר זוכה. רשומות שתואמות לאותו בלוק CIDR נחשבות לכפילויות. כפילויות כאלה ברשימה המקושרת (exclusionList + IncludeList) מוסרות, והערך הכפול המדויק שיוסר לא מוגדר.
-
mtu
מחרוזת אופציונלי
הגדרת MTU לממשק ה-VPN. (ברירת מחדל: 1,500 בייטים)
-
להתחבר מחדש
מחרוזת אופציונלי
Chrome 51 ומעלההאם תוסף ה-VPN מטמיע חיבור מחדש באופן אוטומטי.
אם הערך הוא True, ההודעות
linkDown
,linkUp
,linkChanged
,suspend
ו-resume
בפלטפורמה ישמשו לאות האירועים המתאימים. אם הטופולוגיה של הרשת תשתנה, המערכת תנתק את ה-VPN בכוח, והמשתמש יצטרך להתחבר מחדש באופן ידני. (ברירת מחדל: לא נכון)המאפיין הזה חדש בגרסה 51 של Chrome. הוא יצור חריג בגרסאות קודמות. אפשר להשתמש ב-example/catch כדי להפעיל את התכונה באופן מותנה, בהתאם לתמיכה בדפדפן.
PlatformMessage
הפלטפורמה משתמשת ב-enum כדי לעדכן את הלקוח לגבי סטטוס הסשן של ה-VPN.
טיפוסים בני מנייה (enum)
"מחובר"
מציין שתצורת ה-VPN מחוברת.
"מנותק"
מציין שתצורת ה-VPN מנותקת.
"שגיאה"
מציין שאירעה שגיאה בחיבור ל-VPN. למשל, זמן קצוב לתפוגה. תיאור של השגיאה מוצג כארגומנט של שגיאה ב-onPlatformMessage.
"linkDown"
מציין שחיבור הרשת הפיזית שמוגדר כברירת מחדל מושבת.
"linkUp"
מציין שחיבור הרשת הפיזית שמוגדר כברירת מחדל הוא גיבוי.
"linkChanged"
מציין שחיבור הרשת הפיזי שמוגדר כברירת מחדל השתנה, למשל: wifi->נייד.
"suspend"
סימן שמערכת ההפעלה מתכוננת להשעיה, לכן החיבור ל-VPN אמור להתנתק. לא בטוח שהתוסף יקבל את האירוע הזה לפני ההשעיה.
"resume"
מציין שמערכת ההפעלה פעלה מחדש והמשתמש התחבר שוב, לכן ה-VPN צריך לנסות להתחבר מחדש.
UIEvent
הפלטפורמה משתמשת ב-enum כדי לציין את האירוע שהפעיל את onUIEvent
.
טיפוסים בני מנייה (enum)
"showAddDialog"
בקשה להצגת תיבת הדו-שיח להוספת הגדרה אישית ללקוח ה-VPN
"showConfigureDialog"
בקשה שלקוח ה-VPN יציג למשתמש את תיבת הדו-שיח של הגדרות התצורה.
VpnConnectionState
לקוח ה-VPN משתמש ב-enum כדי לעדכן את הפלטפורמה לגבי המצב הנוכחי שלה. כך אפשר להעביר למשתמשים מסרים משמעותיים.
טיפוסים בני מנייה (enum)
'מחובר'
מציין שחיבור ה-VPN בוצע בהצלחה.
'failure'
מציין שחיבור ה-VPN נכשל.
שיטות
createConfig()
chrome.vpnProvider.createConfig(
name: string,
callback?: function,
)
יצירה של הגדרת VPN חדשה שנשארת לאורך סשנים מרובים של התחברות של המשתמש.
פרמטרים
-
name
string
שם ההגדרה של ה-VPN.
-
קריאה חוזרת (callback)
פונקציה אופציונלי
הפרמטר
callback
נראה כך:(id: string) => void
-
id
string
מזהה ייחודי להגדרה שנוצרה, או
undefined
במקרה של כשל.
-
החזרות
-
הבטחה<string>
Chrome 96 ומעלהיש תמיכה בהבטחות במניפסט מגרסה V3 ואילך, אבל אפשר לבצע קריאה חוזרת (callback) לצורך תאימות לאחור. אי אפשר להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה מסתיימת עם אותו הסוג שמועבר לקריאה החוזרת.
destroyConfig()
chrome.vpnProvider.destroyConfig(
id: string,
callback?: function,
)
משמיד תצורת VPN שנוצרה על ידי התוסף.
פרמטרים
-
id
string
מזהה הגדרת ה-VPN שצריך להשמיד.
-
קריאה חוזרת (callback)
פונקציה אופציונלי
הפרמטר
callback
נראה כך:() => void
החזרות
-
Promise<void>
Chrome 96 ומעלהיש תמיכה בהבטחות במניפסט מגרסה V3 ואילך, אבל אפשר לבצע קריאה חוזרת (callback) לצורך תאימות לאחור. אי אפשר להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה מסתיימת עם אותו הסוג שמועבר לקריאה החוזרת.
notifyConnectionStateChanged()
chrome.vpnProvider.notifyConnectionStateChanged(
state: VpnConnectionState,
callback?: function,
)
מודיע לפלטפורמה את מצב הסשן של ה-VPN. הפעולה הזו תצליח רק כאשר הפעלת ה-VPN נמצאת בבעלות התוסף.
פרמטרים
-
state
המצב של סשן ה-VPN של לקוח ה-VPN.
-
קריאה חוזרת (callback)
פונקציה אופציונלי
הפרמטר
callback
נראה כך:() => void
החזרות
-
Promise<void>
Chrome 96 ומעלהיש תמיכה בהבטחות במניפסט מגרסה V3 ואילך, אבל אפשר לבצע קריאה חוזרת (callback) לצורך תאימות לאחור. אי אפשר להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה מסתיימת עם אותו הסוג שמועבר לקריאה החוזרת.
sendPacket()
chrome.vpnProvider.sendPacket(
data: ArrayBuffer,
callback?: function,
)
שולחת חבילת IP דרך המנהרה שנוצרה עבור הפעלת ה-VPN. הפעולה הזו תצליח רק כאשר הפעלת ה-VPN נמצאת בבעלות התוסף.
פרמטרים
-
נתונים
ArrayBuffer
חבילת ה-IP שתישלח לפלטפורמה.
-
קריאה חוזרת (callback)
פונקציה אופציונלי
הפרמטר
callback
נראה כך:() => void
החזרות
-
Promise<void>
Chrome 96 ומעלהיש תמיכה בהבטחות במניפסט מגרסה V3 ואילך, אבל אפשר לבצע קריאה חוזרת (callback) לצורך תאימות לאחור. אי אפשר להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה מסתיימת עם אותו הסוג שמועבר לקריאה החוזרת.
setParameters()
chrome.vpnProvider.setParameters(
parameters: Parameters,
callback?: function,
)
מגדיר את הפרמטרים לסשן ה-VPN. אפשר לקרוא לפונקציה הזו מיד לאחר הקבלה של "connected"
מהפלטפורמה. הפעולה הזו תצליח רק כאשר הפעלת ה-VPN נמצאת בבעלות התוסף.
פרמטרים
-
פרמטרים
הפרמטרים של סשן ה-VPN.
-
קריאה חוזרת (callback)
פונקציה אופציונלי
הפרמטר
callback
נראה כך:() => void
החזרות
-
Promise<void>
Chrome 96 ומעלהיש תמיכה בהבטחות במניפסט מגרסה V3 ואילך, אבל אפשר לבצע קריאה חוזרת (callback) לצורך תאימות לאחור. אי אפשר להשתמש בשתיהן באותה בקשה להפעלת פונקציה. ההבטחה מסתיימת עם אותו הסוג שמועבר לקריאה החוזרת.
אירועים
onConfigCreated
chrome.vpnProvider.onConfigCreated.addListener(
callback: function,
)
מופעל כשהפלטפורמה יוצרת תצורה עבור התוסף.
פרמטרים
-
קריאה חוזרת (callback)
פונקציה
הפרמטר
callback
נראה כך:(id: string, name: string, data: object) => void
-
id
string
-
name
string
-
נתונים
אובייקט
-
onConfigRemoved
chrome.vpnProvider.onConfigRemoved.addListener(
callback: function,
)
מופעל כשהפלטפורמה מסירה תצורה שנוצרה על ידי התוסף.
פרמטרים
-
קריאה חוזרת (callback)
פונקציה
הפרמטר
callback
נראה כך:(id: string) => void
-
id
string
-
onPacketReceived
chrome.vpnProvider.onPacketReceived.addListener(
callback: function,
)
מופעל כשחבילת IP מתקבלת דרך המנהרה בסשן ה-VPN שבבעלות התוסף.
פרמטרים
-
קריאה חוזרת (callback)
פונקציה
הפרמטר
callback
נראה כך:(data: ArrayBuffer) => void
-
נתונים
ArrayBuffer
-
onPlatformMessage
chrome.vpnProvider.onPlatformMessage.addListener(
callback: function,
)
מופעל כאשר מתקבלת הודעה מהפלטפורמה לגבי הגדרת VPN בבעלות התוסף.
פרמטרים
-
קריאה חוזרת (callback)
פונקציה
הפרמטר
callback
נראה כך:(id: string, message: PlatformMessage, error: string) => void
-
id
string
-
הודעה
-
error
string
-
onUIEvent
chrome.vpnProvider.onUIEvent.addListener(
callback: function,
)
מופעל כשיש אירוע בממשק המשתמש של התוסף. אירועים בממשק המשתמש הם אותות מהפלטפורמה, שמציינים לאפליקציה שצריך להציג למשתמש תיבת דו-שיח של ממשק המשתמש.