<?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-D53A00E4-CF37-5F11-8D15-C5ECCCE64597" xml:lang="en"><title>Vibra
API</title><abstract><shortdesc>Vibra API provides the functionality to control the device
vibra, which is accessed using the <apiname>CHWRMVibra</apiname> instance.
It also provides methods to retrieve the current settings of the vibration
feature in the user profile and the current status of the vibra. It uses synchronous
method calls which block the client application until a response is received
from the plug-in. </shortdesc> <p>Vibra API also allows the client to request
for tactile vibration feedback. </p> </abstract><prolog><metadata><keywords/></metadata></prolog><conbody>
<p>The API consists of <codeph>CHWRMVibra</codeph>,<codeph>MHWRMVibraObserver</codeph> and <codeph>MHWRMVibraFeedbackObserver</codeph> classes. </p>
<p>It provides the following fields: </p>
<table id="GUID-65DF6175-8150-5F3D-BF8F-D7D9E1105C1A">
<tgroup cols="3"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/>
<thead>
<row>
<entry valign="top"><p> <b>Fields</b>  </p> </entry>
<entry valign="top"><p> <b>Values </b>  </p> </entry>
<entry valign="top"><p> <b>Descriptions</b>  </p> </entry>
</row>
</thead>
<tbody>
<row>

<entry><p> <codeph>KHWRMVibraMinIntensity</codeph>  </p> </entry>
<entry><p>-100 </p> </entry>
<entry><p>Minimum allowed intensity setting for vibra. </p> </entry>
</row>
<row>
<entry><p> <codeph>KHWRMVibraMinPulseIntensity</codeph>  </p> </entry>
<entry><p>1</p> </entry>
<entry><p>Minimum allowed intensity setting for vibra pulse. </p> </entry>
</row>
<row>
<entry><p> <codeph>KHWRMVibraMaxIntensity</codeph>  </p> </entry>
<entry><p>100</p> </entry>
<entry><p>Maximum allowed intensity setting for vibra. </p> </entry>
</row>
<row>
<entry><p> <codeph>KHWRMVibraMaxDuration</codeph>  </p> </entry>
<entry><p>(<codeph>KMaxTInt</codeph>/1000)-1 </p> </entry>
<entry><p>Maximum allowed duration value in milliseconds. </p> </entry>
</row>
<row>
<entry><p> <codeph>KHWRMVibraInfiniteDuration</codeph>  </p> </entry>
<entry><p>0</p> </entry>
<entry><p>Specifies that vibrating must continue for maximum vibrating time
supported by device if vibrating is not explicitly stopped. </p> </entry>
</row>
</tbody>
</tgroup>
</table>
<section><title> Observer</title> <p>A separate callback interface <xref href="GUID-68D63D0A-4CC6-34A6-AF5B-BB59AC96625E.dita"><apiname>MHWRMVibraObserver</apiname></xref> for status reporting is also
used. The client creates an instance of <xref href="GUID-68D63D0A-4CC6-34A6-AF5B-BB59AC96625E.dita"><apiname>CHWRMVibra</apiname></xref> using <xref href="GUID-68D63D0A-4CC6-34A6-AF5B-BB59AC96625E.dita"><apiname>NewL()</apiname></xref>. If the client requires the status information,
it must provide a callback pointer of the <xref href="GUID-68D63D0A-4CC6-34A6-AF5B-BB59AC96625E.dita"><apiname>MHWRMVibraObserver</apiname></xref> implementing
class for the <xref href="GUID-68D63D0A-4CC6-34A6-AF5B-BB59AC96625E.dita"><apiname>NewL()</apiname></xref> method. </p> <fig id="GUID-95D74CC2-CEDD-569B-8B34-A47FDA4F8DE0">
<title>              Vibra API Interfaces            </title>
<image href="GUID-DC44DCFC-8549-5CDE-B6DA-F5FD73E2D9FC_d0e110354_href.jpg" placement="inline"/>
</fig> </section>
<section><title>Tactile vibration feedback</title> <p>Tactile vibration is
used in many touch screen devices to provide vibration feedback to the user
through display surface. </p> <p>The clients can specify the intensity and
duration of the feedback pulse, and receive notifications when the tactile
feedback settings changes in the user profile through <xref href="GUID-68D63D0A-4CC6-34A6-AF5B-BB59AC96625E.dita"><apiname>MHWRMVibraFeedbackObserver</apiname></xref> class. </p> <p> <b> Note</b>: The tactile feedback functionality is only available to the clients configured
at the firmware build time (Symbian platform licensees). </p> <table id="GUID-D75949EB-BC44-4120-825B-8B905562777D"><title>Definitions</title>
<tgroup cols="2"><colspec colname="COLSPEC0" colwidth="0.42*"/><colspec colname="COLSPEC1" colwidth="1.58*"/>
<tbody>
<row>
<entry><p>Vibra frozen state </p> </entry>
<entry><p>Whenever vibra is released, its current state is stored as frozen
state. On next reserve, the user can specify that the frozen state be restored. </p> </entry>
</row>
<row>
<entry><p>Vibra virtual state </p> </entry>
<entry><p>Reserves the specified resource. If reservation is not suspended,
then actual vibra is also set to the same state. If reservation is suspended,
actual vibra is not affected by any control methods.</p> </entry>
</row>
</tbody>
</tgroup>
</table></section>
</conbody></concept>