browser.vpnProvider

说明

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

权限

vpnProvider

可用性

Chrome 43 及更高版本 browser.*（自 Chrome 148 起） 仅限 ChromeOS

概念和用法

browser.vpnProvider 的典型用法如下：

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

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

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

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

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

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

  • 如果上述步骤顺利完成，系统会创建一条通往 ChromeOS 网络栈的虚拟隧道。您可以通过调用 sendPacket() 通过隧道发送 IP 数据包，并且可以使用 onPacketReceived 事件处理脚本接收源自 ChromeOS 设备的任何数据包。

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

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

类型

Parameters

属性

  • 地址

    字符串

    VPN 接口的 IP 地址（采用 CIDR 表示法）。目前仅支持 IPv4。

  • broadcastAddress

    字符串 可选

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

  • dnsServers

    字符串[]

    DNS 服务器的 IP 列表。

  • domainSearch

    string[] 可选

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

  • exclusionList

    字符串[]

    从隧道中排除流向 IP 地址块列表（采用 CIDR 表示法）的网络流量。这可用于绕过进出 VPN 服务器的流量。当多条规则与某个目标匹配时，匹配前缀最长的规则胜出。对应于同一 CIDR 块的条目会被视为重复条目。系统会消除整理后的列表（exclusionList + inclusionList）中的此类重复项，但不会定义要消除的确切重复条目。

  • inclusionList

    字符串[]

    将流向以 CIDR 表示法表示的 IP 地址块列表的网络流量纳入隧道。此参数可用于设置拆分隧道。默认情况下，不会将任何流量定向到隧道。向此列表中添加条目“0.0.0.0/0”后，所有用户流量都会重定向到隧道。当多条规则与某个目标匹配时，匹配前缀最长的规则胜出。对应于同一 CIDR 块的条目会被视为重复条目。系统会从整理后的列表（exclusionList + inclusionList）中移除此类重复项，但不会指定要移除的确切重复条目。

  • mtu

    字符串 可选

    VPN 接口的 MTU 设置。（默认值：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 连接中发生了错误，例如超时。错误说明会作为错误参数提供给 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

    字符串

    VPN 配置的名称。

返回

  • Promise<string>

    Chrome 96 及更高版本 browser.*（自 Chrome 148 起）

    返回一个 Promise，该 Promise 会在配置创建成功时解析，或在发生错误时拒绝。

destroyConfig()

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

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

参数

  • id

    字符串

    要销毁的 VPN 配置的 ID。

返回

  • 承诺<void>

    Chrome 96 及更高版本 browser.*（自 Chrome 148 起）

    返回一个 Promise，该 Promise 会在配置销毁时解析，或者在出错时拒绝。

notifyConnectionStateChanged()

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

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

参数

返回

  • 承诺<void>

    Chrome 96 及更高版本 browser.*（自 Chrome 148 起）

    返回一个 Promise，该 Promise 会在通知完成时解析，或在出现错误时拒绝。

sendPacket()

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

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

参数

  • 数据

    ArrayBuffer

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

返回

  • 承诺<void>

    Chrome 96 及更高版本 browser.*（自 Chrome 148 起）

    返回一个 Promise，该 Promise 会在数据包发送时解析，或在发生错误时拒绝。

setParameters()

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

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

参数

  • 参数

    参数

    VPN 会话的参数。

返回

  • 承诺<void>

    Chrome 96 及更高版本 browser.*（自 Chrome 148 起）

    返回一个 Promise，该 Promise 会在参数设置成功时解析，或在发生错误时拒绝。

事件

onConfigCreated

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

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

参数

  • callback

    函数

    callback 参数如下所示： 

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

    • id

      字符串

    • name

      字符串

    • 数据

      对象

onConfigRemoved

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

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

参数

  • callback

    函数

    callback 参数如下所示： 

    (id: string) => void

    • id

      字符串

onPacketReceived

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

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

参数

  • callback

    函数

    callback 参数如下所示： 

    (data: ArrayBuffer) => void

    • 数据

      ArrayBuffer

onPlatformMessage

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

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

参数

  • callback

    函数

    callback 参数如下所示： 

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

onUIEvent

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

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

参数

  • callback

    函数

    callback 参数如下所示： 

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

    • 事件

      UIEvent

    • id

      字符串 可选