chrome.vpnProvider

الوصف

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

الأذونات

vpnProvider

مدى التوفّر

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

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

في ما يلي الاستخدامات المعتادة لـ chrome.vpnProvider:

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

  • أضِف أدوات معالجة الأحداث onPlatformMessage وonPacketReceived وonConfigRemoved.

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

  • ابدأ الاتصال بخادم VPN وشغِّل برنامج VPN.

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

  • إرسال إشعار بحالة الاتصال على النحو "connected" من خلال استدعاء notifyConnectionStateChanged()

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

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

  • إذا لم تعُد هناك حاجة إلى إعدادات VPN، يمكن إزالتها من خلال استدعاء destroyConfig().

الأنواع

Parameters

الخصائص

  • معالجة

    سلسلة

    عنوان IP لواجهة شبكة VPN بتدوين CIDR إنّ IPv4 هو الوضع الوحيد المتوافق حاليًا.

  • broadcastAddress

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

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

  • dnsServers

    string[]

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

  • domainSearch

    string[] اختياري

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

  • exclusionList

    string[]

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

  • inclusionList

    string[]

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

  • mtu

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

    إعداد MTU لواجهة شبكة VPN (القيمة التلقائية: 1500 بايت)

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

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

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

    تحديد ما إذا كانت إضافة VPN تنفّذ عملية إعادة الاتصال تلقائيًا

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

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

PlatformMessage

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

Enum

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

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

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

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

‫"linkUp"
يشير إلى أنّ الاتصال التلقائي بالشبكة الفعلية قد عاد.

linkChanged
يشير إلى أنّه تم تغيير الاتصال التلقائي بالشبكة الفعلية، مثلاً من شبكة Wi-Fi إلى شبكة الجوّال.

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

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

UIEvent

تستخدم المنصة التعداد لتحديد الحدث الذي أدّى إلى تشغيل onUIEvent.

Enum

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

‫"showConfigureDialog"
يطلب هذا الأمر من عميل شبكة VPN عرض مربّع حوار إعدادات الضبط للمستخدم.

VpnConnectionState

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

Enum

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

"failure"
تحدّد هذه السمة أنّ الاتصال بشبكة VPN قد تعذّر.

الطُرق

createConfig()

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

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

المعلمات

  • الاسم

    سلسلة

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

المرتجعات

  • Promise<string>

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

destroyConfig()

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

تدمّر هذه الطريقة إعدادات شبكة VPN التي أنشأتها الإضافة.

المعلمات

  • id

    سلسلة

    معرّف إعدادات شبكة VPN التي سيتم إيقافها

المرتجعات

  • Promise<void>

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

notifyConnectionStateChanged()

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

يُعلم هذا الإجراء النظام الأساسي بحالة جلسة الشبكة الافتراضية الخاصة. ولن ينجح ذلك إلا عندما تكون الإضافة هي مالكة جلسة شبكة VPN.

المعلمات

  • الولاية

    VpnConnectionState

    حالة جلسة شبكة VPN الخاصة بعميل شبكة VPN

المرتجعات

  • Promise<void>

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

sendPacket()

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

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

المعلمات

  • البيانات

    ArrayBuffer

    حزمة بروتوكول الإنترنت التي سيتم إرسالها إلى المنصة

المرتجعات

  • Promise<void>

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

setParameters()

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

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

المعلمات

المرتجعات

  • Promise<void>

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

الفعاليات

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,
)

يتم تشغيله عند تلقّي حزمة بروتوكول إنترنت عبر النفق لجلسة شبكة 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

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