<?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-54042C84-6216-5930-9CBF-BAF635CECD4D" xml:lang="en"><title>Power

HAL Handler Tutorial</title><shortdesc>User-side programs can get and set a number of system attributes

about power using the <apiname>HAL</apiname> interface. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>The base port must provide and register a HAL handler to handle these attributes. </p>

<p>The power attributes are in the <xref href="GUID-FB85CE22-DDFF-37E6-A6CE-7F70A994D371.dita"><apiname>EHalGroupPower</apiname></xref> HAL group.

The handler provides a kernel-side implementation to deal with the user-side

calls to <xref href="GUID-BD00E7FC-C234-3111-87A5-10F79EB0F2B8.dita#GUID-BD00E7FC-C234-3111-87A5-10F79EB0F2B8/GUID-573C49D6-7763-37AE-B2B2-4C8FB1327E21"><apiname>HAL::Get()</apiname></xref> and <xref href="GUID-BD00E7FC-C234-3111-87A5-10F79EB0F2B8.dita#GUID-BD00E7FC-C234-3111-87A5-10F79EB0F2B8/GUID-9454F1B2-D525-3D6D-A872-C6457CACD4FC"><apiname>HAL::Set()</apiname></xref> when

one of the following parameters is passed: </p>

<ul>

<li id="GUID-9AEBA9C2-BF3C-541D-BFD0-4E610DBE80A3"><p> <xref href="GUID-8BE90160-2C60-3582-82C8-4A108C7C0317.dita#GUID-8BE90160-2C60-3582-82C8-4A108C7C0317/GUID-7344DA81-987E-351E-9F91-7AA78C3FA033"><apiname>HALData::EPowerGood</apiname></xref>  </p> </li>

<li id="GUID-5F3A4C2B-941F-5D57-8B43-EC451D840854"><p> <xref href="GUID-8BE90160-2C60-3582-82C8-4A108C7C0317.dita#GUID-8BE90160-2C60-3582-82C8-4A108C7C0317/GUID-C7DDA0E9-5882-3988-8747-AA790AC31E05"><apiname>HALData::EPowerBatteryStatus</apiname></xref>  </p> </li>

<li id="GUID-0D50D9CD-8AE9-5831-8E80-EE8B5230907D"><p> <xref href="GUID-8BE90160-2C60-3582-82C8-4A108C7C0317.dita#GUID-8BE90160-2C60-3582-82C8-4A108C7C0317/GUID-6A6650DE-67C1-3E1E-AFC7-CA7ADCED621D"><apiname>HALData::EAccessoryPower</apiname></xref>  </p> </li>

<li id="GUID-06A8A38B-3F3F-5B41-B79F-57CD49ABC382"><p> <xref href="GUID-8BE90160-2C60-3582-82C8-4A108C7C0317.dita#GUID-8BE90160-2C60-3582-82C8-4A108C7C0317/GUID-5800E3AA-61A7-33B1-BBAE-6E4D826373AB"><apiname>HALData::EPowerBackup</apiname></xref>  </p> </li>

<li id="GUID-77277657-3765-531B-8E19-8D2E11BAA558"><p> <xref href="GUID-8BE90160-2C60-3582-82C8-4A108C7C0317.dita#GUID-8BE90160-2C60-3582-82C8-4A108C7C0317/GUID-C6E1EDDD-06C4-3A4D-9C93-67316D6C4823"><apiname>HALData::EPowerBackupStatus</apiname></xref>  </p> </li>

<li id="GUID-9179DF67-5AFC-5C98-ACFD-391035A32756"><p> <xref href="GUID-8BE90160-2C60-3582-82C8-4A108C7C0317.dita#GUID-8BE90160-2C60-3582-82C8-4A108C7C0317/GUID-435EB49C-8821-37DD-8D13-46158B6261BD"><apiname>HALData::EPowerExternal</apiname></xref>  </p> </li>

<li id="GUID-E10E8676-5DB4-5045-9BDC-DF280695A4C6"><p> <xref href="GUID-8BE90160-2C60-3582-82C8-4A108C7C0317.dita#GUID-8BE90160-2C60-3582-82C8-4A108C7C0317/GUID-079CD0A7-6C36-3A05-8EFA-51FDD649C657"><apiname>HALData::EPenDisplayOn</apiname></xref>  </p> </li>

