NetworkStatsManager
public class NetworkStatsManager
extends Object
Provides access to network usage history and statistics. Usage data is collected in discrete bins of time called 'Buckets'. See NetworkStats.Bucket
for details.
Queries can define a time interval in the form of start and end timestamps (Long.MIN_VALUE and Long.MAX_VALUE can be used to simulate open ended intervals). By default, apps can only obtain data about themselves. See the below note for special cases in which apps can obtain data about other applications.
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 and state 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 and roaming. Therefore there can be multiple buckets for a particular key but all Bucket's state is going to be
STATE_ALL
and all Bucket's roaming is going to be
ROAMING_ALL
.
NOTE: Calling
querySummaryForDevice(int, String, long, long)
or accessing stats for apps other than the calling app requires the 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
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
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 |
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 |
From class java.lang.Object
Object |
clone() Creates and returns a copy of this object. |
boolean |
equals(Object obj) Indicates whether some other object is "equal to" this one. |
void |
finalize() Called by the garbage collector on an object when garbage collection determines that there are no more references to the object. |
final Class<?> |
getClass() Returns the runtime class of this Object . |
int |
hashCode() Returns a hash code value for the object. |
final void |
notify() Wakes up a single thread that is waiting on this object's monitor. |
final void |
notifyAll() Wakes up all threads that are waiting on this object's monitor. |
String |
toString() Returns a string representation of the object. |
final void |
wait(long millis, int nanos) Causes the current thread to wait until another thread invokes the notify() method or the notifyAll() method for this object, or some other thread interrupts the current thread, or a certain amount of real time has elapsed. |
final void |
wait(long millis) Causes the current thread to wait until either another thread invokes the notify() method or the notifyAll() method for this object, or a specified amount of time has elapsed. |
final void |
wait() Causes the current thread to wait until another thread invokes the notify() method or the notifyAll() method for this object. |
|
Public methods
queryDetails
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 or uid. This means buckets' start and end timestamps are going to be between 'startTime' and 'endTime' parameters. State is going to be STATE_ALL
, uid will vary, tag TAG_NONE
and roaming is going to be 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.
Returns |
NetworkStats |
Statistics object or null if permissions are insufficient or error happened during statistics collection. |
queryDetailsForUid
NetworkStats queryDetailsForUid (int networkType,
String subscriberId,
long startTime,
long endTime,
int uid)
Query network usage statistics details for a given uid. #see queryDetailsForUidTag(int, String, long, long, int, int)
Parameters |
networkType |
int
|
subscriberId |
String
|
startTime |
long
|
endTime |
long
|
uid |
int
|
queryDetailsForUidTag
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. Only usable for uids belonging to calling user. Result is aggregated over state but not aggregated over time. This means buckets' start and end timestamps are going to be between 'startTime' and 'endTime' parameters. State is going to be STATE_ALL
, uid the same as the 'uid' parameter and tag the same as 'tag' parameter.
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.
Parameters |
networkType |
int : As defined in ConnectivityManager , e.g. TYPE_MOBILE , TYPE_WIFI etc. |
subscriberId |
String : If applicable, the subscriber id of the network interface. |
startTime |
long : Start of period. Defined in terms of "Unix time", see currentTimeMillis() . |
endTime |
long : End of period. Defined in terms of "Unix time", see currentTimeMillis() . |
uid |
int : UID of app |
tag |
int : TAG of interest. Use TAG_NONE for no tags. |
Returns |
NetworkStats |
Statistics object or null if an error happened during statistics collection. |
querySummary
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 or uid. This means buckets' start and end timestamps are going to be the same as the 'startTime' and 'endTime' parameters. State and uid are going to vary, and tag is going to be the same.
Returns |
NetworkStats |
Statistics object or null if permissions are insufficient or error happened during statistics collection. |
querySummaryForDevice
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 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 STATE_ALL
, uid UID_ALL
, tag TAG_NONE
and roaming ROAMING_ALL
.
Returns |
NetworkStats.Bucket |
Bucket object or null if permissions are insufficient or error happened during statistics collection. |
querySummaryForUser
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 STATE_ALL
and uid UID_ALL
.
Returns |
NetworkStats.Bucket |
Bucket object or null if permissions are insufficient or error happened during statistics collection. |
registerUsageCallback
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(NetworkStatsManager.UsageCallback)
is called.
Parameters |
networkType |
int : Type of network to monitor. Either TYPE_MOBILE or TYPE_WIFI . |
subscriberId |
String : If applicable, the subscriber id of the network interface. |
thresholdBytes |
long : Threshold in bytes to be notified on. |
callback |
NetworkStatsManager.UsageCallback : The NetworkStatsManager.UsageCallback that the system will call when data usage has exceeded the specified threshold. |
handler |
Handler : to dispatch callback events through, otherwise if null it uses the calling thread. |
registerUsageCallback
void registerUsageCallback (int networkType,
String subscriberId,
long thresholdBytes,
NetworkStatsManager.UsageCallback callback)
Registers to receive notifications about data usage on specified networks. #see registerUsageCallback(int, String[], long, UsageCallback, Handler)
Parameters |
networkType |
int
|
subscriberId |
String
|
thresholdBytes |
long
|
callback |
NetworkStatsManager.UsageCallback
|