/* 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"

/**
 * Information about networks that is exposed to network manager API consumers.
 */
[scriptable, uuid(cb62ae03-6bda-43ff-9560-916d60203d33)]
interface nsINetworkInterface : nsISupports
{
  const long NETWORK_STATE_UNKNOWN = -1;
  const long NETWORK_STATE_CONNECTING = 0;
  const long NETWORK_STATE_CONNECTED = 1;
  const long NETWORK_STATE_DISCONNECTING = 2;
  const long NETWORK_STATE_DISCONNECTED = 3;

  /**
   * Current network state, one of the NETWORK_STATE_* constants.
   *
   * When this changes, network interface implementations notify with
   * updateNetworkInterface() API.
   */
  readonly attribute long state;

  const long NETWORK_TYPE_UNKNOWN     = -1;
  const long NETWORK_TYPE_WIFI        = 0;
  const long NETWORK_TYPE_MOBILE      = 1;
  const long NETWORK_TYPE_MOBILE_MMS  = 2;
  const long NETWORK_TYPE_MOBILE_SUPL = 3;
  const long NETWORK_TYPE_WIFI_P2P    = 4;
  const long NETWORK_TYPE_MOBILE_IMS  = 5;
  const long NETWORK_TYPE_MOBILE_DUN  = 6;

  /**
   * Network type. One of the NETWORK_TYPE_* constants.
   */
  readonly attribute long type;

  /**
   * Name of the network interface. This identifier is unique.
   */
  readonly attribute DOMString name;

  /**
   * The host name of the http proxy server.
   */
  readonly attribute DOMString httpProxyHost;

  /*
   * The port number of the http proxy server.
   */
  readonly attribute long httpProxyPort;

  /**
   * Get the list of ip addresses and prefix lengths, ip address could be IPv4
   * or IPv6, typically 1 IPv4 or 1 IPv6 or one of each.
   *
   * @param ips
   *        The list of ip addresses retrieved.
   * @param prefixLengths
   *        The list of prefix lengths retrieved.
   *
   * @returns the length of the lists.
   */
  void getAddresses([array, size_is(count)] out wstring ips,
                    [array, size_is(count)] out unsigned long prefixLengths,
                    [retval] out unsigned long count);

  /**
   * Get the list of gateways, could be IPv4 or IPv6, typically 1 IPv4 or 1
   * IPv6 or one of each.
   *
   * @param count
   *        The length of the list of gateways
   *
   * @returns the list of gateways.
   */
  void getGateways([optional] out unsigned long count,
                   [array, size_is(count), retval] out wstring gateways);

  /**
   * Get the list of dnses, could be IPv4 or IPv6.
   *
   * @param count
   *        The length of the list of dnses.
   *
   * @returns the list of dnses.
   */
  void getDnses([optional] out unsigned long count,
                [array, size_is(count), retval] out wstring dnses);
};

/**
 * Manage network interfaces.
 */
[scriptable, uuid(b0ab71bf-4b38-4796-8a3c-4141255f4259)]
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 connections, 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 networkInterfaces;

  /**
   * 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 interface handling all data traffic.
   *
   * When this changes, the 'network-active-changed' observer
   * notification is dispatched.
   */
  readonly attribute nsINetworkInterface active;

  /**
   * 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 interface where 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 nsINetworkInterface network,
                     in DOMString host);

  /**
   * Remove host route to the specified network from routing table.
   *
   * @param network
   *        The network interface where 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 nsINetworkInterface network,
                        in DOMString host);
};