chrome.vpnProvider

תיאור

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

הרשאות

vpnProvider

זמינות

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

מושגים ושימוש

השימוש האופייני ב-chrome.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

    String[]

    רשימה של כתובות IP של שרתי ה-DNS.

  • domainSearch

    string[] אופציונלי

    רשימה של דומיינים לחיפוש. (ברירת מחדל: אין דומיין חיפוש)

  • exclusionList

    String[]

    החרגה של התנועה ברשת מרשימת החסימות של כתובות ה-IP בסימון CIDR. אפשר להשתמש באפשרות הזו כדי לעקוף את תעבורת הנתונים אל שרת ה-VPN וממנו. כשיש הרבה כללים שתואמים ליעד, הכלל עם הקידומת הארוכה ביותר של התאמה ינצח. רשומות שתואמות לאותו בלוק CIDR נחשבות לכפילויות. כפילויות כאלה ברשימה המאוגדת (exclusionList + IncludeList) מבטלות, והרשומה הכפולה המדויקת שתימחק לא מוגדרת.

  • inclusionList

    String[]

    יש לכלול את התנועה ברשת לרשימת הבלוקים של כתובות ה-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 באופן מאולץ, והמשתמש יצטרך להתחבר מחדש באופן ידני. (ברירת מחדל: false)

    הנכס הזה חדש בגרסה 51 של Chrome. היא תיצור חריגה בגרסאות הקודמות. אפשר להשתמש ב-try/catch כדי להפעיל את התכונה באופן מותנה בהתאם לתמיכה בדפדפן.

PlatformMessage

הפלטפורמה משתמשת ב-enum כדי להודיע ללקוח על סטטוס הסשן של ה-VPN.

Enum

"מחובר"
מציין שהגדרת ה-VPN מחוברת.

'מנותק'
מציין שהגדרת ה-VPN התנתקה.

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

"linkDown"
מציין שברירת המחדל של החיבור לרשת הפיזית מושבתת.

"linkUp"
מציין שברירת המחדל של החיבור לרשת הפיזית היא חזרה.

"linkChanged"
מציין שחיבור ברירת המחדל לרשת הפיזית השתנה, למשל. wifi->נייד.

'השעיה'
מציין שמערכת ההפעלה מתכוננת להשעיה, לכן ה-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 חדשות שנשמרות בכמה סשנים של התחברות של המשתמש.

פרמטרים

  • שם

    מחרוזת

    שם הגדרת ה-VPN.

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

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

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

    (id: string) => void

    • id [מזהה]

      מחרוזת

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

החזרות

  • Promise<string>

    Chrome מגרסה 96 ואילך

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

destroyConfig()

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

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

פרמטרים

  • id [מזהה]

    מחרוזת

    מזהה של תצורת ה-VPN שרוצים להשמיד.

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

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

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

    () => void

החזרות

  • הבטחה<Empty>

    Chrome מגרסה 96 ואילך

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

notifyConnectionStateChanged()

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

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

פרמטרים

  • הסמוי הסופי

    VpnConnectionState

    מצב הסשן של לקוח ה-VPN.

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

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

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

    () => void

החזרות

  • הבטחה<Empty>

    Chrome מגרסה 96 ואילך

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

sendPacket()

הבטחה 
chrome.vpnProvider.sendPacket(
  data: ArrayBuffer,
  callback?: function,
)

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

פרמטרים

  • נתונים

    ArrayBuffer

    חבילת ה-IP שתישלח לפלטפורמה.

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

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

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

    () => void

החזרות

  • הבטחה<Empty>

    Chrome מגרסה 96 ואילך

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

setParameters()

הבטחה 
chrome.vpnProvider.setParameters(
  parameters: Parameters,
  callback?: function,
)

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

פרמטרים

  • פרמטרים

    פרמטרים

    הפרמטרים של סשן ה-VPN.

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

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

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

    () => void

החזרות

  • הבטחה<Empty>

    Chrome מגרסה 96 ואילך

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

אירועים

onConfigCreated

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

מופעל כשהפלטפורמה יצרה מערך הגדרות אישיות עבור התוסף.

פרמטרים

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

    פונקציה

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

    (id: string, name: string, data: object) => void

    • id [מזהה]

      מחרוזת

    • שם

      מחרוזת

    • נתונים

      אובייקט

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 [מזהה]

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