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

    字串陣列 選用

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

  • exclusionList

    string[]

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

  • inclusionList

    string[]

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

  • mtu

    字串 選填

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

  • 重新連線

    字串 選填

    Chrome 51 以上版本

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

    如果為 true，系統會使用 linkDown、linkUp、linkChanged、suspend 和 resume 平台訊息，發出相應事件的信號。如果設為 false，系統會在網路拓撲變更時強制中斷 VPN 連線，使用者必須手動重新連線。(預設值：false)

    這項屬性是 Chrome 51 的新功能，在舊版中會產生例外狀況。您可以根據瀏覽器支援情況，使用 try/catch 有條件地啟用這項功能。

PlatformMessage

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

列舉

「已連線」
表示 VPN 設定已連線。

「disconnected」
表示 VPN 設定已中斷連線。

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

「linkDown」
表示預設實體網路連線已中斷。

「linkUp」
表示預設實體網路連線已恢復運作。

「linkChanged」
表示預設實體網路連線已變更，例如從 Wi-Fi 變更為行動網路。

「暫停」
表示作業系統準備暫停，因此 VPN 應中斷連線。擴充功能不一定會在暫停前收到這個事件。

「resume」
表示作業系統已恢復運作，且使用者已重新登入，因此 VPN 應嘗試重新連線。

UIEvent

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

列舉

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

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

VpnConnectionState

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

列舉

「已連線」
指定 VPN 連線成功。

「failure」
指定 VPN 連線失敗。

方法

createConfig()

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

建立新的 VPN 設定，供使用者在多個登入工作階段中使用。

參數

  • 名稱

    字串

    VPN 設定的名稱。

傳回

  • Promise<string>

    Chrome 96 以上版本

destroyConfig()

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

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

參數

  • id

    字串

    要銷毀的 VPN 設定 ID。

傳回

  • Promise<void>

    Chrome 96 以上版本

notifyConnectionStateChanged()

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

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

參數

傳回

  • Promise<void>

    Chrome 96 以上版本

sendPacket()

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

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

參數

  • 資料

    ArrayBuffer

    要傳送至平台的 IP 封包。

傳回

  • Promise<void>

    Chrome 96 以上版本

setParameters()

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

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

參數

  • parameters

    參數

    VPN 工作階段的參數。

傳回

  • Promise<void>

    Chrome 96 以上版本

事件

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

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

參數

  • callback

    函式

    callback 參數如下： 

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