This tutorial describes how to use the Vibra API of the hardware resource manager.
To use the Vibra API, the client must first create an instance of the [[[ERROR: [NOKX000E] Unable to find definition for key reference 'CHWRMVibra']]]CHWRMVibra.
[[[ERROR: [NOKX000E] Unable to find definition for key reference 'CHWRMVibra']]]CHWRMVibra can be used in two modes:
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 [[[ERROR: [NOKX000E] Unable to find definition for key reference 'CHWRMVibra']]]VibraSettings() method.
[[[ERROR: [NOKX000E] Unable to find definition for key reference 'CHWRMVibra']]]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.