chrome.vpnProvider

說明

使用 chrome.vpnProvider API 實作 VPN 用戶端。

權限

vpnProvider

可用性

Chrome 43 以上版本 僅適用於 ChromeOS

概念和用法

chrome.vpnProvider 的一般使用如下：

  • 呼叫 createConfig() 來建立 VPN 設定。VPN 設定是使用者在 ChromeOS UI 中看見的永久項目。使用者可以從清單中選取 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

    string optional

    VPN 介面的廣播位址。(預設：從 IP 位址和遮罩中推斷)

  • dnsServers

    string[]

    DNS 伺服器的 IP 清單。

  • domainSearch

    string[] 選填

    搜尋網域清單。(預設值：沒有搜尋網域)

  • exclusionList

    string[]

    從通道排除傳送至 IP 區塊清單的網路流量 (以 CIDR 標記法表示)。可用來略過傳入及傳出 VPN 伺服器的流量。當多個規則符合目的地時，相符前置字元最長的規則會勝出。系統會將對應至相同 CIDR 區塊的項目視為重複項目。系統會排除已收合 (exclusionList + includeList) 清單中包含的重複項目，且不會重複刪除的重複項目。

  • inclusionList

    string[]

    包括傳送至通道的 IP 區塊清單 (以 CIDR 標記法表示) 的網路流量。這個參數可用來設定分割通道。根據預設，所有流量都不會導向至通道。正在新增「0.0.0.0/0」項目所有的使用者流量都會重新導向至通道。當多個規則符合目的地時，相符前置字元最長的規則會勝出。系統會將對應至相同 CIDR 區塊的項目視為重複項目。系統會排除已收合 (exclusionList + includeList) 清單中包含的重複項目，且不會重複刪除的重複項目。

  • mtu

    string optional

    VPN 介面的 MTU 設定。(預設：1500 個位元組)

  • 重新連線

    string optional

    Chrome 51 以上版本

    VPN 擴充功能是否實作自動重新連線。

    如為 true，系統會使用 linkDown、linkUp、linkChanged、suspend 和 resume 平台訊息來傳送個別事件。設為 false 時，如果網路拓撲有所變更，系統會強制中斷 VPN 連線，而使用者必須手動重新連線。(預設值：false)

    這是 Chrome 51 版的新功能；就會產生例外狀況try/catch 可用於根據瀏覽器支援，有條件地啟用此功能。

PlatformMessage

平台會使用列舉值，通知用戶端 VPN 工作階段的狀態。

列舉

"已連線"
表示已連線 VPN 設定。

"已中斷連線"
表示 VPN 設定已中斷連線。

"error"
表示 VPN 連線發生錯誤，例如逾時。錯誤的說明會做為 onPlatformMessage 的錯誤引數提供。

"linkDown"
表示預設的實體網路連線已中斷。

"linkUp"
表示已備份預設實體網路連線。

"linkChanged"
表示預設實體網路連線已變更，例如。

"suspend"
表示 OS 正在準備暫停，因此 VPN 應停止連線。擴充功能不保證會在暫停前收到該事件。

"resume"
表示 OS 已繼續執行，且使用者已重新登入，因此 VPN 應嘗試重新連線。

UIEvent

平台會使用列舉來指出觸發 onUIEvent 的事件。

列舉

"showAddDialog"
要求 VPN 用戶端向使用者顯示新增設定對話方塊。

"showConfigureDialog"
要求 VPN 用戶端向使用者顯示配置設定對話方塊。

VpnConnectionState

VPN 用戶端會使用列舉值，告知平台目前的狀態。這有助於向使用者提供有意義的訊息。

列舉

"已連線"
表示 VPN 連線已成功。

"failure"
表示 VPN 連線失敗。

方法

createConfig()

Promise 
chrome.vpnProvider.createConfig(
  name: string,
  callback?: function,
)

建立新的 VPN 設定，這項設定會套用至使用者的多個登入工作階段。

參數

  • 名稱

    字串

    VPN 設定的名稱。

  • 回呼

    函式 選用

    callback 參數如下所示： 

    (id: string) => void

    • id

      字串

      所建立設定的專屬 ID，失敗時則為 undefined。

傳回

  • 承諾<字串>

    Chrome 96 以上版本

    Promise 適用於 Manifest V3 及以上版本，但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。

destroyConfig()

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

刪除擴充功能建立的 VPN 設定。

參數

  • id

    字串

    要刪除的 VPN 設定 ID。

  • 回呼

    函式 選用

    callback 參數如下所示： 

    () => void

傳回

  • 承諾<void>

    Chrome 96 以上版本

    Promise 適用於 Manifest V3 及以上版本，但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。

notifyConnectionStateChanged()

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

向平台通知 VPN 工作階段狀態。只有在 VPN 工作階段的擁有者是擴充功能時，系統才會執行這項作業。

參數

  • VPN 用戶端的 VPN 工作階段狀態。

  • 回呼

    函式 選用

    callback 參數如下所示： 

    () => void

傳回

  • 承諾<void>

    Chrome 96 以上版本

    Promise 適用於 Manifest V3 及以上版本，但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。

sendPacket()

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

透過為 VPN 工作階段建立的通道，傳送 IP 封包。只有在 VPN 工作階段的擁有者是擴充功能時，系統才會執行這項作業。

參數

  • 資料

    ArrayBuffer

    要傳送至平台的 IP 封包。

  • 回呼

    函式 選用

    callback 參數如下所示： 

    () => void

傳回

  • 承諾<void>

    Chrome 96 以上版本

    Promise 適用於 Manifest V3 及以上版本，但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。

setParameters()

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

設定 VPN 工作階段的參數。從平台收到 "connected" 後，應立即呼叫這個方法。只有在 VPN 工作階段的擁有者是擴充功能時，系統才會執行這項作業。

參數

  • parameters

    參數

    VPN 工作階段的參數。

  • 回呼

    函式 選用

    callback 參數如下所示： 

    () => void

傳回

  • 承諾<void>

    Chrome 96 以上版本

    Promise 適用於 Manifest V3 及以上版本，但系統會為 回溯相容性您無法在同一函式呼叫中同時使用兩者。 保證會以傳遞至回呼的相同類型來解析。

活動

onConfigCreated

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

在平台為擴充功能建立設定時觸發。

參數

  • 回呼

    函式

    callback 參數如下所示： 

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

    • id

      字串

    • 名稱

      字串

    • 資料

      物件

onConfigRemoved

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

當平台移除擴充功能建立的設定時觸發。

參數

  • 回呼

    函式

    callback 參數如下所示： 

    (id: string) => void

    • id

      字串

onPacketReceived

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

透過擴充功能擁有的 VPN 工作階段通道接收 IP 封包時觸發。

參數

  • 回呼

    函式

    callback 參數如下所示： 

    (data: ArrayBuffer) => void

    • 資料

      ArrayBuffer

onPlatformMessage

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

針對擴充功能擁有的 VPN 設定從平台收到訊息時觸發。

參數

  • 回呼

    函式

    callback 參數如下所示： 

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

onUIEvent

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

擴充功能有 UI 事件時觸發。UI 事件是平台提供的信號，指出應用程式需要向使用者顯示 UI 對話方塊。

參數

  • 回呼

    函式

    callback 參數如下所示： 

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

    • 活動

      UIEvent

    • id

      string optional