chrome.vpnProvider

الوصف

استخدِم واجهة برمجة التطبيقات chrome.vpnProvider لتنفيذ برنامج شبكة VPN.

الأذونات

vpnProvider

مدى التوفّر

الإصدار 43 من Chrome أو الإصدارات الأحدث نظام التشغيل ChromeOS فقط

المفاهيم والاستخدام

في ما يلي الاستخدام النموذجي لـ chrome.vpnProvider:

  • يمكنك إنشاء إعدادات الشبكة الافتراضية الخاصة من خلال الاتصال بالرقم createConfig(). إعدادات الشبكة الافتراضية الخاصة هي إدخال دائم يظهر للمستخدم في واجهة مستخدم ChromeOS. يمكن للمستخدم تحديد تهيئة الشبكة الظاهرية الخاصة من قائمة والاتصال بها أو قطع الاتصال بها.

  • يمكنك إضافة أدوات استماع إلى أحداث onPlatformMessage وonPacketReceived وonConfigRemoved.

  • عندما يتصل المستخدم بإعداد شبكة VPN، سيتم استلام onPlatformMessage مع الرسالة "connected". تُعرف الفترة بين رسالتَي "connected" و"disconnected" باسم "جلسة شبكة VPN". خلال هذه الفترة الزمنية، يُقال إنّ الإضافة التي تتلقّى الرسالة هي نفسها صاحبة جلسة شبكة VPN.

  • ابدأ الاتصال بخادم الشبكة الافتراضية الخاصة (VPN) وابدأ تشغيل برنامج الشبكة الافتراضية الخاصة.

  • اضبط معلَمات الاتصال من خلال استدعاء setParameters().

  • يمكنك إشعار حالة الاتصال كـ "connected" من خلال الاتصال بـ notifyConnectionStateChanged().

  • عند إكمال الخطوات السابقة بدون أخطاء، يتم إنشاء نفق افتراضي لحزمة الشبكة في نظام التشغيل ChromeOS. يمكن إرسال حِزم IP عبر النفق من خلال استدعاء sendPacket()، وسيتم استلام أي حِزم تنشأ على جهاز ChromeOS باستخدام معالِج حدث onPacketReceived.

  • عندما ينقطع اتصال المستخدم بإعداد شبكة VPN، سيتم تنشيط onPlatformMessage مع عرض الرسالة "disconnected".

  • إذا لم تعُد إعدادات الشبكة الافتراضية الخاصة ضرورية، يمكنك إيقافها من خلال استدعاء destroyConfig().

الأنواع

Parameters

