chrome.vpnProvider

ملاحظة مُهمّة: لا تعمل واجهة برمجة التطبيقات هذه إلا على نظام التشغيل ChromeOS.

الوصف

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

الأذونات

vpnProvider

مدى توفّر الخدمة

Chrome 43 والإصدارات الأحدث ChromeOS فقط

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

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

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

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

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

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

• اضبط معلَمات الربط عن طريق طلب الرمز setParameters().

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

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

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

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

الأنواع

Parameters

أماكن إقامة

• معالجة

  سلسلة

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

• broadcastAddress

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

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

• dnsServers

  سلسلة[]

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

• domainSearch

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

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

• exclusionList

  سلسلة[]

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

• inclusionList

  سلسلة[]

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

• mtu

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

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

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

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

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

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

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

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

PlatformMessage

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

التعداد

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

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

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

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

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

"linkChanged"
يشير إلى تغيير الاتصال الفعلي بالشبكة الفعلي، مثل wifi->mobile.

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

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

UIEvent

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

التعداد

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

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

VpnConnectionState

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

التعداد

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

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

الطُرق

createConfig()

وعد

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

ينشئ هذا الإعداد ضبطًا جديدًا لشبكة افتراضية خاصة (VPN) ويستمر في جميع جلسات تسجيل الدخول المتعددة للمستخدم.

المَعلمات

• اسم

  سلسلة

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

• معاودة الاتصال

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

  تبدو معلَمة callback على النحو التالي:

  (id: string)=>void

  • id

    سلسلة

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

المرتجعات

• وعد<string>

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

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

destroyConfig()

وعد

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

يؤدي إلى محو إعدادات الشبكة الافتراضية الخاصة التي أنشأتها الإضافة.

المَعلمات

• id

  سلسلة

  رقم تعريف إعداد شبكة VPN المطلوب محوه.

• معاودة الاتصال

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

  تبدو معلَمة callback على النحو التالي:

  ()=>void

المرتجعات

• Promise<void>

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

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

notifyConnectionStateChanged()

وعد

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

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

المَعلمات

• state

  VpnConnectionState

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

• معاودة الاتصال

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

  تبدو معلَمة callback على النحو التالي:

  ()=>void

المرتجعات

• Promise<void>

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

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

sendPacket()

وعد

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

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

المَعلمات

• البيانات

  ArrayBuffer

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

• معاودة الاتصال

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

  تبدو معلَمة callback على النحو التالي:

  ()=>void

المرتجعات

• Promise<void>

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

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

setParameters()

وعد

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

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

المَعلمات

• المَعلَمات

  المعلّمات

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

• معاودة الاتصال

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

  تبدو معلَمة callback على النحو التالي:

  ()=>void

المرتجعات

• Promise<void>

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

  تتوفّر الوعود في إصدار 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,
)

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

المَعلمات

• معاودة الاتصال

  الوظيفة

  تبدو معلَمة callback على النحو التالي:

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

  • id

    سلسلة

  • رسالة

    PlatformMessage

  • خطأ

    سلسلة

onUIEvent

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

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

المَعلمات

• معاودة الاتصال

  الوظيفة

  تبدو معلَمة callback على النحو التالي:

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

  • حدث

    UIEvent

  • id

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