<?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-D987BEC9-B976-5A65-B6B3-D44BC8A96430" xml:lang="en"><title>Hardware

Resource Manager Overview</title><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>Hardware Resource Manager (HWRM) is a client-server solution, which utilizes

ECom plug-ins to achieve device independency. ECom plug-ins convert the client

requests into the hardware control commands. </p>

<section><title>Purpose</title> <p>HWRM performs the following functions: </p> <ul>

<li id="GUID-B9558230-898F-51E8-8839-4CEB8C8D3FB4"><p>Provide client APIs

to control lights, vibra. </p> </li>

<li id="GUID-6CC6C834-CE06-534C-A39A-D1C617F04094"><p>Retrieve battery information

of the device. </p> </li>

<li id="GUID-B45D85ED-6DD6-5445-A51C-561D6C609204"><p>Publish certain power-state

related Publish and Subscribe properties. </p> </li>

<li id="GUID-34B70C64-2C40-55F5-9C30-6C851E1351D1"><p>Enable clients to retrieve

status information on the hardware elements such as light, vibration, power. </p> </li>

</ul> </section>

<section><title>Required background</title> <p>Knowledge of the client-server

architecture, asynchronous processing, and active objects feature of the Symbian

system model architecture. </p> </section>

<section><title>HWRM architecture</title> <p>HWRM is made up of the following

components: </p> <ul>

<li id="GUID-52035A19-05AF-5C9B-A525-9B84523EFA30"><p><b>Client APIs</b>  </p> </li>

<li id="GUID-E833B270-2E7A-583B-9177-7F5AB0386D6E"><p><b>HWRM Server</b>  </p> </li>

<li><p><b>HWRM Plug-ins</b></p></li>

</ul> <fig id="GUID-F4261959-A2C5-445F-BA71-D84D8CBA9050">

<title>              Hardware Resource Manager's Architectural Relationships

           </title>

<image href="GUID-0211CAA4-32FF-52F2-81DA-78C52C412AED_d0e135000_href.png" placement="inline"/>

</fig> <p><b>Client APIs </b> </p> <p>HWRM provides client APIs that can control

various hardware elements. It also provides callback pointers, so that the

client applications can register to receive notification on the hardware status

changes. Refer to the <xref href="GUID-2E3BE23C-B9DC-5B5D-A56A-1DB819EFC9A6.dita">tutorials</xref> for

information on how to use client APIs. Client APIs are useful for both application

developers and the handset manufacturers. </p> <p><b>HWRM server</b> </p> <p>HWRM

server uses plug-in handlers to forward the client API requests to appropriate

plug-ins. The client application communicates with HWRM server through the

client APIs (Light API, Vibra API, and Power API). HWRM server defines the

observer classes, which provide the callback pointers. </p> <p>The server

calls <xref href="GUID-4603653B-34E4-3CC5-9978-95F9532A0616.dita#GUID-4603653B-34E4-3CC5-9978-95F9532A0616/GUID-5FB0A5EF-C2BB-3D0D-ACFD-9C7EE5BF41D2"><apiname>CHWRMPluginService::ProcessCommandL()</apiname></xref> function to

forward the client requests to plug-ins. An ongoing <xref href="GUID-DC7941A2-9310-3739-AB95-EF080EAEA042.dita"><apiname>ProcessCommandL()</apiname></xref> is

cancelled by HWRM server using <xref href="GUID-4603653B-34E4-3CC5-9978-95F9532A0616.dita#GUID-4603653B-34E4-3CC5-9978-95F9532A0616/GUID-3BF46D44-ED10-30AC-AE0A-18776FE69A83"><apiname>CHWRMPluginService::CancelCommandL()</apiname></xref>.

The plug-ins process the server's request and pass the response by calling <xref href="GUID-5F264EF2-6E50-34F7-96E1-99645EC86265.dita#GUID-5F264EF2-6E50-34F7-96E1-99645EC86265/GUID-6DDB5354-C3C1-35F9-B237-9ECA5018BA41"><apiname>CHWRMPluginCallback::ProcessResponseL()</apiname></xref> function.

