<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

<!-- This component and the accompanying materials are made available under the terms of the License 

"Eclipse Public License v1.0" which accompanies this distribution, 

and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

<!-- Initial Contributors:

    Nokia Corporation - initial contribution.

Contributors: 

-->

<!DOCTYPE concept

  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept id="GUID-03494D84-7E6D-5128-A8CF-2F6E25543591" xml:lang="en"><title>Power

States API Tutorial </title><shortdesc>This tutorial describes how to use the Power State API of HWRM.

The client applications subscribes to one or more of the three keys published

by this API. It is notified via the publish and subscribe framework

whenever the key is updated. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<section id="GUID-1E4A8512-08CA-57D7-A4DC-9809C54BB07E"><title>Introduction</title> <p>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. </p> <p>Refer

to <xref href="GUID-16A42EB3-4F45-5623-9981-1DEE3234471E.dita">Power States API</xref> section

to get more information about the keys published by the Power States API. </p> </section>

<example id="GUID-8FC57C06-8147-54E9-9FE6-3EBD08632D69"><title>Procedure</title> <p>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: </p> <ol id="GUID-00B23E06-ECDD-5893-9DC3-B5F508C48D32">

<li id="GUID-AFAC3B2F-D079-52CD-9823-1B599C15D300"><p>Create an instance of <codeph>CBattLevelWatch</codeph> using <codeph>NewL()</codeph>. </p> </li>

<li id="GUID-C3BDBE99-52B2-569A-B3F3-614E68468E3D"><p> <codeph>NewL()</codeph> calls <codeph>ConstructL()</codeph> and

completes the 2-phase construction. </p> </li>

<li id="GUID-9FBDAE7D-DF0C-539F-9531-171CB9F5CB05"><p> <codeph> RunL()</codeph> is

called, which subscribes to battery level status. </p> </li>

</ol> <p>Once the battery level is obtained asynchronously, you can switch

to the appropriate battery level. </p> </example>

<section><title>Example</title> <p>Header file: </p> <codeblock id="GUID-31A57213-9337-567A-B1A8-2E77C01CDA4A" xml:space="preserve">// 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;

    };</codeblock> <p>Source file: </p> <codeblock id="GUID-8A464018-4CFE-5722-A56D-A42012B48A37" xml:space="preserve">

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;

                }

            }

        }

    }

</codeblock> </section>

</conbody><related-links>

<link href="GUID-FE910347-7CC1-5241-B443-88AD3F5A96EF.dita"><linktext>Publish and

Subscribe documentation</linktext></link>