chrome.vpnProvider

תיאור

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

הרשאות

vpnProvider

זמינות

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

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

שימוש אופייני ב-chrome.vpnProvider:

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

  • מוסיפים פונקציות מסוג Event Listener לאירועים 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

מאפיינים

  • כתובת

    מחרוזת

    כתובת ה-IP של ממשק ה-VPN בסימון CIDR. בשלב הזה, רק מצב IPv4 נתמך.

  • broadcastAddress

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

    כתובת השידור של ממשק ה-VPN. (ברירת מחדל: נגזר מכתובת ה-IP וממסכת הרשת)

  • dnsServers

    string[]

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

  • domainSearch

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

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

  • exclusionList

    string[]

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

  • inclusionList

    string[]

    כוללים את תנועת הרשת ברשימת בלוקים של כתובות IP בסימון CIDR למנהרה. אפשר להשתמש בפרמטר הזה כדי להגדיר פיצול מנהרות. כברירת מחדל, לא מופנית תנועה למנהרה. הוספת הערך '0.0.0.0/0' לרשימה הזו תגרום להפניה מחדש של כל תנועת המשתמשים למנהרה. כשיש הרבה כללים שתואמים ליעד, הכלל עם הקידומת התואמת הארוכה ביותר הוא זה שייבחר. רשומות שתואמות לאותו בלוק CIDR נחשבות כרשומות כפולות. כפילויות כאלה ברשימה המצורפת (exclusionList + inclusionList) מוסרות, ולא מוגדר איזו רשומה כפולה בדיוק תוסר.

  • mtu

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

    הגדרת MTU לממשק ה-VPN. (ברירת מחדל: 1,500 בייטים)

  • התחברות מחדש

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

    ‫Chrome 51+‎

    האם תוסף ה-VPN מטמיע חיבור מחדש אוטומטי.

    אם הערך הוא true, הודעות הפלטפורמה linkDown,‏ linkUp,‏ linkChanged,‏ suspend ו-resume ישמשו לסימון האירועים המתאימים. אם הערך הוא False, המערכת תנתק את ה-VPN בכוח אם הטופולוגיה של הרשת תשתנה, והמשתמש יצטרך להתחבר מחדש באופן ידני. (ברירת מחדל: false)

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

PlatformMessage

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

Enum

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

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

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

‫linkDown
מציין שחיבור הרשת הפיזי שמוגדר כברירת מחדל לא פעיל.

‫linkUp
מציין שחיבור הרשת הפיזי שמוגדר כברירת מחדל חזר לפעולה.

‫linkChanged
מציין שחיבור הרשת הפיזי שמוגדר כברירת מחדל השתנה, למשל מ-Wi-Fi לנייד.

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

‫resume
מציין שהמערכת הפעלה חזרה לפעולה והמשתמש התחבר מחדש, ולכן ה-VPN צריך לנסות להתחבר מחדש.

UIEvent

הפלטפורמה משתמשת ב-enum כדי לציין את האירוע שהפעיל את onUIEvent.

Enum

‫showAddDialog
שליחת בקשה ללקוח ה-VPN להצגת תיבת הדו-שיח להוספת הגדרה למשתמש.

‫showConfigureDialog
שולח בקשה ללקוח ה-VPN להציג למשתמש את תיבת הדו-שיח של הגדרות התצורה.

VpnConnectionState

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

Enum

connected
מציין שהחיבור ל-VPN הצליח.

‫failure
מציין שחיבור ה-VPN נכשל.

Methods

createConfig()

chrome.vpnProvider.createConfig(
  name: string,
): Promise<string>

יוצרת הגדרת VPN חדשה שנשמרת בכמה סשנים של התחברות של המשתמש.

פרמטרים

  • שם

    מחרוזת

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

החזרות

  • Promise<string>

    ‫Chrome 96 ואילך

destroyConfig()

chrome.vpnProvider.destroyConfig(
  id: string,
): Promise<void>

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

פרמטרים

  • id [מזהה]

    מחרוזת

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

החזרות

  • Promise<void>

    ‫Chrome 96 ואילך

notifyConnectionStateChanged()

chrome.vpnProvider.notifyConnectionStateChanged(
  state: VpnConnectionState,
): Promise<void>

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

פרמטרים

החזרות

  • Promise<void>

    ‫Chrome 96 ואילך

sendPacket()

chrome.vpnProvider.sendPacket(
  data: ArrayBuffer,
): Promise<void>

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

פרמטרים

  • נתונים

    ArrayBuffer

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

החזרות

  • Promise<void>

    ‫Chrome 96 ואילך

setParameters()

chrome.vpnProvider.setParameters(
  parameters: Parameters,
): Promise<void>

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

פרמטרים

החזרות

  • Promise<void>

    ‫Chrome 96 ואילך

אירועים

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

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