diff --git a/dom/webidl/ResourceStats.webidl b/dom/webidl/ResourceStats.webidl new file mode 100644 index 000000000000..a2bdc75c8ea4 --- /dev/null +++ b/dom/webidl/ResourceStats.webidl @@ -0,0 +1,68 @@ +/* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ +/* 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/. + */ + +[HeaderFile="mozilla/dom/ResourceStatsControl.h", + Func="mozilla::dom::ResourceStatsControl::HasResourceStatsSupport", + AvailableIn="CertifiedApps", + JSImplementation="@mozilla.org/networkStatsData;1"] +interface NetworkStatsData +{ + readonly attribute unsigned long long receivedBytes; + readonly attribute unsigned long long sentBytes; + readonly attribute DOMTimeStamp timestamp; // timestamp of the record +}; + +[HeaderFile="mozilla/dom/ResourceStatsControl.h", + Func="mozilla::dom::ResourceStatsControl::HasResourceStatsSupport", + AvailableIn="CertifiedApps", + JSImplementation="@mozilla.org/powerStatsData;1"] +interface PowerStatsData +{ + readonly attribute unsigned long long consumedPower; // unit: mW + readonly attribute DOMTimeStamp timestamp; // timestamp of the record +}; + +[HeaderFile="mozilla/dom/ResourceStatsControl.h", + Func="mozilla::dom::ResourceStatsControl::HasResourceStatsSupport", + AvailableIn="CertifiedApps", + JSImplementation="@mozilla.org/resourceStats;1"] +interface ResourceStats +{ + /** + * Type of statistics/ + */ + readonly attribute ResourceType type; + + /** + * The |component| specifies statistics belongs to. This will be null if + * the ResourceStatsOptions.component argument passed to getStats() is null. + */ + readonly attribute DOMString? component; + + /** + * |serviceType| specifies the system service. This will be null if the + * ResourceStatsOptions.serviceType argument passed to getStats() is null. + */ + readonly attribute SystemService? serviceType; + + /** + * |manifestURL| specifies the manifestURL of an application. This will be + * null if the ResourceStatsOptions.manifestURL argument passed to getStats() + * is null. + */ + readonly attribute DOMString? manifestURL; + + /** + * Statistics, one element per day + */ + sequence<(NetworkStatsData or PowerStatsData)> getData(); + + /** + * Date range + */ + readonly attribute DOMTimeStamp start; // start timestamp + readonly attribute DOMTimeStamp end; // end timestamp +}; diff --git a/dom/webidl/ResourceStatsManager.webidl b/dom/webidl/ResourceStatsManager.webidl new file mode 100644 index 000000000000..689fe1e69140 --- /dev/null +++ b/dom/webidl/ResourceStatsManager.webidl @@ -0,0 +1,224 @@ +/* -*- Mode: IDL; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */ +/* 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/. + */ + +/** + * Supported resource statistics + */ +enum ResourceType { + "network", + "power" +}; + +/** + * List of system services supporting resource statistics + */ +enum SystemService { + "ota", + "tethering" +}; + +dictionary ResourceStatsOptions +{ + /** + * |component| specifies which component's resource usage will be returned. + * If null or undefined, sum of all components' usage is returned. + * + * |component| is expressed in ":", where is the + * name of the component and is used to identify different entities. + * + * The field is mainly used in specifying the identity of different SIMs + * when quering mobile network usage, e.g. "mobile:". + * + * Quering statistics of other components should specify the |component| to + * ":0", such as "cpu:0" or "wifi:0". + */ + DOMString? component = null; + + /** + * |manifestURL| specifies the manifestURL of an application. + * |systemService| specifies the system service. + * + * If both |systemService| and |manifestURL| are null or undefined, then a + * system-wide resource statistics is returned. + * + * If |manifestURL| is specified, then the resource statistics of the + * specified application is returned. + * + * If |systemService| is specified, then the resource statistics of the + * specified system service is returned. + * + * If |systemService| and |manifestURL| are both specified, then the return + * statistics indicates the resources that the system service consumed for + * the application. + */ + SystemService? serviceType = null; + DOMString? manifestURL = null; +}; + +dictionary ResourceStatsAlarmOptions +{ + /** + * |startTime| indicates the start time of counting the resource usage. + * + * |data| is used to reflect in the alarm object when the alarm is triggered. + * |data| should be copied using the structured clone algorithm. + */ + [EnforceRange] DOMTimeStamp startTime; // time in milliseconds since Epoch + any data; +}; + +[HeaderFile="mozilla/dom/ResourceStatsControl.h", + Func="mozilla::dom::ResourceStatsControl::HasResourceStatsSupport", + AvailableIn="CertifiedApps", + JSImplementation="@mozilla.org/resourceStatsAlarm;1"] +interface ResourceStatsAlarm +{ + /** + * ID of the alarm + */ + readonly attribute unsigned long alarmId; + + /** + * Type of resource this alarm monitor + */ + readonly attribute ResourceType type; + + /** + * The target component this alarm monitor. + */ + readonly attribute DOMString? component; + + /** + * |manifestURL| specifies the manifestURL of an application. + * |systemService| specifies the system service. + * + * Both attributes are null means that this alarm monitors a system-wide + * resource usage. + */ + readonly attribute SystemService? serviceType; + readonly attribute DOMString? manifestURL; + + /** + * |threshold| specifies the limit of resource usage. + */ + readonly attribute unsigned long long threshold; + + /** + * |data| is used to reflect in the alarm object when the alarm is triggered. + */ + readonly attribute any data; +}; + +[HeaderFile="mozilla/dom/ResourceStatsControl.h", + Func="mozilla::dom::ResourceStatsControl::HasResourceStatsSupport", + Constructor(ResourceType type), + AvailableIn="CertifiedApps", + JSImplementation="@mozilla.org/resourceStatsManager;1"] +interface ResourceStatsManager +{ + /** + * Query resource statistics. + * + * |statsOptions| specifies the detail of statistics of interest. + * + * |start| and |end| specifies the time range of interest, both included. + * If |start| is null or undefined, retrieve the stats since measurements. + * If |end| is null or undefined. retrieve the stats until the current time. + * + * If success, the fulfillment value is a ResourceStats object. + */ + Promise getStats(optional ResourceStatsOptions statsOptions, + [EnforceRange] optional DOMTimeStamp? start = null, + [EnforceRange] optional DOMTimeStamp? end = null); + + /** + * Clear resource statistics stored in database. + * + * |statsOptions| specifies the detail of statistics to delete. + * + * |start| and |end| specifies the time range of interest, both included. + * If |start| is null or undefined, delete the stats since measurements. + * If |end| is null or undefined. delete the stats until the current time. + */ + Promise clearStats(optional ResourceStatsOptions statsOptions, + [EnforceRange] optional DOMTimeStamp? start = null, + [EnforceRange] optional DOMTimeStamp? end = null); + + /** + * Clear all resource statistics stored in database. + */ + Promise clearAllStats(); + + /** + * Install an alarm to monitor resource usage. + * + * The |threshold| specifies the limit of resource usage. When resource + * usage reaches the threshold, a "resourceStats-alarm" system message + * is sent to the application. + * + * |statsOptions| specifies the detail of statistics of interest. + * + * |alarmOptions| is a ResourceStatsAlarmOptions object. + * + * If success, the fulfillment value is an alarm ID. + */ + Promise addAlarm([EnforceRange] unsigned long long threshold, + optional ResourceStatsOptions statsOptions, + optional ResourceStatsAlarmOptions alarmOptions); + + /** + * Obtain alarms. + * + * If |statsOptions| is provided, then only the alarms monitoring that + * resource are returned. Otherwise, all alarms set for this resource type + * is returned. + * + * If success, the fulfillment value is an array of ResourceStatsAlarm. + */ + Promise getAlarms(optional ResourceStatsOptions statsOptions); + + /** + * Remove the specified alarm. + * + * |alarmId| specifies the alarm to be removed. + */ + Promise removeAlarm([EnforceRange] unsigned long alarmId); + + /** + * Remove all alarms. + */ + Promise removeAllAlarms(); + + /** + * Enumerate components that have stored statistics in database. + * + * If success, the fulfillment value is an array of DOMString. + */ + Promise getAvailableComponents(); + + /** + * Return supporting resource statistics, i.e. ["Network", "Power"] + * + * This should be specified as static attribute after Bug 863952 is resolved. + */ + [Cached, Pure] + readonly attribute sequence resourceTypes; + + /** + * Time in milliseconds between statistics stored in database. + * + * This should be specified as static attribute after Bug 863952 is resolved. + */ + readonly attribute unsigned long sampleRate; + + /** + * Time in milliseconds recorded by the API until present time. All + * statistics older than maxStorageAge from now are deleted. + * + * This should be specified as static attribute after Bug 863952 is resolved. + */ + readonly attribute unsigned long long maxStorageAge; +}; diff --git a/dom/webidl/moz.build b/dom/webidl/moz.build index f0c1c9393d6c..22a434f3b3e9 100644 --- a/dom/webidl/moz.build +++ b/dom/webidl/moz.build @@ -298,6 +298,8 @@ WEBIDL_FILES = [ 'PushManager.webidl', 'Range.webidl', 'Rect.webidl', + 'ResourceStats.webidl', + 'ResourceStatsManager.webidl', 'RGBColor.webidl', 'RTCConfiguration.webidl', 'RTCIceCandidate.webidl',