michael@0: /* This Source Code Form is subject to the terms of the Mozilla Public
michael@0:  * License, v. 2.0. If a copy of the MPL was not distributed with this file,
michael@0:  * You can obtain one at http://mozilla.org/MPL/2.0/. */
michael@0: 
michael@0: #include "nsISupports.idl"
michael@0: 
michael@0: interface nsIDOMDOMRequest;
michael@0: 
michael@0: /**
michael@0:  * Represents a data interface for which the manager is recording statistics.
michael@0:  */
michael@0: [scriptable, uuid(f540615b-d803-43ff-8200-2a9d145a5645)]
michael@0: interface nsIDOMMozNetworkStatsInterface : nsISupports
michael@0: {
michael@0:   readonly attribute long type;
michael@0: 
michael@0:   /**
michael@0:    * Id value is '0' for wifi or the iccid for mobile (SIM).
michael@0:    */
michael@0:   readonly attribute DOMString id;
michael@0: };
michael@0: 
michael@0: [scriptable, builtinclass, uuid(063ebeb2-5c6e-47ae-bdcd-5e6ebdc7a68c)]
michael@0: interface nsIDOMMozNetworkStatsAlarm : nsISupports
michael@0: {
michael@0:   readonly attribute unsigned long alarmId;
michael@0:   readonly attribute nsIDOMMozNetworkStatsInterface network;
michael@0:   readonly attribute long threshold;
michael@0:   readonly attribute jsval data;
michael@0: };
michael@0: 
michael@0: [scriptable,  uuid(8a66f4c1-0c25-4a66-9fc5-0106947b91f9)]
michael@0: interface nsIDOMMozNetworkStatsManager : nsISupports
michael@0: {
michael@0:   /**
michael@0:    * Constants for known interface types.
michael@0:    */
michael@0:   const long WIFI = 0;
michael@0:   const long MOBILE = 1;
michael@0: 
michael@0:   /**
michael@0:    * Find samples between two dates start and end, both included.
michael@0:    *
michael@0:    * If options is provided, per-app or per-system service usage will be
michael@0:    * retrieved; otherwise the target will be overall system usage.
michael@0:    *
michael@0:    * If success, the request result will be an nsIDOMMozNetworkStats object.
michael@0:    */
michael@0:   nsIDOMDOMRequest getSamples(in nsIDOMMozNetworkStatsInterface network,
michael@0:                               in jsval start,
michael@0:                               in jsval end,
michael@0:                    [optional] in jsval options /* NetworkStatsGetOptions */);
michael@0: 
michael@0:   /**
michael@0:    * Install an alarm on a network. The network must be in the return of
michael@0:    * getAvailableNetworks() otherwise an "InvalidNetwork" exception will
michael@0:    * be raised.
michael@0:    *
michael@0:    * When total data usage reaches threshold bytes, a "networkstats-alarm"
michael@0:    * system message is sent to the application, where the optional parameter
michael@0:    * |data| must be a cloneable object.
michael@0:    *
michael@0:    * If success, the |result| field of the DOMRequest keeps the alarm Id.
michael@0:    */
michael@0:   nsIDOMDOMRequest addAlarm(in nsIDOMMozNetworkStatsInterface network,
michael@0:                             in long threshold,
michael@0:                             [optional] in jsval options /* NetworkStatsAlarmOptions */);
michael@0: 
michael@0:   /**
michael@0:    * Obtain all alarms for those networks returned by getAvailableNetworks().
michael@0:    * If a network is provided, only retrieves the alarms for that network.
michael@0:    * The network must be one of those returned by getAvailebleNetworks() or an
michael@0:    * "InvalidNetwork" exception will be raised.
michael@0:    *
michael@0:    * Each alarm object has the same fields as that in the system message:
michael@0:    *  - alarmId
michael@0:    *  - network
michael@0:    *  - threshold
michael@0:    *  - data
michael@0:    */
michael@0:   nsIDOMDOMRequest getAllAlarms([optional] in nsIDOMMozNetworkStatsInterface network);
michael@0: 
michael@0:   /**
michael@0:    * Remove all network alarms. If an |alarmId| is provided, then only that
michael@0:    * alarm is removed.
michael@0:    */
michael@0:   nsIDOMDOMRequest removeAlarms([optional] in long alarmId);
michael@0: 
michael@0:   /**
michael@0:    * Remove all stats related with the provided network from DB.
michael@0:    */
michael@0:   nsIDOMDOMRequest clearStats(in nsIDOMMozNetworkStatsInterface network);
michael@0: 
michael@0:   /**
michael@0:    * Remove all stats in the database.
michael@0:    */
michael@0:   nsIDOMDOMRequest clearAllStats();
michael@0: 
michael@0:   /**
michael@0:    * Return available networks that used to be saved in the database.
michael@0:    */
michael@0:   nsIDOMDOMRequest getAvailableNetworks(); // array of nsIDOMMozNetworkStatsInterface.
michael@0: 
michael@0:   /**
michael@0:    * Return available service types that used to be saved in the database.
michael@0:    */
michael@0:   nsIDOMDOMRequest getAvailableServiceTypes(); // array of string.
michael@0: 
michael@0:   /**
michael@0:    * Minimum time in milliseconds between samples stored in the database.
michael@0:    */
michael@0:   readonly attribute long sampleRate;
michael@0: 
michael@0:   /**
michael@0:    * Time in milliseconds recorded by the API until present time. All samples
michael@0:    * older than maxStorageAge from now are deleted.
michael@0:    */
michael@0:   readonly attribute long long maxStorageAge;
michael@0: };