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     connected,
  49     disconnected,
  50     error
  51   };
  52
  53   // The enum is used by the VPN client to inform the platform
  54   // of its current state. This helps provide meaningful messages
  55   // to the user.
  56   enum VpnConnectionState {
  57     connected,
  58     failure
  59   };
  60
  61   // The callback is used by <code>setParameters, sendPacket</code>
  62   // to signal completion. The callback is called with
  63   // <code>chrome.runtime.lastError</code> set to error code if
  64   // there is an error.
  65   [inline_doc] callback CallCompleteCallback = void ();
  66
  67   interface Functions {
  68     // Creates a new VPN configuration that persists across multiple login
  69     // sessions of the user.
  70     // |name|: The name of the VPN configuration.
  71     // |callback|: Called when the configuration is created or if there is an
  72     // error.
  73     static void createConfig(DOMString name,
  74                              CallCompleteCallback callback);
  75
  76     // Destroys a VPN configuration created by the extension.
  77     // |name|: The name of the VPN configuration to destroy.
  78     // |callback|: Called when the configuration is destroyed or if there is an
  79     // error.
  80     static void destroyConfig(DOMString name,
  81                               optional CallCompleteCallback callback);
  82
  83     // Sets the parameters for the VPN session. This should be called
  84     // immediately after <code>"connected"</code> is received from the platform.
  85     // This will succeed only when the VPN session is owned by the extension.
  86     // |parameters|: The parameters for the VPN session.
  87     // |callback|: Called when the parameters are set or if there is an error.
  88     static void setParameters(Parameters parameters,
  89                               CallCompleteCallback callback);
  90
  91     // Sends an IP packet through the tunnel created for the VPN session.
  92     // This will succeed only when the VPN session is owned by the extension.
  93     // |data|: The IP packet to be sent to the platform.
  94     // |callback|: Called when the packet is sent or if there is an error.
  95     static void sendPacket(ArrayBuffer data,
  96                            optional CallCompleteCallback callback);
  97
  98     // Notifies the VPN session state to the platform.
  99     // This will succeed only when the VPN session is owned by the extension.
 100     // |state|: The VPN session state of the VPN client.
 101     // |callback|: Called when the notification is complete or if there is an
 102     // error.
 103     static void notifyConnectionStateChanged(
 104         VpnConnectionState state,
 105         optional CallCompleteCallback callback);
 106   };
 107
 108   interface Events {
 109     // Triggered when a message is received from the platform for a
 110     // VPN configuration owned by the extension.
 111     // |name|: Name of the configuration the message is intended for.
 112     // |message|: The message received from the platform.
 113     // |error|: Error message when there is an error.
 114     static void onPlatformMessage(DOMString name,
 115                                   PlatformMessage message,
 116                                   DOMString error);
 117
 118     // Triggered when an IP packet is received via the tunnel for the VPN
 119     // session owned by the extension.
 120     // |data|: The IP packet received from the platform.
 121     static void onPacketReceived(ArrayBuffer data);
 122
 123     // Triggered when a configuration created by the extension is removed by the
 124     // platform.
 125     // |name|: Name of the configuration removed.
 126     static void onConfigRemoved(DOMString name);
 127   };
 128 };