public class NetworkStatsManager extends Object
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.
querySummaryForDevice(int, java.lang.String, long, long)
querySummaryForUser(int, java.lang.String, long, long)
querySummary(int, java.lang.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.
queryDetailsForUid(int, java.lang.String, long, long, int)
queryDetails(int, java.lang.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
NetworkStats.Bucket.STATE_ALL
and all Bucket's roaming is going to be
NetworkStats.Bucket.ROAMING_ALL
.
NOTE: Calling querySummaryForDevice(int, java.lang.String, long, long)
or accessing stats for apps other than the
calling app requires the permission android.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, java.lang.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 , 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.Modifier and Type | Class and Description |
---|---|
static class |
NetworkStatsManager.UsageCallback
Base class for usage callbacks.
|
Modifier and Type | Field and Description |
---|---|
static int |
CALLBACK_LIMIT_REACHED |
static int |
CALLBACK_RELEASED |
Constructor and Description |
---|
NetworkStatsManager(Context context) |
Modifier and Type | Method and Description |
---|---|
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)
Registers to receive notifications about data usage on specified networks.
|
void |
registerUsageCallback(int networkType,
String subscriberId,
long thresholdBytes,
NetworkStatsManager.UsageCallback callback,
Handler handler)
Registers to receive notifications about data usage on specified networks.
|
void |
unregisterUsageCallback(NetworkStatsManager.UsageCallback callback)
Unregisters callbacks on data usage.
|
public static final int CALLBACK_LIMIT_REACHED
public static final int CALLBACK_RELEASED
public NetworkStatsManager(Context context)
public NetworkStats.Bucket querySummaryForDevice(int networkType, String subscriberId, long startTime, long endTime) throws SecurityException, RemoteException
NetworkStats.Bucket.STATE_ALL
, uid
NetworkStats.Bucket.UID_ALL
, tag NetworkStats.Bucket.TAG_NONE
and roaming NetworkStats.Bucket.ROAMING_ALL
.networkType
- As defined in ConnectivityManager
, e.g.
ConnectivityManager.TYPE_MOBILE
, ConnectivityManager.TYPE_WIFI
etc.subscriberId
- If applicable, the subscriber id of the network interface.startTime
- Start of period. Defined in terms of "Unix time", see
System.currentTimeMillis()
.endTime
- End of period. Defined in terms of "Unix time", see
System.currentTimeMillis()
.SecurityException
RemoteException
public NetworkStats.Bucket querySummaryForUser(int networkType, String subscriberId, long startTime, long endTime) throws SecurityException, RemoteException
NetworkStats.Bucket.STATE_ALL
and uid
NetworkStats.Bucket.UID_ALL
.networkType
- As defined in ConnectivityManager
, e.g.
ConnectivityManager.TYPE_MOBILE
, ConnectivityManager.TYPE_WIFI
etc.subscriberId
- If applicable, the subscriber id of the network interface.startTime
- Start of period. Defined in terms of "Unix time", see
System.currentTimeMillis()
.endTime
- End of period. Defined in terms of "Unix time", see
System.currentTimeMillis()
.SecurityException
RemoteException
public NetworkStats querySummary(int networkType, String subscriberId, long startTime, long endTime) throws SecurityException, RemoteException
networkType
- As defined in ConnectivityManager
, e.g.
ConnectivityManager.TYPE_MOBILE
, ConnectivityManager.TYPE_WIFI
etc.subscriberId
- If applicable, the subscriber id of the network interface.startTime
- Start of period. Defined in terms of "Unix time", see
System.currentTimeMillis()
.endTime
- End of period. Defined in terms of "Unix time", see
System.currentTimeMillis()
.SecurityException
RemoteException
public NetworkStats queryDetailsForUid(int networkType, String subscriberId, long startTime, long endTime, int uid) throws SecurityException, RemoteException
SecurityException
RemoteException
public NetworkStats queryDetailsForUidTag(int networkType, String subscriberId, long startTime, long endTime, int uid, int tag) throws SecurityException
NetworkStats.Bucket.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.
networkType
- As defined in ConnectivityManager
, e.g.
ConnectivityManager.TYPE_MOBILE
, ConnectivityManager.TYPE_WIFI
etc.subscriberId
- If applicable, the subscriber id of the network interface.startTime
- Start of period. Defined in terms of "Unix time", see
System.currentTimeMillis()
.endTime
- End of period. Defined in terms of "Unix time", see
System.currentTimeMillis()
.uid
- UID of apptag
- TAG of interest. Use NetworkStats.Bucket.TAG_NONE
for no tags.SecurityException
- if permissions are insufficient to read network statistics.public NetworkStats queryDetails(int networkType, String subscriberId, long startTime, long endTime) throws SecurityException, RemoteException
NetworkStats.Bucket.STATE_ALL
, uid will vary,
tag NetworkStats.Bucket.TAG_NONE
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.
networkType
- As defined in ConnectivityManager
, e.g.
ConnectivityManager.TYPE_MOBILE
, ConnectivityManager.TYPE_WIFI
etc.subscriberId
- If applicable, the subscriber id of the network interface.startTime
- Start of period. Defined in terms of "Unix time", see
System.currentTimeMillis()
.endTime
- End of period. Defined in terms of "Unix time", see
System.currentTimeMillis()
.SecurityException
RemoteException
public void registerUsageCallback(int networkType, String subscriberId, long thresholdBytes, NetworkStatsManager.UsageCallback callback)
public void registerUsageCallback(int networkType, String subscriberId, long thresholdBytes, NetworkStatsManager.UsageCallback callback, Handler handler)
The callbacks will continue to be called as long as the process is live or
unregisterUsageCallback(android.app.usage.NetworkStatsManager.UsageCallback)
is called.
networkType
- Type of network to monitor. Either
ConnectivityManager.TYPE_MOBILE
or ConnectivityManager.TYPE_WIFI
.subscriberId
- If applicable, the subscriber id of the network interface.thresholdBytes
- Threshold in bytes to be notified on.callback
- The NetworkStatsManager.UsageCallback
that the system will call when data usage
has exceeded the specified threshold.handler
- to dispatch callback events through, otherwise if null
it uses
the calling thread.public void unregisterUsageCallback(NetworkStatsManager.UsageCallback callback)
callback
- The NetworkStatsManager.UsageCallback
used when registering.