Power State API

Power State API provides the Publish and Subscribe (P&S) power state keys that are updated by HWRM server.

The P&S power state keys provide up-to-date information on the charging status, battery level and battery state of the device. Any application may subscribe to these keys that are updated to receive notifications for any change in state. This interface is provided by three Publish and Subscribe keys. For details on using the P&S API, refer to the Publish and Subscribe documentation.

P&S is used by HW Resource Manager to globally publish the power state information. The P&S UID is KPSUidHWRMPowerState and provides the following keys:

KHWRMBatteryLevel

P&S key to represent the battery level of the device. It also relates to the number of battery bars displayed. This property is updated only when battery level changes. Valid values are defined by the EPSHWRMBatteryLevel enumeration and ranges from -1 to 7.

If an error occurs or the battery level is not initialized, the enumeration value of EBatteryLevelUnknown is used. In all other scenarios, the battery level is used with level 0 being the lowest (battery empty) and level 7 the highest (battery full).

Refer to the Keys and Enumerations section for more information.

KHWRMBatteryStatus

P&S key to represent the battery status of the device. For example, Uninitialized, Ok, Low, Empty. This property may be updated to same status as previously, to indicate that the note in question must be displayed again.

EPSHWRMBatteryStatus enumeration defines the valid values as shown in the following table:

EPSHWRMBatteryStatus Description

EBatteryStatusUnknown

Battery status is unknown or some error has occurred in retrieving the battery status.

EBatteryStatusOk

Battery level is normal.

EBatteryStatusLow

Battery level is low, and the user can be notified with a message warning them that battery is low. This value is updated approximately ten times before battery is completely empty and updated comes at approximately 10-minute intervals. If phone is in-call mode, update comes at approximately 1-minute intervals.

EBatteryStatusEmpty

Battery level is empty. This value is updated slightly before the phone must be powered down automatically because of insufficient battery power.

Refer to the Keys and Enumerations section for more information.

KHWRMChargingStatus

P&S key to represent the charging status of the device. For example, Charging, NotCharging, ChargingComplete. This property is updated only when charging status changes.

EPSHWRMChargingStatus enumeration defines the valid values as shown in the following table:

EPSHWRMChargingStatus Description

EChargingStatusError

An error occurred when the charger is connected to the device.

EChargingStatusNotConnected

A charger has not been connected to the device. This also represents the uninitialized value if no charger has been initialized.

EChargingStatusCharging

Charger is connected to the device and charging is ongoing.

EChargingStatusNotCharging

Charger is connected to the device but the device is not charging, for example, due to battery being full.

EChargingStatusAlmostComplete

Device is charging and the battery is almost full.

EChargingStatusChargingComplete

Charging has just been completed, and hence a notification may be shown to the user if required.

EChargingStatusChargingContinued

Special case where charging was interrupted briefly but is now continuing, for example, when a dynamo type of charger is used.

Refer to the Keys and Enumerations section for more information.

Keys

Keys Valid Values Description

KHWRMBatteryLevel

0x00000001

P&S key representing battery level of device.

KHWRMBatteryStatus

0x00000002

P&S key representing battery status of device.

KHWRMChargingStatus

0x00000003

P&S key representing charging status of device.

Enumerations

Battery level of device

Interpreted as EPSHWRMBatteryLevel enumeration and can be related to the number of battery bars displayed by the device.

EPSHWRMBatteryLevel Valid Values Description

EBatteryLevelUnknown

-1

Uninitialized or some other error.

EBatteryLevelLevel0

0

Lowest battery level.

EBatteryLevelLevel1

1

Battery Level 1.

EBatteryLevelLevel2

2

Battery Level 2.

EBatteryLevelLevel3

3

Intermediate levels

EBatteryLevelLevel4

4

Battery Level 4.

EBatteryLevelLevel5

5

Battery Level 5.

EBatteryLevelLevel6

6

Battery Level 6.

EBatteryLevelLevel7

7

Highest battery level.

Battery status of device

Interpreted as EPSHWRMBatteryStatus enumeration and can be related to the battery status of the device.

EPSHWRMBatteryStatus Valid Values Description

EBatteryStatusUnknown

-1

Uninitialized or some other error.

EBatteryStatusOk

0

This can also be used during charging.

EBatteryStatusLow

1

Show "Battery low " note to user .

EBatteryStatusEmpty

2

Show "Recharge battery " note to user.

Charging status of device

Interpreted as enumeration EPSHWRMChargingStatus and can be related to the charging status of the device.

EPSHWRMChargingStatus Valid Values Description

EChargingStatusError

-1

Some error has occurred when charger is connected or charging.

EChargingStatusNotConnected

0

Charger uninitialized or not connected.

EChargingStatusCharging

1

Device is charging.

EChargingStatusNotCharging

2

Charger is connected, device not charging.

EChargingStatusAlmostComplete

3

Charging almost completed.

EChargingStatusChargingComplete

4

Charging completed.

EChargingStatusChargingContinued

5

Charging continued after brief interruption.

Related concepts
Power State API Tutorial