chrome.vpnProvider

说明

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

权限

vpnProvider

可用性

Chrome 43 及更高版本 仅限 ChromeOS

概念和用法

chrome.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()

Promise 
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，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

destroyConfig()

Promise 
chrome.vpnProvider.destroyConfig(
  id: string,
  callback?: function,
)

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

参数

  • id

    string

    要销毁的 VPN 配置的 ID。

  • callback

    函数（可选）

    callback 参数如下所示：

    ()=>void

返回

  • Promise<void>

    Chrome 96 及更高版本

    Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

notifyConnectionStateChanged()

Promise 
chrome.vpnProvider.notifyConnectionStateChanged(
  state: VpnConnectionState,
  callback?: function,
)

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

参数

  • VPN 客户端的 VPN 会话状态。

  • callback

    函数（可选）

    callback 参数如下所示：

    ()=>void

返回

  • Promise<void>

    Chrome 96 及更高版本

    Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

sendPacket()

Promise 
chrome.vpnProvider.sendPacket(
  data: ArrayBuffer,
  callback?: function,
)

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

参数

  • data

    ArrayBuffer

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

  • callback

    函数（可选）

    callback 参数如下所示：

    ()=>void

返回

  • Promise<void>

    Chrome 96 及更高版本

    Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。promise 使用传递给回调函数的同一类型进行解析。

setParameters()

Promise 
chrome.vpnProvider.setParameters(
  parameters: Parameters,
  callback?: function,
)

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

参数

  • 形参

    参数

    VPN 会话的参数。

  • callback

    函数（可选）

    callback 参数如下所示：

    ()=>void

返回

  • Promise<void>

    Chrome 96 及更高版本

    Manifest V3 及更高版本支持 promise，但提供回调以实现向后兼容性。您不能在同一个函数调用中同时使用这两者。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

onUIEvent

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

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

参数

  • callback

    功能

    callback 参数如下所示：

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

    • event

      UIEvent

    • id

      字符串（可选）