browser.vpnProvider

說明

使用 chrome.vpnProvider API 導入 VPN 用戶端。

權限

vpnProvider

可用性

Chrome 43 以上版本 Chrome 148 以上版本支援 browser.* 僅適用於 ChromeOS

概念和用途

browser.vpnProvider 的一般用法如下：

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

屬性

  • 地址

    字串

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

  • broadcastAddress

    字串 選填

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

  • dnsServers

    string[]

    DNS 伺服器的 IP 清單。

  • domainSearch

    string[] 選填

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

  • exclusionList

    string[]

    從通道中排除傳送至 IP 區塊清單 (以 CIDR 標記法表示) 的網路流量。這可用於略過往返 VPN 伺服器的流量。如果有多項規則符合目的地，系統會優先採用相符前置字元最長的規則。對應至相同 CIDR 區塊的項目會視為重複項目。系統會從整理過的清單 (exclusionList + inclusionList) 中移除這類重複項目，但不會定義要移除的確切重複項目。

  • inclusionList

    string[]

    將網路流量納入以 CIDR 標記法表示的 IP 區塊清單，並傳送至通道。這個參數可用來設定分割通道。根據預設，系統不會將任何流量導向通道。將「0.0.0.0/0」項目新增至這份清單，即可將所有使用者流量重新導向至通道。如果有多項規則符合目的地，系統會優先採用相符前置字元最長的規則。對應至相同 CIDR 區塊的項目會視為重複項目。系統會從整理過的清單 (exclusionList + inclusionList) 中移除這類重複項目，但不會定義要移除的確切重複項目。

  • mtu

    字串 選填

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

  • 重新連結

    字串 選填

    Chrome 51 以上版本 Chrome 148 以上版本為 browser.*

    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」
表示 OS 準備暫停，因此 VPN 應中斷連線。擴充功能不一定會在暫停前收到這個事件。

"resume"
表示 OS 已恢復運作，且使用者已重新登入，因此 VPN 應嘗試重新連線。

UIEvent

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

列舉

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

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

VpnConnectionState

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

列舉

"connected"
表示 VPN 連線成功。

"failure"
指定 VPN 連線失敗。

方法

createConfig()

browser.vpnProvider.createConfig(
  name: string,
): Promise<string>

建立新的 VPN 設定，在使用者多次登入工作階段中持續有效。

參數

  • 名稱

    字串

    VPN 設定名稱。

傳回

  • Promise<string>

    Chrome 96 以上版本 Chrome 148 以上版本中的 browser.*

    傳回 Promise，在設定建立完成時解析，或在發生錯誤時拒絕。

destroyConfig()

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

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

參數

  • id

    字串

    要刪除的 VPN 設定 ID。

傳回

  • 承諾<void>

    Chrome 96 以上版本 Chrome 148 以上版本中的 browser.*

    傳回 Promise，在設定刪除時解析，或在發生錯誤時拒絕。

notifyConnectionStateChanged()

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

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

參數

傳回

  • 承諾<void>

    Chrome 96 以上版本 Chrome 148 以上版本中的 browser.*

    傳回 Promise，在通知完成時解析，或在發生錯誤時拒絕。

sendPacket()

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

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

參數

  • 資料

    ArrayBuffer

    要傳送至平台的 IP 封包。

傳回

  • 承諾<void>

    Chrome 96 以上版本 Chrome 148 以上版本中的 browser.*

    傳回 Promise，在封包傳送時解析，或在發生錯誤時拒絕。

setParameters()

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

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

參數

  • parameters

    參數

    VPN 工作階段的參數。

傳回

  • 承諾<void>

    Chrome 96 以上版本 Chrome 148 以上版本中的 browser.*

    傳回 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,
)

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

參數

  • callback

    函式

    callback 參數如下： 

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