chrome.vpnProvider

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

תיאור

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

הרשאות

vpnProvider

זמינות

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

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

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

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

• להוסיף מאזינים לאירועים 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

  מחרוזת[]

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

פרמטרים

• state

  VpnConnectionState

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

  • id

    מחרוזת

  • הודעה

    PlatformMessage

  • error

    מחרוזת

onUIEvent

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

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

פרמטרים

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

  פונקציה

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

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

  • אירוע

    UIEvent

  • id

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