Class CHWRMVibra

class CHWRMVibra : public CBase;

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;

Derivation

• CBase - Base class for all classes to be instantiated on the heap.

• CHWRMVibra - The class used to control the device vibra.

Members

Defined in CHWRMVibra:

• EVibraModeOFFVibration setting in the user profile is off.
• EVibraModeONVibration setting in the user profile is on.
• EVibraModeUnknownNot initialized yet or there is an error condion.
• EVibraStatusNotAllowedVibra is set off in the user profile or some application is specifically blockin...
• EVibraStatusOnVibra is on.
• EVibraStatusStoppedVibra is stopped.
• EVibraStatusUnknownVibra is not initialized yet or status is uncertain because of an error conditio...
• NewL()Two-phased constructor.
• NewL(MHWRMVibraObserver *)Two-phased constructor. Use this method for creating a vibra client with callbac...
• NewLC()Two-phased constructor. Leaves instance to cleanup stack.
• NewLC(MHWRMVibraObserver *)Two-phased constructor. Use this method for creating a vibra client with callbac...
• ReleaseVibra()Releases vibration feature if it was previously reserved for this client. If thi...
• ReserveVibraL()Reserves vibration feature exclusively for this client. A higher priority client...
• ReserveVibraL(TBool,TBool)Reserves vibration feature exclusively for this client. A higher priority client...
• StartVibraL(TInt)Starts the device vibration feature with the product specific default intensity....
• StartVibraL(TInt,TInt)Starts the device vibration feature. If StartVibraL is called again before the f...
• StopVibraL()Interrupts the device vibration that is started with the StartVibraL method imme...
• TVibraModeStateVibration setting in the user profile.
• TVibraStatusStatus of the vibration feature
• VibraSettings()constThis method retrieves the current settings of the vibration feature in the user ...
• VibraStatus()constThis method retrieves the current vibra status.

Inherited from CBase:

• Delete(CBase *)Deletes the specified object.
• Extension_(TUint,TAny *&,TAny *)Extension function
• operator new(TUint)Allocates the object from the heap and then initialises its contents to binary z...
• operator new(TUint,TAny *)Initialises the object to binary zeroes.
• operator new(TUint,TLeave)Allocates the object from the heap and then initialises its contents to binary z...
• operator new(TUint,TLeave,TUint)Allocates the object from the heap and then initialises its contents to binary z...
• operator new(TUint,TUint)Allocates the object from the heap and then initialises its contents to binary z...

IMPORT_C static CHWRMVibra* NewL();

Description

Two-phased constructor.

Return value

CHWRMVibra * A pointer to a new instance of the CHWRMVibra class.

Leave codes

KErrNotSupported Device doesn't support vibration feature. KErrNoMemory There is a memory allocation failure.

IMPORT_C static CHWRMVibra* NewLC();

Description

Two-phased constructor. Leaves instance to cleanup stack.

Return value

CHWRMVibra * A pointer to a new instance of the CHWRMVibra class.

Leave codes

KErrNotSupported Device doesn't support vibration feature. KErrNoMemory There is a memory allocation failure.

IMPORT_C static CHWRMVibra* NewL(MHWRMVibraObserver *aCallback);

Description

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

Parameters

MHWRMVibraObserver *aCallback Pointer to callback instance

Return value

CHWRMVibra * A pointer to a new instance of the CHWRMVibra class.

Leave codes

KErrNotSupported Device doesn't support vibration feature. KErrNoMemory There is a memory allocation failure.

IMPORT_C static CHWRMVibra* NewLC(MHWRMVibraObserver *aCallback);

Description

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

Parameters

MHWRMVibraObserver *aCallback Pointer to callback instance

Return value

CHWRMVibra * A pointer to a new instance of the CHWRMVibra class.

Leave codes

KErrNotSupported Device doesn't support vibration feature. KErrNoMemory There is a memory allocation failure.

virtual void ReserveVibraL()=0;

Description

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

KErrAccessDenied No CCoeEnv present. KErrNotReady Trying to reserve while on background. KErrNoMemory There is a memory allocation failure.

virtual void ReserveVibraL(TBool aRestoreState, TBool aForceNoCCoeEnv)=0;

Description

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

TBool aRestoreState If 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. TBool aForceNoCCoeEnv If 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

KErrAccessDenied Parameter aForceNoCCoeEnv is ETrue and client is not trusted. KErrBadHandle Parameter aForceNoCCoeEnv is EFalse and no CCoeEnv present. KErrNotReady Trying to reserve while on background and parameter aForceNoCCoeEnv is EFalse. KErrNoMemory There is a memory allocation failure.

virtual void ReleaseVibra()=0;

Description

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.

virtual void StartVibraL(TInt aDuration)=0;

Description

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.

Parameters

TInt aDuration Duration 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

KErrArgument Duration is invalid. KErrAccessDenied Vibration setting in the user profile is not set. KErrBadHandle Vibra session has been invalidated. KErrLocked Vibra is locked down because too much continuous use or explicitly blocked by for example some vibration sensitive accessory. KErrTimedOut Timeout occurred in controlling vibra. KErrInUse Vibra is not reserved to this client but it is reserved to some other client. KErrNoMemory There is a memory allocation failure. KErrGeneral There is a hardware error.

See also:

• MHWRMVibraObserverA callback interface for vibra status reporting.

virtual void StartVibraL(TInt aDuration, TInt aIntensity)=0;

Description

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.

Parameters

TInt aDuration Duration 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. TInt aIntensity Intensity 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

KErrNotSupported The device doesn't support user-defined vibra intensity. KErrArgument One of the parameters is out of range. KErrAccessDenied Vibration setting in the user profile is not set. KErrBadHandle Vibra session has been invalidated. KErrLocked Vibra is locked down because too much continuous use or explicitly blocked by for example some vibration sensitive accessory. KErrTimedOut Timeout occurred in controlling vibra. KErrInUse Vibra is not reserved to this client but it is reserved to some other client. KErrNoMemory There is a memory allocation failure. KErrGeneral There is a hardware error.

See also:

• MHWRMVibraObserverA callback interface for vibra status reporting.

virtual void StopVibraL()=0;

Description

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

Leave codes

KErrBadHandle Vibra session has been invalidated. KErrTimedOut Timeout occurred in controlling vibra. KErrInUse Vibra is not reserved to this client but it is reserved to some other client. KErrNoMemory There is a memory allocation failure. KErrGeneral There is a hardware error.

See also:

• MHWRMVibraObserverA callback interface for vibra status reporting.

virtual TVibraModeState VibraSettings() const=0;

Description

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.

Return value

CHWRMVibra::TVibraModeState TVibraModeState indicating the current vibra mode setting.

See also:

• CHWRMVibra::TVibraModeStateVibration setting in the user profile.
• MHWRMVibraObserverA callback interface for vibra status reporting.

virtual TVibraStatus VibraStatus() const=0;

Description

This method retrieves the current vibra status.

Return value

CHWRMVibra::TVibraStatus TVibraStatus indicating the current vibra status

See also:

• CHWRMVibra::TVibraStatusStatus of the vibration feature
• MHWRMVibraObserverA callback interface for vibra status reporting.

TVibraModeState

Description

Vibration setting in the user profile.

EVibraModeUnknown 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.

TVibraStatus

Description

Status of the vibration feature

EVibraStatusUnknown 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.