Collapse all Symbian^3 Product Developer Library

Vibra API Tutorial

This tutorial describes how to use the Vibra API of the hardware resource manager.

Introduction

To use the Vibra API, the client must first create an instance of the CHWRMVibra.

CHWRMVibra can be used in two modes:

With notify handling.
Without notify handling.

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.

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 VibraSettings() method.

StartVibraL() starts the device's vibration feature. If StartVibraL() 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.

The duration 0 specifies that the vibration continues indefinitely and must be stopped with a call to StopVibraL(). 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.

Vibration can be interrupted with the method StopVibraL() before the specified interval has elapsed.

The current status of the vibration feature can be obtained with the VibraStatus() method.

The device vibration feature can be reserved to a single instance of CHWRMVibra by calling the ReserveVibraL() method. After the vibration feature is no longer required exclusively, it must be released with a call to ReleaseVibra(). 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.

Vibra can be controlled without a reservation, if there is no other client with a reservation.

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 CCoeEnv is available. Trusted clients have an option to disable this auto-reservation feature.

The client does not receive notifications on whether its reservation is suspended, but StartVibraL() and StopVibraL() 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.

Using Vibra API, you can perform any of the tasks listed in the procedure section.

Vibra API Tutorial

Introduction

Procedure

See also