chrome.vpnProvider

توضیحات

برای پیاده‌سازی یک کلاینت VPN از API chrome.vpnProvider استفاده کنید.

مجوزها

vpnProvider

در دسترس بودن

فقط کروم ۴۳+ (سیستم عامل کروم)

کاربرد

استفاده معمول از vpnProvider به شرح زیر است:

  • با استفاده از متد createConfig پیکربندی‌های VPN ایجاد کنید. پیکربندی VPN یک ورودی دائمی است که در رابط کاربری بومی ChromeOS به کاربر نشان داده می‌شود. کاربر می‌تواند پیکربندی VPN را از یک لیست انتخاب کرده و به آن متصل شود یا از آن جدا شود.

  • به رویدادهای onPlatformMessage ، onPacketReceived و onConfigRemoved شنونده اضافه کنید.

  • وقتی کاربر به پیکربندی VPN متصل می‌شود، onPlatformMessage با پیام "connected" دریافت می‌شود. ما به دوره زمانی بین پیام‌های "connected" و "disconnected" به عنوان یک جلسه VPN اشاره می‌کنیم. در این دوره زمانی، به افزونه‌ای که پیام را دریافت می‌کند، گفته می‌شود که صاحب جلسه VPN است.

  • اتصال به سرور VPN را آغاز کنید و کلاینت VPN را اجرا کنید.

  • پارامترهای اتصال را با استفاده از setParameters تنظیم کنید.

  • با استفاده از notifyConnectionStateChanged وضعیت اتصال را به عنوان "connected" اعلام کنید.

  • وقتی مراحل بالا بدون خطا انجام شوند، یک تونل مجازی به پشته شبکه ChromeOS ایجاد می‌شود. بسته‌های IP می‌توانند از طریق تونل با استفاده sendPacket ارسال شوند و هر بسته‌ای که از دستگاه ChromeOS سرچشمه می‌گیرد با استفاده از رویداد onPacketReceived دریافت می‌شود.

  • وقتی کاربر از پیکربندی VPN جدا می‌شود، onPlatformMessage با پیام "disconnected" اجرا می‌شود.

  • If the VPN configuration is no longer necessary, it can be destroyed using destroyConfig .

انواع

Parameters

خواص

  • آدرس

    رشته

    آدرس IP برای رابط VPN در نماد CIDR. IPv4 در حال حاضر تنها حالت پشتیبانی شده است.

  • آدرس پخش

    رشته اختیاری

    آدرس پخش برای رابط VPN. (پیش‌فرض: از آدرس IP و ماسک استنباط می‌شود)

  • سرورهای DNS

    رشته[]

    فهرستی از IPهای مربوط به سرورهای DNS.

  • جستجوی دامنه

    رشته[] اختیاری

    فهرستی از دامنه‌های جستجو. (پیش‌فرض: بدون دامنه جستجو)

  • فهرست استثنائات

    رشته[]

    ترافیک شبکه به لیست بلوک‌های IP در نمادگذاری CIDR را از تونل حذف کنید. این می‌تواند برای دور زدن ترافیک به و از سرور VPN استفاده شود. هنگامی که بسیاری از قوانین با یک مقصد مطابقت دارند، قانونی که طولانی‌ترین پیشوند تطبیق را دارد برنده می‌شود. ورودی‌هایی که با همان بلوک CIDR مطابقت دارند به عنوان تکراری در نظر گرفته می‌شوند. چنین تکراری‌هایی در لیست جمع‌آوری‌شده (exclusionList + inclusionList) حذف می‌شوند و ورودی تکراری دقیقی که حذف خواهد شد، تعریف نشده است.

  • فهرست شمول

    رشته[]

    ترافیک شبکه را به لیست بلوک‌های IP در نمادگذاری CIDR به تونل اضافه کنید. از این پارامتر می‌توان برای راه‌اندازی یک تونل تقسیم‌شده استفاده کرد. به‌طور پیش‌فرض هیچ ترافیکی به تونل هدایت نمی‌شود. اضافه کردن ورودی "0.0.0.0/0" به این لیست باعث می‌شود تمام ترافیک کاربر به تونل هدایت شود. وقتی چندین قانون با یک مقصد مطابقت دارند، قانونی که طولانی‌ترین پیشوند منطبق را دارد، برنده می‌شود. ورودی‌هایی که با یک بلوک CIDR مشابه مطابقت دارند، به‌عنوان تکراری در نظر گرفته می‌شوند. چنین تکراری‌هایی در لیست جمع‌آوری‌شده (exclusionList + inclusionList) حذف می‌شوند و ورودی تکراری دقیقی که حذف خواهد شد، تعریف نشده است.

  • ام‌تی‌یو

    رشته اختیاری

    تنظیم MTU برای رابط VPN. (پیش‌فرض: ۱۵۰۰ بایت)

  • دوباره وصل شدن

    رشته اختیاری

    کروم ۵۱+

    اینکه آیا افزونه VPN اتصال مجدد خودکار را پیاده‌سازی می‌کند یا خیر.

    اگر مقدار آن درست باشد، پیام‌های پلتفرم linkDown ، linkUp ، linkChanged ، suspend و resume برای اعلام رویدادهای مربوطه استفاده می‌شوند. اگر مقدار آن نادرست باشد، در صورت تغییر توپولوژی شبکه، سیستم به اجبار VPN را قطع می‌کند و کاربر باید به صورت دستی دوباره متصل شود. (پیش‌فرض: نادرست)

    این ویژگی در کروم ۵۱ جدید است؛ در نسخه‌های قبلی یک استثنا ایجاد می‌کرد. try/catch می‌تواند برای فعال کردن مشروط این ویژگی بر اساس پشتیبانی مرورگر استفاده شود.

