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
17package android.os.health;
18
19import android.annotation.SystemService;
20import android.content.Context;
21import android.os.BatteryStats;
22import android.os.Process;
23import android.os.RemoteException;
24import android.os.ServiceManager;
25import android.os.ServiceManager.ServiceNotFoundException;
26
27import 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)
45public class SystemHealthManager {
46    private final IBatteryStats mBatteryStats;
47
48    /**
49     * Construct a new SystemHealthManager object.
50     * @hide
51     */
52    public SystemHealthManager() {
53        this(IBatteryStats.Stub.asInterface(ServiceManager.getService(BatteryStats.SERVICE_NAME)));
54    }
55
56    /** {@hide} */
57    public SystemHealthManager(IBatteryStats batteryStats) {
58        mBatteryStats = batteryStats;
59    }
60
61    /**
62     * Obtain a SystemHealthManager object for the supplied context.
63     *
64     * @hide
65     */
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     */
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     */
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     */
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