To use CHWRMVibra, the client must first construct an
instance of the class.
CHWRMVibra can be used in two modes:
Without notify handling.
With notify handling.
An instance with notify handling is created if the client requires up-to-date status information. Otherwise an instance without callback pointer is created. After an instance is created, vibra can be directly controlled via the provided class methods.
To be able 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 vibrations starts immediately, i.e. 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 comes, 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 autoreservation feature.
The client gets no notifications about whether or not its reservation is
suspended, but StartVibraL() and StopVibraL() can
be called normally when the client’s reservation is suspended. In that 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.
Some vibration sensitive device accessories can block vibra usage entirely through internal mechanisms.
A CHWRMVibra instance can be created by using NewL() or NewLC() methods.
After this, vibra can be directly controlled via the provided class methods.
The user has to create an instance of the CHWRMVibra implementation
class using the NewL or NewLC constructor
without a parameter. The following code snippet demonstrates how to create
an instance without notify handling for controlling the device vibra.
CHWRMVibra* vibra = CHWRMVibra::NewLC(); // No callbacks
The client needs to derive a class from the MHWRMVibraObserver interface
and implement the VibraModeChanged() and VibraStatusChanged() methods.
The following code snippet gives an example of the header of the class implemented
by the client.
// INCLUDES
#include <HWRMVibra.h> // Link against HWRMVibraClient.lib.
class CTest : public CBase,
public MHWRMVibraObserver
{
public:
CTest();
~CTest();
void ConstructL();
static CTest* NewL();
// from MHWRMVibraObserver
virtual void VibraModeChanged(CHWRMVibra::TVibraModeState aStatus);
virtual void VibraStatusChanged(CHWRMVibra::TVibraStatus aStatus);
private:
CHWRMVibra* iVibra;
};
The user has to create an instance of the CHWRMVibra implementation
class using the NewL or NewLC constructor
with a parameter. This parameter is a pointer to an object that is derived
from MHWRMVibraObserver. Every vibra user setting profile
change causes the notification MHWRMVibraObserver::VibraModeChanged().
Every vibra status change causes the notificationMHWRMVibraObserver::VibraStatusChanged().
The following code snippet demonstrates how to create an instance with notify
handling for controlling the device vibra.
void CTest::ConstructL()
{
iVibra = CHWRMVibra::NewL(this)
}
The VibraSettings() call retrieves the current settings
of the vibration feature in the user profile. The developer can check the
vibra settings in the profile, and if there is no vibra active but it is needed
by the application, the user can be informed. The following code snippet demonstrates
how to retrieve the vibra settings.
CHWRMVibra::TVibraModeState vibraModeState = iVibra->VibraSettings();
The VibraStatus() method retrieves the current vibra status.
The following code snippet demonstrates how to retrieve the vibra status.
CHWRMVibra::TVibraStatus vibraStatus = iVibra->VibraStatus();
The ReserveVibraL() call reserves the vibration feature
exclusively for the client. A higher priority client may cause lower priority
client reservation to be temporarily suspended. Commands can still be issued
in suspended state, but they are not acted upon unless suspension is lifted
within specified duration. The suspended client does not get any notification
about suspension. If vibra is already reserved by a higher or equal priority
application, reserving still succeeds, but reservation is immediately suspended.
The following code snippet demonstrates how to reserve the device vibration
feature.
iVibra->ReserveVibraL(ETrue, EFalse);
ETrue in first parameter means that any previously frozen
state is restored. Second parameter EFalse means that the CCoeEnv background/foreground
status is always used to control further reservations.
Calling the ReserveVibraL() method without parameters
is equal to calling ReserveVibraL(EFalse, EFalse), i.e. any
previously frozen state is not restored and the CCoeEnv background/foreground
status is always used to control further reservations.
The StartVibraL() call starts the device vibration feature.
If StartVibraL() is called again before the first vibration
completes, the first vibration is interrupted and the second vibrations starts
immediately – i.e. the periods of vibration are not cumulative. The vibration
can be interrupted with the method StopVibraL() before the
specified interval has elapsed. Vibra settings of the vibration feature in
the user profile must be active.
Note: The device may have implementation defined or hardware imposed limits to the duration of the vibration feature. In such circumstances any vibration is cut off at that limit even if the duration parameter is greater than the limit.
The following code snippet demonstrates how to start the device vibration feature with factory-defined intensity.
iVibra->StartVibraL(5000); // Start vibra for five seconds.
The following code snippet demonstrates how to start the device vibration feature with client-defined intensity.
iVibra->StartVibraL(5000, 50); // Start vibra for five seconds with intensity 50.
The StopVibra() call interrupts immediately the device
vibration that was started with the StartVibraL() method.
The following code snippet demonstrates how to stop the vibration feature.
iVibra->StopVibraL();
The ReleaseVibra() call releases the vibration feature
if it was previously reserved with a ReserveVibraL() method
for the client. If the client has not reserved the vibration feature, the
method does nothing. If vibra is on when it is released and no other client
has a suspended reservation, vibra is stopped. The following code snippet
demonstrates how to release the vibration feature.
iVibra->ReleaseVibra();
When the CHWRMVibra instance is not needed anymore it
must be released. If the vibration feature is still reserved to the client
it is released when the instance is released. The following code snippet demonstrates
how to release the instance created by using NewLC().
CleanupStack::PopAndDestroy(vibra);
The following code snippet demonstrates how to release the instance created
by using NewL().
CTest::~CTest()
{
delete iVibra;
}
The leave mechanism of the Symbian OS is used to handle error conditions on method calls.
Vibra API does not consume significant amount of memory after the CHWRMVibra implementation
instance is created.
The API does not explicitly support any kinds of extensions to it.