1# @ohos.batteryStatistics (Battery Statistics) (System API)
2
3The **batteryStatistics** module provides APIs for querying software and hardware power consumption statistics.
4
5> **NOTE**
6>
7> - The initial APIs of this module are supported since API version 8. Newly added APIs will be marked with a superscript to indicate their earliest API version.
8>
9> - The APIs provided by this module are system APIs.
10
11## Modules to Import
12
13```js
14import {batteryStats} from '@kit.BasicServicesKit';
15```
16
17## batteryStats.getBatteryStats
18
19getBatteryStats(): Promise<Array&lt;BatteryStatsInfo&gt;>
20
21Obtains the power consumption information list. This API uses a promise to return the result.
22
23**System API**: This is a system API.
24
25**System capability**: SystemCapability.PowerManager.BatteryStatistics
26
27**Return value**
28
29| Type                                                 | Description                           |
30| ----------------------------------------------------- | ------------------------------- |
31| Promise<Array<[BatteryStatsInfo](#batterystatsinfo)>> | Promise used to return the power consumption information list.|
32
33**Error codes**
34
35For details about the error codes, see [Thermal Manager Error Codes](errorcode-batteryStatistics.md).
36
37| Code  | Error Message   |
38|---------|---------|
39| 4600101 | Failed to connect to the service. |
40| 202     | Permission verification failed. A non-system application calls a system API.  |
41
42**Example**
43
44```js
45batteryStats.getBatteryStats()
46.then((data: batteryStats.BatteryStatsInfo[]) => {
47    console.info('battery statistics info: ' + data);
48})
49.catch((err: Error) => {
50    console.error('get battery statistics failed, err: ' + err);
51});
52```
53
54## batteryStats.getBatteryStats
55
56getBatteryStats(callback: AsyncCallback<Array&lt;BatteryStatsInfo&gt;>): void
57
58Obtains the power consumption information list. This API uses an asynchronous callback to return the result.
59
60**System API**: This is a system API.
61
62**System capability**: SystemCapability.PowerManager.BatteryStatistics
63
64**Parameters**
65
66| Name  | Type                                                       | Mandatory| Description                                                        |
67| -------- | ----------------------------------------------------------- | ---- | ------------------------------------------------------------ |
68| callback | AsyncCallback<Array<[BatteryStatsInfo](#batterystatsinfo)>> | Yes  | Callback used to return the result. If the operation is successful, **err** is undefined and **data** is the obtained Array<[BatteryStatsInfo](#batterystatsinfo)>. Otherwise, **err** is an error object. **AsyncCallback** has encapsulated an API of the **BatteryStatsInfo** class.|
69
70**Error codes**
71
72For details about the error codes, see [Thermal Manager Error Codes](errorcode-batteryStatistics.md).
73
74| Code  | Error Message   |
75|---------|---------|
76| 4600101 | Failed to connect to the service. |
77| 401     | Parameter error. Possible causes: 1.Parameter verification failed. |
78| 202     | Permission verification failed. A non-system application calls a system API.  |
79
80**Example**
81
82```js
83batteryStats.getBatteryStats((err: Error, data : batteryStats.BatteryStatsInfo[]) => {
84    if (typeof err === 'undefined') {
85        console.info('battery statistics info: ' + data);
86    } else {
87        console.error('get battery statistics failed, err: ' + err);
88    }
89});
90```
91
92## batteryStats.getAppPowerValue
93
94getAppPowerValue(uid: number): number
95
96Obtains the power consumption of an application.
97
98**System API**: This is a system API.
99
100**System capability**: SystemCapability.PowerManager.BatteryStatistics
101
102**Parameters**
103
104| Name| Type  | Mandatory| Description       |
105| ------ | ------ | ---- | ----------- |
106| uid    | number | Yes  | Application UID.|
107
108**Return value**
109
110| Type  | Description                             |
111| ------ | --------------------------------- |
112| number | Power consumption of the application with this UID, in unit of mAh.|
113
114**Error codes**
115
116For details about the error codes, see [Thermal Manager Error Codes](errorcode-batteryStatistics.md).
117
118| Code  | Error Message   |
119|---------|---------|
120| 4600101 | Failed to connect to the service. |
121| 202     | Permission verification failed. A non-system application calls a system API.  |
122| 401     | Parameter error. Possible causes: 1.Parameter verification failed. |
123
124**Example**
125
126```js
127try {
128    let value = batteryStats.getAppPowerValue(10021);
129    console.info('battery statistics value of app is: ' + value);
130} catch(err) {
131    console.error('get battery statistics value of app failed, err: ' + err);
132}
133```
134
135## batteryStats.getAppPowerPercent
136
137getAppPowerPercent(uid: number): number
138
139Obtains the proportion of the power consumption of an application.
140
141**System API**: This is a system API.
142
143**System capability**: SystemCapability.PowerManager.BatteryStatistics
144
145**Parameters**
146
147| Name| Type  | Mandatory| Description       |
148| ------ | ------ | ---- | ----------- |
149| uid    | number | Yes  | Application UID.|
150
151**Return value**
152
153| Type  | Description                     |
154| ------ | ------------------------- |
155| number | Proportion of the power consumption of an application with this UID.|
156
157**Error codes**
158
159For details about the error codes, see [Thermal Manager Error Codes](errorcode-batteryStatistics.md).
160
161| Code  | Error Message   |
162|---------|---------|
163| 4600101 | Failed to connect to the service. |
164| 202     | Permission verification failed. A non-system application calls a system API.  |
165| 401     | Parameter error. Possible causes: 1.Parameter verification failed. |
166
167**Example**
168
169```js
170try {
171    let percent = batteryStats.getAppPowerPercent(10021);
172    console.info('battery statistics percent of app is: ' + percent);
173} catch(err) {
174    console.error('get battery statistics percent of app failed, err: ' + err);
175}
176```
177
178## batteryStats.getHardwareUnitPowerValue
179
180getHardwareUnitPowerValue(type: ConsumptionType): number
181
182Obtains the power consumption of a hardware unit according to the consumption type.
183
184**System API**: This is a system API.
185
186**System capability**: SystemCapability.PowerManager.BatteryStatistics
187
188**Parameters**
189
190| Name| Type                               | Mandatory| Description          |
191| ------ | ----------------------------------- | ---- | -------------- |
192| type   | [ConsumptionType](#consumptiontype) | Yes  | Power consumption type. The value must be an enum.|
193
194**Return value**
195
196| Type  | Description                                      |
197| ------ | ------------------------------------------ |
198| number | Power consumption of the hardware unit corresponding to the power consumption type, in unit of mAh.|
199
200**Error codes**
201
202For details about the error codes, see [Thermal Manager Error Codes](errorcode-batteryStatistics.md).
203
204| Code  | Error Message   |
205|---------|---------|
206| 4600101 | Failed to connect to the service. |
207| 401     | Parameter error. Possible causes: 1.Parameter verification failed. |
208| 202     | Permission verification failed. A non-system application calls a system API.  |
209
210**Example**
211
212```js
213try {
214    let value = batteryStats.getHardwareUnitPowerValue(batteryStats.ConsumptionType.CONSUMPTION_TYPE_SCREEN);
215    console.info('battery statistics value of hardware is: ' + value);
216} catch(err) {
217    console.error('get battery statistics percent of hardware failed, err: ' + err);
218}
219```
220
221## batteryStats.getHardwareUnitPowerPercent
222
223getHardwareUnitPowerPercent(type: ConsumptionType): number
224
225Obtains the proportion of the power consumption of a hardware unit according to the power consumption type.
226
227**System API**: This is a system API.
228
229**System capability**: SystemCapability.PowerManager.BatteryStatistics
230
231**Parameters**
232
233| Name| Type                               | Mandatory| Description          |
234| ------ | ----------------------------------- | ---- | -------------- |
235| type   | [ConsumptionType](#consumptiontype) | Yes  | Power consumption type. The value must be an enum.|
236
237**Return value**
238
239| Type  | Description                              |
240| ------ | ---------------------------------- |
241| number | Proportion of the power consumption of the hardware unit corresponding to the power consumption type.|
242
243**Error codes**
244
245For details about the error codes, see [Thermal Manager Error Codes](errorcode-batteryStatistics.md).
246
247| Code  | Error Message   |
248|---------|---------|
249| 4600101 | Failed to connect to the service. |
250| 401     | Parameter error. Possible causes: 1.Parameter verification failed. |
251| 202     | Permission verification failed. A non-system application calls a system API. |
252
253**Example**
254
255```js
256try {
257    let percent = batteryStats.getHardwareUnitPowerPercent(batteryStats.ConsumptionType.CONSUMPTION_TYPE_SCREEN);
258    console.info('battery statistics percent of hardware is: ' + percent);
259} catch(err) {
260    console.error('get battery statistics percent of hardware failed, err: ' + err);
261}
262```
263
264## BatteryStatsInfo
265
266Describes the device power consumption information.
267
268**System API**: This is a system API.
269
270**System capability**: SystemCapability.PowerManager.BatteryStatistics
271
272### Attributes
273
274| Name | Type                               | Readable| Writable| Description                  |
275| ----- | ----------------------------------- | ---- | ---- | ---------------------- |
276| uid   | number                              | Yes  | No  | UID related to power consumption information.   |
277| type  | [ConsumptionType](#consumptiontype) | Yes  | No  | Power consumption type.  |
278| power | number                              | Yes  | No  | Power consumption, in unit of mAh.|
279
280## ConsumptionType
281
282Enumerates power consumption types.
283
284**System API**: This is a system API.
285
286**System capability**: SystemCapability.PowerManager.BatteryStatistics
287
288| Name                      | Value  | Description                         |
289| -------------------------- | ---- | ----------------------------- |
290| CONSUMPTION_TYPE_INVALID   | -17  | Unknown type.       |
291| CONSUMPTION_TYPE_APP       | -16  | Power consumption of an application.     |
292| CONSUMPTION_TYPE_BLUETOOTH | -15  | Power consumption of Bluetooth.     |
293| CONSUMPTION_TYPE_IDLE      | -14  | Power consumption when the CPU is idle.|
294| CONSUMPTION_TYPE_PHONE     | -13  | Power consumption of a phone call. |
295| CONSUMPTION_TYPE_RADIO     | -12  | Power consumption of wireless communication. |
296| CONSUMPTION_TYPE_SCREEN    | -11  | Power consumption of the screen.     |
297| CONSUMPTION_TYPE_USER      | -10  | Power consumption of the user.     |
298| CONSUMPTION_TYPE_WIFI      | -9   | Power consumption of Wi-Fi.   |
299