CHWRMVibra Class Reference

API published in: S60 3rd Ed

Link against: hwrmvibraclient.lib

Capability Information

Required Capabilities

None

#include <hwrmvibra.h>

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>  // link against HWRMVibraClient.lib

 // 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;


Public Types
enum	TVibraModeState { EVibraModeUnknown = 0, EVibraModeON, EVibraModeOFF }
	Vibration setting in the user profile. More...
enum	TVibraStatus { EVibraStatusUnknown = 0, EVibraStatusNotAllowed, EVibraStatusStopped, EVibraStatusOn }
	Status of the vibration feature. More...
Public Member Functions
virtual void	ReserveVibraL ()=0
	Reserves vibration feature exclusively for this client.
virtual void	ReserveVibraL (TBool aRestoreState, TBool aForceNoCCoeEnv)=0
	Reserves vibration feature exclusively for this client.
virtual void	ReleaseVibra ()=0
	Releases vibration feature if it was previously reserved for this client.
virtual void	StartVibraL (TInt aDuration)=0
	Starts the device vibration feature with the product specific default intensity.
virtual void	StartVibraL (TInt aDuration, TInt aIntensity)=0
	Starts the device vibration feature.
virtual void	StopVibraL ()=0
	Interrupts the device vibration that is started with the StartVibraL method immediately.
virtual TVibraModeState	VibraSettings () const =0
	This method retrieves the current settings of the vibration feature in the user profile.
virtual TVibraStatus	VibraStatus () const =0
	This method retrieves the current vibra status.
Static Public Member Functions
static IMPORT_C CHWRMVibra *	NewL ()
	Two-phased constructor.
static IMPORT_C CHWRMVibra *	NewLC ()
	Two-phased constructor.
static IMPORT_C CHWRMVibra *	NewL (MHWRMVibraObserver *aCallback)
	Two-phased constructor.
static IMPORT_C CHWRMVibra *	NewLC (MHWRMVibraObserver *aCallback)
	Two-phased constructor.

Member Enumeration Documentation

enum CHWRMVibra::TVibraModeState

Vibration setting in the user profile.

Enumerator:

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.

enum CHWRMVibra::TVibraStatus

Status of the vibration feature.

Enumerator:

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.

Member Function Documentation

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

Two-phased constructor.

Use this method for creating a vibra client with callbacks.

Parameters:

aCallback

Pointer to callback instance

Returns:: A pointer to a new instance of the CHWRMVibra class.

Leave:: KErrNotSupported Device doesn't support vibration feature.

Leave:: KErrNoMemory There is a memory allocation failure.

static IMPORT_C CHWRMVibra* CHWRMVibra::NewL ( ) [static]

Two-phased constructor.

Returns:: A pointer to a new instance of the CHWRMVibra class.

Leave:: KErrNotSupported Device doesn't support vibration feature.

Leave:: KErrNoMemory There is a memory allocation failure.

static IMPORT_C CHWRMVibra* 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

Returns:: A pointer to a new instance of the CHWRMVibra class.

Leave:: KErrNotSupported Device doesn't support vibration feature.

Leave:: KErrNoMemory There is a memory allocation failure.

static IMPORT_C CHWRMVibra* CHWRMVibra::NewLC ( ) [static]

Two-phased constructor.

Leaves instance to cleanup stack.

Returns:: A pointer to a new instance of the CHWRMVibra class.

Leave:: KErrNotSupported Device doesn't support vibration feature.

Leave:: KErrNoMemory There is a memory allocation failure.

virtual void CHWRMVibra::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.

virtual void CHWRMVibra::ReserveVibraL	(	TBool	aRestoreState,
		TBool	aForceNoCCoeEnv
	)	`[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:

	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 S60 or a product.

Leave:: KErrAccessDenied Parameter aForceNoCCoeEnv is ETrue and client is not trusted.

Leave:: KErrBadHandle Parameter aForceNoCCoeEnv is EFalse and no CCoeEnv present.

Leave:: KErrNotReady Trying to reserve while on background and parameter aForceNoCCoeEnv is EFalse.

Leave:: KErrNoMemory There is a memory allocation failure.

virtual void CHWRMVibra::ReserveVibraL ( ) [pure virtual]

Reserves vibration feature exclusively for this client.

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:: KErrAccessDenied No CCoeEnv present.

Leave:: KErrNotReady Trying to reserve while on background.

Leave:: KErrNoMemory There is a memory allocation failure.

virtual void CHWRMVibra::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.

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:

	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:: KErrNotSupported The device doesn't support user-defined vibra intensity.

Leave:: KErrArgument One of the parameters is out of range.

Leave:: KErrAccessDenied Vibration setting in the user profile is not set.

Leave:: KErrBadHandle Vibra session has been invalidated.

Leave:: KErrLocked Vibra is locked down because too much continuous use or explicitly blocked by for example some vibration sensitive accessory.

Leave:: KErrTimedOut Timeout occurred in controlling vibra.

Leave:: KErrInUse Vibra is not reserved to this client but it is reserved to some other client.

Leave:: KErrNoMemory There is a memory allocation failure.

Leave:: KErrGeneral There is a hardware error.

See also:: MHWRMVibraObserver

virtual void CHWRMVibra::StartVibraL ( TInt aDuration ) [pure virtual]

Starts the device vibration feature with the product specific default intensity.

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:: KErrArgument Duration is invalid.

Leave:: KErrAccessDenied Vibration setting in the user profile is not set.

Leave:: KErrBadHandle Vibra session has been invalidated.

Leave:: KErrLocked Vibra is locked down because too much continuous use or explicitly blocked by for example some vibration sensitive accessory.

Leave:: KErrTimedOut Timeout occurred in controlling vibra.

Leave:: KErrInUse Vibra is not reserved to this client but it is reserved to some other client.

Leave:: KErrNoMemory There is a memory allocation failure.

Leave:: KErrGeneral There is a hardware error.

See also:: MHWRMVibraObserver

virtual void CHWRMVibra::StopVibraL ( ) [pure virtual]

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

Leave:: KErrBadHandle Vibra session has been invalidated.

Leave:: KErrTimedOut Timeout occurred in controlling vibra.

Leave:: KErrInUse Vibra is not reserved to this client but it is reserved to some other client.

Leave:: KErrNoMemory There is a memory allocation failure.

Leave:: KErrGeneral There is a hardware error.

See also:: MHWRMVibraObserver

virtual TVibraModeState CHWRMVibra::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.

Returns:: TVibraModeState indicating the current vibra mode setting.

See also:: TVibraModeState
MHWRMVibraObserver

virtual TVibraStatus CHWRMVibra::VibraStatus ( ) const [pure virtual]

This method retrieves the current vibra status.

Returns:: TVibraStatus indicating the current vibra status

See also:: TVibraStatus
MHWRMVibraObserver

The documentation for this class was generated from the following file:

hwrmvibra.h

CHWRMVibra Class Reference

Capability Information

Detailed Description

Public Types

Public Member Functions

Static Public Member Functions

Member Enumeration Documentation

Member Function Documentation