<?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_d0e159188_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>
</related-links></concept>