أماكن إقامة

  • معالجة

    سلسلة

    عنوان IP لواجهة الشبكة الافتراضية الخاصة بتدوين CIDR. الإصدار 4 من بروتوكول الإنترنت هو الوضع المدعوم الوحيد حاليًا.

  • broadcastAddress

    سلسلة اختيارية

    عنوان البث لواجهة شبكة VPN. (التلقائي: يتم استنتاجه من عنوان IP والقناع)

  • dnsServers

    سلسلة[]

    قائمة بعناوين IP لخوادم نظام أسماء النطاقات.

  • domainSearch

    string[] اختيارية

    قائمة بنطاقات البحث (الافتراضي: بلا نطاق بحث)

  • exclusionList

    سلسلة[]

    استبعد حركة بيانات الشبكة من قائمة مجموعات عناوين IP بتدوين CIDR من النفق. ويمكن استخدام ذلك لتجاوز حركة المرور من وإلى خادم الشبكة الظاهرية الخاصة. عندما تتطابق عدة قواعد مع وجهة، تفوز القاعدة التي تحتوي على أطول بادئة مطابقة. يتم التعامل مع الإدخالات التي تتوافق مع كتلة CIDR نفسها على أنها مكررة. يتم إزالة هذه التكرارات من القائمة المجمّعة (exclusionList + التضمينList) والإدخال المكرّر المحدّد الذي سيتم إزالته غير محدَّد.

  • inclusionList

    سلسلة[]

    تضمين حركة بيانات الشبكة في قائمة مجموعات عناوين IP بتدوين CIDR للنفق. يمكن استخدام هذه المعلمة لإعداد اتصال نفقي مقسّم. لا يتم توجيه أي حركة مرور إلى النفق تلقائيًا. إضافة الإدخال "0.0.0.0/0" إلى هذه القائمة، حيث تتم إعادة توجيه جميع حركة مرور المستخدمين إلى النفق. عندما تتطابق عدة قواعد مع وجهة، تفوز القاعدة التي تحتوي على أطول بادئة مطابقة. يتم التعامل مع الإدخالات التي تتوافق مع كتلة CIDR نفسها على أنها مكررة. يتم إزالة هذه التكرارات من القائمة المجمّعة (exclusionList + التضمينList) والإدخال المكرّر المحدّد الذي سيتم إزالته غير محدَّد.

  • mtu

    سلسلة اختيارية

    إعداد MTU لواجهة VPN. (القيمة التلقائية: 1,500 بايت)

  • إعادة الاتصال

    سلسلة اختيارية

    الإصدار 51 من Chrome أو الإصدارات الأحدث

    ما إذا كانت إضافة شبكة VPN تنفّذ إعادة الاتصال التلقائي أم لا

    في حال كانت القيمة صحيحة، سيتم استخدام رسائل النظام الأساسي linkDown وlinkUp وlinkChanged وsuspend وresume للإشارة إلى الأحداث ذات الصلة. في حال اختيار القيمة "false"، سيفرض النظام قطع اتصال شبكة VPN إذا تغيّرت هيكلة الشبكة، وسيحتاج المستخدم إلى إعادة الاتصال يدويًا. (الإعداد التلقائي: false)

    هذه الخاصية جديدة في الإصدار 51 من Chrome؛ سينشئ استثناءً في الإصدارات السابقة. يمكن استخدام test/catch لتفعيل الميزة بشكل مشروط استنادًا إلى توافق المتصفّح.

PlatformMessage

يستخدم النظام الأساسي التعداد لإعلام العميل بحالة جلسة شبكة VPN.

Enum

"تم الاتصال"
تشير إلى أنّ إعدادات شبكة VPN متصلة.

"غير متّصل"
تشير إلى أنّ إعدادات شبكة VPN غير متصلة.

"خطأ"
تشير إلى حدوث خطأ في الاتصال عبر شبكة VPN، على سبيل المثال انتهاء المهلة. يتم تقديم وصف للخطأ كوسيطة خطأ في onPlatformMessage.

"linkDown"
تشير إلى أنّ الاتصال الفعلي التلقائي بالشبكة معطَّل.

"linkUp"
يشير إلى أنّه تم الاحتفاظ بنسخة احتياطية من الاتصال الفعلي بالشبكة.

"linkChanged"
تشير إلى تغيير الاتصال الفعلي التلقائي بالشبكة، على سبيل المثال wifi->الجهاز الجوّال.

"suspend"
تشير إلى أنّ نظام التشغيل يستعد للتعليق، لذلك من المفترض أن تتوقّف شبكة VPN عن الاتصال. ليس من المضمون تلقّي التمديد لهذا الحدث قبل التعليق.

"resume"
تشير هذه القيمة إلى أنّه تم استئناف نظام التشغيل وأنّ المستخدم سجَّل الدخول مرة أخرى، لذا يجب أن تحاول شبكة VPN إعادة الاتصال.

UIEvent

تستخدِم المنصّة التعداد للإشارة إلى الحدث الذي أدّى إلى ظهور onUIEvent.

Enum

"showAddDialog"
تطلب من برنامج الشبكة الافتراضية الخاصة (VPN) عرض مربع حوار "إضافة إعداد" للمستخدم.

