browser.vpnProvider

תיאור

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

הרשאות

vpnProvider

זמינות

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

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

שימוש אופייני ב-browser.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 יתקבלו באמצעות גורם מטפל באירועים onPacketReceived.

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

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

סוגים

Parameters

מאפיינים

  • כתובת

    מחרוזת

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

  • broadcastAddress

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

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

  • dnsServers

    string[]

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

  • domainSearch

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

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

  • exclusionList

    string[]

    להחריג ממנהרת ה-VPN תנועת רשת לרשימת בלוקים של כתובות 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.

ספירה

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

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

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

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

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

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

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

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

UIEvent

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

ספירה

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

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

VpnConnectionState

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

ספירה

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

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

Methods

createConfig()

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

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

פרמטרים

  • שם

    מחרוזת

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

החזרות

  • Promise<string>

    ‫Chrome 96 ואילך

    הפונקציה מחזירה אובייקט Promise שמותאם כשההגדרה נוצרת, או נדחה אם יש שגיאה.

destroyConfig()

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

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

פרמטרים

  • id [מזהה]

    מחרוזת

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

החזרות

  • Promise<void>

    ‫Chrome 96 ואילך

    הפונקציה מחזירה אובייקט Promise שמותאם כשההגדרה נמחקת, או נדחה אם יש שגיאה.

notifyConnectionStateChanged()

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

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

פרמטרים

החזרות

  • Promise<void>

    ‫Chrome 96 ואילך

    מחזירה אובייקט Promise שמושלם כשההתראה מסתיימת או נדחה אם יש שגיאה.

sendPacket()

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

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

פרמטרים

  • נתונים

    ArrayBuffer

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

החזרות

  • Promise<void>

    ‫Chrome 96 ואילך

    הפונקציה מחזירה אובייקט Promise שמותאם כשהחבילה נשלחת, או נדחה אם יש שגיאה.

setParameters()

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

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

פרמטרים

החזרות

  • Promise<void>

    ‫Chrome 96 ואילך

    מחזירה אובייקט Promise שמותאם כשהפרמטרים מוגדרים, או נדחה אם יש שגיאה.

אירועים

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

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