PlatformMessage

این enum توسط پلتفرم برای اطلاع‌رسانی به کلاینت در مورد وضعیت جلسه VPN استفاده می‌شود.

شمارشی

"متصل"
نشان می‌دهد که پیکربندی VPN متصل شده است.

"قطع ارتباط"
نشان می‌دهد که پیکربندی VPN قطع شده است.

"خطا"
نشان می‌دهد که خطایی در اتصال VPN رخ داده است، مثلاً یک وقفه زمانی. توضیحی از خطا به عنوان آرگومان خطا به onPlatformMessage داده می‌شود.

"لینک داون"
نشان می‌دهد که اتصال فیزیکی شبکه پیش‌فرض قطع است.

"لینک‌آپ"
نشان می‌دهد که اتصال شبکه فیزیکی پیش‌فرض پشتیبان‌گیری شده است.

"لینک تغییر کرد"
نشان می‌دهد که اتصال شبکه فیزیکی پیش‌فرض تغییر کرده است، مثلاً wifi->mobile.

"تعلیق"
نشان می‌دهد که سیستم عامل در حال آماده شدن برای تعلیق است، بنابراین VPN باید اتصال خود را قطع کند. تضمینی وجود ندارد که افزونه قبل از تعلیق، این رویداد را دریافت کند.

"رزومه"
نشان می‌دهد که سیستم عامل دوباره راه‌اندازی شده و کاربر دوباره وارد سیستم شده است، بنابراین VPN باید سعی کند دوباره متصل شود.

UIEvent

این enum توسط پلتفرم برای نشان دادن رویدادی که onUIEvent را فعال کرده است، استفاده می‌شود.

شمارشی

"نمایش افزودن دیالوگ"
درخواست می‌کند که کلاینت VPN کادر محاوره‌ای افزودن پیکربندی را به کاربر نشان دهد.

"نمایش پیکربندی دیالوگ"
درخواست می‌کند که کلاینت VPN کادر محاوره‌ای تنظیمات پیکربندی را به کاربر نشان دهد.

VpnConnectionState

این enum توسط کلاینت VPN برای اطلاع‌رسانی به پلتفرم در مورد وضعیت فعلی‌اش استفاده می‌شود. این امر به ارائه پیام‌های معنادار به کاربر کمک می‌کند.

شمارشی

"متصل"
مشخص می‌کند که اتصال VPN موفقیت‌آمیز بوده است.

«شکست»
مشخص می‌کند که اتصال VPN ناموفق بوده است.

روش‌ها

createConfig()

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

یک پیکربندی VPN جدید ایجاد می‌کند که در چندین جلسه ورود کاربر باقی می‌ماند.

پارامترها

  • نام

    رشته

    نام پیکربندی VPN.

  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به شکل زیر است: 

    (id: string) => void

    • شناسه

      رشته

      یک شناسه منحصر به فرد برای پیکربندی ایجاد شده، یا در صورت عدم موفقیت undefined .

بازگشت‌ها

  • قول<string>

    کروم ۹۶+

    یک Promise برمی‌گرداند که هنگام ایجاد پیکربندی برطرف می‌شود یا در صورت وجود خطا، رد می‌شود.

    Promiseها فقط برای Manifest V3 و نسخه‌های بعدی پشتیبانی می‌شوند، سایر پلتفرم‌ها باید از callbackها استفاده کنند.

destroyConfig()

وعده
chrome.vpnProvider.destroyConfig(
  id: string,
  callback?: function,
): Promise<void>

پیکربندی VPN ایجاد شده توسط افزونه را از بین می‌برد.

پارامترها

  • شناسه

    رشته

    شناسه پیکربندی VPN برای از بین بردن.

  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به شکل زیر است: 

    () => void

