NOTE: Gecko is a fast evolving project. Please check dom/network/interfaces/nsIDOMNetworkStatsManager.idl to make sure this data is accurate.

dom/network/interfaces/nsIDOMNetworkStatsManager.idlScriptable
Interface that provides access to network usage statistics.
Inherits from: nsISupports Last changed in Gecko 18.0 (Firefox 18.0 / Thunderbird 18.0 / SeaMonkey 2.15)

Implemented by: @mozilla.org/networkStatsManager;1. To create an instance, use:

var networkStatsManager = Components.classes["@mozilla.org/networkStatsManager;1"]
                          .createInstance(Components.interfaces.nsIDOMNetworkStatsManager); 

Furthermore, the NetworkStatsManager is published through a mozNetworkStats child object within the navigator object. If the object exists, you can use the Network Statistics service. You can test for the presence of the service as follows, for example:

if ("mozNetworkStats" in navigator) {
  /* NetworkStats is available */
} else {
  alert("I'm sorry, but NetworkStats services are not supported.");
}

Method overview

nsIDOMDOMRequest getSamples(in nsISupports network,
                            in jsval start,
                            in jsval end,
                            [optional] in jsval options /* NetworkStatsGetOptions */);
nsIDOMDOMRequest addAlarm(in nsISupports network,
                          in long threshold,
                          [optional] in jsval options /* NetworkStatsAlarmOptions */);
nsIDOMDOMRequest getAllAlarms([optional] in nsISupports network);
nsIDOMDOMRequest removeAlarms([optional] in long alarmId);
nsIDOMDOMRequest clearStats(in nsISupports network);
nsIDOMDOMRequest clearAllStats();
nsIDOMDOMRequest getAvailableNetworks();
nsIDOMDOMRequest getAvailableServiceTypes();

Attributes

Attribute Type Description
sampleRate long Minimum time in milliseconds between samples stored in the database. Read only.
maxStorageAge long long Time in milliseconds recorded by the API until present time. All samples older than maxStorageAge from now are deleted. Read only.

Constants

Constant Type Description
WIFI long Constant for WIFI, set to 0
MOBILE long Constant for MOBILE, set to 1

Methods

getSamples()

Asynchronously queries network interface statistics. The query may be filtered by connection type and date.

nsIDOMDOMRequest getSamples(in nsISupports network,
                            in jsval start,
                            in jsval end,
                            [optional] in jsval options /* NetworkStatsGetOptions */);
Parameters
network
The origin of the data. It can specify wifi, mobile, or null. If null, data measurement from both origins are merged. To know in advance which kind of origin is available, the MozNetworkStatsManager.getAvailableNetworks method returns an Array of interfaces.
start
A Date object representing the beginning of data measurement.
end
A Date object representing the end of data measurement.
options Optional
Filtering options.
NetworkStatsGetOptions is a dictionary object providing filtering options.
Return value

An nsIDOMDOMRequest object. If successful, the request result is an nsIDOMMozNetworkStats object describing the network statistics. If network stats are not available for some dates, then rxBytes and txBytes are undefined for those dates. If the filtering start date is greater than the end date, an exception is thrown.

Exceptions thrown
NS_ERROR_INVALID_ARG
The filtering start date is greater than the end date.
NS_ERROR_NOT_IMPLMENTED
Both appManifestURL and serviceType are specified at the same time in the NetworkStatsGetOptions dictionary.
InvalidNetwork
The network must be in the return of getAvailableNetworks.

addAlarm()

Install an alarm on a network. When total data usage reaches threshold bytes, a "networkstats-alarm" system message is sent to the application, where the optional parameter data must be a cloneable object.

nsIDOMDOMRequest addAlarm(in nsISupports network,
                          in long threshold,
                          [optional] in jsval options /* NetworkStatsAlarmOptions */);
Parameters
network
The origin of the data. It can specify wifi, mobile, or null. If null, data measurement from both origins are merged. To know in advance which kind of origin is available, the MozNetworkStatsManager.getAvailableNetworks method returns an Array of interfaces.
threshold
The total data usage threshold in bytes.
options Optional
Filtering options.
NetworkStatsAlarmOptions is a dictionary object providing filtering options.
Return Value

An nsIDOMDOMRequest object. If successful, the result field of the DOMRequest keeps the alarm Id.

Exceptions Thrown
InvalidNetwork
The network must be in the return of getAvailableNetworks.

getAllAlarms()

Obtain all alarms for those networks returned by getAvailableNetworks. If a network is provided, only retrieves the alarms for that network.

nsIDOMDOMRequest getAllAlarms([optional] in nsISupports network);
Parameters
network Optional
The origin of the data. It can specify wifi, mobile, or null. If null, data measurement from both origins are merged. To know in advance which kind of origin is available, the MozNetworkStatsManager.getAvailableNetworks method returns an Array of interfaces.
Return Value

An Alarm object with the same fields as that in the system message; alarmId, network, threshold, and data.

Exceptions Thrown
InvalidNetwork
The network must be in the return of getAvailableNetworks.

removeAlarms()

Remove all network alarms. If an alarmId is provided, then only that alarm is removed.

nsIDOMDOMRequest removeAlarms([optional] in long alarmId);
Parameters
alarmID
ID of an alarm, like the one returned by addAlarm.
Return Value

An nsIDOMDOMRequest object.

clearStats()

 Remove all stats related with the provided network from DB.

nsIDOMDOMRequest clearStats(in nsISupports network);
Parameters
network
The origin of the data. It can specify wifi, mobile, or null. If null, data measurement from both origins are merged. To know in advance which kind of origin is available, the MozNetworkStatsManager.getAvailableNetworks method returns an Array of interfaces.
Return Value

An nsIDOMDOMRequest object.

clearAllStats()

Clears all statistics from the statistics database.

void clearAllStats();
Parameters

None.

Return Value

An nsIDOMDOMRequest object.

getAvailableNetworks()

Returns available networks that used to be saved in the database.

nsIDOMDOMRequest getAvailableNetworks();
Parameters

None.

Return Value

An nsIDOMDOMRequest object. If successful, the result field of the DOMRequest holds an array of the currently available network interfaces.

getAvailableServiceTypes()

Returns available service types that used to be saved in the database.

nsIDOMDOMRequest getAvailableServiceTypes();
Parameters

None.

Return Value

An nsIDOMDOMRequest object. If successful, the result field of the DOMRequest holds an array of the currently available service types.

NetworkStatsAlarmOptions

NetworkStatsAlarmOptions is a dictionary object used to filter an alarm request made when calling addAlarm(). It contains the following fields:

startTime
A Date object representing the start time.
data
A Date object representing the date of data.

NetworkStatsGetOptions

NetworkStatsGetOptions is a dictionary object used to filter a network statistics request made when calling getSamples(). It contains the following fields:

appManifestURL
A string used to filter network stats by app.
serviceType
A string used to filter network stats by system service.
browsingTrafficOnly
A boolean set to filter network stats by browsing traffic. If true, return only browsing traffic, which is generated from the mozbrowser iframe element within an app. If false or not set, the total traffic, which is generated from both the mozapp and mozbrowser iframe elements, is returned.

For example, this object might be { appManifestURL : manifestURL }.

See also