• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1 /*
2  * Copyright (C) 2020 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;
18 
19 import android.annotation.IntDef;
20 import android.annotation.NonNull;
21 import android.util.IntArray;
22 
23 import java.lang.annotation.Retention;
24 import java.lang.annotation.RetentionPolicy;
25 
26 /**
27  * Query parameters for the {@link BatteryStatsManager#getBatteryUsageStats()} call.
28  *
29  * @hide
30  */
31 public final class BatteryUsageStatsQuery implements Parcelable {
32 
33     @NonNull
34     public static final BatteryUsageStatsQuery DEFAULT =
35             new BatteryUsageStatsQuery.Builder().build();
36 
37     /**
38      * Flags for the {@link BatteryStatsManager#getBatteryUsageStats()} method.
39      * @hide
40      */
41     @IntDef(flag = true, prefix = { "FLAG_BATTERY_USAGE_STATS_" }, value = {
42             FLAG_BATTERY_USAGE_STATS_POWER_PROFILE_MODEL,
43             FLAG_BATTERY_USAGE_STATS_INCLUDE_HISTORY,
44             FLAG_BATTERY_USAGE_STATS_INCLUDE_PROCESS_STATE_DATA,
45             FLAG_BATTERY_USAGE_STATS_INCLUDE_VIRTUAL_UIDS,
46     })
47     @Retention(RetentionPolicy.SOURCE)
48     public @interface BatteryUsageStatsFlags {}
49 
50     /**
51      * Indicates that power estimations should be based on the usage time and
52      * average power constants provided in the PowerProfile, even if on-device power monitoring
53      * is available.
54      *
55      * @hide
56      */
57     public static final int FLAG_BATTERY_USAGE_STATS_POWER_PROFILE_MODEL = 0x0001;
58 
59     /**
60      * Indicates that battery history should be included in the BatteryUsageStats.
61      * @hide
62      */
63     public static final int FLAG_BATTERY_USAGE_STATS_INCLUDE_HISTORY = 0x0002;
64 
65     /**
66      * Indicates that identifiers of power models used for computations of power
67      * consumption should be included in the BatteryUsageStats.
68      */
69     public static final int FLAG_BATTERY_USAGE_STATS_INCLUDE_POWER_MODELS = 0x0004;
70 
71     public static final int FLAG_BATTERY_USAGE_STATS_INCLUDE_PROCESS_STATE_DATA = 0x0008;
72 
73     public static final int FLAG_BATTERY_USAGE_STATS_INCLUDE_VIRTUAL_UIDS = 0x0010;
74 
75     private static final long DEFAULT_MAX_STATS_AGE_MS = 5 * 60 * 1000;
76 
77     private final int mFlags;
78     @NonNull
79     private final int[] mUserIds;
80     private final long mMaxStatsAgeMs;
81     private final long mFromTimestamp;
82     private final long mToTimestamp;
83     private final @BatteryConsumer.PowerComponent int[] mPowerComponents;
84 
BatteryUsageStatsQuery(@onNull Builder builder)85     private BatteryUsageStatsQuery(@NonNull Builder builder) {
86         mFlags = builder.mFlags;
87         mUserIds = builder.mUserIds != null ? builder.mUserIds.toArray()
88                 : new int[]{UserHandle.USER_ALL};
89         mMaxStatsAgeMs = builder.mMaxStatsAgeMs;
90         mFromTimestamp = builder.mFromTimestamp;
91         mToTimestamp = builder.mToTimestamp;
92         mPowerComponents = builder.mPowerComponents;
93     }
94 
95     @BatteryUsageStatsFlags
getFlags()96     public int getFlags() {
97         return mFlags;
98     }
99 
100     /**
101      * Returns an array of users for which the attribution is requested.  It may
102      * contain {@link UserHandle#USER_ALL} to indicate that the attribution
103      * should be performed for all users. Battery consumed by users <b>not</b> included
104      * in this array will be returned in the aggregated form as {@link UserBatteryConsumer}'s.
105      */
106     @NonNull
getUserIds()107     public int[] getUserIds() {
108         return mUserIds;
109     }
110 
111     /**
112      * Returns true if the power calculations must be based on the PowerProfile constants,
113      * even if measured energy data is available.
114      */
shouldForceUsePowerProfileModel()115     public boolean shouldForceUsePowerProfileModel() {
116         return (mFlags & FLAG_BATTERY_USAGE_STATS_POWER_PROFILE_MODEL) != 0;
117     }
118 
isProcessStateDataNeeded()119     public boolean isProcessStateDataNeeded() {
120         return (mFlags & FLAG_BATTERY_USAGE_STATS_INCLUDE_PROCESS_STATE_DATA) != 0;
121     }
122 
123     /**
124      * Returns the power components that should be estimated or null if all power components
125      * are being requested.
126      */
getPowerComponents()127     public int[] getPowerComponents() {
128         return mPowerComponents;
129     }
130 
131     /**
132      * Returns the client's tolerance for stale battery stats. The data is allowed to be up to
133      * this many milliseconds out-of-date.
134      */
getMaxStatsAge()135     public long getMaxStatsAge() {
136         return mMaxStatsAgeMs;
137     }
138 
139     /**
140      * Returns the exclusive lower bound of the stored snapshot timestamps that should be included
141      * in the aggregation.  Ignored if {@link #getToTimestamp()} is zero.
142      */
getFromTimestamp()143     public long getFromTimestamp() {
144         return mFromTimestamp;
145     }
146 
147     /**
148      * Returns the inclusive upper bound of the stored snapshot timestamps that should
149      * be included in the aggregation.  The default is to include only the current stats
150      * accumulated since the latest battery reset.
151      */
getToTimestamp()152     public long getToTimestamp() {
153         return mToTimestamp;
154     }
155 
BatteryUsageStatsQuery(Parcel in)156     private BatteryUsageStatsQuery(Parcel in) {
157         mFlags = in.readInt();
158         mUserIds = new int[in.readInt()];
159         in.readIntArray(mUserIds);
160         mMaxStatsAgeMs = in.readLong();
161         mFromTimestamp = in.readLong();
162         mToTimestamp = in.readLong();
163         mPowerComponents = in.createIntArray();
164     }
165 
166     @Override
writeToParcel(Parcel dest, int flags)167     public void writeToParcel(Parcel dest, int flags) {
168         dest.writeInt(mFlags);
169         dest.writeInt(mUserIds.length);
170         dest.writeIntArray(mUserIds);
171         dest.writeLong(mMaxStatsAgeMs);
172         dest.writeLong(mFromTimestamp);
173         dest.writeLong(mToTimestamp);
174         dest.writeIntArray(mPowerComponents);
175     }
176 
177     @Override
describeContents()178     public int describeContents() {
179         return 0;
180     }
181 
182     @NonNull
183     public static final Creator<BatteryUsageStatsQuery> CREATOR =
184             new Creator<BatteryUsageStatsQuery>() {
185                 @Override
186                 public BatteryUsageStatsQuery createFromParcel(Parcel in) {
187                     return new BatteryUsageStatsQuery(in);
188                 }
189 
190                 @Override
191                 public BatteryUsageStatsQuery[] newArray(int size) {
192                     return new BatteryUsageStatsQuery[size];
193                 }
194             };
195 
196     /**
197      * Builder for BatteryUsageStatsQuery.
198      */
199     public static final class Builder {
200         private int mFlags;
201         private IntArray mUserIds;
202         private long mMaxStatsAgeMs = DEFAULT_MAX_STATS_AGE_MS;
203         private long mFromTimestamp;
204         private long mToTimestamp;
205         private @BatteryConsumer.PowerComponent int[] mPowerComponents;
206 
207         /**
208          * Builds a read-only BatteryUsageStatsQuery object.
209          */
build()210         public BatteryUsageStatsQuery build() {
211             return new BatteryUsageStatsQuery(this);
212         }
213 
214         /**
215          * Add a user whose battery stats should be included in the battery usage stats.
216          * {@link UserHandle#USER_ALL} will be used by default if no users are added explicitly.
217          */
addUser(@onNull UserHandle userHandle)218         public Builder addUser(@NonNull UserHandle userHandle) {
219             if (mUserIds == null) {
220                 mUserIds = new IntArray(1);
221             }
222             mUserIds.add(userHandle.getIdentifier());
223             return this;
224         }
225 
226         /**
227          * Requests that battery history be included in the BatteryUsageStats.
228          */
includeBatteryHistory()229         public Builder includeBatteryHistory() {
230             mFlags |= BatteryUsageStatsQuery.FLAG_BATTERY_USAGE_STATS_INCLUDE_HISTORY;
231             return this;
232         }
233 
234         /**
235          * Requests that per-process state data be included in the BatteryUsageStats, if
236          * available. Check {@link BatteryUsageStats#isProcessStateDataIncluded()} on the result
237          * to see if the data is available.
238          */
includeProcessStateData()239         public Builder includeProcessStateData() {
240             mFlags |= BatteryUsageStatsQuery.FLAG_BATTERY_USAGE_STATS_INCLUDE_PROCESS_STATE_DATA;
241             return this;
242         }
243 
244         /**
245          * Requests to return modeled battery usage stats only, even if on-device
246          * power monitoring data is available.
247          *
248          * Should only be used for testing and debugging.
249          */
powerProfileModeledOnly()250         public Builder powerProfileModeledOnly() {
251             mFlags |= BatteryUsageStatsQuery.FLAG_BATTERY_USAGE_STATS_POWER_PROFILE_MODEL;
252             return this;
253         }
254 
255         /**
256          * Requests to return identifiers of models that were used for estimation
257          * of power consumption.
258          *
259          * Should only be used for testing and debugging.
260          */
includePowerModels()261         public Builder includePowerModels() {
262             mFlags |= BatteryUsageStatsQuery.FLAG_BATTERY_USAGE_STATS_INCLUDE_POWER_MODELS;
263             return this;
264         }
265 
266         /**
267          * Requests to return only statistics for the specified power components.  The default
268          * is all power components.
269          */
includePowerComponents( @atteryConsumer.PowerComponent int[] powerComponents)270         public Builder includePowerComponents(
271                 @BatteryConsumer.PowerComponent int[] powerComponents) {
272             mPowerComponents = powerComponents;
273             return this;
274         }
275 
276         /**
277          * Requests to return attribution data for virtual UIDs such as
278          * {@link Process#SDK_SANDBOX_VIRTUAL_UID}.
279          */
includeVirtualUids()280         public Builder includeVirtualUids() {
281             mFlags |= BatteryUsageStatsQuery.FLAG_BATTERY_USAGE_STATS_INCLUDE_VIRTUAL_UIDS;
282             return this;
283         }
284 
285         /**
286          * Requests to aggregate stored snapshots between the two supplied timestamps
287          * @param fromTimestamp Exclusive starting timestamp, as per System.currentTimeMillis()
288          * @param toTimestamp Inclusive ending timestamp, as per System.currentTimeMillis()
289          */
aggregateSnapshots(long fromTimestamp, long toTimestamp)290         public Builder aggregateSnapshots(long fromTimestamp, long toTimestamp) {
291             mFromTimestamp = fromTimestamp;
292             mToTimestamp = toTimestamp;
293             return this;
294         }
295 
296         /**
297          * Set the client's tolerance for stale battery stats. The data may be up to
298          * this many milliseconds out-of-date.
299          */
setMaxStatsAgeMs(long maxStatsAgeMs)300         public Builder setMaxStatsAgeMs(long maxStatsAgeMs) {
301             mMaxStatsAgeMs = maxStatsAgeMs;
302             return this;
303         }
304     }
305 }
306