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