<?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-D78DCB72-7CEE-5075-A6FA-58D57AB5BA73" xml:lang="en"><title>Vibra

API Tutorial </title><shortdesc>This tutorial describes how to use the Vibra API of the hardware

resource manager. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<section><title>Introduction</title> <p>To use the Vibra API,

the client must first create an instance of the <xref href="GUID-68D63D0A-4CC6-34A6-AF5B-BB59AC96625E.dita"><apiname>CHWRMVibra</apiname></xref>. </p> <p> <xref href="GUID-68D63D0A-4CC6-34A6-AF5B-BB59AC96625E.dita"><apiname>CHWRMVibra</apiname></xref> can be used in two modes: </p> <ul>

<li id="GUID-65226087-E8A5-5B84-8675-A971983C03D2"><p>With notify handling. </p> </li>

<li id="GUID-E41B1DB9-6880-5F59-AB8B-BBFA5B734CA8"><p>Without notify handling. </p> </li>

</ul> <p>An instance with notify handling is created if the client requires

up-to-date status information. Else, an instance without callback pointer

is created. After an instance is created, vibra can be directly controlled

through the provided class methods. </p> <p>To control the device's vibration

feature, the vibra settings of the vibration feature in the user profile must

be active. If the settings are not active, vibration is not activated. The

vibration feature state can be retrieved using the <xref href="GUID-68D63D0A-4CC6-34A6-AF5B-BB59AC96625E.dita"><apiname>VibraSettings()</apiname></xref> method. </p> <p> <xref href="GUID-68D63D0A-4CC6-34A6-AF5B-BB59AC96625E.dita"><apiname>StartVibraL()</apiname></xref> starts the device's vibration

feature. If <codeph>StartVibraL()</codeph> is called again before the first

vibration completes, the first vibration is interrupted and the second vibration

starts immediately, that is, the periods of vibration are not cumulative. </p> <p>The

duration <codeph>0</codeph> specifies that the vibration continues indefinitely

and must be stopped with a call to <codeph>StopVibraL()</codeph>. The device

may have implementation defined or hardware imposed limits to the duration

of the vibration feature. In such circumstances, vibration is ended at that

limit even if the duration parameter is greater than the limit. </p> <p>Vibration

can be interrupted with the method <codeph>StopVibraL()</codeph> before the

specified interval has elapsed. </p> <p>The current status of the vibration

feature can be obtained with the <codeph>VibraStatus()</codeph> method. </p> <p>The

device vibration feature can be reserved to a single instance of <codeph>CHWRMVibra</codeph> by

calling the <codeph>ReserveVibraL()</codeph> method. After the vibration feature

is no longer required exclusively, it must be released with a call to <codeph>ReleaseVibra()</codeph>.

If there is already a reservation active when a reservation from a higher

priority client arrives, the previously active reservation is suspended, and

the new reservation is set as the active one. On the other hand, if there

is already a reservation active when a reservation from a same or lower priority

client comes, the new reservation is immediately put in the suspended mode.

Some trusted clients have higher than default priorities. </p> <p>Vibra can

be controlled without a reservation, if there is no other client with a reservation. </p> <p>If

the client is not trusted, Vibra API automatically releases reservation when

the client goes to background and reserves it again when the client comes

back to foreground. This also implies that untrusted clients can only use

Vibra API where <codeph>CCoeEnv</codeph> is available. Trusted clients have

an option to disable this auto-reservation feature. </p> <p>The client does

not receive notifications on whether its reservation is suspended, but <codeph>StartVibraL()</codeph> and <codeph>StopVibraL()</codeph> can

be called normally when the client's reservation is suspended. In such case,

only the virtual state of the vibra is remembered by the session; the actual

vibra is not controlled. When suspended reservation is activated, the actual

vibra state is restored to the same as the virtual state. </p> <p>Using Vibra

API, you can perform any of the tasks listed in the procedure section.</p></section>

<section><title>Procedure</title> <ul>

<li id="GUID-1395F0F9-E42A-5D3A-882B-FEBA612A1F93"><p><xref href="GUID-623CA1EE-4D25-495A-BD2F-BA7BF95D6D9C.dita">Creating

a Vibra instance to control the vibra</xref>  </p> </li>

<li id="GUID-43FB5A23-920E-5FED-A9EB-24B1C6561CB6"><p><xref href="GUID-D89D1809-0A64-4331-BA5C-2B82187BEFB6.dita">Retrieving

the vibra settings</xref>  </p> </li>

<li id="GUID-55D570AA-01CD-57E5-BD89-FEB9319DF2A5"><p><xref href="GUID-AE5432AE-C699-4403-BCFC-474515C9BEC8.dita">Retrieving

the vibra status</xref>  </p> </li>

<li id="GUID-E9440FB8-AA83-56EA-A553-A7CBAE1ED526"><p><xref href="GUID-F575F364-4BCA-42C7-BE00-7B31D8B55AE1.dita">Reserving

the device vibra</xref>  </p> </li>

<li id="GUID-81A4E159-92B3-5ED7-8F10-FDA59F103986"><p><xref href="GUID-B57857D6-F00B-458A-8194-42CACA0BF131.dita">Starting

the device vibra</xref>  </p> </li>

<li id="GUID-B60F29FB-89ED-532A-9D58-650BEDA373C3"><p><xref href="GUID-B80ADD0D-2834-4478-A4AD-1FEBC0112A43.dita">Stopping

device vibra</xref>  </p> </li>

<li id="GUID-CD985A37-C4E0-5555-80E7-327E6CE98F81"><p><xref href="GUID-A0122085-369E-46EF-9CA1-0269982A5284.dita">Releasing

device vibra</xref>  </p> </li>

<li id="GUID-7CCAA66F-BC1C-5D19-9ED8-81E6FED9DBA0"><p><xref href="GUID-2D8A7DCE-47A2-4326-BF2F-B4901F1723A0.dita">Releasing

the instance</xref>  </p> </li>

<li id="GUID-58B61829-89B3-5AA5-8CCB-3CF802D498D4"><p><xref href="GUID-D157C4D3-FC2F-47DD-BD33-F8BA6156833D.dita">Sending

tactile feedback pulse</xref>  </p> </li>

</ul> </section>

<section><title>See also</title> <p><xref href="GUID-D53A00E4-CF37-5F11-8D15-C5ECCCE64597.dita">Vibra

API</xref>  </p> </section>