Power States API Tutorial

Introduction

A key represents one of the parameters of the battery such as charging state, battery level and battery state, hence there are three keys published by the Power State API. The client applications can subscribe to any or all three keys published, depending on the type of information the client requires. Each key is updated by the HWRM server whenever there has been a change in the hardware state of the battery level, battery state or charging state.

Refer to Power States API section to get more information about the keys published by the Power States API.

Procedure

The following steps explains a simple example of how an active object may be created to subscribe to the battery level Publish and Subscribe key:

1. Create an instance of CBattLevelWatch using NewL().

2. NewL() calls ConstructL() and completes the 2-phase construction.

3. RunL() is called, which subscribes to battery level status.

Once the battery level is obtained asynchronously, you can switch to the appropriate battery level.

Example

Header file:

// Active object that tracks changes to the ‘BatteryLevel’ property
class CBattLevelWatch : public CActive
    {
    enum {EPriority=0};
    public:
        static CBattLevelWatch* NewL();
    private:
        CBattLevelWatch();
        void ConstructL();
        ~CBattLevelWatch();
        void RunL();
        void DoCancel(); 
    private:
        RProperty iProperty;
    };

Source file:

CBattLevelWatch* CBattLevelWatch::NewL()
    {
    CBattLevelWatch* me=new( ELeave ) CBattLevelWatch;
    CleanupStack::PushL( me );
    me->ConstructL();
    CleanupStack::Pop( me );
    return me;
    }

CBattLevelWatch::CBattLevelWatch()
    :CActive( EPriority )
    {}

void CBattLevelWatch::ConstructL()
    {
    User::LeaveIfError( iProperty.Attach( KPSUidHWRMPowerState,KHWRMBatteryLevel ) );
    CActiveScheduler::Add( this );
    // initial subscription and process current property value
    RunL();
    }

CBattLevelWatch::~CBattLevelWatch()
    {
    Cancel();
    iProperty.Close();
    }

void CBattLevelWatch::DoCancel()
    {
    iProperty.Cancel();
    }

void CBattLevelWatch::RunL()
    {
    // resubscribe before processing new value to prevent missing updates
    iProperty.Subscribe( iStatus );
    SetActive();

    // property updated, get new value
    TInt batteryLevel;
    if( iProperty.Get( batteryLevel )==KErrNotFound )
        {
        // property deleted, do necessary actions here...
        . . .
        }
    else
        {
        // use new value battery level...
        switch( batteryLevel )
            {
            case EBatteryLevelUnknown:
                {
                // Handle uninitialized or some other error value
                . . .
                break;
                }
            case EBatteryLevelLevel0:
                {
                // Handle Lowest battery level value
                . . .
                break;
                }
            case EBatteryLevelLevel1:
                {
                // Handle battery level 1 value
                . . .
                break;
                }
            case EBatteryLevelLevel2:
                {
                // Handle battery level 2 value
                . . .
                break;
                }
            case EBatteryLevelLevel3:
                {
                // Handle battery level 3 value
                . . .
                break;
                }
            case EBatteryLevelLevel4:
                {
                // Handle battery level 4 value
                . . .
                break;
                }
            case EBatteryLevelLevel5:
                {
                // Handle battery level 5 value
                . . .
                break;
                }
            case EBatteryLevelLevel6:
                {
                // Handle battery level 6 value
                . . .
                break;
                }
            case EBatteryLevelLevel7:
                {
                // Handle Highest battery level value
                . . .
                break;
                }
            default:
                {
                // Handle UNKNOWN BATTERY LEVEL!
                break;
                }
            }
        }
    }