nsIDOMMozNetworkStatsManager

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

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

Attributes

Constants

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

• nsIDOMMozNetworkStats