dom/webidl/ResourceStatsManager.webidl

   1 /* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
   2 /* This Source Code Form is subject to the terms of the Mozilla Public
   3  * License, v. 2.0. If a copy of the MPL was not distributed with this file,
   4  * You can obtain one at http://mozilla.org/MPL/2.0/.
   5  */
   6
   7 /**
   8  * Supported resource statistics
   9  */
  10 enum ResourceType {
  11   "network",
  12   "power"
  13 };
  14
  15 /**
  16  * List of system services supporting resource statistics
  17  */
  18 enum SystemService {
  19   "ota",
  20   "tethering"
  21 };
  22
  23 dictionary ResourceStatsOptions
  24 {
  25   /**
  26    * |component| specifies which component's resource usage will be returned.
  27    * If null or undefined, sum of all components' usage is returned.
  28    *
  29    * |component| is expressed in "<component>:<id>", where <component> is the
  30    * name of the component and <id> is used to identify different entities.
  31    *
  32    * The <id> field is mainly used in specifying the identity of different SIMs
  33    * when quering mobile network usage, e.g. "mobile:<iccid>".
  34    *
  35    * Quering statistics of other components should specify the |component| to
  36    *  "<component>:0", such as "cpu:0" or "wifi:0".
  37    */
  38   DOMString? component = null;
  39
  40   /**
  41    * |manifestURL| specifies the manifestURL of an application.
  42    * |systemService| specifies the system service.
  43    *
  44    * If both |systemService| and |manifestURL| are null or undefined, then a
  45    * system-wide resource statistics is returned.
  46    *
  47    * If |manifestURL| is specified, then the resource statistics of the
  48    * specified application is returned.
  49    *
  50    * If |systemService| is specified, then the resource statistics of the
  51    * specified system service is returned.
  52    *
  53    * If |systemService| and |manifestURL| are both specified, then the return
  54    * statistics indicates the resources that the system service consumed for
  55    * the application.
  56    */
  57   SystemService? serviceType = null;
  58   DOMString? manifestURL = null;
  59 };
  60
  61 dictionary ResourceStatsAlarmOptions
  62 {
  63   /**
  64    * |startTime| indicates the start time of counting the resource usage.
  65    *
  66    * |data| is used to reflect in the alarm object when the alarm is triggered.
  67    * |data| should be copied using the structured clone algorithm.
  68    */
  69   [EnforceRange] DOMTimeStamp   startTime;  // time in milliseconds since Epoch
  70   any                           data;
  71 };
  72
  73 [CheckPermissions="resourcestats-manage",
  74  Pref="dom.resource_stats.enabled",
  75  AvailableIn="CertifiedApps",
  76  JSImplementation="@mozilla.org/resourceStatsAlarm;1"]
  77 interface ResourceStatsAlarm
  78 {
  79   /**
  80    * ID of the alarm
  81    */
  82   readonly attribute unsigned long          alarmId;
  83
  84   /**
  85    * Type of resource this alarm monitor
  86    */
  87   readonly attribute ResourceType           type;
  88
  89   /**
  90    * The target component this alarm monitor.
  91    */
  92   readonly attribute DOMString?             component;
  93
  94   /**
  95    * |manifestURL| specifies the manifestURL of an application.
  96    * |systemService| specifies the system service.
  97    *
  98    * Both attributes are null means that this alarm monitors a system-wide
  99    * resource usage.
 100    */
 101   readonly attribute SystemService?         serviceType;
 102   readonly attribute DOMString?             manifestURL;
 103
 104   /**
 105    * |threshold| specifies the limit of resource usage.
 106    */
 107   readonly attribute unsigned long long     threshold;
 108
 109   /**
 110    * |data| is used to reflect in the alarm object when the alarm is triggered.
 111    */
 112   readonly attribute any                    data;
 113 };
 114
 115 [CheckPermissions="resourcestats-manage",
 116  Pref="dom.resource_stats.enabled",
 117  Constructor(ResourceType type),
 118  AvailableIn="CertifiedApps",
 119  JSImplementation="@mozilla.org/resourceStatsManager;1"]
 120 interface ResourceStatsManager
 121 {
 122   /**
 123    * Query resource statistics.
 124    *
 125    * |statsOptions| specifies the detail of statistics of interest.
 126    *
 127    * |start| and |end| specifies the time range of interest, both included.
 128    * If |start| is null or undefined, retrieve the stats since measurements.
 129    * If |end| is null or undefined. retrieve the stats until the current time.
 130    *
 131    * If success, the fulfillment value is a ResourceStats object.
 132    */
 133   Promise<ResourceStats> getStats(optional ResourceStatsOptions statsOptions,
 134                                   [EnforceRange] optional DOMTimeStamp? start = null,
 135                                   [EnforceRange] optional DOMTimeStamp? end = null);
 136
 137   /**
 138    * Clear resource statistics stored in database.
 139    *
 140    * |statsOptions| specifies the detail of statistics to delete.
 141    *
 142    * |start| and |end| specifies the time range of interest, both included.
 143    * If |start| is null or undefined, delete the stats since measurements.
 144    * If |end| is null or undefined. delete the stats until the current time.
 145    */
 146   // XXXbz What is this promise resolved with?
 147   Promise<any> clearStats(optional ResourceStatsOptions statsOptions,
 148                           [EnforceRange] optional DOMTimeStamp? start = null,
 149                           [EnforceRange] optional DOMTimeStamp? end = null);
 150
 151   /**
 152    * Clear all resource statistics stored in database.
 153    */
 154   // XXXbz What is this promise resolved with?
 155   Promise<any> clearAllStats();
 156
 157   /**
 158    * Install an alarm to monitor resource usage.
 159    *
 160    * The |threshold| specifies the limit of resource usage. When resource
 161    * usage reaches the threshold, a "resourceStats-alarm" system message
 162    * is sent to the application.
 163    *
 164    * |statsOptions| specifies the detail of statistics of interest.
 165    *
 166    * |alarmOptions| is a ResourceStatsAlarmOptions object.
 167    *
 168    * If success, the fulfillment value is an alarm ID.
 169    */
 170   Promise<unsigned long> addAlarm([EnforceRange] unsigned long long threshold,
 171                                   optional ResourceStatsOptions statsOptions,
 172                                   optional ResourceStatsAlarmOptions alarmOptions);
 173
 174   /**
 175    * Obtain alarms.
 176    *
 177    * If |statsOptions| is provided, then only the alarms monitoring that
 178    * resource are returned. Otherwise, all alarms set for this resource type
 179    * is returned.
 180    *
 181    * If success, the fulfillment value is an array of ResourceStatsAlarm.
 182    */
 183   Promise<sequence<ResourceStatsAlarm>> getAlarms(optional ResourceStatsOptions statsOptions);
 184
 185   /**
 186    * Remove the specified alarm.
 187    *
 188    * |alarmId| specifies the alarm to be removed.
 189    */
 190   // XXXbz What is this promise resolved with?
 191   Promise<any> removeAlarm([EnforceRange] unsigned long alarmId);
 192
 193   /**
 194    * Remove all alarms.
 195    */
 196   // XXXbz What is this promise resolved with?
 197   Promise<any> removeAllAlarms();
 198
 199   /**
 200    * Enumerate components that have stored statistics in database.
 201    *
 202    * If success, the fulfillment value is an array of DOMString.
 203    */
 204   Promise<sequence<DOMString>> getAvailableComponents();
 205
 206   /**
 207    * Return supporting resource statistics, i.e. ["Network", "Power"]
 208    *
 209    * This should be specified as static attribute after Bug 863952 is resolved.
 210    */
 211   [Cached, Pure]
 212   readonly attribute sequence<DOMString> resourceTypes;
 213
 214   /**
 215    * Time in milliseconds between statistics stored in database.
 216    *
 217    * This should be specified as static attribute after Bug 863952 is resolved.
 218    */
 219   readonly attribute unsigned long sampleRate;
 220
 221   /**
 222    * Time in milliseconds recorded by the API until present time. All
 223    * statistics older than maxStorageAge from now are deleted.
 224    *
 225    * This should be specified as static attribute after Bug 863952 is resolved.
 226    */
 227   readonly attribute unsigned long long maxStorageAge;
 228 };