chrome.vpnProvider

Описание

Используйте API chrome.vpnProvider для реализации VPN-клиента.

Разрешения

vpnProvider

Доступность

Только Chrome OS 43+

Концепции и использование

Типичное использование chrome.vpnProvider выглядит следующим образом:

  • Создавайте конфигурации VPN, вызывая createConfig() . Конфигурация VPN — это постоянная запись, отображаемая пользователю в пользовательском интерфейсе ChromeOS. Пользователь может выбрать конфигурацию VPN из списка и подключиться к ней или отключиться.

  • Добавьте прослушиватели событий onPlatformMessage , onPacketReceived и onConfigRemoved .

  • Когда пользователь подключается к VPN-конфигурации, будет получено сообщение onPlatformMessage с сообщением "connected" . Промежуток времени между сообщениями "connected" и "disconnected" называется «VPN-сеансом». В этот период считается, что расширение, получившее сообщение, владеет VPN-сеансом.

  • Подключитесь к VPN-серверу и запустите VPN-клиент.

  • Задайте параметры соединения, вызвав setParameters() .

  • Уведомите о состоянии соединения как "connected" , вызвав notifyConnectionStateChanged() .

  • Если предыдущие шаги выполнены без ошибок, создаётся виртуальный туннель к сетевому стеку ChromeOS. IP-пакеты можно отправлять через туннель, вызывая sendPacket() , а любые пакеты, исходящие с устройства ChromeOS, будут приниматься с помощью обработчика событий onPacketReceived .

  • Когда пользователь отключается от конфигурации VPN, будет запущено onPlatformMessage с сообщением "disconnected" .

  • Если конфигурация VPN больше не нужна, ее можно уничтожить, вызвав destroyConfig() .

Типы

Parameters

Характеристики

  • адрес

    нить

    IP-адрес VPN-интерфейса в нотации CIDR. В настоящее время поддерживается только режим IPv4.

  • трансляционный адрес

    строка необязательная

    Широковещательный адрес для интерфейса VPN. (по умолчанию: выводится из IP-адреса и маски)

  • DNS-серверы

    нить[]

    Список IP-адресов DNS-серверов.

  • domainSearch

    строка[] необязательная

    Список доменов поиска. (по умолчанию: домен поиска отсутствует)

  • список исключений

    нить[]

    Исключить сетевой трафик из туннеля, направляемый в список IP-блоков в нотации CIDR. Это можно использовать для обхода трафика, поступающего на VPN-сервер и от него. Если несколько правил соответствуют одному и тому же пункту назначения, приоритет отдаётся правилу с самым длинным совпадающим префиксом. Записи, соответствующие одному и тому же блоку CIDR, считаются дубликатами. Такие дубликаты в объединённом списке (exclusionList + inclusionList) удаляются, и точный дубликат, который будет удалён, не определён.

  • includeList

    нить[]

    Включить сетевой трафик в список IP-блоков в нотации CIDR для туннеля. Этот параметр можно использовать для настройки разделённого туннеля. По умолчанию трафик в туннель не направляется. Добавление записи "0.0.0.0/0" в этот список перенаправляет весь пользовательский трафик в туннель. Если назначению соответствует несколько правил, приоритет отдаётся правилу с самым длинным совпадающим префиксом. Записи, соответствующие одному и тому же блоку CIDR, считаются дубликатами. Такие дубликаты в объединенном списке (exclusionList + inclusionList) удаляются, и точный дубликат, который будет удалён, не определён.

  • МТУ

    строка необязательная

    Настройка MTU для интерфейса VPN. (по умолчанию: 1500 байт)

  • переподключиться

    строка необязательная

    Хром 51+

    Реализует ли VPN-расширение автоматическое переподключение.

    Если задано значение true, сообщения платформы linkDown , linkUp , linkChanged , suspend и resume будут использоваться для оповещения о соответствующих событиях. Если задано значение false, система принудительно отключит VPN при изменении топологии сети, и пользователю потребуется вручную переподключиться. (по умолчанию: false)

    Это свойство является новым в Chrome 51; в более ранних версиях оно будет генерировать исключение. try/catch можно использовать для условного включения функции в зависимости от поддержки браузера.

