NetworkStatsManager
public
class
NetworkStatsManager
extends Object
java.lang.Object | |
↳ | android.app.usage.NetworkStatsManager |
Provides access to network usage history and statistics. Usage data is collected in
discrete bins of time called 'Buckets'. See NetworkStats.Bucket
for details.
Summary queries
querySummaryForDevice(int, String, long, long)
querySummaryForUser(int, String, long, long)
querySummary(int, String, long, long)
These queries aggregate network usage across the whole interval. Therefore there will be only one
bucket for a particular key, state, metered and roaming combination. In case of the user-wide
and device-wide summaries a single bucket containing the totalised network usage is returned.
History queries
queryDetailsForUid(int, String, long, long, int)
queryDetails(int, String, long, long)
These queries do not aggregate over time but do aggregate over state, metered and roaming.
Therefore there can be multiple buckets for a particular key. However, all Buckets will have
state
NetworkStats.Bucket#STATE_ALL
,
defaultNetwork
NetworkStats.Bucket#DEFAULT_NETWORK_ALL
,
metered
NetworkStats.Bucket#METERED_ALL
,
roaming
NetworkStats.Bucket#ROAMING_ALL
.
NOTE: Calling querySummaryForDevice(int, String, long, long)
or accessing stats for apps other than the
calling app requires the permission Manifest.permission.PACKAGE_USAGE_STATS
,
which is a system-level permission and will not be granted to third-party apps. However,
declaring the permission implies intention to use the API and the user of the device can grant
permission through the Settings application.
Profile owner apps are automatically granted permission to query data on the profile they manage
(that is, for any query except querySummaryForDevice(int, String, long, long)
). Device owner apps and carrier-
privileged apps likewise get access to usage data for all users on the device.
In addition to tethering usage, usage by removed users and apps, and usage by the system
is also included in the results for callers with one of these higher levels of access.
NOTE: Prior to API level android.os.Build.VERSION_CODES.N
, all calls to these APIs required
the above permission, even to access an app's own data usage, and carrier-privileged apps were
not included.
Summary
Nested classes | |
---|---|
class |
NetworkStatsManager.UsageCallback
Base class for usage callbacks. |
Public methods | |
---|---|
NetworkStats
|
queryDetails(int networkType, String subscriberId, long startTime, long endTime)
Query network usage statistics details. |
NetworkStats
|
queryDetailsForUid(int networkType, String subscriberId, long startTime, long endTime, int uid)
Query network usage statistics details for a given uid. |
NetworkStats
|
queryDetailsForUidTag(int networkType, String subscriberId, long startTime, long endTime, int uid, int tag)
Query network usage statistics details for a given uid and tag. |
NetworkStats
|
queryDetailsForUidTagState(int networkType, String subscriberId, long startTime, long endTime, int uid, int tag, int state)
Query network usage statistics details for a given uid, tag, and state. |
NetworkStats
|
querySummary(int networkType, String subscriberId, long startTime, long endTime)
Query network usage statistics summaries. |
NetworkStats.Bucket
|
querySummaryForDevice(int networkType, String subscriberId, long startTime, long endTime)
Query network usage statistics summaries. |
NetworkStats.Bucket
|
querySummaryForUser(int networkType, String subscriberId, long startTime, long endTime)
Query network usage statistics summaries. |
void
|
registerUsageCallback(int networkType, String subscriberId, long thresholdBytes, NetworkStatsManager.UsageCallback callback, Handler handler)
Registers to receive notifications about data usage on specified networks. |
void
|
registerUsageCallback(int networkType, String subscriberId, long thresholdBytes, NetworkStatsManager.UsageCallback callback)
Registers to receive notifications about data usage on specified networks. |
void
|
unregisterUsageCallback(NetworkStatsManager.UsageCallback callback)
Unregisters callbacks on data usage. |
Inherited methods | |
---|---|
Public methods
queryDetails
public NetworkStats queryDetails (int networkType, String subscriberId, long startTime, long endTime)
Query network usage statistics details. Result filtered to include only uids belonging to
calling user. Result is aggregated over state but not aggregated over time, uid, tag,
metered, nor roaming. This means buckets' start and end timestamps are going to be between
'startTime' and 'endTime' parameters. State is going to be
NetworkStats.Bucket#STATE_ALL
, uid will vary,
tag NetworkStats.Bucket#TAG_NONE
,
default network is going to be NetworkStats.Bucket#DEFAULT_NETWORK_ALL
,
metered is going to be NetworkStats.Bucket#METERED_ALL
,
and roaming is going to be NetworkStats.Bucket#ROAMING_ALL
.
Only includes buckets that atomically occur in the inclusive time range. Doesn't
interpolate across partial buckets. Since bucket length is in the order of hours, this
method cannot be used to measure data usage on a fine grained time scale.
This may take a long time, and apps should avoid calling this on their main thread.
This method may take several seconds to complete, so it should
only be called from a worker thread.
Parameters | |
---|---|
networkType |
int : As defined in ConnectivityManager , e.g.
ConnectivityManager#TYPE_MOBILE , ConnectivityManager#TYPE_WIFI
etc. |
subscriberId |
String : If applicable, the subscriber id of the network interface.
Starting with API level 29, the Starting with API level 31, calling apps can provide a
|
startTime |
long : Start of period. Defined in terms of "Unix time", see
System.currentTimeMillis() . |
endTime |
long : End of period. Defined in terms of "Unix time", see
System.currentTimeMillis() . |
Returns | |
---|---|
NetworkStats |
Statistics object or null if permissions are insufficient or error happened during statistics collection. |
Throws | |
---|---|
RemoteException |
|
SecurityException |
queryDetailsForUid
public NetworkStats queryDetailsForUid (int networkType, String subscriberId, long startTime, long endTime, int uid)
Query network usage statistics details for a given uid.
This may take a long time, and apps should avoid calling this on their main thread.
This method may take several seconds to complete, so it should
only be called from a worker thread.
Parameters | |
---|---|
networkType |
int : As defined in ConnectivityManager , e.g.
ConnectivityManager#TYPE_MOBILE , ConnectivityManager#TYPE_WIFI
etc. |
subscriberId |
String : If applicable, the subscriber id of the network interface.
Starting with API level 29, the Starting with API level 31, calling apps can provide a
|
startTime |
long : Start of period. Defined in terms of "Unix time", see
System.currentTimeMillis() . |
endTime |
long : End of period. Defined in terms of "Unix time", see
System.currentTimeMillis() . |
uid |
int : UID of app |
Returns | |
---|---|
NetworkStats |
Statistics which is described above.
This value cannot be null . |
Throws | |
---|---|
SecurityException |
if permissions are insufficient to read network statistics. |
queryDetailsForUidTag
public NetworkStats queryDetailsForUidTag (int networkType, String subscriberId, long startTime, long endTime, int uid, int tag)
Query network usage statistics details for a given uid and tag.
This may take a long time, and apps should avoid calling this on their main thread.
Only usable for uids belonging to calling user. Result is not aggregated over time.
This means buckets' start and end timestamps are going to be between 'startTime' and
'endTime' parameters. The uid is going to be the same as the 'uid' parameter, the tag
the same as the 'tag' parameter, and the state the same as the 'state' parameter.
defaultNetwork is going to be NetworkStats.Bucket#DEFAULT_NETWORK_ALL
,
metered is going to be NetworkStats.Bucket#METERED_ALL
, and
roaming is going to be NetworkStats.Bucket#ROAMING_ALL
.
Only includes buckets that atomically occur in the inclusive time range. Doesn't
interpolate across partial buckets. Since bucket length is in the order of hours, this
method cannot be used to measure data usage on a fine grained time scale.
This may take a long time, and apps should avoid calling this on their main thread.
This method may take several seconds to complete, so it should
only be called from a worker thread.
Parameters | |
---|---|
networkType |
int : As defined in ConnectivityManager , e.g.
ConnectivityManager#TYPE_MOBILE , ConnectivityManager#TYPE_WIFI
etc. |
subscriberId |
String : If applicable, the subscriber id of the network interface.
Starting with API level 29, the Starting with API level 31, calling apps can provide a
|
startTime |
long : Start of period. Defined in terms of "Unix time", see
System.currentTimeMillis() . |
endTime |
long : End of period. Defined in terms of "Unix time", see
System.currentTimeMillis() . |
uid |
int : UID of app |
tag |
int : TAG of interest. Use NetworkStats.Bucket#TAG_NONE for aggregated data
across all the tags. |
Returns | |
---|---|
NetworkStats |
Statistics which is described above.
This value cannot be null . |
Throws | |
---|---|
SecurityException |
if permissions are insufficient to read network statistics. |
queryDetailsForUidTagState
public NetworkStats queryDetailsForUidTagState (int networkType, String subscriberId, long startTime, long endTime, int uid, int tag, int state)
Query network usage statistics details for a given uid, tag, and state.
Only usable for uids belonging to calling user. Result is not aggregated over time.
This means buckets' start and end timestamps are going to be between 'startTime' and
'endTime' parameters. The uid is going to be the same as the 'uid' parameter, the tag
the same as the 'tag' parameter, and the state the same as the 'state' parameter.
defaultNetwork is going to be NetworkStats.Bucket#DEFAULT_NETWORK_ALL
,
metered is going to be NetworkStats.Bucket#METERED_ALL
, and
roaming is going to be NetworkStats.Bucket#ROAMING_ALL
.
Only includes buckets that atomically occur in the inclusive time range. Doesn't
interpolate across partial buckets. Since bucket length is in the order of hours, this
method cannot be used to measure data usage on a fine grained time scale.
This may take a long time, and apps should avoid calling this on their main thread.
This method may take several seconds to complete, so it should
only be called from a worker thread.
Parameters | |
---|---|
networkType |
int : As defined in ConnectivityManager , e.g.
ConnectivityManager#TYPE_MOBILE , ConnectivityManager#TYPE_WIFI
etc. |
subscriberId |
String : If applicable, the subscriber id of the network interface.
Starting with API level 29, the Starting with API level 31, calling apps can provide a
|
startTime |
long : Start of period. Defined in terms of "Unix time", see
System.currentTimeMillis() . |
endTime |
long : End of period. Defined in terms of "Unix time", see
System.currentTimeMillis() . |
uid |
int : UID of app |
tag |
int : TAG of interest. Use NetworkStats.Bucket#TAG_NONE for aggregated data
across all the tags. |
state |
int : state of interest. Use NetworkStats.Bucket#STATE_ALL to aggregate
traffic from all states. |
Returns | |
---|---|
NetworkStats |
Statistics which is described above.
This value cannot be null . |
Throws | |
---|---|
SecurityException |
if permissions are insufficient to read network statistics. |
querySummary
public NetworkStats querySummary (int networkType, String subscriberId, long startTime, long endTime)
Query network usage statistics summaries. Result filtered to include only uids belonging to
calling user. Result is aggregated over time, hence all buckets will have the same start and
end timestamps. Not aggregated over state, uid, default network, metered, or roaming. This
means buckets' start and end timestamps are going to be the same as the 'startTime' and
'endTime' parameters. State, uid, metered, and roaming are going to vary, and tag is going to
be the same.
This may take a long time, and apps should avoid calling this on their main thread.
This method may take several seconds to complete, so it should
only be called from a worker thread.
Parameters | |
---|---|
networkType |
int : As defined in ConnectivityManager , e.g.
ConnectivityManager#TYPE_MOBILE , ConnectivityManager#TYPE_WIFI
etc. |
subscriberId |
String : If applicable, the subscriber id of the network interface.
Starting with API level 29, the Starting with API level 31, calling apps can provide a
|
startTime |
long : Start of period. Defined in terms of "Unix time", see
System.currentTimeMillis() . |
endTime |
long : End of period. Defined in terms of "Unix time", see
System.currentTimeMillis() . |
Returns | |
---|---|
NetworkStats |
Statistics object or null if permissions are insufficient or error happened during statistics collection. |
Throws | |
---|---|
RemoteException |
|
SecurityException |
querySummaryForDevice
public NetworkStats.Bucket querySummaryForDevice (int networkType, String subscriberId, long startTime, long endTime)
Query network usage statistics summaries. Result is summarised data usage for the whole
device. Result is a single Bucket aggregated over time, state, uid, tag, metered, and
roaming. This means the bucket's start and end timestamp are going to be the same as the
'startTime' and 'endTime' parameters. State is going to be
NetworkStats.Bucket#STATE_ALL
, uid NetworkStats.Bucket#UID_ALL
,
tag NetworkStats.Bucket#TAG_NONE
,
default network NetworkStats.Bucket#DEFAULT_NETWORK_ALL
,
metered NetworkStats.Bucket#METERED_ALL
,
and roaming NetworkStats.Bucket#ROAMING_ALL
.
This may take a long time, and apps should avoid calling this on their main thread.
This method may take several seconds to complete, so it should
only be called from a worker thread.
Parameters | |
---|---|
networkType |
int : As defined in ConnectivityManager , e.g.
ConnectivityManager#TYPE_MOBILE , ConnectivityManager#TYPE_WIFI
etc. |
subscriberId |
String : If applicable, the subscriber id of the network interface.
Starting with API level 29, the Starting with API level 31, calling apps can provide a
|
startTime |
long : Start of period. Defined in terms of "Unix time", see
System.currentTimeMillis() . |
endTime |
long : End of period. Defined in terms of "Unix time", see
System.currentTimeMillis() . |
Returns | |
---|---|
NetworkStats.Bucket |
Bucket object or null if permissions are insufficient or error happened during statistics collection. |
Throws | |
---|---|
RemoteException |
|
SecurityException |
querySummaryForUser
public NetworkStats.Bucket querySummaryForUser (int networkType, String subscriberId, long startTime, long endTime)
Query network usage statistics summaries. Result is summarised data usage for all uids
belonging to calling user. Result is a single Bucket aggregated over time, state and uid.
This means the bucket's start and end timestamp are going to be the same as the 'startTime'
and 'endTime' parameters. State is going to be NetworkStats.Bucket#STATE_ALL
,
uid NetworkStats.Bucket#UID_ALL
, tag NetworkStats.Bucket#TAG_NONE
,
metered NetworkStats.Bucket#METERED_ALL
, and roaming
NetworkStats.Bucket#ROAMING_ALL
.
This may take a long time, and apps should avoid calling this on their main thread.
This method may take several seconds to complete, so it should
only be called from a worker thread.
Parameters | |
---|---|
networkType |
int : As defined in ConnectivityManager , e.g.
ConnectivityManager#TYPE_MOBILE , ConnectivityManager#TYPE_WIFI
etc. |
subscriberId |
String : If applicable, the subscriber id of the network interface.
Starting with API level 29, the Starting with API level 31, calling apps can provide a
|
startTime |
long : Start of period. Defined in terms of "Unix time", see
System.currentTimeMillis() . |
endTime |
long : End of period. Defined in terms of "Unix time", see
System.currentTimeMillis() . |
Returns | |
---|---|
NetworkStats.Bucket |
Bucket object or null if permissions are insufficient or error happened during statistics collection. |
Throws | |
---|---|
RemoteException |
|
SecurityException |
registerUsageCallback
public void registerUsageCallback (int networkType, String subscriberId, long thresholdBytes, NetworkStatsManager.UsageCallback callback, Handler handler)
Registers to receive notifications about data usage on specified networks.
The callbacks will continue to be called as long as the process is live or
unregisterUsageCallback(UsageCallback)
is called.
Parameters | |
---|---|
networkType |
int : Type of network to monitor. Either
ConnectivityManager#TYPE_MOBILE or ConnectivityManager#TYPE_WIFI . |
subscriberId |
String : If applicable, the subscriber id of the network interface.
Starting with API level 29, the Starting with API level 31, calling apps can provide a
|
thresholdBytes |
long : Threshold in bytes to be notified on. |
callback |
NetworkStatsManager.UsageCallback : The UsageCallback that the system will call when data usage
has exceeded the specified threshold.
This value cannot be null . |
handler |
Handler : to dispatch callback events through, otherwise if null it uses
the calling thread. |
registerUsageCallback
public void registerUsageCallback (int networkType, String subscriberId, long thresholdBytes, NetworkStatsManager.UsageCallback callback)
Registers to receive notifications about data usage on specified networks.
The callbacks will continue to be called as long as the process is live or
unregisterUsageCallback(UsageCallback)
is called.
Parameters | |
---|---|
networkType |
int : Type of network to monitor. Either
ConnectivityManager#TYPE_MOBILE or ConnectivityManager#TYPE_WIFI . |
subscriberId |
String : If applicable, the subscriber id of the network interface.
Starting with API level 29, the Starting with API level 31, calling apps can provide a
|
thresholdBytes |
long : Threshold in bytes to be notified on. |
callback |
NetworkStatsManager.UsageCallback : The UsageCallback that the system will call when data usage
has exceeded the specified threshold.
This value cannot be null . |
unregisterUsageCallback
public void unregisterUsageCallback (NetworkStatsManager.UsageCallback callback)
Unregisters callbacks on data usage.
Parameters | |
---|---|
callback |
NetworkStatsManager.UsageCallback : The UsageCallback used when registering.
This value cannot be null . |
Content and code samples on this page are subject to the licenses described in the Content License. Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
Last updated 2024-04-11 UTC.