"showConfigureDialog"
تطلب من برنامج الشبكة الافتراضية الخاصة (VPN) عرض مربّع حوار إعدادات الضبط للمستخدم.

VpnConnectionState

يستخدم عميل شبكة VPN التعداد لإبلاغ النظام الأساسي بحالته الحالية. يساعد هذا في تقديم رسائل ذات مغزى للمستخدم.

Enum

"متصل"
يحدد هذا الخيار أنّ الاتصال بشبكة VPN كان ناجحًا.

"failure"
يحدد هذا الخيار تعذّر الاتصال بشبكة VPN.

الطُرق

createConfig()

وعود 
chrome.vpnProvider.createConfig(
  name: string,
  callback?: function,
)

ينشئ إعدادًا جديدًا لشبكة VPN يتم الاحتفاظ به عبر جلسات تسجيل دخول متعددة للمستخدم.

المعلمات

  • الاسم

    سلسلة

    اسم إعداد شبكة VPN.

  • رد الاتصال

    الدالة اختيارية

    تظهر المَعلمة callback على النحو التالي: 

    (id: string) => void

    • id

      سلسلة

      معرّف فريد للإعدادات التي تم إنشاؤها أو undefined عند التعذُّر.

المرتجعات

  • وعود<string>

    الإصدار 96 من Chrome أو الإصدارات الأحدث

    تتوفّر الوعود في الإصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير معاودة الاتصال. التوافق مع الأنظمة القديمة. لا يمكنك استخدام كلتيهما في نفس استدعاء الدالة. تشير رسالة الأشكال البيانية يتم حل الوعد بنفس النوع الذي يتم إرساله إلى معاودة الاتصال.

destroyConfig()

وعود 
chrome.vpnProvider.destroyConfig(
  id: string,
  callback?: function,
)

يؤدي إلى إتلاف إعداد شبكة ظاهرية خاصة (VPN) تم إنشاؤه بواسطة الإضافة.

المعلمات

  • id

    سلسلة

    رقم تعريف إعداد الشبكة الافتراضية الخاصة (VPN) المراد إتلافه.

  • رد الاتصال

    الدالة اختيارية

    تظهر المَعلمة callback على النحو التالي: 

    () => void

المرتجعات

  • وعود <باطلة>

    الإصدار 96 من Chrome أو الإصدارات الأحدث

    تتوفّر الوعود في الإصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير معاودة الاتصال. التوافق مع الأنظمة القديمة. لا يمكنك استخدام كلتيهما في نفس استدعاء الدالة. تشير رسالة الأشكال البيانية يتم حل الوعد بنفس النوع الذي يتم إرساله إلى معاودة الاتصال.

notifyConnectionStateChanged()

وعود 
chrome.vpnProvider.notifyConnectionStateChanged(
  state: VpnConnectionState,
  callback?: function,
)

يتم إرسال إشعار بحالة جلسة شبكة VPN إلى النظام الأساسي. لن ينجح ذلك إلا إذا كانت جلسة شبكة VPN مملوكة من الإضافة.

المعلمات

  • الولاية

    VpnConnectionState

    حالة جلسة شبكة VPN لعميل الشبكة الافتراضية الخاصة (VPN).

  • رد الاتصال

    الدالة اختيارية

    تظهر المَعلمة callback على النحو التالي: 

    () => void

المرتجعات

  • وعود <باطلة>

    الإصدار 96 من Chrome أو الإصدارات الأحدث

    تتوفّر الوعود في الإصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير معاودة الاتصال. التوافق مع الأنظمة القديمة. لا يمكنك استخدام كلتيهما في نفس استدعاء الدالة. تشير رسالة الأشكال البيانية يتم حل الوعد بنفس النوع الذي يتم إرساله إلى معاودة الاتصال.

sendPacket()

وعود 
chrome.vpnProvider.sendPacket(
  data: ArrayBuffer,
  callback?: function,
)