PlatformMessage

Перечисление используется платформой для уведомления клиента о состоянии сеанса VPN.

Перечисление

"связанный"
Указывает на то, что конфигурация VPN подключена.

"отключен"
Указывает на то, что конфигурация VPN отключена.

"ошибка"
Указывает на ошибку VPN-подключения, например, тайм-аут. Описание ошибки указывается в качестве аргумента ошибки для onPlatformMessage.

"linkDown"
Указывает на то, что физическое сетевое соединение по умолчанию не работает.

"linkUp"
Указывает на то, что физическое сетевое соединение по умолчанию является резервным.

"linkChanged"
Указывает на то, что физическое сетевое соединение по умолчанию изменилось, например, Wi-Fi->мобильная связь.

"приостановить"
Указывает, что ОС готовится к приостановке работы, поэтому VPN-соединение должно быть разорвано. Расширение не гарантирует получение этого события до приостановки работы.

"резюме"
Указывает на то, что ОС возобновила работу и пользователь снова вошел в систему, поэтому VPN должен попытаться повторно подключиться.

UIEvent

Перечисление используется платформой для указания события, которое вызвало onUIEvent .

Перечисление

"showAddDialog"
Просит VPN-клиент показать пользователю диалоговое окно добавления конфигурации.

"showConfigureDialog"
Просит VPN-клиент показать пользователю диалоговое окно параметров конфигурации.

VpnConnectionState

Перечисление используется VPN-клиентом для информирования платформы о своём текущем состоянии. Это помогает предоставлять пользователю содержательные сообщения.

Перечисление

"связанный"
Указывает, что VPN-подключение прошло успешно.

"отказ"
Указывает на сбой VPN-подключения.

Методы

createConfig()

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

Создает новую конфигурацию VPN, которая сохраняется для нескольких сеансов входа пользователя.

Параметры

  • имя

    нить

    Имя конфигурации VPN.

Возврат

  • Обещание<строка>

    Хром 96+

destroyConfig()

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

Уничтожает конфигурацию VPN, созданную расширением.

Параметры

  • идентификатор

    нить

    Идентификатор конфигурации VPN, который необходимо уничтожить.

Возврат

  • Обещание<void>

    Хром 96+

notifyConnectionStateChanged()

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

Уведомляет платформу о состоянии VPN-сеанса. Это будет успешно выполнено только в том случае, если VPN-сеанс принадлежит расширению.

Параметры

Возврат

  • Обещание<void>

    Хром 96+

sendPacket()

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

Отправляет IP-пакет через туннель, созданный для VPN-сеанса. Это будет успешно выполнено только в том случае, если VPN-сеанс принадлежит расширению.

Параметры

  • данные

    ArrayBuffer

    IP-пакет для отправки на платформу.

Возврат

  • Обещание<void>

    Хром 96+

setParameters()

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

Задаёт параметры VPN-сеанса. Вызывается сразу после получения сообщения "connected" от платформы. Это будет успешно выполнено только в том случае, если VPN-сеанс принадлежит расширению.

Параметры

Возврат

  • Обещание<void>

    Хром 96+

События

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

    • данные

      ArrayBuffer

onPlatformMessage

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

Срабатывает при получении сообщения от платформы о конфигурации VPN, принадлежащей расширению.

Параметры

  • перезвонить

    функция

    Параметр callback выглядит так: 

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

    • идентификатор

      нить

    • сообщение

      PlatformMessage

    • ошибка

      нить

onUIEvent

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

Срабатывает при возникновении события пользовательского интерфейса для расширения. События пользовательского интерфейса — это сигналы от платформы, которые сообщают приложению о необходимости отображения диалогового окна пользовательского интерфейса.

Параметры

  • перезвонить

    функция

    Параметр callback выглядит так: 

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

    • событие

      UIEvent

    • идентификатор

      строка необязательная