extensions/common/api/vpn_provider.idl

   1 // Copyright 2014 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 // Use the <code>chrome.vpnProvider</code> API to implement a VPN
   6 // client.
   7 namespace vpnProvider {
   8   // A parameters class for the VPN interface.
   9   dictionary Parameters {
  10     // IP address for the VPN interface in CIDR notation.
  11     // IPv4 is currently the only supported mode.
  12     DOMString address;
  13     // Broadcast address for the VPN interface. (default: deduced
  14     // from IP address and mask)
  15     DOMString? broadcastAddress;
  16     // MTU setting for the VPN interface. (default: 1500 bytes)
  17     DOMString? mtu;
  18     // Exclude network traffic to the list of IP blocks in CIDR notation from
  19     // the tunnel. This can be used to bypass traffic to and from the VPN
  20     // server.
  21     // When many rules match a destination, the rule with the longest matching
  22     // prefix wins.
  23     // Entries that correspond to the same CIDR block are treated as duplicates.
  24     // Such duplicates in the collated (exclusionList + inclusionList) list are
  25     // eliminated and the exact duplicate entry that will be eliminated is
  26     // undefined.
  27     DOMString[] exclusionList;
  28     // Include network traffic to the list of IP blocks in CIDR notation to the
  29     // tunnel. This parameter can be used to set up a split tunnel. By default
  30     // no traffic is directed to the tunnel. Adding the entry "0.0.0.0/0" to
  31     // this list gets all the user traffic redirected to the tunnel.
  32     // When many rules match a destination, the rule with the longest matching
  33     // prefix wins.
  34     // Entries that correspond to the same CIDR block are treated as duplicates.
  35     // Such duplicates in the collated (exclusionList + inclusionList) list are
  36     // eliminated and the exact duplicate entry that will be eliminated is
  37     // undefined.
  38     DOMString[] inclusionList;
  39     // A list of search domains. (default: no search domain)
  40     DOMString[]? domainSearch;
  41     // A list of IPs for the DNS servers.
  42     DOMString[] dnsServers;
  43   };
  44
  45   // The enum is used by the platform to notify the client of the VPN session
  46   // status.
  47   enum PlatformMessage {
  48     // VPN configuration connected.
  49     connected,
  50     // VPN configuration disconnected.
  51     disconnected,
  52     // An error occurred in VPN connection, for example a timeout. A description
  53     // of the error is give as the <ahref="#property-onPlatformMessage-error">
  54     // error argument to onPlatformMessage</a>.
  55     error
  56   };
  57
  58   // The enum is used by the VPN client to inform the platform
  59   // of its current state. This helps provide meaningful messages
  60   // to the user.
  61   enum VpnConnectionState {
  62     // VPN connection was successful.
  63     connected,
  64     // VPN connection failed.
  65     failure
  66   };
  67
  68   // The enum is used by the platform to indicate the event that triggered
  69   // <code>onUIEvent</code>.
  70   enum UIEvent {
  71     // Request the VPN client to show add configuration dialog to the user.
  72     showAddDialog,
  73     // Request the VPN client to show configuration settings dialog to the user.
  74     showConfigureDialog
  75   };
  76
  77   // The callback is used by <code>setParameters, sendPacket</code>
  78   // to signal completion. The callback is called with
  79   // <code>chrome.runtime.lastError</code> set to error code if
  80   // there is an error.
  81   [inline_doc] callback CallCompleteCallback = void ();
  82
  83   // The callback is used by <code>createConfig</code> to signal completion.
  84   // The callback is called with <code>chrome.runtime.lastError</code> set to
  85   // an error code if there is an error.
  86   // |id|: A unique ID for the created configuration, empty string on failure.
  87   [inline_doc] callback CreateConfigCompleteCallback = void (DOMString id);
  88
  89   interface Functions {
  90     // Creates a new VPN configuration that persists across multiple login
  91     // sessions of the user.
  92     // |name|: The name of the VPN configuration.
  93     // |callback|: Called when the configuration is created or if there is an
  94     // error.
  95     static void createConfig(DOMString name,
  96                              CreateConfigCompleteCallback callback);
  97
  98     // Destroys a VPN configuration created by the extension.
  99     // |id|: ID of the VPN configuration to destroy.
 100     // |callback|: Called when the configuration is destroyed or if there is an
 101     // error.
 102     static void destroyConfig(DOMString id,
 103                               optional CallCompleteCallback callback);
 104
 105     // Sets the parameters for the VPN session. This should be called
 106     // immediately after <code>"connected"</code> is received from the platform.
 107     // This will succeed only when the VPN session is owned by the extension.
 108     // |parameters|: The parameters for the VPN session.
 109     // |callback|: Called when the parameters are set or if there is an error.
 110     static void setParameters(Parameters parameters,
 111                               CallCompleteCallback callback);
 112
 113     // Sends an IP packet through the tunnel created for the VPN session.
 114     // This will succeed only when the VPN session is owned by the extension.
 115     // |data|: The IP packet to be sent to the platform.
 116     // |callback|: Called when the packet is sent or if there is an error.
 117     static void sendPacket(ArrayBuffer data,
 118                            optional CallCompleteCallback callback);
 119
 120     // Notifies the VPN session state to the platform.
 121     // This will succeed only when the VPN session is owned by the extension.
 122     // |state|: The VPN session state of the VPN client.
 123     // |callback|: Called when the notification is complete or if there is an
 124     // error.
 125     static void notifyConnectionStateChanged(
 126         VpnConnectionState state,
 127         optional CallCompleteCallback callback);
 128   };
 129
 130   interface Events {
 131     // Triggered when a message is received from the platform for a
 132     // VPN configuration owned by the extension.
 133     // |id|: ID of the configuration the message is intended for.
 134     // |message|: The message received from the platform.
 135     // |error|: Error message when there is an error.
 136     static void onPlatformMessage(DOMString id,
 137                                   PlatformMessage message,
 138                                   DOMString error);
 139
 140     // Triggered when an IP packet is received via the tunnel for the VPN
 141     // session owned by the extension.
 142     // |data|: The IP packet received from the platform.
 143     static void onPacketReceived(ArrayBuffer data);
 144
 145     // Triggered when a configuration created by the extension is removed by the
 146     // platform.
 147     // |id|: ID of the removed configuration.
 148     static void onConfigRemoved(DOMString id);
 149
 150     // Triggered when a configuration is created by the platform for the
 151     // extension.
 152     // |id|: ID of the configuration created.
 153     // |name|: Name of the configuration created.
 154     // |data|: Configuration data provided by the administrator.
 155     static void onConfigCreated(DOMString id, DOMString name, object data);
 156
 157     // Triggered when there is a UI event for the extension. UI events are
 158     // signals from the platform that indicate to the app that a UI dialog
 159     // needs to be shown to the user.
 160     // |event|: The UI event that is triggered.
 161     // |id|: ID of the configuration for which the UI event was triggered.
 162     static void onUIEvent(UIEvent event, optional DOMString id);
 163   };
 164 };