CHWRMVibra Class Reference

#include <hwrmvibra.h>

Link against: hwrmvibraclient.lib

class CHWRMVibra : public CBase, public CBase, public CBase

Inherits from

Detailed Description

The class used to control the device vibra.

HW Resource Manager Vibra API is a library API providing ability to control the device vibra. The API provides also methods to retrieve the current settings of the vibration feature in the user profile and the current status of the vibra.

The type of HW Resource Manager Vibra API is a synchronous method call meaning the method call will block the client application. The API is meant for all applications which need to control the device vibra.

The API consist of the classes CHWRMVibra and MHWRMVibraObserver. If the client requires up-to-date status information, it should also provide callback pointer of the MHWRMVibraObserver implementing class for the NewL-method.

Usage:

 #include <hwrmvibra.h> 

 // A CHWRMVibra instance can be created by using NewL() or NewLC() methods. 
 // Up-to-date status information not required, no callbacks.
 CHWRMVibra* vibra = CHWRMVibra::NewL();

 // After this, vibra can be directly controlled via the provided class methods. 
 vibra->StartVibraL(5000); // Start vibra for five seconds
 vibra->StopVibraL(); // Immediately stop vibra

 // To clean up, delete the created object:
 delete vibra;

Member Enumeration Documentation

Enum TVibraFeedbackModeState

Tactile feedback vibration setting in the user profile.

EnumeratorValueDescription
EVibraFeedbackModeUnknown0Not initialized yet or there is an error condion.
EVibraFeedbackModeONFeedback vibration setting in the user profile is on.
EVibraFeedbackModeOFFFeedback vibration setting in the user profile is off.

Enum TVibraModeState

Vibration setting in the user profile.

EnumeratorValueDescription
EVibraModeUnknown0

Not initialized yet or there is an error condion.

EVibraModeON

Vibration setting in the user profile is on.

EVibraModeOFF

Vibration setting in the user profile is off.

Enum TVibraStatus

Status of the vibration feature

EnumeratorValueDescription
EVibraStatusUnknown0

Vibra is not initialized yet or status is uncertain because of an error condition.

EVibraStatusNotAllowed

Vibra is set off in the user profile or some application is specifically blocking vibra.

EVibraStatusStopped

Vibra is stopped.

EVibraStatusOn

Vibra is on.

Member Function Documentation

NewL ( )

IMPORT_C CHWRMVibra *NewL()[static]

Two-phased constructor.

Return Value
A pointer to a new instance of the CHWRMVibra class.
Leave Codes
KErrNotSupportedDevice doesn't support vibration feature.
KErrNoMemoryThere is a memory allocation failure.

NewL ( MHWRMVibraObserver * )

IMPORT_C CHWRMVibra *NewL(MHWRMVibraObserver *aCallback)[static]

Two-phased constructor. Use this method for creating a vibra client with callbacks.

Parameters
aCallbackPointer to callback instance
Return Value
A pointer to a new instance of the CHWRMVibra class.
Leave Codes
KErrNotSupportedDevice doesn't support vibration feature.
KErrNoMemoryThere is a memory allocation failure.

NewLC ( )

IMPORT_C CHWRMVibra *NewLC()[static]

Two-phased constructor. Leaves instance to cleanup stack.

Return Value
A pointer to a new instance of the CHWRMVibra class.
Leave Codes
KErrNotSupportedDevice doesn't support vibration feature.
KErrNoMemoryThere is a memory allocation failure.

NewLC ( MHWRMVibraObserver * )

IMPORT_C CHWRMVibra *NewLC(MHWRMVibraObserver *aCallback)[static]

Two-phased constructor. Use this method for creating a vibra client with callbacks. Leaves instance to cleanup stack.

Parameters
aCallbackPointer to callback instance
Return Value
A pointer to a new instance of the CHWRMVibra class.
Leave Codes
KErrNotSupportedDevice doesn't support vibration feature.
KErrNoMemoryThere is a memory allocation failure.

PulseVibraL ( )

voidPulseVibraL()[pure virtual]

This method is intended only for firmware build time configured privileged clients.

Executes a tactile feedback vibration pulse with product specific default intensity and duration. If PulseVibraL is called before ongoing vibration completes and PulseVibraL calling client has higher priority than executing client, pulse request is accepted. Also possible vibra-reservations are bypassed. If client calling PulseVibraL has lower or equal priority than executing client, ongoing vibration is not affected.

Tactile feedback vibration 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 will cut off at that limit even if the duration parameter is greater than the limit.

See also: MHWRMVibraFeedbackObserver

Leave Codes
KErrAccessDeniedVibration setting in the user profile is not set or client is not privileged to use pulse feature.
KErrBadHandleVibra session has been invalidated.
KErrLockedVibra is locked down because too much continuous use or explicitly blocked by for example some vibration sensitive accessory.
KErrTimedOutTimeout occurred in controlling vibra.
KErrInUseVibra is not reserved to this client but it is reserved to some other client or ongoing vibration has been requested by higher priority client.
KErrNoMemoryThere is a memory allocation failure.
KErrGeneralThere is a hardware error.

