1 /*
2  * Copyright (C) 2016 The Android Open Source Project
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 package android.os.health;
18 
19 import android.annotation.SystemService;
20 import android.content.Context;
21 import android.os.BatteryStats;
22 import android.os.Process;
23 import android.os.RemoteException;
24 import android.os.ServiceManager;
25 import android.os.ServiceManager.ServiceNotFoundException;
26 
27 import com.android.internal.app.IBatteryStats;
28 
29 /**
30  * Provides access to data about how various system resources are used by applications.
31  * @more
32  * <p>
33  * If you are going to be using this class to log your application's resource usage,
34  * please consider the amount of resources (battery, network, etc) that will be used
35  * by the logging itself.  It can be substantial.
36  * <p>
37  * <b>Battery Usage</b><br>
38  * The statistics related to power (battery) usage are recorded since the device
39  * was last unplugged. It is expected that applications schedule more work to do
40  * while the device is plugged in (e.g. using {@link android.app.job.JobScheduler
41  * JobScheduler}), and while that can affect charging rates, it is still preferable
42  * to actually draining the battery.
43  */
44 @SystemService(Context.SYSTEM_HEALTH_SERVICE)
45 public class SystemHealthManager {
46     private final IBatteryStats mBatteryStats;
47 
48     /**
49      * Construct a new SystemHealthManager object.
50      * @hide
51      */
SystemHealthManager()52     public SystemHealthManager() {
53         this(IBatteryStats.Stub.asInterface(ServiceManager.getService(BatteryStats.SERVICE_NAME)));
54     }
55 
56     /** {@hide} */
SystemHealthManager(IBatteryStats batteryStats)57     public SystemHealthManager(IBatteryStats batteryStats) {
58         mBatteryStats = batteryStats;
59     }
60 
61     /**
62      * Obtain a SystemHealthManager object for the supplied context.
63      *
64      * @hide
65      */
from(Context context)66     public static SystemHealthManager from(Context context) {
67         return (SystemHealthManager)context.getSystemService(Context.SYSTEM_HEALTH_SERVICE);
68     }
69 
70     /**
71      * Return a {@link HealthStats} object containing a snapshot of system health
72      * metrics for the given uid (user-id, which in usually corresponds to application).
73      * @more
74      *
75      * An application must hold the {@link android.Manifest.permission#BATTERY_STATS
76      * android.permission.BATTERY_STATS} permission in order to retrieve any HealthStats
77      * other than its own.
78      *
79      * @param uid User ID for a given application.
80      * @return A {@link HealthStats} object containing the metrics for the requested
81      * application. The keys for this HealthStats object will be from the {@link UidHealthStats}
82      * class.
83      * @see Process#myUid() Process.myUid()
84      */
takeUidSnapshot(int uid)85     public HealthStats takeUidSnapshot(int uid) {
86         try {
87             final HealthStatsParceler parceler = mBatteryStats.takeUidSnapshot(uid);
88             return parceler.getHealthStats();
89         } catch (RemoteException ex) {
90             throw new RuntimeException(ex);
91         }
92     }
93 
94     /**
95      * Return a {@link HealthStats} object containing a snapshot of system health
96      * metrics for the application calling this API. This method is the same as calling
97      * {@code takeUidSnapshot(Process.myUid())}.
98      *
99      * @return A {@link HealthStats} object containing the metrics for this application. The keys
100      * for this HealthStats object will be from the {@link UidHealthStats} class.
101      */
takeMyUidSnapshot()102     public HealthStats takeMyUidSnapshot() {
103         return takeUidSnapshot(Process.myUid());
104     }
105 
106     /**
107      * Return a {@link HealthStats} object containing a snapshot of system health
108      * metrics for the given uids (user-id, which in usually corresponds to application).
109      * @more
110      *
111      * An application must hold the {@link android.Manifest.permission#BATTERY_STATS
112      * android.permission.BATTERY_STATS} permission in order to retrieve any HealthStats
113      * other than its own.
114      *
115      * @param uids An array of User IDs to retrieve.
116      * @return An array of {@link HealthStats} objects containing the metrics for each of
117      * the requested uids. The keys for this HealthStats object will be from the
118      * {@link UidHealthStats} class.
119      */
takeUidSnapshots(int[] uids)120     public HealthStats[] takeUidSnapshots(int[] uids) {
121         try {
122             final HealthStatsParceler[] parcelers = mBatteryStats.takeUidSnapshots(uids);
123             final HealthStats[] results = new HealthStats[uids.length];
124             final int N = uids.length;
125             for (int i=0; i<N; i++) {
126                 results[i] = parcelers[i].getHealthStats();
127             }
128             return results;
129         } catch (RemoteException ex) {
130             throw new RuntimeException(ex);
131         }
132     }
133 
134 }
135 
136