chrome.vpnProvider

תיאור

שימוש ב-API chrome.vpnProvider כדי להטמיע לקוח VPN.

הרשאות

vpnProvider

זמינות

Chrome 43 ואילך ChromeOS בלבד

Usage

השימוש האופייני ב-vpnProvider הוא:

  • יצירת הגדרות VPN באמצעות השיטה createConfig. הגדרת VPN היא רשומה קבועה שמוצגת למשתמש בממשק משתמש מקורי של ChromeOS. המשתמש יכול לבחור תצורת VPN מתוך רשימה ולהתחבר אליה או להתנתק ממנה.

  • להוסיף מאזינים לאירועים onPlatformMessage, onPacketReceived ו-onConfigRemoved.

  • כשהמשתמש יתחבר לתצורת ה-VPN, onPlatformMessage יתקבל עם ההודעה "connected". אנחנו מתייחסים לפרק הזמן שבין ההודעות "connected" לבין "disconnected" כסשן VPN. בפרק הזמן הזה, אנחנו אומרים שהתוסף שמקבל את ההודעה הוא הבעלים של הסשן של ה-VPN.

  • יוצרים חיבור לשרת ה-VPN ומפעילים את לקוח ה-VPN.

  • מגדירים את הפרמטרים של החיבור באמצעות setParameters.

  • שליחת הודעה למצב החיבור בתור "connected" באמצעות notifyConnectionStateChanged.

  • כשהשלבים שלמעלה יושלמו ללא שגיאות, תיווצר מנהרה וירטואלית לסטאק הרשתות של ChromeOS. ניתן לשלוח מנות IP דרך המנהרה באמצעות sendPacket, וכל המנות שמקורן במכשיר ChromeOS יתקבלו באמצעות האירוע onPacketReceived.

  • כשהמשתמש יתנתק מתצורת ה-VPN, onPlatformMessage יופעל עם ההודעה "disconnected".

  • אם אין יותר צורך בהגדרת ה-VPN, אפשר להשמיד אותה באמצעות destroyConfig.

סוגים

Parameters

תכונות

  • כתובת

    מחרוזת

    כתובת ה-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

    מחרוזת

    שם ההגדרה של ה-VPN.

  • קריאה חוזרת (callback)

    פונקציה אופציונלי

    הפרמטר callback נראה כך: 

    (id: string)=>void

    • id

      מחרוזת

      מזהה ייחודי להגדרה שנוצרה, או undefined במקרה של כשל.

החזרות

  • הבטחה<string>

    Chrome 96 ומעלה

    הבטחות נתמכות רק במניפסט מגרסה V3 ואילך. בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callback).

destroyConfig()

הבטחה 
chrome.vpnProvider.destroyConfig(
  id: string,
  callback?: function,
)

משמיד תצורת VPN שנוצרה על ידי התוסף.

פרמטרים

  • id

    מחרוזת

    מזהה הגדרת ה-VPN שצריך להשמיד.

  • קריאה חוזרת (callback)

    פונקציה אופציונלי

    הפרמטר callback נראה כך: 

    ()=>void

החזרות

  • Promise<void>

    Chrome 96 ומעלה

    הבטחות נתמכות רק במניפסט מגרסה V3 ואילך. בפלטפורמות אחרות צריך להשתמש בקריאות חוזרות (callback).

notifyConnectionStateChanged()

הבטחה 
chrome.vpnProvider.notifyConnectionStateChanged(
  state: VpnConnectionState,
  callback?: function,
)

מודיע לפלטפורמה את מצב הסשן של ה-VPN. הפעולה הזו תצליח רק כאשר הפעלת ה-VPN נמצאת בבעלות התוסף.

פרמטרים

  • המצב של סשן ה-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

      מחרוזת

    • name

      מחרוזת

    • נתונים

      אובייקט

onConfigRemoved

chrome.vpnProvider.onConfigRemoved.addListener(
  callback: function,
)

מופעל כשהפלטפורמה מסירה תצורה שנוצרה על ידי התוסף.

פרמטרים

  • קריאה חוזרת (callback)

    פונקציה

    הפרמטר callback נראה כך: 

    (id: string)=>void

    • id

      מחרוזת

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

onUIEvent

chrome.vpnProvider.onUIEvent.addListener(
  callback: function,
)

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

פרמטרים

  • קריאה חוזרת (callback)

    פונקציה

    הפרמטר callback נראה כך: 

    (event: UIEvent,id?: string)=>void

    • אירוע

      UIEvent

    • id

      מחרוזת אופציונלי