browser.vpnProvider

الوصف

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

الأذونات

vpnProvider

مدى التوفّر

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

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

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

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

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

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

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

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

  • أبلِغ عن حالة الاتصال على أنّها "connected" من خلال استدعاء notifyConnectionStateChanged().

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

  • عندما يقطع المستخدم الاتصال بإعدادات شبكة VPN، سيتم تشغيل 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.

تعداد

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

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

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

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

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

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

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

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

UIEvent

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

تعداد

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

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

VpnConnectionState

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

تعداد

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

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

الطُرق

createConfig()

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

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

المعلمات

  • الاسم

    سلسلة

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

المرتجعات

  • Promise<string>

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

    تعرض هذه الدالة Promise يتم تنفيذه عند إنشاء الإعدادات أو يتم رفضه في حال حدوث خطأ.

destroyConfig()

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

تدمير إعدادات شبكة VPN التي أنشأتها الإضافة

المعلمات

  • id

    سلسلة

    معرّف إعدادات شبكة VPN المطلوب إزالتها.

المرتجعات

  • Promise<void>

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

    تعرض هذه الدالة Promise يتم تنفيذه عند إيقاف الإعدادات أو يتم رفضه في حال حدوث خطأ.

notifyConnectionStateChanged()

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

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

المعلمات

  • الولاية

    VpnConnectionState

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

المرتجعات

  • Promise<void>

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

    تعرض هذه الطريقة Promise يتم تنفيذه عند اكتمال الإشعار أو يتم رفضه في حال حدوث خطأ.

sendPacket()

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

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

المعلمات

  • البيانات

    ArrayBuffer

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

المرتجعات

  • Promise<void>

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

    تعرض هذه الطريقة Promise يتم تنفيذه عند إرسال الحزمة أو يتم رفضه في حال حدوث خطأ.

setParameters()

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

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

المعلمات

المرتجعات

  • Promise<void>

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

    تعرض هذه الطريقة 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,
)

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

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