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

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

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

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

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

     6 <!-- Initial Contributors:

     7     Nokia Corporation - initial contribution.

     8 Contributors: 

     9 -->

    10 <!DOCTYPE concept

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

    12 <concept id="GUID-65CDCA83-C726-5173-8E46-B8981D1D7B02" xml:lang="en"><title>Battery

    13 Monitor Implementation Tutorial</title><shortdesc>A base port can implement code to monitor the battery of the phone

    14 and to provide notifications when the battery power is low.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

    15 <p> The battery monitor code is implemented in the power controller kernel

    16 extension. </p>

    17 <p>Note: to implement battery monitor code, the battery monitor hardware must

    18 be accessible to the Application CPU of the phone. </p>

    19 <p>Typically, your battery monitor class would derive from the <codeph>DBatteryMonitor</codeph> class,

    20 defined as: </p>

    21 <codeblock id="GUID-D0249D2C-933F-584F-9596-126CCC4361AC" xml:space="preserve">class DBatteryMonitor

    22     {

    23 public:

    24     IMPORT_C DBatteryMonitor();

    25     IMPORT_C void Register();

    26 public:

    27     virtual TSupplyStatus MachinePowerStatus() = 0;

    28     virtual void SystemTimeChanged(TInt anOldTime, TInt aNewTime) = 0;

    29     };</codeblock>

    30 <p>Symbian platform considers that batteries can be in one of 4 possible logical

    31 states, defined by the <codeph>TSupplyStatus</codeph> enum. It is up to the

    32 implementor of the battery monitor component to map these logical states to

    33 points on the main battery discharge curve. </p>

    34 <p>There are two pure virtual functions to be implemented: </p>

    35 <ul>

    36 <li id="GUID-714DB74E-2405-54B5-B129-B6D2A3C4D5B5"><p> <xref href="GUID-65CDCA83-C726-5173-8E46-B8981D1D7B02.dita#GUID-65CDCA83-C726-5173-8E46-B8981D1D7B02/GUID-3471CC3E-0903-54F0-8EB2-5201AB139731">DBatteryMonitor::MachinePowerStatus()</xref> </p> </li>

    37 <li id="GUID-4296048D-82EC-5513-A089-E723D390EF5E"><p> <xref href="GUID-65CDCA83-C726-5173-8E46-B8981D1D7B02.dita#GUID-65CDCA83-C726-5173-8E46-B8981D1D7B02/GUID-1A5D9A50-1A28-59B5-862B-3DA5EAAAC26F">DBatteryMonitor::SystemTimeChanged()</xref> </p> </li>

    38 </ul>

    39 <p>We also suggest that the battery monitor component offer a public function

    40 prototyped as: </p>

    41 <codeblock id="GUID-EFB607B3-828C-54C3-A365-662FD6A74701" xml:space="preserve">void SupplyInfo(TSupplyInfoV1&amp; si);</codeblock>

    42 <p>to supply information about the state of the main battery and the backup

    43 battery (if there is one), or external power to user side components that

    44 may require it (e.g. a user-side power monitor component that is used to track

    45 the state of batteries and initiate an orderly shutdown if it reaches a critically

    46 low level), and is usually called by the <codeph>EHalGroupPower</codeph> handler

    47 for <codeph>EPowerHalSupplyInfo</codeph> in response to calling <codeph>HAL::Get()</codeph> with <codeph>EPowerGood</codeph>, <codeph>EPowerBatteryStatus</codeph>, <codeph>EPowerBackupStatus</codeph>, and <codeph>EPowerExternal</codeph>.

    48 Such a function would need to fill in a subset of the fields defined by <codeph>TSupplyInfoV1</codeph>. </p>

    49 <section id="GUID-3471CC3E-0903-54F0-8EB2-5201AB139731"><title>DBatteryMonitor::MachinePowerStatus()</title> <codeblock id="GUID-32E4B2FF-F638-59DC-98B9-CBFE15E1FCEC" xml:space="preserve">virtual TSupplyStatus MachinePowerStatus() = 0;</codeblock> <p>This

    50 should read and return the logical state of the main battery or, if external

    51 power is connected, it should return <codeph>EGood</codeph>. </p> <p><b>When

    52 is it called?</b> </p> <p>The function is called by peripheral drivers via

    53 a call to <xref href="GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D.dita#GUID-C6946ECB-775F-3EC2-A56F-78F25B9FBE3D/GUID-84835157-E5B9-3834-8FFC-CD482A946F4A"><apiname>Kern::MachinePowerStatus()</apiname></xref> before starting lengthy

    54 operations or operations that may result in a substantial increase in power

    55 consumption. </p> <p><b>Implementation issues</b> </p> <p>A suggested implementation

    56 would have the function reading the state of the main battery, or whether

    57 external power is connected, and mapping to one of the logical states defined

    58 by <codeph>TSupplyStatus</codeph>. When requested by the power manager it

    59 returns the logical state. </p> </section>

    60 <section id="GUID-1A5D9A50-1A28-59B5-862B-3DA5EAAAC26F"><title>DBatteryMonitor::SystemTimeChanged()</title> <codeblock id="GUID-CC55B65D-B849-5FAA-A678-3DFD58D14F9D" xml:space="preserve">virtual void SystemTimeChanged(TInt anOldTime, TInt aNewTime) = 0;</codeblock> <p>This

    61 function is now deprecated, and you should just define an empty implementation. </p> </section>

    62 </conbody></concept>