CHWRMVibra Class Reference

#include <hwrmvibra.h>

Link against: hwrmvibraclient.lib

class CHWRMVibra : public CBase, public CBase, public CBase

Inherits from

CHWRMVibra

Public Member Enumerations
enum	TVibraFeedbackModeState { EVibraFeedbackModeUnknown, EVibraFeedbackModeON, EVibraFeedbackModeOFF }
enum	TVibraModeState { EVibraModeUnknown, EVibraModeON, EVibraModeOFF }
enum	TVibraStatus { EVibraStatusUnknown, EVibraStatusNotAllowed, EVibraStatusStopped, EVibraStatusOn }

Public Member Functions
IMPORT_C CHWRMVibra *	NewL()
IMPORT_C CHWRMVibra *	NewL(MHWRMVibraObserver *)
IMPORT_C CHWRMVibra *	NewLC()
IMPORT_C CHWRMVibra *	NewLC(MHWRMVibraObserver *)
pure virtual void	PulseVibraL()
pure virtual void	PulseVibraL(TInt)
pure virtual void	PulseVibraL(TInt, TInt)
pure virtual void	ReleaseVibra()
pure virtual void	ReserveVibraL()
pure virtual void	ReserveVibraL(TBool, TBool)
pure virtual void	SetFeedbackObserver(MHWRMVibraFeedbackObserver *)
pure virtual void	StartVibraL(TInt)
pure virtual void	StartVibraL(TInt, TInt)
pure virtual void	StopVibraL()
pure virtual TVibraFeedbackModeState	VibraFeedbackSettings()
pure virtual TVibraModeState	VibraSettings()
pure virtual TVibraStatus	VibraStatus()

Inherited Functions
	CBase::CBase()
	CBase::Delete(CBase *)
	CBase::Extension_(TUint,TAny &,TAny )
	CBase::operator new(TUint)
	CBase::operator new(TUint,TAny *)
	CBase::operator new(TUint,TLeave)
	CBase::operator new(TUint,TLeave,TUint)
	CBase::operator new(TUint,TUint)
	CBase::~CBase()

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.

Enumerator	Value	Description
EVibraFeedbackModeUnknown	0	Not initialized yet or there is an error condion.
EVibraFeedbackModeON		Feedback vibration setting in the user profile is on.
EVibraFeedbackModeOFF		Feedback vibration setting in the user profile is off.

Enum TVibraModeState

Vibration setting in the user profile.

Enumerator	Value	Description
EVibraModeUnknown	0	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

Enumerator	Value	Description
EVibraStatusUnknown	0	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
KErrNotSupported	Device doesn't support vibration feature.
KErrNoMemory	There 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
aCallback	Pointer to callback instance

Return Value: 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.

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
KErrNotSupported	Device doesn't support vibration feature.
KErrNoMemory	There 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
aCallback	Pointer to callback instance

Return Value: 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.

PulseVibraL ( )

void

PulseVibraL

(

)

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

Leave Codes
KErrAccessDenied	Vibration setting in the user profile is not set or client is not privileged to use pulse feature.
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 or ongoing vibration has been requested by higher priority client.
KErrNoMemory	There is a memory allocation failure.
KErrGeneral	There is a hardware error.

PulseVibraL ( TInt )

void

PulseVibraL

(

TInt

aDuration

)

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

Parameters
aDuration	Duration of the vibration measured in milliseconds. Duration can have maximum value of KHWRMVibraMaxDuration.

Leave Codes
KErrArgument	One of the parameters is out of range.
KErrAccessDenied	Vibration setting in the user profile is not set or client is not privileged to use pulse feature.
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 or ongoing vibration has been requested by higher priority client.
KErrNoMemory	There is a memory allocation failure.
KErrGeneral	There is a hardware error.

PulseVibraL ( TInt, TInt )

void	PulseVibraL	(	TInt	aDuration,
			TInt	aIntensity
		)	[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.

Parameters
aDuration	Duration of the vibration measured in milliseconds. Duration can have maximum value of KHWRMVibraMaxDuration.
aIntensity	Intensity 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
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 or client is not privileged to use pulse feature.
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 or ongoing vibration has been requested by higher priority client.
KErrNoMemory	There is a memory allocation failure.
KErrGeneral	There is a hardware error.

ReleaseVibra ( )

void

ReleaseVibra

(

)

[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 ( )

void

ReserveVibraL

(

)

[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
KErrAccessDenied	No CCoeEnv present.
KErrNotReady	Trying to reserve while on background.
KErrNoMemory	There is a memory allocation failure.

ReserveVibraL ( TBool, TBool )

void	ReserveVibraL	(	TBool	aRestoreState,
			TBool	aForceNoCCoeEnv
		)	[pure virtual]

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

Parameters

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.

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.

SetFeedbackObserver ( MHWRMVibraFeedbackObserver * )

void

SetFeedbackObserver

(

MHWRMVibraFeedbackObserver *

aCallback

)

[pure virtual]

Use this method for setting feedback observer.

Parameters
aCallback	Pointer to callback instance

StartVibraL ( TInt )

void

StartVibraL

(

TInt

aDuration

)

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

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

StartVibraL ( TInt, TInt )

void	StartVibraL	(	TInt	aDuration,
			TInt	aIntensity
		)	[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.

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

StopVibraL ( )

void

StopVibraL

(

)

[pure virtual]

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.

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.

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.

Return Value: TVibraModeState indicating the current vibra mode setting.

VibraStatus ( )

TVibraStatus

VibraStatus

(

)

const [pure virtual]

This method retrieves the current vibra status.

Return Value: TVibraStatus indicating the current vibra status