chrome.vpnProvider

الوصف

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

الأذونات

vpnProvider

مدى التوفّر

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

الاستخدام

الاستخدام المعتاد لـ vpnProvider هو ما يلي:

  • يمكنك إنشاء عمليات ضبط الشبكة الافتراضية الخاصة باستخدام الطريقة createConfig. إعدادات شبكة VPN هي إدخال دائم يظهر للمستخدم في واجهة مستخدم 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 مملوكة من الإضافة.

المعلمات

  • البيانات

    مخزن المصفوفات

    حزمة 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

    • البيانات

      مخزن المصفوفات

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

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