<?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_d0e135754_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>