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 封包，任何源自 ChromeOS 裝置的封包都可以使用 onPacketReceived 事件處理常式接收。

  • 當使用者中斷 VPN 設定的連線時，系統會觸發 onPlatformMessage 並顯示「"disconnected"」訊息。

  • 如果不再需要 VPN 設定，可以呼叫 destroyConfig() 將其刪除。

類型

Parameters

屬性

  • 地址

    字串

    以 CIDR 標記法表示的 VPN 介面 IP 位址。IPv4 是目前唯一支援的模式。

  • broadcastAddress

    字串 選用

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

  • dnsServers

    string[]

    DNS 伺服器的 IP 清單。

  • domainSearch

    string[] 選填

    搜尋網域清單。(預設：無搜尋網域)

  • exclusionList

    string[]

    從通道中排除以 CIDR 標記法表示的 IP 區塊清單的網路流量。可用於略過往返 VPN 伺服器的流量。如有多項規則與目的地相符，則適用前置字元最長的規則。系統會將對應至相同 CIDR 區塊的項目視為重複項目。系統會排除彙整 (exclusionList + includeList) 清單中的這種重複項目，並且排除的重複項目不會定義。

  • inclusionList

    string[]

    包含傳送至通道的 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 工作階段狀態。

列舉

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

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

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

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

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

"linkChanged"
表示預設實體網路連線已變更，例如 Wi-Fi->行動網路。

"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。

傳回

  • Promise<string>

    Chrome 96 以上版本

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

destroyConfig()

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

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

參數

  • id

    字串

    要刪除的 VPN 設定 ID。

  • 回呼

    函式選用

    callback 參數如下所示： 

    ()=>void

傳回

  • Promise<void>

    Chrome 96 以上版本

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

notifyConnectionStateChanged()

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

將 VPN 工作階段狀態通知平台。只有在擴充功能擁有 VPN 工作階段時，這項操作才會成功。

參數

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

  • 回呼

    函式選用

    callback 參數如下所示： 

    ()=>void

傳回

  • Promise<void>

    Chrome 96 以上版本

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

sendPacket()

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

透過為 VPN 工作階段建立的通道傳送 IP 封包。只有在擴充功能擁有 VPN 工作階段時，這項操作才會成功。

參數

  • 資料或曾存取這類資料的人員

    ArrayBuffer

    要傳送至平台的 IP 封包。

  • 回呼

    函式選用

    callback 參數如下所示： 

    ()=>void

傳回

  • Promise<void>

    Chrome 96 以上版本

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

setParameters()

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

設定 VPN 工作階段的參數。從平台收到 "connected" 後，應立即呼叫此方法。只有在擴充功能擁有 VPN 工作階段時，這項操作才會成功。

參數

  • 參數

    參數

    VPN 工作階段的參數。

  • 回呼

    函式選用

    callback 參數如下所示： 

    ()=>void

傳回

  • Promise<void>

    Chrome 96 以上版本

    Manifest V3 以上版本支援 Promise，但是為了提供回溯相容性而提供的回呼。您無法在同一個函式呼叫中同時使用這兩者。承諾會用傳遞至回呼的同類型解析。

活動

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