يرسل حزمة IP من خلال النفق الذي تم إنشاؤه لجلسة شبكة VPN. لن ينجح ذلك إلا إذا كانت جلسة شبكة VPN مملوكة من الإضافة.

المعلمات

  • البيانات

    ArrayBuffer

    حزمة IP المراد إرسالها إلى النظام الأساسي

  • رد الاتصال

    الدالة اختيارية

    تظهر المَعلمة callback على النحو التالي: 

    () => void

المرتجعات

  • وعود <باطلة>

    الإصدار 96 من Chrome أو الإصدارات الأحدث

    تتوفّر الوعود في الإصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير معاودة الاتصال. التوافق مع الأنظمة القديمة. لا يمكنك استخدام كلتيهما في نفس استدعاء الدالة. تشير رسالة الأشكال البيانية يتم حل الوعد بنفس النوع الذي يتم إرساله إلى معاودة الاتصال.

setParameters()

وعود 
chrome.vpnProvider.setParameters(
  parameters: Parameters,
  callback?: function,
)

تضبط هذه السياسة معلَمات جلسة شبكة VPN. يجب طلب هذه المعلومات مباشرةً بعد تلقّي ""connected"" من المنصة. لن ينجح ذلك إلا إذا كانت جلسة شبكة VPN مملوكة من الإضافة.

المعلمات

  • المعلمات

    المعلّمات

    مَعلمات جلسة شبكة VPN.

  • رد الاتصال

    الدالة اختيارية

    تظهر المَعلمة callback على النحو التالي: 

    () => void

المرتجعات

  • وعود <باطلة>

    الإصدار 96 من Chrome أو الإصدارات الأحدث

    تتوفّر الوعود في الإصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير معاودة الاتصال. التوافق مع الأنظمة القديمة. لا يمكنك استخدام كلتيهما في نفس استدعاء الدالة. تشير رسالة الأشكال البيانية يتم حل الوعد بنفس النوع الذي يتم إرساله إلى معاودة الاتصال.

فعاليات

onConfigCreated

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

يتم تشغيله عندما يتم إنشاء إعداد من خلال النظام الأساسي للإضافة.

المعلمات

  • رد الاتصال

    دالة

    تظهر المَعلمة callback على النحو التالي: 

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

    • id

      سلسلة

    • الاسم

      سلسلة

    • البيانات

      كائن

onConfigRemoved

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

يتم تشغيله عند إزالة الإعداد الذي تم إنشاؤه من خلال الإضافة بواسطة النظام الأساسي.

المعلمات

  • رد الاتصال

    دالة

    تظهر المَعلمة callback على النحو التالي: 

    (id: string) => void

    • id

      سلسلة

onPacketReceived

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

يتم تشغيله عند تلقّي حزمة IP عبر النفق لجلسة شبكة VPN التي تملكها الإضافة.

المعلمات

  • رد الاتصال

    دالة

    تظهر المَعلمة callback على النحو التالي: 

    (data: ArrayBuffer) => void

    • البيانات

      ArrayBuffer

onPlatformMessage

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

يتم تشغيله عند تلقّي رسالة من النظام الأساسي لإعدادات الشبكة الافتراضية الخاصة التي تمتلكها الإضافة.

المعلمات

  • رد الاتصال

    دالة

    تظهر المَعلمة callback على النحو التالي: 

    (id: string, message: PlatformMessage, error: string) => void

onUIEvent

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

يتم تشغيله عند وجود حدث في واجهة المستخدم للإضافة. أحداث واجهة المستخدم هي إشارات من النظام الأساسي تشير إلى التطبيق بأنّه يجب عرض مربّع حوار واجهة المستخدم للمستخدم.

المعلمات

  • رد الاتصال

    دالة

    تظهر المَعلمة callback على النحو التالي: 

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

    • event

      UIEvent

    • id

      سلسلة اختيارية