说明
使用 chrome.vpnProvider
API 实现 VPN 客户端。
权限
vpnProvider
可用性
用量
vpnProvider 的典型用法如下:
使用
createConfig
方法创建 VPN 配置。VPN 配置是在原生 ChromeOS 界面中向用户显示的持久性条目。用户可以从列表中选择一项 VPN 配置,然后连接或断开连接。为
onPlatformMessage
、onPacketReceived
和onConfigRemoved
事件添加监听器。当用户连接到 VPN 配置时,会收到包含
"connected"
消息的onPlatformMessage
。我们将消息"connected"
和"disconnected"
之间的时间段称为 VPN 会话。在此时间段内,系统会说接收消息的扩展程序拥有该 VPN 会话。发起与 VPN 服务器的连接,并启动 VPN 客户端。
使用
setParameters
设置连接的参数。使用
notifyConnectionStateChanged
将连接状态通知为"connected"
。如果上述步骤顺利完成,且未出现错误,系统会创建通向 ChromeOS 网络堆栈的虚拟隧道。您可以使用
sendPacket
通过隧道发送 IP 数据包,而系统将使用事件onPacketReceived
接收源自 ChromeOS 设备的所有数据包。当用户断开 VPN 配置连接时,会触发
onPlatformMessage
并显示消息"disconnected"
。如果不再需要 VPN 配置,可以使用
destroyConfig
将其销毁。
类型
Parameters
属性
-
地址
string
VPN 接口的 IP 地址(采用 CIDR 表示法)。IPv4 是目前唯一受支持的模式。
-
broadcastAddress
字符串(可选)
VPN 接口的广播地址。(默认值:根据 IP 地址和掩码推导出)
-
dnsServers
字符串[]
DNS 服务器的 IP 列表。
-
domainSearch
string[] 可选
搜索网域列表。(默认:无搜索域)
-
exclusionList
字符串[]
将来自隧道的网络流量排除(采用 CIDR 表示法的 IP 地址块列表)。这可用于绕过进出 VPN 服务器的流量。如果有许多规则与某个目标匹配,则匹配前缀最长的规则胜出。与同一 CIDR 地址块对应的条目将被视为重复项。整理 (exclusionList + includeList) 列表中的此类重复条目会被排除,并且要去除的确切重复条目未定义。
-
inclusionList
字符串[]
将网络流量包括到隧道的 IP 地址块列表(采用 CIDR 表示法)。此参数可用于设置拆分隧道。默认情况下,不会有任何流量定向到隧道。向此列表中添加条目“0.0.0.0/0”可将所有用户流量重定向到隧道。如果有许多规则与某个目标匹配,则匹配前缀最长的规则胜出。与同一 CIDR 地址块对应的条目将被视为重复项。整理 (exclusionList + includeList) 列表中的此类重复条目会被排除,并且要去除的确切重复条目未定义。
-
mtu
字符串(可选)
VPN 接口的 MTU 设置。(默认:1500 字节)
-
重新连接
字符串(可选)
Chrome 51 及更高版本VPN 扩展程序是否实现了自动重新连接。
如果为 true,则
linkDown
、linkUp
、linkChanged
、suspend
和resume
平台消息将用于指示相应的事件。如果为 false,如果网络拓扑发生变化,系统将强制断开 VPN 连接,并且用户需要手动重新连接。(默认值:false)此属性是 Chrome 51 中的新增属性,在之前的版本中会形成例外情况。try/catch 可用于根据浏览器的支持情况有条件地启用该功能。
PlatformMessage
平台会使用枚举将 VPN 会话状态告知客户端。
枚举
"Connected"
表示 VPN 配置已连接。
"disconnect"
表示 VPN 配置已断开连接。
"error"
表示 VPN 连接中发生了错误,例如超时。错误描述以错误参数的形式提供给 onPlatformMessage。
"linkDown"
表示默认物理网络连接已断开。
"linkUp"
表示默认物理网络连接已恢复。
"linkChanged"
表示默认物理网络连接已更改,如 WiFi->mobile。
"suspend"
表示操作系统正在准备挂起,因此 VPN 应断开连接。在暂停之前,我们不保证该扩展程序一定会收到此事件。
"resume"
表示操作系统已恢复,且用户已重新登录,因此 VPN 应尝试重新连接。
UIEvent
平台会使用枚举来指示触发 onUIEvent
的事件。
枚举
"showAddDialog"
请求 VPN 客户端向用户显示添加配置对话框。
"showConfigureDialog"
请求 VPN 客户端向用户显示配置设置对话框。
VpnConnectionState
VPN 客户端使用枚举来告知平台其当前状态。这有助于向用户提供有意义的消息。
枚举
"Connected"
指定 VPN 连接成功。
"failure"
指定 VPN 连接失败。
方法
createConfig()
chrome.vpnProvider.createConfig(
name: string,
callback?: function,
)
创建可在用户的多个登录会话中持续有效的新 VPN 配置。
参数
-
name
string
VPN 配置的名称。
-
callback
函数(可选)
callback
参数如下所示:(id: string) => void
-
id
string
所创建配置的唯一 ID,如果失败,则为
undefined
。
-
返回
-
Promise<string>
Chrome 96 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
destroyConfig()
chrome.vpnProvider.destroyConfig(
id: string,
callback?: function,
)
销毁扩展程序创建的 VPN 配置。
参数
-
id
string
要销毁的 VPN 配置的 ID。
-
callback
函数(可选)
callback
参数如下所示:() => void
返回
-
Promise<void>
Chrome 96 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
notifyConnectionStateChanged()
chrome.vpnProvider.notifyConnectionStateChanged(
state: VpnConnectionState,
callback?: function,
)
将 VPN 会话状态通知平台。只有当 VPN 会话归扩展程序所有时,此操作才能成功。
参数
-
state
VPN 客户端的 VPN 会话状态。
-
callback
函数(可选)
callback
参数如下所示:() => void
返回
-
Promise<void>
Chrome 96 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
sendPacket()
chrome.vpnProvider.sendPacket(
data: ArrayBuffer,
callback?: function,
)
通过为 VPN 会话创建的隧道发送 IP 数据包。只有当 VPN 会话归扩展程序所有时,此操作才能成功。
参数
-
data
ArrayBuffer
要发送到平台的 IP 数据包。
-
callback
函数(可选)
callback
参数如下所示:() => void
返回
-
Promise<void>
Chrome 96 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
setParameters()
chrome.vpnProvider.setParameters(
parameters: Parameters,
callback?: function,
)
设置 VPN 会话的参数。此方法应在从平台收到 "connected"
后立即调用。只有当 VPN 会话归扩展程序所有时,此操作才能成功。
参数
-
形参
VPN 会话的参数。
-
callback
函数(可选)
callback
参数如下所示:() => void
返回
-
Promise<void>
Chrome 96 及更高版本只有 Manifest V3 及更高版本支持 Promise,其他平台需要使用回调。
活动
onConfigCreated
chrome.vpnProvider.onConfigCreated.addListener(
callback: function,
)
当平台为扩展程序创建配置时触发。
参数
-
callback
功能
callback
参数如下所示:(id: string, name: string, data: object) => void
-
id
string
-
name
string
-
data
对象
-
onConfigRemoved
chrome.vpnProvider.onConfigRemoved.addListener(
callback: function,
)
当平台移除扩展程序创建的配置时触发。
参数
-
callback
功能
callback
参数如下所示:(id: string) => void
-
id
string
-
onPacketReceived
chrome.vpnProvider.onPacketReceived.addListener(
callback: function,
)
当通过该扩展程序拥有的 VPN 会话的隧道收到 IP 数据包时触发。
参数
-
callback
功能
callback
参数如下所示:(data: ArrayBuffer) => void
-
data
ArrayBuffer
-
onPlatformMessage
chrome.vpnProvider.onPlatformMessage.addListener(
callback: function,
)
当从平台收到扩展程序拥有的 VPN 配置的消息时即会触发。
参数
-
callback
功能
callback
参数如下所示:(id: string, message: PlatformMessage, error: string) => void
-
id
string
-
error
string
-
onUIEvent
chrome.vpnProvider.onUIEvent.addListener(
callback: function,
)
当存在扩展程序的界面事件时触发。界面事件是来自平台的信号,用于向应用表明需要向用户显示界面对话框。