<?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-C3B6E5F6-74DC-5C0E-94C8-B4822F4A2EB6" xml:lang="en"><title>Power

API Tutorial </title><shortdesc>This tutorial explains how to use the Power API of the HWRM. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<section><title>Introduction</title> <p>Power API methods can be used by constructing

an instance of <xref href="GUID-4A98138C-4C68-3399-80E8-25CB41E43D5C.dita"><apiname>CHWRMPower</apiname></xref> and calling

its functions. However, to use its full functionality write a class which

implements one or more of the observer interfaces described in the following

table. Then, construct an instance of <xref href="GUID-4A98138C-4C68-3399-80E8-25CB41E43D5C.dita"><apiname>CHWRMPower</apiname></xref> and

provide it with pointers to observers. </p> <table id="GUID-CC645CB8-B78E-5624-B669-31B5A08F77C2">

<tgroup cols="3"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/>

<thead>

<row>

<entry>Interface</entry>

<entry>Notification</entry>

<entry>Method to override</entry>

</row>

</thead>

<tbody>

<row>

<entry><p> <xref href="GUID-4A98138C-4C68-3399-80E8-25CB41E43D5C.dita"><apiname>MHWRMBatteryPowerObserver</apiname></xref>  </p> </entry>

<entry><p>Average battery voltage and current consumption </p> </entry>

<entry><p> <xref href="GUID-4A98138C-4C68-3399-80E8-25CB41E43D5C.dita"><apiname>PowerMeasurement</apiname></xref>  </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-4A98138C-4C68-3399-80E8-25CB41E43D5C.dita"><apiname>MHWRMBatteryChargingStatusObserver</apiname></xref>  </p> </entry>

<entry><p>Charging status </p> </entry>

<entry><p> <xref href="GUID-4A98138C-4C68-3399-80E8-25CB41E43D5C.dita"><apiname>ChargingStatusChange</apiname></xref>  </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-4A98138C-4C68-3399-80E8-25CB41E43D5C.dita"><apiname>MHWRMBatteryChargingCurrentObserver</apiname></xref>  </p> </entry>

<entry><p>Average charging current </p> </entry>

<entry><p> <xref href="GUID-4A98138C-4C68-3399-80E8-25CB41E43D5C.dita"><apiname>AverageChargingCurrentChange</apiname></xref>  </p> </entry>

</row>

<row>

<entry><p> <xref href="GUID-4A98138C-4C68-3399-80E8-25CB41E43D5C.dita"><apiname>MHWRMBatteryFullChargingTimeObserver</apiname></xref>  </p> </entry>

<entry><p>Remaining charging time </p> </entry>

<entry><p> <xref href="GUID-4A98138C-4C68-3399-80E8-25CB41E43D5C.dita"><apiname>BatteryFullChargingTimeChange</apiname></xref>  </p> </entry>

</row>

</tbody>

</tgroup>

</table> <p>For example, if the application requires periodic measurements

of average battery voltage and current consumption, it must implement <xref href="GUID-4A98138C-4C68-3399-80E8-25CB41E43D5C.dita"><apiname>MHWRMBatteryPowerObserver</apiname></xref> and instantiate a <xref href="GUID-4A98138C-4C68-3399-80E8-25CB41E43D5C.dita"><apiname>CHWRMPower</apiname></xref> object using the <xref href="GUID-4A98138C-4C68-3399-80E8-25CB41E43D5C.dita"><apiname>CHWRMPower::NewL(NULL,

MHWRMBatteryPowerObserver *)</apiname></xref> method. </p> <p> <b>Note:</b> The battery

charging observers cannot be passed to <xref href="GUID-4A98138C-4C68-3399-80E8-25CB41E43D5C.dita"><apiname>CHWRMPower</apiname></xref> using

a <xref href="GUID-4A98138C-4C68-3399-80E8-25CB41E43D5C.dita"><apiname>NewL()</apiname></xref> function. Call the dedicated

function, <xref href="GUID-4A98138C-4C68-3399-80E8-25CB41E43D5C.dita"><apiname>CHRMPower::SetBatteryChargingObserver()</apiname></xref>. </p> </section>

<section><title>Procedure</title> <ol id="GUID-8FD35358-CFCD-5010-AFD8-C277463B2970">

<li id="GUID-E7A8616C-DA3A-5CC7-831F-3BA977F7C129-GENID-1-7-1-8-1-1-5-1-4-1-5-1-8-1-3-2-2-1"><p><xref href="GUID-047E3462-F806-4C54-9DC5-6B78907CA949.dita">Derive

a class from one or more of the above interfaces</xref>. </p> </li>

<li id="GUID-E7A8616C-DA3A-5CC7-831F-3BA977F7C129-GENID-1-7-1-8-1-1-5-1-4-1-5-1-8-1-3-2-2-2"><p><xref href="GUID-047E3462-F806-4C54-9DC5-6B78907CA949.dita">Implement

the appropriate observer functions.</xref></p> </li>

<li id="GUID-6DF35505-CA49-56AB-94E2-4291E2DFF232"><p><xref href="GUID-BC627588-E8C7-4DDB-8313-7C57E0CCD93B.dita">Create

a power client using <apiname keyref="CHWRMPower">CHWRMPower::NewL()</apiname> or <apiname keyref="CHWRMPower">NewLC()</apiname>.</xref> </p><p><xref href="GUID-7CF7D29B-14A4-432E-BBB2-E3AF283E45E3.dita">You

can retrieve the battery voltage or consumption information.</xref></p> </li>

<li id="GUID-300E10F0-5414-55CB-8D9C-2B78E3782C34"><p><xref href="GUID-6CF00375-0A3E-4B85-9BA3-307BBB4ECFC7.dita">Call <apiname keyref="CHWRMPower">CHRMPower::SetBatteryChargingObserver()</apiname>, if

necessary.</xref></p> </li>

<li id="GUID-76E7EFB8-0464-5887-B144-1ACDFDE1D7F6"><p><xref href="GUID-FC7F8CFE-F9AD-4442-9289-CCEFEC62DF68.dita">Start

receiving notification using the appropriate start function(s).</xref> </p> </li>

<li id="GUID-209732A3-E374-54D2-87F7-5C3C45A23E85"><p><xref href="GUID-6A0D353D-A9B0-46EA-8FDC-1FBBD4A20CFB.dita">Stop

receiving notification using the appropriate stop function(s).</xref></p> </li>

</ol> <p> <b>Note: </b> If the notification period exceeds the maximum reporting

period, set when the HWRM server starts, notification is cancelled. </p> </section>

</conbody><related-links>

<link href="GUID-1E55DD3C-D699-5062-88C1-C826F06CD48C.dita"><linktext>Power API</linktext>

</link>