PulseVibraL ( TInt )

voidPulseVibraL(TIntaDuration)[pure virtual]

This method is intended only for firmware build time configured privileged clients.

Executes a tactile feedback vibration pulse with product specific default intensity and specified duration. If PulseVibraL is called before ongoing vibration completes and PulseVibraL calling client has higher priority than executing client, pulse request is accepted. Also possible vibra-reservations are bypassed. If client calling PulseVibraL has lower or equal priority than executing client, ongoing vibration is not affected.

Tactile feedback vibration 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 will cut off at that limit even if the duration parameter is greater than the limit.

See also: MHWRMVibraFeedbackObserver

Parameters
aDurationDuration of the vibration measured in milliseconds. Duration can have maximum value of KHWRMVibraMaxDuration.
Leave Codes
KErrArgumentOne of the parameters is out of range.
KErrAccessDeniedVibration setting in the user profile is not set or client is not privileged to use pulse feature.
KErrBadHandleVibra session has been invalidated.
KErrLockedVibra is locked down because too much continuous use or explicitly blocked by for example some vibration sensitive accessory.
KErrTimedOutTimeout occurred in controlling vibra.
KErrInUseVibra is not reserved to this client but it is reserved to some other client or ongoing vibration has been requested by higher priority client.
KErrNoMemoryThere is a memory allocation failure.
KErrGeneralThere is a hardware error.

PulseVibraL ( TInt, TInt )

voidPulseVibraL(TIntaDuration,
TIntaIntensity
)[pure virtual]

This method is intended only for firmware build time configured privileged clients.

Executes a tactile feedback vibration pulse. If PulseVibraL is called before ongoing vibration completes and PulseVibraL calling client has higher priority than executing client, pulse request is accepted. Also possible vibra-reservations are bypassed. If client calling PulseVibraL has lower or equal priority than executing client, ongoing vibration is not affected.

Tactile feedback vibration 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 will cut off at that limit even if the duration parameter is greater than the limit.

See also: MHWRMVibraFeedbackObserver

Parameters
aDurationDuration of the vibration measured in milliseconds. Duration can have maximum value of KHWRMVibraMaxDuration.
aIntensityIntensity of the pulse in decimal is KHWRMVibraMinPulseIntensity to KHWRMVibraMaxIntensity, which shows the percentage of the vibra motor full rotation speed. NOTE: The device might have hardware-imposed limits on supported vibra intensity values, so actual effect might vary between different hardware.
Leave Codes
KErrNotSupportedThe device doesn't support user-defined vibra intensity.
KErrArgumentOne of the parameters is out of range.
KErrAccessDeniedVibration setting in the user profile is not set or client is not privileged to use pulse feature.
KErrBadHandleVibra session has been invalidated.
KErrLockedVibra is locked down because too much continuous use or explicitly blocked by for example some vibration sensitive accessory.
KErrTimedOutTimeout occurred in controlling vibra.
KErrInUseVibra is not reserved to this client but it is reserved to some other client or ongoing vibration has been requested by higher priority client.
KErrNoMemoryThere is a memory allocation failure.
KErrGeneralThere is a hardware error.

ReleaseVibra ( )

voidReleaseVibra()[pure virtual]

Releases vibration feature if it was previously reserved for this client. If this client has not reserved vibration feature, does nothing. If vibra is on when it is released and no other client has a suspended reservation, vibra is stopped.

ReserveVibraL ( )

voidReserveVibraL()[pure virtual]

Reserves vibration feature exclusively for this 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 will not be acted upon unless suspension is lifted within specified duration. The suspended client will not get any notification about suspension. If vibra is already reserved by a higher or equal priority application, reserving will still succeed, but reservation is immediately suspended.

Calling this method is equal to call ReserveVibraL(EFalse, EFalse), i.e. any previously frozen state will not be restored and CCoeEnv background/foreground status is always used to control further reservations.

Leave Codes
KErrAccessDeniedNo CCoeEnv present.
KErrNotReadyTrying to reserve while on background.
KErrNoMemoryThere is a memory allocation failure.

ReserveVibraL ( TBool, TBool )

voidReserveVibraL(TBoolaRestoreState,
TBoolaForceNoCCoeEnv
)[pure virtual]

Reserves vibration feature exclusively for this 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 will not be acted upon unless suspension is lifted within specified duration. The suspended client will not get any notification about suspension. If vibra is already reserved by a higher or equal priority application, reserving will still succeed, but reservation is immediately suspended.