بازگشت‌ها

  • قول<void>

    کروم ۹۶+

    یک Promise برمی‌گرداند که در صورت از بین رفتن پیکربندی یا رد شدن در صورت وجود خطا، برطرف می‌شود.

    Promiseها فقط برای Manifest V3 و نسخه‌های بعدی پشتیبانی می‌شوند، سایر پلتفرم‌ها باید از callbackها استفاده کنند.

notifyConnectionStateChanged()

وعده
chrome.vpnProvider.notifyConnectionStateChanged(
  state: VpnConnectionState,
  callback?: function,
): Promise<void>

وضعیت جلسه VPN را به پلتفرم اطلاع می‌دهد. این کار تنها زمانی موفقیت‌آمیز خواهد بود که جلسه VPN متعلق به افزونه باشد.

پارامترها

  • وضعیت جلسه VPN مربوط به کلاینت VPN.

  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به شکل زیر است: 

    () => void

بازگشت‌ها

  • قول<void>

    کروم ۹۶+

    یک Promise برمی‌گرداند که پس از تکمیل اعلان، برطرف می‌شود یا در صورت وجود خطا، رد می‌شود.

    Promiseها فقط برای Manifest V3 و نسخه‌های بعدی پشتیبانی می‌شوند، سایر پلتفرم‌ها باید از callbackها استفاده کنند.

sendPacket()

وعده
chrome.vpnProvider.sendPacket(
  data: ArrayBuffer,
  callback?: function,
): Promise<void>

یک بسته IP را از طریق تونل ایجاد شده برای جلسه VPN ارسال می‌کند. این کار تنها زمانی موفقیت‌آمیز خواهد بود که جلسه VPN متعلق به افزونه باشد.

پارامترها

  • داده‌ها

    آرایه بافر

    بسته IP که قرار است به پلتفرم ارسال شود.

  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به شکل زیر است: 

    () => void

بازگشت‌ها

  • قول<void>

    کروم ۹۶+

    یک Promise برمی‌گرداند که هنگام ارسال بسته برطرف می‌شود یا در صورت وجود خطا، رد می‌شود.

    Promiseها فقط برای Manifest V3 و نسخه‌های بعدی پشتیبانی می‌شوند، سایر پلتفرم‌ها باید از callbackها استفاده کنند.

setParameters()

وعده
chrome.vpnProvider.setParameters(
  parameters: Parameters,
  callback?: function,
): Promise<void>

پارامترهای مربوط به جلسه VPN را تنظیم می‌کند. این باید بلافاصله پس از دریافت "connected" از پلتفرم فراخوانی شود. این تنها زمانی موفق خواهد بود که جلسه VPN متعلق به افزونه باشد.

پارامترها

  • پارامترها

    پارامترها

    پارامترهای مربوط به جلسه VPN.

  • تماس برگشتی

    تابع اختیاری

    پارامتر callback به شکل زیر است: 

    () => void

بازگشت‌ها

  • قول<void>

    کروم ۹۶+

    یک Promise برمی‌گرداند که با تنظیم پارامترها برطرف می‌شود یا در صورت وجود خطا، رد می‌شود.

    Promiseها فقط برای Manifest V3 و نسخه‌های بعدی پشتیبانی می‌شوند، سایر پلتفرم‌ها باید از callbackها استفاده کنند.

رویدادها

onConfigCreated

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

زمانی فعال می‌شود که پیکربندی توسط پلتفرم برای افزونه ایجاد شود.

پارامترها

  • تماس برگشتی

    تابع

    پارامتر callback به شکل زیر است: 

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

    • شناسه

      رشته

    • نام

      رشته

    • داده‌ها

      شیء

onConfigRemoved

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

زمانی فعال می‌شود که پیکربندی ایجاد شده توسط افزونه توسط پلتفرم حذف شود.

پارامترها

  • تماس برگشتی

    تابع

    پارامتر callback به شکل زیر است: 

    (id: string) => void

    • شناسه

      رشته

onPacketReceived

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

زمانی فعال می‌شود که یک بسته IP از طریق تونل مربوط به جلسه VPN متعلق به افزونه دریافت شود.

پارامترها

  • تماس برگشتی

    تابع

    پارامتر callback به شکل زیر است: 

    (data: ArrayBuffer) => void

    • داده‌ها

      آرایه بافر

onPlatformMessage

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

Triggered when a message is received from the platform for a VPN configuration owned by the extension.

پارامترها

  • تماس برگشتی

    تابع

    پارامتر callback به شکل زیر است: 

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

onUIEvent

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

زمانی فعال می‌شود که یک رویداد رابط کاربری برای افزونه وجود داشته باشد. رویدادهای رابط کاربری سیگنال‌هایی از پلتفرم هستند که به برنامه نشان می‌دهند که یک کادر محاوره‌ای رابط کاربری باید به کاربر نشان داده شود.

پارامترها

  • تماس برگشتی

    تابع

    پارامتر callback به شکل زیر است: 

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