chrome.vpnProvider

说明

使用 chrome.vpnProvider API 实现 VPN 客户端。

权限

vpnProvider

可用性

Chrome 43 及更高版本 仅限 ChromeOS

概念和用法

chrome.vpnProvider 的典型用法如下：

  • 通过调用 createConfig() 创建 VPN 配置。VPN 配置是指在 ChromeOS 界面中向用户显示的持久性条目。用户可以从列表中选择 VPN 配置，并连接或断开连接。

  • 为 onPlatformMessage、onPacketReceived 和 onConfigRemoved 事件添加监听器。

  • 当用户连接到 VPN 配置时，系统会收到 onPlatformMessage，并显示消息 "connected"。"connected" 消息和 "disconnected" 消息之间的时段称为“VPN 会话”。在此时间段内，接收消息的扩展程序被视为拥有 VPN 会话。

  • 启动与 VPN 服务器的连接并启动 VPN 客户端。

  • 通过调用 setParameters() 设置连接的参数。

  • 通过调用 notifyConnectionStateChanged() 将连接状态通知为 "connected"。

  • 如果上述步骤顺利完成，系统会为 ChromeOS 的网络堆栈创建一个虚拟隧道。通过调用 sendPacket()，IP 数据包可以通过隧道发送；ChromeOS 设备上发出的任何数据包都将通过 onPacketReceived 事件处理程序接收。

  • 当用户断开与 VPN 配置的连接时，系统会触发 onPlatformMessage 并显示消息 "disconnected"。

  • 如果不再需要 VPN 配置，可以通过调用 destroyConfig() 将其销毁。

类型

Parameters

属性

  • 地址

    字符串

    VPN 接口的 IP 地址（采用 CIDR 表示法）。目前，唯一支持的模式是 IPv4。

  • broadcastAddress

    字符串（选填）

    VPN 接口的广播地址。（默认值：根据 IP 地址和掩码推断得出）

  • dnsServers

    字符串[]

    DNS 服务器的 IP 列表。

  • domainSearch

    string[] 可选

    搜索网域列表。（默认值：无搜索网域）

  • exclusionList

    字符串[]

    从隧道中排除以 CIDR 表示法表示的 IP 块列表的网络流量。这可用于绕过 VPN 服务器的传入和传出流量。如果多条规则与某个目的地匹配，则匹配前缀最长的规则胜出。对应于同一 CIDR 块的条目会被视为重复条目。系统会消除汇总列表（exclusionList + inclusionList）中的此类重复项，但具体消除哪个完全相同的重复条目是不确定的。

  • inclusionList

    字符串[]

    将网络流量（采用 CIDR 表示法）添加到隧道 IP 块列表中。此参数可用于设置拆分隧道。默认情况下，没有流量会定向到隧道。将条目“0.0.0.0/0”添加到此列表后，所有用户流量都会重定向到隧道。如果多条规则与某个目的地匹配，则匹配前缀最长的规则胜出。对应于同一 CIDR 块的条目会被视为重复条目。系统会消除汇总列表（exclusionList + inclusionList）中的此类重复项，但具体消除哪个完全相同的重复条目是不确定的。

  • mtu

    字符串（选填）

    VPN 接口的 MTU 设置。（默认值：1500 字节）

  • 重新连接

    字符串（选填）

    Chrome 51 及更高版本

    VPN 扩展程序是否实现自动重新连接。

    如果为 true，则 linkDown、linkUp、linkChanged、suspend 和 resume 平台消息将用于发出相应事件的信号。如果为 false，当网络拓扑发生变化时，系统会强制断开 VPN 连接，用户需要手动重新连接。（默认值：false）

    此属性是 Chrome 51 中的新属性；在更早的版本中，它会生成异常。try/catch 可用于根据浏览器支持情况有条件地启用该功能。

PlatformMessage

平台使用此枚举来通知客户端 VPN 会话状态。

枚举

“已连接”
表示 VPN 配置已连接。

“已断开连接”
表示 VPN 配置已断开连接。

“error”
表示 VPN 连接中发生了错误，例如超时。错误说明作为 onPlatformMessage 的 error 实参提供。

“linkDown”
表示默认物理网络连接已断开。

“linkUp”
表示默认的物理网络连接已恢复。

“linkChanged”
表示默认的物理网络连接已更改，例如从 WLAN 更改为移动网络。

“暂停”
表示操作系统正在准备暂停，因此 VPN 应断开连接。无法保证扩展程序在暂停之前收到此事件。

“resume”
表示操作系统已恢复，用户已重新登录，因此 VPN 应尝试重新连接。

UIEvent

平台使用此枚举来指明触发 onUIEvent 的事件。

枚举

“showAddDialog”
请求 VPN 客户端向用户显示添加配置对话框。

“showConfigureDialog”
请求 VPN 客户端向用户显示配置设置对话框。

VpnConnectionState

VPN 客户端使用此枚举向平台告知其当前状态。这有助于向用户提供有意义的消息。

枚举

“已连接”
指定 VPN 连接成功。

“失败”
指定 VPN 连接失败。

方法

createConfig()

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

创建新的 VPN 配置，该配置在用户的多个登录会话中保持不变。

参数

  • name

    字符串

    VPN 配置的名称。

返回

  • Promise<string>

    Chrome 96 及更高版本

destroyConfig()

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

销毁扩展程序创建的 VPN 配置。

参数

  • id

    字符串

    要销毁的 VPN 配置的 ID。

返回

  • Promise<void>

    Chrome 96 及更高版本

notifyConnectionStateChanged()

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

向平台通知 VPN 会话状态。只有当 VPN 会话归扩展程序所有时，此方法才会成功。

参数

返回

  • Promise<void>

    Chrome 96 及更高版本

sendPacket()

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

通过为 VPN 会话创建的隧道发送 IP 数据包。只有当 VPN 会话归扩展程序所有时，此方法才会成功。

参数

  • 数据

    ArrayBuffer

    要发送到平台的 IP 数据包。

返回

  • Promise<void>

    Chrome 96 及更高版本

setParameters()

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

设置 VPN 会话的参数。应在从平台收到 "connected" 后立即调用此方法。只有当 VPN 会话归扩展程序所有时，此方法才会成功。

参数

  • 参数

    参数

    VPN 会话的参数。

返回

  • Promise<void>

    Chrome 96 及更高版本

事件

onConfigCreated

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

当平台为扩展程序创建配置时触发。

参数

  • callback

    函数

    callback 参数如下所示： 

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

    • id

      字符串

    • name

      字符串

    • 数据

      对象

onConfigRemoved

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

当扩展程序创建的配置被平台移除时触发。

参数

  • callback

    函数

    callback 参数如下所示： 

    (id: string) => void

    • id

      字符串

onPacketReceived

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

当通过隧道接收到扩展程序所拥有的 VPN 会话的 IP 数据包时触发。

参数

  • callback

    函数

    callback 参数如下所示： 

    (data: ArrayBuffer) => void

    • 数据

      ArrayBuffer

onPlatformMessage

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

当从平台收到扩展程序所拥有的 VPN 配置的消息时触发。

参数

  • callback

    函数

    callback 参数如下所示： 

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

onUIEvent

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

当扩展程序发生界面事件时触发。界面事件是来自平台的信号，用于向应用表明需要向用户显示界面对话框。

参数

  • callback

    函数

    callback 参数如下所示： 

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

    • 事件

      UIEvent

    • id

      字符串（选填）