<?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-65CDCA83-C726-5173-8E46-B8981D1D7B02" xml:lang="en"><title>Battery
Monitor Implementation Tutorial</title><shortdesc>A base port can implement code to monitor the battery of the phone
and to provide notifications when the battery power is low.</shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>
<p> The battery monitor code is implemented in the power controller kernel
extension. </p>
<p>Note: to implement battery monitor code, the battery monitor hardware must
be accessible to the Application CPU of the phone. </p>
<p>Typically, your battery monitor class would derive from the <codeph>DBatteryMonitor</codeph> class,
defined as: </p>
<codeblock id="GUID-D0249D2C-933F-584F-9596-126CCC4361AC" xml:space="preserve">class DBatteryMonitor
    {
public:
    IMPORT_C DBatteryMonitor();
    IMPORT_C void Register();
public:
    virtual TSupplyStatus MachinePowerStatus() = 0;
    virtual void SystemTimeChanged(TInt anOldTime, TInt aNewTime) = 0;
    };</codeblock>
<p>Symbian platform considers that batteries can be in one of 4 possible logical
states, defined by the <codeph>TSupplyStatus</codeph> enum. It is up to the
implementor of the battery monitor component to map these logical states to
points on the main battery discharge curve. </p>
<p>There are two pure virtual functions to be implemented: </p>
<ul>
<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>
<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>
</ul>
<p>We also suggest that the battery monitor component offer a public function
prototyped as: </p>
<codeblock id="GUID-EFB607B3-828C-54C3-A365-662FD6A74701" xml:space="preserve">void SupplyInfo(TSupplyInfoV1&amp; si);</codeblock>
<p>to supply information about the state of the main battery and the backup
battery (if there is one), or external power to user side components that
may require it (e.g. a user-side power monitor component that is used to track
the state of batteries and initiate an orderly shutdown if it reaches a critically
low level), and is usually called by the <codeph>EHalGroupPower</codeph> handler
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>.
Such a function would need to fill in a subset of the fields defined by <codeph>TSupplyInfoV1</codeph>. </p>
<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
should read and return the logical state of the main battery or, if external
power is connected, it should return <codeph>EGood</codeph>. </p> <p><b>When
is it called?</b> </p> <p>The function is called by peripheral drivers via
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
operations or operations that may result in a substantial increase in power
consumption. </p> <p><b>Implementation issues</b> </p> <p>A suggested implementation
would have the function reading the state of the main battery, or whether
external power is connected, and mapping to one of the logical states defined
by <codeph>TSupplyStatus</codeph>. When requested by the power manager it
returns the logical state. </p> </section>
<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
function is now deprecated, and you should just define an empty implementation. </p> </section>
</conbody></concept>