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 网络堆栈的虚拟隧道。IP 数据包可通过调用 sendPacket() 通过隧道发送，而源自 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 +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"
表示默认物理网络连接发生了更改，例如“Wi-Fi”->“移动”。

"suspend"
表示操作系统正准备挂起，因此 VPN 应断开连接。我们不保证该扩展程序在暂停之前会收到此事件。

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

UIEvent

平台会使用枚举来指示触发了 onUIEvent 的事件。

枚举

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

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

VpnConnectionState

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

枚举

"Connected"
表示 VPN 连接成功。

"failure"
指定 VPN 连接失败。

方法

createConfig()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.vpnProvider.createConfig(
  name: string,
  callback?: function,
)

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

参数

  • name

    字符串

    VPN 配置的名称。

  • callback

    函数（可选）

    callback 参数如下所示： 

    (id: string) => void

    • id

      字符串

      所创建配置的唯一 ID，如果创建失败，则为 undefined。

返回

  • 承诺<字符串>

    Chrome 96 及更高版本

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

destroyConfig()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.vpnProvider.destroyConfig(
  id: string,
  callback?: function,
)

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

参数

  • id

    字符串

    要销毁的 VPN 配置的 ID。

  • callback

    函数（可选）

    callback 参数如下所示： 

    () => void

返回

  • 承诺<void>

    Chrome 96 及更高版本

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

notifyConnectionStateChanged()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.vpnProvider.notifyConnectionStateChanged(
  state: VpnConnectionState,
  callback?: function,
)

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

参数

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

  • callback

    函数（可选）

    callback 参数如下所示： 

    () => void

返回

  • 承诺<void>

    Chrome 96 及更高版本

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

sendPacket()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.vpnProvider.sendPacket(
  data: ArrayBuffer,
  callback?: function,
)

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

参数

  • 数据

    ArrayBuffer

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

  • callback

    函数（可选）

    callback 参数如下所示： 

    () => void

返回

  • 承诺<void>

    Chrome 96 及更高版本

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

setParameters()

<ph type="x-smartling-placeholder"></ph> 承诺 
chrome.vpnProvider.setParameters(
  parameters: Parameters,
  callback?: function,
)

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

参数

  • 参数

    参数

    VPN 会话的参数。

  • callback

    函数（可选）

    callback 参数如下所示： 

    () => void

返回

  • 承诺<void>

    Chrome 96 及更高版本

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

事件

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

      字符串（可选）