Описание
Используйте API chrome.vpnProvider, чтобы реализовать VPN-клиент.
Разрешения
vpnProviderДоступность
Основные понятия и использование
Обычно browser.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
Свойства
-
Обращаться (к определенному вопросу)
string
IP-адрес для интерфейса VPN в нотации CIDR. В настоящее время поддерживается только IPv4.
-
broadcastAddress
Строка (необязательно)
Широковещательный адрес для интерфейса VPN. (по умолчанию: определяется по IP-адресу и маске)
-
dnsServers
string[]
Список IP-адресов DNS-серверов.
-
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 и более поздних версий browser.* начиная с Chrome 148Реализует ли расширение VPN автоматическое повторное подключение.
Если задано значение true, то для передачи сигналов о соответствующих событиях будут использоваться сообщения платформы
linkDown,linkUp,linkChanged,suspendиresume. Если выбрано значение False, система принудительно отключит VPN при изменении топологии сети, и пользователю потребуется подключиться вручную. (по умолчанию – false)Это свойство появилось в Chrome 51. В более ранних версиях оно будет вызывать исключение. Чтобы условно включить эту функцию в зависимости от поддержки браузера, можно использовать try/catch.
PlatformMessage
Перечисление используется платформой для уведомления клиента о статусе сеанса VPN.
Перечисление
connected
Указывает, что конфигурация VPN подключена.
"disconnected"
Указывает, что конфигурация VPN отключена.
"error"
Указывает, что при VPN-подключении произошла ошибка, например истекло время ожидания. Описание ошибки передается в качестве аргумента error в onPlatformMessage.
"linkDown"
Указывает, что физическое сетевое подключение по умолчанию не работает.
linkUp
Указывает, что физическое сетевое подключение по умолчанию восстановлено.
"linkChanged"
Указывает, что физическое сетевое подключение по умолчанию изменилось, например с Wi-Fi на мобильную сеть.
"suspend"
Указывает, что ОС готовится к приостановке, поэтому VPN-подключение должно быть разорвано. Расширение может не получить это событие до приостановки.
"resume"
Указывает, что ОС возобновила работу и пользователь снова вошел в систему, поэтому VPN-клиент должен попытаться повторно подключиться.
UIEvent
Перечисление используется платформой, чтобы указать событие, которое активировало onUIEvent.
Перечисление
"showAddDialog"
Запрашивает у клиента VPN показ диалогового окна добавления конфигурации.
"showConfigureDialog"
Запрашивает у VPN-клиента показ диалогового окна с настройками конфигурации.
VpnConnectionState
Перечисление используется VPN-клиентом, чтобы сообщать платформе о своем текущем состоянии. Это помогает предоставлять пользователю содержательные сообщения.
Перечисление
connected
VPN-подключение установлено.
"failure"
Указывает, что VPN-подключение не удалось установить.
Методы
createConfig()
browser.vpnProvider.createConfig(
name: string,
): Promise<string>
Создает новую конфигурацию VPN, которая сохраняется в течение нескольких сеансов пользователя.
Параметры
-
name
string
Название конфигурации VPN.
Возвраты
-
Promise<string>
Chrome 96 и более поздние версии browser.* начиная с Chrome 148Возвращает объект Promise, который распознается, когда конфигурация создана, или отклоняется в случае ошибки.
destroyConfig()
browser.vpnProvider.destroyConfig(
id: string,
): Promise<void>
Удаляет конфигурацию VPN, созданную расширением.
Параметры
-
id
string
Идентификатор конфигурации VPN, которую нужно удалить.
Возвраты
-
Promise<void>
Chrome 96 и более поздние версии browser.* начиная с Chrome 148Возвращает объект Promise, который распознается, когда конфигурация удалена, или отклоняется в случае ошибки.
notifyConnectionStateChanged()
browser.vpnProvider.notifyConnectionStateChanged(
state: VpnConnectionState,
): Promise<void>
Уведомляет платформу о состоянии сеанса VPN. Это возможно, только если сеанс VPN принадлежит расширению.
Параметры
-
штат
Состояние сеанса VPN-клиента.
Возвраты
-
Promise<void>
Chrome 96 и более поздние версии browser.* начиная с Chrome 148Возвращает объект Promise, который распознается, когда уведомление завершено, и отклоняется в случае ошибки.
sendPacket()
browser.vpnProvider.sendPacket(
data: ArrayBuffer,
): Promise<void>
Отправляет IP-пакет через туннель, созданный для сеанса VPN. Это возможно, только если сеанс VPN принадлежит расширению.
Параметры
-
делал.
ArrayBuffer
IP-пакет, который будет отправлен на платформу.
Возвраты
-
Promise<void>
Chrome 96 и более поздние версии browser.* начиная с Chrome 148Возвращает объект Promise, который распознается, когда пакет отправлен, или отклоняется, если произошла ошибка.
setParameters()
browser.vpnProvider.setParameters(
parameters: Parameters,
): Promise<void>
Задает параметры для сеанса VPN. Этот метод должен вызываться сразу после получения "connected" от платформы. Это возможно, только если сеанс VPN принадлежит расширению.
Параметры
-
Параметры
Параметры сеанса VPN.
Возвраты
-
Promise<void>
Chrome 96 и более поздние версии browser.* начиная с Chrome 148Возвращает объект Promise, который распознается, когда параметры заданы, или отклоняется в случае ошибки.
События
onConfigCreated
browser.vpnProvider.onConfigCreated.addListener(
callback: function,
)
Срабатывает, когда платформа создает конфигурацию для расширения.
Параметры
-
обратный вызов
function
Параметр
callbackвыглядит следующим образом:(id: string, name: string, data: object) => void
-
id
string
-
name
string
-
делал.
Объект
-
onConfigRemoved
browser.vpnProvider.onConfigRemoved.addListener(
callback: function,
)
Активируется, когда конфигурация, созданная расширением, удаляется платформой.
Параметры
-
обратный вызов
function
Параметр
callbackвыглядит следующим образом:(id: string) => void
-
id
string
-
onPacketReceived
browser.vpnProvider.onPacketReceived.addListener(
callback: function,
)
Срабатывает, когда через туннель для сеанса VPN, принадлежащего расширению, получен IP-пакет.
Параметры
-
обратный вызов
function
Параметр
callbackвыглядит следующим образом:(data: ArrayBuffer) => void
-
делал.
ArrayBuffer
-
onPlatformMessage
browser.vpnProvider.onPlatformMessage.addListener(
callback: function,
)
Активируется, когда от платформы поступает сообщение для конфигурации VPN, принадлежащей расширению.
Параметры
-
обратный вызов
function
Параметр
callbackвыглядит следующим образом:(id: string, message: PlatformMessage, error: string) => void
-
id
string
-
Сообщение
-
ошибка
string
-
onUIEvent
browser.vpnProvider.onUIEvent.addListener(
callback: function,
)
Активируется, когда в интерфейсе происходит событие, связанное с расширением. События пользовательского интерфейса – это сигналы от платформы, которые указывают приложению, что пользователю нужно показать диалоговое окно.