chrome/common/extensions/api/vpn_provider.idl - chromium/src - Git at Google

 // 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-&gt;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.
     [supportsPromises] 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.
     [supportsPromises] 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.
     [supportsPromises] 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.
     [supportsPromises] 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.
     [supportsPromises] 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);
   };
 };
	// 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.
	[supportsPromises] 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.
	[supportsPromises] 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.
	[supportsPromises] 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.
	[supportsPromises] 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.
	[supportsPromises] 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);
	};
	};