The <xref href="GUID-E053425D-3A2F-39A5-B18A-0E2E8883D8F6.dita#GUID-E053425D-3A2F-39A5-B18A-0E2E8883D8F6/GUID-6F02C8B1-B01F-35C5-9010-51B8A3E04FDC"><apiname>MHWRMPluginCallback::EventL()</apiname></xref> method is used to communicate

various events that takes place in the plug-ins. </p> <p>HWRM uses the central

repository to store the various values and settings such as the light intensity,

duration and delays. </p> <p><b>HWRM plug-ins</b></p><p>HWRM

plug-ins convert client requests to hardware control commands.</p><p>HWRM

forwards the client requests to the plug-ins through the plug-in APIs. All

events are notified to HWRM server using <xref href="GUID-E053425D-3A2F-39A5-B18A-0E2E8883D8F6.dita#GUID-E053425D-3A2F-39A5-B18A-0E2E8883D8F6/GUID-6F02C8B1-B01F-35C5-9010-51B8A3E04FDC"><apiname>MHWRMPluginCallback::EventL()</apiname></xref> method.

After executing each command, the server is notified. The notification is

accompanied by an error code. HWRM server passes these error codes to the

clients. When the request is completed successfully, <codeph>KErrNone</codeph> is

returned. If an error occurs while executing a command, such as target hardware

not implemented or not ready, the corresponding error code is returned. Refer

to the <xref href="GUID-62F3CC35-F992-5099-BDC2-BA0117C79631.dita">Hardware Resource

Manager Plug-ins</xref> section for more details.</p></section>

<section><title>APIs</title> <p>The HWRM provides the following client APIs

and plug-in APIs: </p> <table id="GUID-3EBE4E80-0F05-5BE3-BFCB-440B15246AE8">

<tgroup cols="2">

<colspec colname="col0" colwidth="0.79*"/><colspec colname="col1" colwidth="1.21*"/>

<thead>

<row>

<entry><b>Class</b></entry>

<entry><b>Description</b></entry>

</row>

</thead>

<tbody>

<row>

<entry><p><codeph>CHWRMLight</codeph> </p> </entry>

<entry><p>Abstract class defining Lights client API. </p> </entry>

</row>

<row>

<entry><p><codeph>CHWRMExtendedLight</codeph></p></entry>

<entry><p>Abstract class defining Extended Lights client API.</p></entry>

</row>

<row>

<entry><p><codeph>CHWRMVibra</codeph> </p> </entry>

<entry><p>Abstract class defining Vibra client API. </p> </entry>

</row>

<row>

<entry><p><codeph>CHWRMPower</codeph> </p> </entry>

<entry><p>Class defining Power client API. </p> </entry>

</row>

</tbody>

</tgroup>

</table> </section>

<section><title>Typical use cases</title> <p>HWRM is used for the following: </p> <ul>

<li><p>Used to configure a plug-in.</p></li>

<li id="GUID-EC0ED774-FA8C-5795-A8B8-828915C925B0"><p>Start/stop device vibra. </p> </li>

<li id="GUID-A7F6688C-3421-566B-96C1-FAC8A27E994E"><p>Release the reserved

lights </p> </li>

<li id="GUID-760C9732-6587-55BD-A8B3-C1838A668347"><p>Retrieve the supported

light targets of the device, current light status, vibra settings and status. </p> </li>

<li id="GUID-831C3322-D28C-507A-BB5C-EA85944D8BB7"><p>Reserve light targets,

device vibra. </p> </li>

<li id="GUID-83313ED4-CC3F-575D-9D5B-01485DC2B7B4"><p>Switch ON/OFF the lights. </p> </li>

<li id="GUID-9A30DBFC-3CE4-5A85-9E7B-27178872AE5A"><p>Request for tactile

vibration pulse. </p> </li>

</ul> </section>

</conbody><related-links>

<link href="GUID-25A005BF-731B-58DB-8EF7-AB7840DA563F.dita"><linktext>HWRM Concepts</linktext>

</link>

<link href="GUID-2E3BE23C-B9DC-5B5D-A56A-1DB819EFC9A6.dita"><linktext>HWRM Tutorials</linktext>

</link>