<?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>
</conbody></concept>