// Copyright 2014 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
// Use the <code>chrome.vpnProvider</code> API to implement a VPN
// client.
[platforms=("chromeos", "lacros"),
implemented_in="chrome/browser/chromeos/extensions/vpn_provider/vpn_provider_api.h"]
namespace vpnProvider {
// A parameters class for the VPN interface.
dictionary Parameters {
// IP address for the VPN interface in CIDR notation.
// IPv4 is currently the only supported mode.
DOMString address;
// Broadcast address for the VPN interface. (default: deduced
// from IP address and mask)
DOMString? broadcastAddress;
// MTU setting for the VPN interface. (default: 1500 bytes)
DOMString? mtu;
// Exclude network traffic to the list of IP blocks in CIDR notation from
// the tunnel. This can be used to bypass traffic to and from the VPN
// server.
// When many rules match a destination, the rule with the longest matching
// prefix wins.
// Entries that correspond to the same CIDR block are treated as duplicates.
// Such duplicates in the collated (exclusionList + inclusionList) list are
// eliminated and the exact duplicate entry that will be eliminated is
// undefined.
DOMString[] exclusionList;
// Include network traffic to the list of IP blocks in CIDR notation to the
// tunnel. This parameter can be used to set up a split tunnel. By default
// no traffic is directed to the tunnel. Adding the entry "0.0.0.0/0" to
// this list gets all the user traffic redirected to the tunnel.
// When many rules match a destination, the rule with the longest matching
// prefix wins.
// Entries that correspond to the same CIDR block are treated as duplicates.
// Such duplicates in the collated (exclusionList + inclusionList) list are
// eliminated and the exact duplicate entry that will be eliminated is
// undefined.
DOMString[] inclusionList;
// A list of search domains. (default: no search domain)
DOMString[]? domainSearch;
// A list of IPs for the DNS servers.
DOMString[] dnsServers;
// Whether or not the VPN extension implements auto-reconnection.
//
// If true, the <code>linkDown</code>, <code>linkUp</code>,
// <code>linkChanged</code>, <code>suspend</code>, and <code>resume</code>
// platform messages will be used to signal the respective events.
// If false, the system will forcibly disconnect the VPN if the network
// topology changes, and the user will need to reconnect manually.
// (default: false)
//
// This property is new in Chrome 51; it will generate an exception in
// earlier versions. try/catch can be used to conditionally enable the
// feature based on browser support.
DOMString? reconnect;
};
// The enum is used by the platform to notify the client of the VPN session
// status.
enum PlatformMessage {
// Indicates that the VPN configuration connected.
connected,
// Indicates that the VPN configuration disconnected.
disconnected,
// Indicates that an error occurred in VPN connection, for example a timeout. A description
// of the error is given as the <a href="#property-onPlatformMessage-error">
// error argument to onPlatformMessage</a>.
error,
// Indicates that the default physical network connection is down.
linkDown,
// Indicates that the default physical network connection is back up.
linkUp,
// Indicates that the default physical network connection changed, e.g. wifi->mobile.
linkChanged,
// Indicates that the OS is preparing to suspend, so the VPN should drop its connection.
// The extension is not guaranteed to receive this event prior to
// suspending.
suspend,
// Indicates that the OS has resumed and the user has logged back in, so the VPN should
// try to reconnect.
resume
};
// The enum is used by the VPN client to inform the platform
// of its current state. This helps provide meaningful messages
// to the user.
enum VpnConnectionState {
// Specifies that VPN connection was successful.
connected,
// Specifies that VPN connection has failed.
failure
};
// The enum is used by the platform to indicate the event that triggered
// <code>onUIEvent</code>.
enum UIEvent {
// Requests that the VPN client show the add configuration dialog box to
// the user.
showAddDialog,
// Requests that the VPN client show the configuration settings dialog box
// to the user.
showConfigureDialog
};
// The callback is used by <code>setParameters, sendPacket</code>
// to signal completion. The callback is called with
// <code>chrome.runtime.lastError</code> set to error code if
// there is an error.
[inline_doc] callback CallCompleteCallback = void ();
// The callback is used by <code>createConfig</code> to signal completion.
// The callback is called with <code>chrome.runtime.lastError</code> set to
// an error code if there is an error.
// |id|: A unique ID for the created configuration, or <code>undefined</code>
// on failure.
[inline_doc] callback CreateConfigCompleteCallback = void (DOMString id);
interface Functions {
// Creates a new VPN configuration that persists across multiple login
// sessions of the user.
// |name|: The name of the VPN configuration.
// |callback|: Called when the configuration is created or if there is an
// error.
static void createConfig(
DOMString name,
CreateConfigCompleteCallback callback);
// Destroys a VPN configuration created by the extension.
// |id|: ID of the VPN configuration to destroy.
// |callback|: Called when the configuration is destroyed or if there is an
// error.
static void destroyConfig(
DOMString id,
optional CallCompleteCallback callback);
// Sets the parameters for the VPN session. This should be called
// immediately after <code>"connected"</code> is received from the platform.
// This will succeed only when the VPN session is owned by the extension.
// |parameters|: The parameters for the VPN session.
// |callback|: Called when the parameters are set or if there is an error.
static void setParameters(
Parameters parameters,
CallCompleteCallback callback);
// Sends an IP packet through the tunnel created for the VPN session.
// This will succeed only when the VPN session is owned by the extension.
// |data|: The IP packet to be sent to the platform.
// |callback|: Called when the packet is sent or if there is an error.
static void sendPacket(
ArrayBuffer data,
optional CallCompleteCallback callback);
// Notifies the VPN session state to the platform.
// This will succeed only when the VPN session is owned by the extension.
// |state|: The VPN session state of the VPN client.
// |callback|: Called when the notification is complete or if there is an
// error.
static void notifyConnectionStateChanged(
VpnConnectionState state,
optional CallCompleteCallback callback);
};
interface Events {
// Triggered when a message is received from the platform for a
// VPN configuration owned by the extension.
// |id|: ID of the configuration the message is intended for.
// |message|: The message received from the platform. Note that new
// message types may be added in future Chrome versions to support new
// features.
// |error|: Error message when there is an error.
static void onPlatformMessage(DOMString id,
PlatformMessage message,
DOMString error);
// Triggered when an IP packet is received via the tunnel for the VPN
// session owned by the extension.
// |data|: The IP packet received from the platform.
static void onPacketReceived(ArrayBuffer data);
// Triggered when a configuration created by the extension is removed by the
// platform.
// |id|: ID of the removed configuration.
static void onConfigRemoved(DOMString id);
// Triggered when a configuration is created by the platform for the
// extension.
// |id|: ID of the configuration created.
// |name|: Name of the configuration created.
// |data|: Configuration data provided by the administrator.
static void onConfigCreated(DOMString id, DOMString name, object data);
// Triggered when there is a UI event for the extension. UI events are
// signals from the platform that indicate to the app that a UI dialog
// needs to be shown to the user.
// |event|: The UI event that is triggered.
// |id|: ID of the configuration for which the UI event was triggered.
static void onUIEvent(UIEvent event, optional DOMString id);
};
};
Codebase Browser
chromium