chrome.vpnProvider

説明

chrome.vpnProvider API を使用して VPN クライアントを実装します。

権限

vpnProvider

対象

Chrome 43 以降 ChromeOS のみ

コンセプトと使用方法

chrome.vpnProvider の一般的な使用方法は次のとおりです。

  • createConfig() を呼び出して VPN 構成を作成します。VPN 構成は、ChromeOS UI でユーザーに表示される永続的なエントリです。ユーザーはリストから VPN 構成を選択して、接続または切断できます。

  • onPlatformMessage、onPacketReceived、onConfigRemoved の各イベントにリスナーを追加します。

  • ユーザーが VPN 構成に接続すると、メッセージ "connected" とともに onPlatformMessage が受信されます。"connected" メッセージと "disconnected" メッセージの間の期間は「VPN セッション」と呼ばれます。この期間中、メッセージを受信する拡張機能が VPN セッションを所有していると見なされます。

  • VPN サーバーへの接続を開始し、VPN クライアントを起動します。

  • setParameters() を呼び出して、接続のパラメータを設定します。

  • notifyConnectionStateChanged() を呼び出して、接続状態を "connected" として通知します。

  • 上記の手順がエラーなく完了すると、ChromeOS のネットワーク スタックに仮想トンネルが作成されます。sendPacket() を呼び出すことで、IP パケットをトンネル経由で送信できます。ChromeOS デバイスから発信されたパケットは、onPacketReceived イベント ハンドラを使用して受信されます。

  • ユーザーが VPN 構成から切断すると、メッセージ "disconnected" で onPlatformMessage が起動します。

  • VPN 構成が不要になった場合は、destroyConfig() を呼び出して破棄できます。

型

Parameters

プロパティ

  • 住所

    文字列

    VPN インターフェースの IP アドレス（CIDR 表記）。現在サポートされているモードは IPv4 のみです。

  • broadcastAddress

    文字列 省略可

    VPN インターフェースのブロードキャスト アドレス。（デフォルト: IP アドレスとマスクから推測）

  • dnsServers

    string[]

    DNS サーバーの IP のリスト。

  • domainSearch

    string[] 省略可

    検索ドメインのリスト。（デフォルト: 検索ドメインなし）

  • exclusionList

    string[]

    CIDR 表記の IP ブロックのリストへのネットワーク トラフィックをトンネルから除外します。これは、VPN サーバーとの間のトラフィックをバイパスするために使用できます。多くのルールが宛先と一致する場合、一致するプレフィックスが最も長いルールが優先されます。同じ CIDR ブロックに対応するエントリは重複として扱われます。照合された（exclusionList + inclusionList）リスト内の重複は削除されます。削除される重複エントリは未定義です。

  • inclusionList

    string[]

    CIDR 表記の IP ブロックのリストに、トンネルへのネットワーク トラフィックを含めます。このパラメータは、スプリット トンネルの設定に使用できます。デフォルトでは、トラフィックはトンネルに転送されません。このリストに「0.0.0.0/0」というエントリを追加すると、すべてのユーザー トラフィックがトンネルにリダイレクトされます。多くのルールが宛先と一致する場合、一致するプレフィックスが最も長いルールが優先されます。同じ CIDR ブロックに対応するエントリは重複として扱われます。照合された（exclusionList + inclusionList）リスト内の重複は削除されます。削除される重複エントリは未定義です。

  • mtu

    文字列 省略可

    VPN インターフェースの MTU 設定。（デフォルト: 1,500 バイト）

  • 再接続

    文字列 省略可

    Chrome 51 以降

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

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

ユーザーの複数のログイン セッションにわたって保持される新しい VPN 構成を作成します。

パラメータ

  • name

    文字列

    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 セッションが拡張機能によって所有されている場合にのみ成功します。

パラメータ

戻り値

  • 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

    • イベント

      UIEvent

    • id

      文字列 省略可