// Copyright 2014 The Chromium Authors. All rights reserved.
// 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.
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 {
    // VPN configuration connected.
    connected,
    // VPN configuration disconnected.
    disconnected,
    // An error occurred in VPN connection, for example a timeout. A description
    // of the error is give as the <ahref="#property-onPlatformMessage-error">
    // error argument to onPlatformMessage</a>.
    error,
    // The default physical network connection is down.
    linkDown,
    // The default physical network connection is back up.
    linkUp,
    // The default physical network connection changed, e.g. wifi-&gt;mobile.
    linkChanged,
    // 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,
    // 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 {
    // VPN connection was successful.
    connected,
    // VPN connection failed.
    failure
  };

  // The enum is used by the platform to indicate the event that triggered
  // <code>onUIEvent</code>.
  enum UIEvent {
    // Request the VPN client to show add configuration dialog to the user.
    showAddDialog,
    // Request the VPN client to show configuration settings dialog 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.
    // |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);
  };
};