/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this file,
 * You can obtain one at http://mozilla.org/MPL/2.0/. */

#include "nsISupports.idl"

interface nsINetworkInfo;
interface nsINetworkInterface;

/**
 * Manage network interfaces.
 */
[scriptable, uuid(1ba9346b-53b5-4660-9dc6-58f0b258d0a6)]
interface nsINetworkManager : nsISupports
{
  /**
   * Register the given network interface with the network manager.
   *
   * Consumers will be notified with the 'network-interface-registered'
   * observer notification.
   *
   * Throws if there's already an interface registered with the same network id.
   *
   * @param network
   *        Network interface to register.
   */
  void registerNetworkInterface(in nsINetworkInterface network);

  /**
   * Update the routes and DNSes according the state of the given network.
   *
   * Consumers will be notified with the 'network-connection-state-changed'
   * observer notification.
   *
   * Throws an exception if the specified network interface object isn't
   * registered.
   *
   * @param network
   *        Network interface to update.
   */
  void updateNetworkInterface(in nsINetworkInterface network);

  /**
   * Unregister the given network interface from the network manager.
   *
   * Consumers will be notified with the 'network-interface-unregistered'
   * observer notification.
   *
   * Throws an exception if the specified network interface object isn't
   * registered.
   *
   * @param network
   *        Network interface to unregister.
   */
  void unregisterNetworkInterface(in nsINetworkInterface network);

  /**
   * Object containing all known network information, keyed by their
   * network id. Network id is composed of a sub-id + '-' + network
   * type. For mobile network types, sub-id is 'ril' + service id; for
   * non-mobile network types, sub-id is always 'device'.
   */
  readonly attribute jsval allNetworkInfo;

  /**
   * Priority list of network types. An array of
   * nsINetworkInterface::NETWORK_TYPE_* constants.
   *
   * The piror position of the type indicates the higher priority. The priority
   * is used to determine route when there are multiple connected networks.
   */
  attribute jsval networkTypePriorityList;

  /**
   * The preferred network type. One of the
   * nsINetworkInterface::NETWORK_TYPE_* constants.
   *
   * This attribute is used for setting default route to favor
   * interfaces with given type.  This can be overriden by calling
   * overrideDefaultRoute().
   */
  attribute long preferredNetworkType;

  /**
   * The network information of the network interface handling all network
   * traffic.
   *
   * When this changes, the 'network-active-changed' observer
   * notification is dispatched.
   */
  readonly attribute nsINetworkInfo activeNetworkInfo;

  /**
   * Override the default behaviour for preferredNetworkType and route
   * all network traffic through the the specified interface.
   *
   * Consumers can observe changes to the active network by subscribing to
   * the 'network-active-changed' observer notification.
   *
   * @param network
   *        Network to route all network traffic to. If this is null,
   *        a previous override is canceled.
   */
  long overrideActive(in nsINetworkInterface network);

  /**
   * Add host route to the specified network into routing table.
   *
   * @param network
   *        The network information for the host to be routed to.
   * @param host
   *        The host to be added.
   *        The host will be resolved in advance if it's not an ip-address.
   *
   * @return a Promise
   *         resolved if added; rejected, otherwise.
   */
  jsval addHostRoute(in nsINetworkInfo network,
                     in DOMString host);

  /**
   * Remove host route to the specified network from routing table.
   *
   * @param network
   *        The network information for the routing to be removed from.
   * @param host
   *        The host routed to the network.
   *        The host will be resolved in advance if it's not an ip-address.
   *
   * @return a Promise
   *         resolved if removed; rejected, otherwise.
   */
  jsval removeHostRoute(in nsINetworkInfo network,
                        in DOMString host);
};