Parameters
aRestoreStateIf ETrue, the state frozen on last release will be restored upon successful reservation. I.e. if vibra was on when it was released by this client the last time, it would continue the vibrating upon successful reservation. For the first reservation of each session this parameter is always considered EFalse regardless of what is supplied, as there is no previous frozen state to restore.
aForceNoCCoeEnvIf EFalse, then reservation requires that this client has the keyboard focus at the time of reservation and vibra will be automatically released and re-reserved based on the keyboard focus status of this client. This also implies that CCoeEnv::Static() != NULL is required. If ETrue, the client will not require CCoeEnv to be present nor does it automatically reserve/release vibra by depending on foreground/background status of the client. Only trusted clients are allowed to set this flag to ETrue. A client is considered trusted if it has nonstandard priority defined in the internal vibra policy of the HW Resource Manager. A client can be defined trusted only by a product.
Leave Codes
KErrAccessDeniedParameter aForceNoCCoeEnv is ETrue and client is not trusted.
KErrBadHandleParameter aForceNoCCoeEnv is EFalse and no CCoeEnv present.
KErrNotReadyTrying to reserve while on background and parameter aForceNoCCoeEnv is EFalse.
KErrNoMemoryThere is a memory allocation failure.

SetFeedbackObserver ( MHWRMVibraFeedbackObserver * )

voidSetFeedbackObserver(MHWRMVibraFeedbackObserver *aCallback)[pure virtual]

Use this method for setting feedback observer.

Parameters
aCallbackPointer to callback instance

StartVibraL ( TInt )

voidStartVibraL(TIntaDuration)[pure virtual]

Starts the device vibration feature with the product specific default intensity. If StartVibraL is called again before the first vibration completes then 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 will cut off at that limit even if the duration parameter is greater than the limit.

See also: MHWRMVibraObserver

Parameters
aDurationDuration of the vibration measured in milliseconds. A value of 0 specifies that the vibration should continue indefinetely and should be stopped with a call to StopVibraL. Duration can have maximum value of KHWRMVibraMaxDuration.
Leave Codes
KErrArgumentDuration is invalid.
KErrAccessDeniedVibration setting in the user profile is not set.
KErrBadHandleVibra session has been invalidated.
KErrLockedVibra is locked down because too much continuous use or explicitly blocked by for example some vibration sensitive accessory.
KErrTimedOutTimeout occurred in controlling vibra.
KErrInUseVibra is not reserved to this client but it is reserved to some other client.
KErrNoMemoryThere is a memory allocation failure.
KErrGeneralThere is a hardware error.

StartVibraL ( TInt, TInt )

voidStartVibraL(TIntaDuration,
TIntaIntensity
)[pure virtual]

Starts the device vibration feature. If StartVibraL is called again before the first vibration completes then 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 will cut off at that limit even if the duration parameter is greater than the limit.

See also: MHWRMVibraObserver

Parameters
aDurationDuration of the vibration measured in milliseconds. A value of 0 specifies that the vibration should continue indefinitly and should be stopped with a call to StopVibraL. Duration can have maximum value of KHWRMVibraMaxDuration.
aIntensityIntensity of the vibra in decimal is -100 to 100, which shows the percentage of the vibra motor full rotation speed. When intensity is negative, the vibra motor rotates in the negative direction. When intensity is positive, the vibra motor rotates in the positive direction. Value 0 stops the vibra. NOTE: The device might have hardware-imposed limits on supported vibra intensity values, so actual effect might vary between different hardware.
Leave Codes
KErrNotSupportedThe device doesn't support user-defined vibra intensity.
KErrArgumentOne of the parameters is out of range.
KErrAccessDeniedVibration setting in the user profile is not set.
KErrBadHandleVibra session has been invalidated.
KErrLockedVibra is locked down because too much continuous use or explicitly blocked by for example some vibration sensitive accessory.
KErrTimedOutTimeout occurred in controlling vibra.
KErrInUseVibra is not reserved to this client but it is reserved to some other client.
KErrNoMemoryThere is a memory allocation failure.
KErrGeneralThere is a hardware error.

StopVibraL ( )

voidStopVibraL()[pure virtual]

Interrupts the device vibration that is started with the StartVibraL method immediately.

See also: MHWRMVibraObserver

Leave Codes
KErrBadHandleVibra session has been invalidated.
KErrTimedOutTimeout occurred in controlling vibra.
KErrInUseVibra is not reserved to this client but it is reserved to some other client.
KErrNoMemoryThere is a memory allocation failure.
KErrGeneralThere is a hardware error.

VibraFeedbackSettings ( )

TVibraFeedbackModeState VibraFeedbackSettings()const [pure virtual]

This method retrieves the current settings of the feedback vibration feature in the user profile. The developer can check the feedback vibration settings in the profile and if there is no feedback vibration active but it is needed by the client application then the user can be informed. However, client needs to explicitly register to listen these changes via SetFeedbackObserver-method.

See also: TVibraFeedbackModeState MHWRMVibraFeedbackObserver

Return Value
TVibraFeedbackModeState indicating the current vibra feedback mode setting.

VibraSettings ( )

TVibraModeState VibraSettings()const [pure virtual]

This method 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 client application then the user can be informed.

See also: TVibraModeState MHWRMVibraObserver

Return Value
TVibraModeState indicating the current vibra mode setting.

VibraStatus ( )

TVibraStatus VibraStatus()const [pure virtual]

This method retrieves the current vibra status.

See also: TVibraStatus MHWRMVibraObserver

Return Value
TVibraStatus indicating the current vibra status