chrome.vpnProvider

Описание

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

Разрешения

vpnProvider

Доступность

Chrome 43+ (только ChromeOS)

Использование

Типичный пример использования 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) удаляются, а точная дублирующаяся запись, которая будет удалена, не определена.

  • включениеСписок

    нить[]

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

  • мту

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

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

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

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

    Chrome 51+

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

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

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

PlatformMessage

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

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

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

«отключен»
Указывает на разрыв соединения VPN.

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

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

"linkUp"
Указывает на то, что основное физическое сетевое соединение восстановлено.

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

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

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

UIEvent

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

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

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

"showConfigureDialog"
Запрашивает у VPN-клиента отображение диалогового окна настроек конфигурации для пользователя.

VpnConnectionState

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

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

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

"отказ"
Указывает на то, что VPN-соединение не удалось.

Методы

createConfig()

Обещать
chrome.vpnProvider.createConfig(
  name: string,
  callback?: function,
): Promise<string>

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

Параметры

  • имя

    нить

    Название конфигурации VPN.

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

    функция необязательна

    Параметр callback выглядит следующим образом: 

    (id: string) => void

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

      нить

      Уникальный идентификатор для созданной конфигурации или undefined в случае ошибки.

Возвраты

  • Promise<string>

    Chrome 96+

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

    Поддержка промисов доступна только для Manifest V3 и более поздних версий; для других платформ необходимо использовать колбэки.

destroyConfig()

Обещать
chrome.vpnProvider.destroyConfig(
  id: string,
  callback?: function,
): Promise<void>

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

Параметры

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

    нить

    Идентификатор конфигурации VPN, подлежащей удалению.

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

    функция необязательна

    Параметр callback выглядит следующим образом: 

    () => void

Возвраты

  • Обещание<пустота>

    Chrome 96+

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

    Поддержка промисов доступна только для Manifest V3 и более поздних версий; для других платформ необходимо использовать колбэки.

notifyConnectionStateChanged()

Обещать
chrome.vpnProvider.notifyConnectionStateChanged(
  state: VpnConnectionState,
  callback?: function,
): Promise<void>

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

Параметры

  • состояние

    VpnConnectionState

    Состояние VPN-сессии VPN-клиента.

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

    функция необязательна

    Параметр callback выглядит следующим образом: 

    () => void

Возвраты

  • Обещание<пустота>

    Chrome 96+

    Возвращает Promise, который разрешается по завершении уведомления или отклоняется в случае ошибки.

    Поддержка промисов доступна только для Manifest V3 и более поздних версий; для других платформ необходимо использовать колбэки.

sendPacket()

Обещать
chrome.vpnProvider.sendPacket(
  data: ArrayBuffer,
  callback?: function,
): Promise<void>

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

Параметры

  • данные

    ArrayBuffer

    IP-пакет, который необходимо отправить на платформу.

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

    функция необязательна

    Параметр callback выглядит следующим образом: 

    () => void

Возвраты

  • Обещание<пустота>

    Chrome 96+

    Возвращает Promise, который разрешается при отправке пакета или отклоняется в случае ошибки.

    Поддержка промисов доступна только для Manifest V3 и более поздних версий; для других платформ необходимо использовать колбэки.

setParameters()

Обещать
chrome.vpnProvider.setParameters(
  parameters: Parameters,
  callback?: function,
): Promise<void>

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

Параметры

  • параметры

    Параметры

    Параметры VPN-сессии.

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

    функция необязательна

    Параметр callback выглядит следующим образом: 

    () => void

Возвраты

  • Обещание<пустота>

    Chrome 96+

    Возвращает Promise, который разрешается при установке параметров или отклоняется в случае ошибки.

    Поддержка промисов доступна только для Manifest V3 и более поздних версий; для других платформ необходимо использовать колбэки.

События

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

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

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