<li id="GUID-81581675-F4E7-517C-BF25-22CDCC87E787"><p> <xref href="GUID-8BE90160-2C60-3582-82C8-4A108C7C0317.dita#GUID-8BE90160-2C60-3582-82C8-4A108C7C0317/GUID-A0F07710-1C15-3B7F-8D45-02D9E40A2514"><apiname>HALData::ECaseSwitchDisplayOn</apiname></xref>  </p> </li>

<li id="GUID-D9DC5061-371E-5B89-8CA5-93FA99B7827A"><p> <xref href="GUID-8BE90160-2C60-3582-82C8-4A108C7C0317.dita#GUID-8BE90160-2C60-3582-82C8-4A108C7C0317/GUID-148D0CDF-6CEC-33BD-876A-CA93D0C702B3"><apiname>HALData::ECaseSwitchDisplayOff</apiname></xref>  </p> </li>

</ul>

<p>A typical application will have a user side monitor that periodically calls <xref href="GUID-BD00E7FC-C234-3111-87A5-10F79EB0F2B8.dita#GUID-BD00E7FC-C234-3111-87A5-10F79EB0F2B8/GUID-573C49D6-7763-37AE-B2B2-4C8FB1327E21"><apiname>HAL::Get()</apiname></xref>,

passing <xref href="GUID-8BE90160-2C60-3582-82C8-4A108C7C0317.dita#GUID-8BE90160-2C60-3582-82C8-4A108C7C0317/GUID-C7DDA0E9-5882-3988-8747-AA790AC31E05"><apiname>HALData::EPowerBatteryStatus</apiname></xref> to get the charge

level of the battery. </p>

<p>Typically, the handler is implemented as part of a <xref href="GUID-3E6D44FE-787B-3D9E-899C-8BAA7DDCBC5C.dita"><apiname>DPowerHal</apiname></xref> derived

object, which is created by the entry point of the base port power kernel

extension. The object is, therefore, part of the power controller kernel extension. </p>

<section id="GUID-292B08F7-9BE6-4D85-A70E-A063D300195F"><title>Implementation notes</title> <ul>

<li id="GUID-A69AD521-6B9C-565F-944F-125774283041"><p>The <xref href="GUID-3E6D44FE-787B-3D9E-899C-8BAA7DDCBC5C.dita"><apiname>DPowerHal</apiname></xref> derived

object constructor must register with the power manager by calling <codeph>Register()</codeph>. </p> </li>

<li id="GUID-5E2558D9-DB44-554A-8A18-33D161E568D2"><p>If there is some power-related

data that can be accessed via the HAL component and that persists through

power cycles (On/Off), it should be initialised here. Typically the <codeph>TOnOffInfoV1</codeph> data

member of the Variant-specific <codeph>TActualMachineConfig</codeph> (usually

found in <filepath>mconf.h</filepath> file under the platform directory) contains

some of that persistent data. </p> </li>

<li id="GUID-07E132AF-0F18-5578-A74C-C87618F98678"><p>The handler itself is

the function <codeph>PowerHalFunction()</codeph>, and must be fully implemented

in the base port. </p> </li>

<li id="GUID-EEB6EB2D-8E99-5EFF-B2C6-4C73E6D39852"><p>The kernel hooks up

the handler to service the HAL functions at boot-time. </p> </li>

<li id="GUID-6C2DE544-5447-5786-8F0C-A065E0C1A59A"><p>The power Hal functions

that the Handler can handle are enumerated by <xref href="GUID-105D7978-FFAD-3868-BE6A-8A9746A82D70.dita"><apiname>TPowerHalFunction</apiname></xref>.

Not all of these functions need to be handled. If not handled, the kernel

returns <codeph>KErrNotSupported</codeph> when the HAL function is called

with the relevant parameter. It is left to the base port to decide which functions

are relevant. </p> </li>

</ul> </section>

</conbody><related-links>

<link href="GUID-2D977A02-5928-5441-8AE7-42A722F2A4B8.dita#GUID-2D977A02-5928-5441-8AE7-42A722F2A4B8/GUID-4DA41221-40B9-5BC7-B2C6-7C6EB4522508">

<linktext>User-Side Hardware Abstraction</linktext></link>

</related-links></concept>