WebAPI/ResourceStats
From MozillaWiki
< WebAPI
Contents
Objective
ResourceStats API provides a generic interface to access resource statistics of Firefox OS devices. It also provides an interface for resource control.
Implementation
WebIDl Definition
ResourceStats.webidl
[JSImplementation="@mozilla.org/networkStatsData;1", Pref="dom.resourceStats.enabled", AvailableIn="CertifiedApps"] interface NetworkStatsData { readonly attribute unsigned long long receivedBytes; readonly attribute unsigned long long sentBytes; readonly attribute DOMTimeStamp timestamp; // timestamp of the record }; [JSImplementation="@mozilla.org/powerStatsData;1", Pref="dom.resourceStats.enabled", AvailableIn="CertifiedApps"] interface PowerStatsData { readonly attribute unsigned long long consumedPower; // unit: mW readonly attribute DOMTimeStamp timestamp; // timestamp of the record }; [JSImplementation="@mozilla.org/resourceStats;1", Pref="dom.resourceStats.enabled", AvailableIn="CertifiedApps"] interface ResourceStats { /** * Type of statistics/ */ readonly attribute ResourceType type; /** * The component that statistics belongs to. * If null, sum of all components' statistics are returned. */ readonly attribute DOMString? component; /** * |serviceType| specifies the system service. * |manifestURL| specifies the manifestURL of an application. * * If both |systemService| and |manifestURL| are null, then getStats() * returns a system-wide resource statistics. * * If |manifestURL| is not null, then getStats() returns statistics of * that application. * * If |serviceType| is not null, then getStats returns statistics of * that system service. * * If both |systemService| and |manifestURL| are specified, then the returned * statistics indicates the resources that the system service consumed for * the application. */ readonly attribute SystemService? serviceType; readonly attribute DOMString? manifestURL; /** * Statistics, one element per day */ sequence<(NetworkStatsData or PowerStatsData)> getStats(); /** * Date range */ readonly attribute DOMTimeStamp start; // start timestamp readonly attribute DOMTimeStamp end; // end timestamp };
ResourceStatsManager.webidl
/** * 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 "<component>:<id>", where <component> is the * name of the component and <id> is used to identify different entities. * * The <id> field is mainly used in specifying the identity of different SIMs * when quering mobile network usage, e.g. "mobile:<iccid>". * * Quering statistics of other components should specify the |component| to * "<component>: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. */ DOMTimeStamp startTime; // time in milliseconds since Epoch any data; }; [JSImplementation="@mozilla.org/resourceStatsAlarm;1", Pref="dom.resourceStats.enabled", AvailableIn="CertifiedApps"] interface ResourceStatsAlarm { readonly attribute unsigned long alarmId; readonly attribute ResourceType type; readonly attribute DOMString component; readonly attribute SystemService serviceType; readonly attribute DOMString manifestURL; readonly attribute unsigned long long threshold; readonly attribute any data; }; [Constructor(ResourceType type), JSImplementation="@mozilla.org/resourceStatsManager;1", Pref="dom.resourceStats.enabled", AvailableIn="CertifiedApps"] 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 an array of ResourceStats object. */ Promise getStats(optional ResourceStatsOptions statsOptions, optional DOMTimeStamp? start = null, 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, optional DOMTimeStamp? start = null, optional DOMTimeStamp? end = null); /** * Clear all resource statistics stored in database. */ Promise clearAllStats(); /** * Install an alarm to monitor resource usage. * * The |threshold| is an object specified 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(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(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<DOMString> 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; };
Bugs
bug 951976: API for Resource Statistics