chrome.vpnProvider

חשוב: ממשק ה-API הזה פועל רק ב-ChromeOS.

תיאור

משתמשים ב-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[]

  להחריג ממנהרת ה-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.

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 הצליח.

'כשל'
מציין שחיבור ה-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 הוא בבעלות התוסף.

פרמטרים

• הסמוי הסופי

  VpnConnectionState

  מצב סשן ה-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 הוא בבעלות התוסף.

פרמטרים

• פרמטרים

  פרמטרים

  הפרמטרים של סשן ה-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

  • id [מזהה]

    מחרוזת

  • הודעה

    PlatformMessage

  • error

    מחרוזת

onUIEvent

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

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

פרמטרים

• callback

  פונקציה

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

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

  • אירוע

    UIEvent

  • id [מזהה]

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