CHWRMHaptics Class Reference

class CHWRMHaptics : public CBase

The class used to control the device's haptics feature.

The Haptics API provides the ability to control the device's haptics feature. The API provides methods for receiving the current status and effect completion of the haptics. The API provides synchronous and asynchronous versions of playing methods due to the nature of effect playing where multiple calls may be made to play effects. Synchronous methods are provided for other API functionality. They will block the calling client during their execution. The API is meant for all applications which need to control the device's haptics feature.

The API consist of the class CHWRMHaptics and related observer classes: MHWRMHapticsObserver and MHWRMHapticsActuatorObserver . If the client requires up-to-date status information, it can be achieved by deriving the client from MHWRMHapticsObserver or MHWRMHapticsActuatorObserver or from both and providing a callback pointer(s) of the implementing class for the NewL() method.

        // ===================================================================
 // Usage example 1:
 //    - Setting the license key.
 //    - Playing a periodic effect
 //    - Preconditions:
 //        - Haptics feature must be enabled by the system.
 // ===================================================================

 #include <hwrmhaptics.h>          // link against hwrmhapticsclient.lib
 #include <hwrmlogicalactuators.h> // enumeration of logical actuators

 TInt minPeriod( 0 );
 TInt effectHandle( 0 );
 TInt suppAct( 0 );

 CHWRMHaptics* haptics = CHWRMHaptics::NewL( NULL, NULL );

 haptics->SupportedActuators( suppAct );

 if( EHWRMLogicalActuatorDevice & suppAct )
     {
     haptics->OpenActuatorL( EHWRMLogicalActuatorDevice );
     }
 else if ( EHWRMLogicalActuatorAny & suppAct )
     {
     haptics->OpenActuatorL( EHWRMLogicalActuatorAny );
     }


 // 3rd party developers can obtain the license key from Forum Nokia
 _LIT8( KLicenseKey,"_this_value_must_be_32_in_length" );

 User::LeaveIfError(
     haptics->SetDeviceProperty( 
         THWRMHapticsDevicePropertyTypes::EHWRMHapticsLicenseKey,
         KLicenseKey ) );

 // --> now playing effects is possible

 CHWRMHaptics::THWRMHapticsPeriodicEffect periodicEff;

 periodicEff.iDuration = 5000;
 periodicEff.iMagnitude = 5000;
 periodicEff.iPeriod = minPeriod;
 periodicEff.iStyle = CHWRMHaptics::EHWRMHapticsStyleSharp;
 periodicEff.iAttackTime = 250;
 periodicEff.iAttackLevel = 10000;
 periodicEff.iFadeTime = 250;
 periodicEff.iFadeLevel = 0;

 haptics->PlayPeriodicEffect( periodicEff, effectHandle );

 // ... something happened in the application and it has lost focus
 // so stop the effect immediately

 haptics->StopPlayingEffect( effectHandle );

 // ================================================================
 // Usage example 2:
 //    - Loading effect data from a file and playing effects from the
 //      loaded data.
 //    - Preconditions:
 //        - license key is set
 //    - Recommended usage style:
 //        - Effect data file can contain definition(s) of periodic
 //          effects, magsweep effects or a combination of these basic
 //          types called timeline effects, which call basic effects in
 //          sequence thus forming new more complex effects.
 //        - Load the effect data once in the client application.
 //        - Play effects from the loaded data using the effectIndex
 // ================================================================

 // Use S60 FileSystem to load the effect data file to a buffer

 ...

 // Effect data has been read into a descriptor by the user.
 // Load the effect data to be used by the haptic subsystem.
 TInt fileHandle( 0 );
 User::LeaveIfError( haptics->LoadEffectData( data, fileHandle ) );
 
 TInt effectIndex = 0;
 TInt hapticsStatus = haptics->PlayEffect( fileHandle,
                                              effectIndex,
                                              effectHandle );
                                                
 hapticsStatus = haptics->DeleteEffectData( fileHandle );

 if( KErrNone != hapticsStatus )
     {
     // do some error handling...
     }

 delete haptics;
 haptics = NULL;
       

Common error codes returned by the Haptics API methods.

KErrArgument Argument is invalid, e.g., malformatted effect data, or too large magnitude value. KErrAccessDenied The license key is not set when trying to use some haptics method. KErrNoMemory There is insufficient memory available for the method to complete. KErrNotReady Initialization has not been done properly when trying to use a haptics method.

hwrmhapticsclient.dll
Since
S60 5.1

Inherits from

Public Member Functions
TInt CreateStreamingEffect ( TInt &)
TInt DefaultDevicePriority ()
TInt DeleteAllEffectData ()
TInt DeleteEffectData ( TInt )
TInt DestroyStreamingEffect ( TInt )
TInt GetDeviceCapability ( TInt , TInt &)
TInt GetDeviceCapability ( TInt , TDes8 &)
TInt GetDeviceProperty ( TInt , TInt &)
TInt GetDeviceProperty ( TInt , TDes8 &)
TInt GetEffectCount ( TInt , TInt &)
TInt GetEffectDuration ( TInt , TInt , TInt &)
TInt GetEffectIndexFromName ( TInt , const TDesC8 &, TInt &)
TInt GetEffectName ( TInt , TInt , TDes8 &)
TInt GetEffectState ( TInt , TInt &)
TInt GetEffectType ( TInt , TInt , TInt &)
TInt GetMagSweepEffectDefinition ( TInt , TInt , CHWRMHaptics::THWRMHapticsMagSweepEffect &)
TInt GetPeriodicEffectDefinition ( TInt , TInt , CHWRMHaptics::THWRMHapticsPeriodicEffect &)
MHWRMHapticsObserver::THWRMHapticsStatus HapticsStatus ()
TInt InfiniteDuration ()
TInt InfiniteRepeat ()
TInt LoadEffectData (const TDesC8 &, TInt &)
TInt MaxCapabilityStringLength ()
TInt MaxDeviceNameLength ()
TInt MaxEffectNameLength ()
TInt MaxPropertyStringLength ()
TInt MaxStreamingSampleSize ()
TInt ModifyPlayingMagSweepEffect ( TInt , const CHWRMHaptics::THWRMHapticsMagSweepEffect &)
void ModifyPlayingMagSweepEffect ( TInt , const CHWRMHaptics::THWRMHapticsMagSweepEffect &, TRequestStatus &)
TInt ModifyPlayingPeriodicEffect ( TInt , const CHWRMHaptics::THWRMHapticsPeriodicEffect &)
void ModifyPlayingPeriodicEffect ( TInt , const CHWRMHaptics::THWRMHapticsPeriodicEffect &, TRequestStatus &)
IMPORT_C CHWRMHaptics * NewL ( MHWRMHapticsObserver *, MHWRMHapticsActuatorObserver *)
IMPORT_C CHWRMHaptics * NewL ( MHWRMHapticsObserver *, MHWRMHapticsActuatorObserver *, TRequestStatus &)
void OpenActuatorL ( THWRMLogicalActuators )
TInt PausePlayingEffect ( TInt )
TInt PlayEffect ( TInt , TInt , TInt &)
void PlayEffect ( TInt , TInt , TInt &, TRequestStatus &)
TInt PlayEffect (const TDesC8 &, TInt , TInt &)
void PlayEffect (const TDesC8 &, TInt , TInt &, TRequestStatus &)
TInt PlayEffectRepeat ( TInt , TInt , TUint8 , TInt &)
void PlayEffectRepeat ( TInt , TInt , TUint8 , TInt &, TRequestStatus &)
TInt PlayEffectRepeat (const TDesC8 &, TInt , TUint8 , TInt &)
void PlayEffectRepeat (const TDesC8 &, TInt , TUint8 , TInt &, TRequestStatus &)
TInt PlayMagSweepEffect (const CHWRMHaptics::THWRMHapticsMagSweepEffect &, TInt &)
void PlayMagSweepEffect (const CHWRMHaptics::THWRMHapticsMagSweepEffect &, TInt &, TRequestStatus &)
TInt PlayPeriodicEffect (const CHWRMHaptics::THWRMHapticsPeriodicEffect &, TInt &)
void PlayPeriodicEffect (const CHWRMHaptics::THWRMHapticsPeriodicEffect &, TInt &, TRequestStatus &)
TInt PlayStreamingSample ( TInt , const TDesC8 &)
void PlayStreamingSample ( TInt , const TDesC8 &, TRequestStatus &)
TInt PlayStreamingSampleWithOffset ( TInt , const TDesC8 &, TInt )
void PlayStreamingSampleWithOffset ( TInt , const TDesC8 &, TInt , TRequestStatus &)
void ReleaseHaptics ()
void ReserveHapticsL ()
void ReserveHapticsL ( TBool )
TInt ResumePausedEffect ( TInt )
TInt SetDeviceProperty ( TInt , TInt )
TInt SetDeviceProperty ( TInt , const TDesC8 &)
TInt StopAllPlayingEffects ()
TInt StopPlayingEffect ( TInt )
TInt SupportedActuators ( TUint32 &)
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()
Public Member Enumerations
enum THWRMHapticsActuatorTypes { EHWRMHapticsTypeERM  = 0, EHWRMHapticsTypeLRA  = 2 }
enum THWRMHapticsDeviceCapabilityTypes {
EHWRMHapticsDeviceCategory  = 0, EHWRMHapticsMaxNestedRepeats , EHWRMHapticsNumActuators , EHWRMHapticsActuatorType , EHWRMHapticsNumEffectSlots , EHWRMHapticsSupportedStyles , EHWRMHapticsMinPeriod , EHWRMHapticsMaxPeriod , EHWRMHapticsMaxEffectDuration , EHWRMHapticsSupportedEffects , EHWRMHapticsDeviceName , EHWRMHapticsMaxEnvelopeTime , EHWRMHapticsAPIVersionNumber , EHWRMHapticsMaxEffectDataSize  = 14
}
enum THWRMHapticsDeviceCategory { EHWRMHapticsVirtual  = 2, EHWRMHapticsEmbedded  = 3 }
enum THWRMHapticsDevicePropertyTypes { EHWRMHapticsLicensekey  = 0, EHWRMHapticsPriority , EHWRMHapticsDisableEffects , EHWRMHapticsStrength , EHWRMHapticsMasterStrength }
enum THWRMHapticsEffectStates { EHWRMHapticsEffectNotPlaying  = 0, EHWRMHapticsEffectPlaying , EHWRMHapticsEffectPaused }
enum THWRMHapticsEffectStyles { EHWRMHapticsStyleSmooth  = 0, EHWRMHapticsStyleStrong , EHWRMHapticsStyleSharp }
enum THWRMHapticsEffectTypes { EHWRMHapticsTypePeriodic  = 0, EHWRMHapticsTypeMagSweep , EHWRMHapticsTypeTimeline , EHWRMHapticsTypeStreaming }
enum THWRMHapticsSupportedEffectStyles { EHWRMHapticsSupportSmooth  = 1, EHWRMHapticsSupportStrong  = 2, EHWRMHapticsSupportSharp  = 4 }
enum THWRMHapticsSupportedEffectTypes { EHWRMHapticsSupportPeriodic  = 1, EHWRMHapticsSupportMagSweep  = 2, EHWRMHapticsSupportTimeline  = 4, EHWRMHapticsSupportStreaming  = 8 }

Member Functions Documentation

CreateStreamingEffect(TInt &)

TInt CreateStreamingEffect ( TInt & aEffectHandle ) [pure virtual]

Creates a streaming effect.

Client calls CreateStreamingEffect() to create a new streaming effect and gets a new handle for it; it should use that effect handle to play a streaming sample by calling PlayStreamingSample() .

Since
S60 5.1

Parameters

TInt & aEffectHandle Reference to the variable that receives a handle to the streaming effect.

DefaultDevicePriority()

TInt DefaultDevicePriority ( ) const [pure virtual]

Gets the default device priority. Method may be used only after an actuator has been opened successfully.

DeleteAllEffectData()

TInt DeleteAllEffectData ( ) [pure virtual]

Delete all loaded effect datas.

Since
S60 5.1

DeleteEffectData(TInt)

TInt DeleteEffectData ( TInt aFileHandle ) [pure virtual]

Delete loaded effect data referenced by file handle.

Since
S60 5.1

Parameters

TInt aFileHandle Handle to file.

DestroyStreamingEffect(TInt)

TInt DestroyStreamingEffect ( TInt aEffectHandle ) [pure virtual]

Destroys a streaming effect previously created in a successful call to CreateStreamingEffect() .

Since
S60 5.1

Parameters

TInt aEffectHandle Handle to the streaming effect to destroy.

GetDeviceCapability(TInt, TInt &)

TInt GetDeviceCapability ( TInt aDeviceCapabilityType,
TInt & aDeviceCapabilityValue
) [pure virtual]

Gets a capability value of the haptics.

Parameters

TInt aDeviceCapabilityType Capability type of the capability to get.
TInt & aDeviceCapabilityValue Reference to the variable that receives the requested capability value of the device.

GetDeviceCapability(TInt, TDes8 &)

TInt GetDeviceCapability ( TInt aDeviceCapabilityType,
TDes8 & aDeviceCapabilityValue
) [pure virtual]

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters

TInt aDeviceCapabilityType
TDes8 & aDeviceCapabilityValue

GetDeviceProperty(TInt, TInt &)

TInt GetDeviceProperty ( TInt aDevicePropertyType,
TInt & aDevicePropertyValue
) [pure virtual]

Gets a property value of the haptics.

THWRMHapticsDevicePropertyTypes for a list of the valid property types.
Since
S60 5.1

Parameters

TInt aDevicePropertyType Property type for the property to get.
TInt & aDevicePropertyValue Reference to the variable that receives the requested property value of the device.

GetDeviceProperty(TInt, TDes8 &)

TInt GetDeviceProperty ( TInt aDevicePropertyType,
TDes8 & aDevicePropertyValue
) [pure virtual]

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters

TInt aDevicePropertyType
TDes8 & aDevicePropertyValue

GetEffectCount(TInt, TInt &)

TInt GetEffectCount ( TInt aFileHandle,
TInt & aCount
) const [pure virtual]

Get a number of effects defined in a loaded effect data buffer.

Since
S60 5.1

Parameters

TInt aFileHandle Handle to the loaded effect data buffer.
TInt & aCount Number of effects in the effect data buffer.

GetEffectDuration(TInt, TInt, TInt &)

TInt GetEffectDuration ( TInt aFileHandle,
TInt aEffectIndex,
TInt & aEffectDuration
) const [pure virtual]

Get the duration of an effect defined in a loaded effect data buffer.

Since
S60 5.1

Parameters

TInt aFileHandle Handle to the loaded effect data buffer.
TInt aEffectIndex Effect for which the duration is wanted.
TInt & aEffectDuration Reference to the variable that receives the requested effect's duration value. Duration is in milliseconds.

GetEffectIndexFromName(TInt, const TDesC8 &, TInt &)

TInt GetEffectIndexFromName ( TInt aFileHandle,
const TDesC8 & aEffectName,
TInt & aEffectIndex
) const [pure virtual]

Gets the index of an effect defined in a loaded effect data buffer from the name of the effect.

Since
S60 5.1

Parameters

TInt aFileHandle Handle to the loaded effect data buffer.
const TDesC8 & aEffectName Name of the effect for which the index is wanted.
TInt & aEffectIndex Reference to the variable that receives the requested effect's index value.

GetEffectName(TInt, TInt, TDes8 &)

TInt GetEffectName ( TInt aFileHandle,
TInt aEffectIndex,
TDes8 & aEffectName
) const [pure virtual]

Gets the name of an effect defined in a loaded effect data buffer.

Since
S60 5.1

Parameters

TInt aFileHandle Handle to the loaded effect data buffer.
TInt aEffectIndex Index of an effect for which a name is wanted.
TDes8 & aEffectName Reference to the variable that receives the requested effect's name. Note that the descriptor's size must be at least the size given from MaxPropertyStringLength().

GetEffectState(TInt, TInt &)

TInt GetEffectState ( TInt aEffectHandle,
TInt & aEffectState
) [pure virtual]

Retrieves the status of an effect (playing, not playing, paused).

THWRMHapticsEffectStates for a list of valid effect states.
Since
S60 5.1

Parameters

TInt aEffectHandle Handle to the effect which must have been obtained by calling PlayMagSweepEffect(), PlayPeriodicEffect(), PlayEffect(), PlayEffectRepeat() or CreateStreamingEffect()
TInt & aEffectState Pointer to the variable that receives the status bits of the effect.

GetEffectType(TInt, TInt, TInt &)

TInt GetEffectType ( TInt aFileHandle,
TInt aEffectIndex,
TInt & aEffectType
) const [pure virtual]

Gets the type of an effect defined in loaded effect data buffer.

Since
S60 5.1

Parameters

TInt aFileHandle Handle to loaded effect data buffer.
TInt aEffectIndex Index of an effect for which a type is wanted.
TInt & aEffectType Reference to the variable that receives the requested effect's type value.

GetMagSweepEffectDefinition(TInt, TInt, CHWRMHaptics::THWRMHapticsMagSweepEffect &)

TInt GetMagSweepEffectDefinition ( TInt aFileHandle,
TInt aEffectIndex,
CHWRMHaptics::THWRMHapticsMagSweepEffect & aEffect
) const [pure virtual]

Gets the parameters of a MagSweep effect defined in a loaded effect data buffer.

THWRMHapticsMagSweepEffect for effect definition.
Since
S60 5.1

Parameters

TInt aFileHandle Handle to the loaded effect data buffer.
TInt aEffectIndex Index of an effect for which a definition is wanted.
CHWRMHaptics::THWRMHapticsMagSweepEffect & aEffect Reference to the variable that receives the effect definition.

GetPeriodicEffectDefinition(TInt, TInt, CHWRMHaptics::THWRMHapticsPeriodicEffect &)

TInt GetPeriodicEffectDefinition ( TInt aFileHandle,
TInt aEffectIndex,
CHWRMHaptics::THWRMHapticsPeriodicEffect & aEffect
) const [pure virtual]

Gets the parameters of a periodic effect defined in a loaded effect data buffer.

THWRMHapticsPeriodicEffect for effect definition.
Since
S60 5.1

Parameters

TInt aFileHandle Handle to the loaded effect data buffer.
TInt aEffectIndex Index of an effect for which a definition is wanted.
CHWRMHaptics::THWRMHapticsPeriodicEffect & aEffect Reference to the variable that receives the effect definition.

HapticsStatus()

MHWRMHapticsObserver::THWRMHapticsStatus HapticsStatus ( ) const [pure virtual]

This method retrieves the current haptics status.

THWRMHapticsStatus

InfiniteDuration()

TInt InfiniteDuration ( ) const [pure virtual]

Gets the value that represents infinite duration. Method may be used only after an actuator has been opened successfully.

InfiniteRepeat()

TInt InfiniteRepeat ( ) const [pure virtual]

Gets the value that represents infinite repeats. Method may be used only after an actuator has been opened successfully.

LoadEffectData(const TDesC8 &, TInt &)

TInt LoadEffectData ( const TDesC8 & aData,
TInt & aFileHandle
) [pure virtual]

Load effect data defined in effect data buffer (obtained e.g. from a file containing the effect data).

Since
S60 5.1

Parameters

const TDesC8 & aData Reference to allocated effect data buffer.
TInt & aFileHandle On return contains a handle to the passed effect data. This handle is haptics specific, i.e., it is not a file system handle but just a handle to the loaded effect data buffer.

MaxCapabilityStringLength()

TInt MaxCapabilityStringLength ( ) const [pure virtual]

Gets the maximum capability string length. Method may be used only after an actuator has been opened successfully.

MaxDeviceNameLength()

TInt MaxDeviceNameLength ( ) const [pure virtual]

Gets the maximum device name length. Method may be used only after an actuator has been opened successfully.

MaxEffectNameLength()

TInt MaxEffectNameLength ( ) const [pure virtual]

Gets the maximum length of an effect name stored in a loaded effect data file. Method may be used only after an actuator has been opened successfully.

MaxPropertyStringLength()

TInt MaxPropertyStringLength ( ) const [pure virtual]

Gets the maximum property string length. Method may be used only after an actuator has been opened successfully.

MaxStreamingSampleSize()

TInt MaxStreamingSampleSize ( ) const [pure virtual]

Gets the maximum streaming sample size. Method may be used only after an actuator has been opened successfully.

ModifyPlayingMagSweepEffect(TInt, const CHWRMHaptics::THWRMHapticsMagSweepEffect &)

TInt ModifyPlayingMagSweepEffect ( TInt aEffectHandle,
const CHWRMHaptics::THWRMHapticsMagSweepEffect & aEffect
) [pure virtual]

Modifies a playing MagSweep effect.

Synchronous method returns when the haptic command has been evaluated and the return value is valid.

THWRMHapticsMagSweepEffect for effect definition.
Since
S60 5.1

Parameters

TInt aEffectHandle Handle to the playing MagSweep effect to modify. The handle to the effect must have been obtained by calling PlayMagSweepEffect(), PlayEffect() or PlayEffectRepeat().
const CHWRMHaptics::THWRMHapticsMagSweepEffect & aEffect Reference to a struct defining the effect parameters.

ModifyPlayingMagSweepEffect(TInt, const CHWRMHaptics::THWRMHapticsMagSweepEffect &, TRequestStatus &)

void ModifyPlayingMagSweepEffect ( TInt aEffectHandle,
const CHWRMHaptics::THWRMHapticsMagSweepEffect & aEffect,
TRequestStatus & aStatus
) [pure virtual]

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters

TInt aEffectHandle
const CHWRMHaptics::THWRMHapticsMagSweepEffect & aEffect
TRequestStatus & aStatus Request status. On completion contains: KErrNone, if successful, otherwise one of the other system-wide error codes.

ModifyPlayingPeriodicEffect(TInt, const CHWRMHaptics::THWRMHapticsPeriodicEffect &)

TInt ModifyPlayingPeriodicEffect ( TInt aEffectHandle,
const CHWRMHaptics::THWRMHapticsPeriodicEffect & aEffect
) [pure virtual]

Modifies a playing periodic effect.

Synchronous method returns when the haptic command has been evaluated and the return value is valid.

THWRMHapticsPeriodicEffect for effect definition.
Since
S60 5.1

Parameters

TInt aEffectHandle Handle to the playing periodic effect to modify. The handle to the effect must have been obtained by calling PlayPeriodicEffect(), PlayEffect() or PlayEffectRepeat().
const CHWRMHaptics::THWRMHapticsPeriodicEffect & aEffect Reference to a struct defining the effect parameters.

ModifyPlayingPeriodicEffect(TInt, const CHWRMHaptics::THWRMHapticsPeriodicEffect &, TRequestStatus &)

void ModifyPlayingPeriodicEffect ( TInt aEffectHandle,
const CHWRMHaptics::THWRMHapticsPeriodicEffect & aEffect,
TRequestStatus & aStatus
) [pure virtual]

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters

TInt aEffectHandle
const CHWRMHaptics::THWRMHapticsPeriodicEffect & aEffect
TRequestStatus & aStatus Request status. On completion contains: KErrNone, if successful, otherwise one of the other system-wide error codes.

NewL(MHWRMHapticsObserver *, MHWRMHapticsActuatorObserver *)

IMPORT_C CHWRMHaptics * NewL ( MHWRMHapticsObserver * aHapticsCallback,
MHWRMHapticsActuatorObserver * aActuatorCallback
) [static]

Two-phased constructor. Use this method for creating a haptics instance with callbacks.

Since
S60 5.1

Parameters

MHWRMHapticsObserver * aHapticsCallback Pointer to callback instance. Can be NULL.
MHWRMHapticsActuatorObserver * aActuatorCallback Pointer to callback instance. Can be NULL.

NewL(MHWRMHapticsObserver *, MHWRMHapticsActuatorObserver *, TRequestStatus &)

IMPORT_C CHWRMHaptics * NewL ( MHWRMHapticsObserver * aHapticsCallback,
MHWRMHapticsActuatorObserver * aActuatorCallback,
TRequestStatus & aStatus
) [static]

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters

MHWRMHapticsObserver * aHapticsCallback
MHWRMHapticsActuatorObserver * aActuatorCallback
TRequestStatus & aStatus Request status. On completion contains: KErrNone, if successful, otherwise one of the other system-wide error codes.

OpenActuatorL(THWRMLogicalActuators)

void OpenActuatorL ( THWRMLogicalActuators aActuator ) [pure virtual]

Method for opening a logical actuator for use.

This method must be called before using any other methods of this class, except when using GetXXX methods. The Haptics API supports a limited number of instances of CHWRMHaptics class. If all instances are currently in use, the next attempt to call OpenActuatorL() from any client fails. Applications should not use more instances than necessary as this may prevent other applications from instantiating the CHWRMHaptics class.

leave
TInt KErrNotSupported, if the used logical actuator is not supported by the system.
leave
TInt KErrAlreadyExists, if the used logical actuator is already opened.
leave
TInt KErrInUse, if some other actuator is already opened.
leave
TInt KErrArgument, if aActuator is not valid enumeration value.
THWRMLogicalActuators for a list of usable actuators.
Since
S60 5.1

Parameters

THWRMLogicalActuators aActuator Enumeration of the type of logical actuator the client wants to use.

PausePlayingEffect(TInt)

TInt PausePlayingEffect ( TInt aEffectHandle ) [pure virtual]

Pauses a playing effect.

Since
S60 5.1

Parameters

TInt aEffectHandle Handle to the playing effect to pause. The handle to the effect must have been obtained by calling PlayMagSweepEffect(), PlayPeriodicEffect() , PlayEffect() , PlayEffectRepeat() or CreateStreamingEffect().

PlayEffect(TInt, TInt, TInt &)

TInt PlayEffect ( TInt aFileHandle,
TInt aEffectIndex,
TInt & aEffectHandle
) [pure virtual]

Plays an effect defined in loaded effect data buffer.

Synchronous method returns when the haptic command has been evaluated and the return value is valid.

Since
S60 5.1

Parameters

TInt aFileHandle Handle to the loaded effect data.
TInt aEffectIndex Index of the effect to play. The index of the effect must be greater than or equal to 0 and less than the number of effects returned by GetEffectCount().
TInt & aEffectHandle Reference to the variable that receives a handle to the playing effect.

PlayEffect(TInt, TInt, TInt &, TRequestStatus &)

void PlayEffect ( TInt aFileHandle,
TInt aEffectIndex,
TInt & aEffectHandle,
TRequestStatus & aStatus
) [pure virtual]

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters

TInt aFileHandle
TInt aEffectIndex
TInt & aEffectHandle
TRequestStatus & aStatus Request status. On completion contains: KErrNone, if successful, KErrInUse when haptics is reserved for a higher or equal priority client, otherwise one of the other system-wide error codes.

PlayEffect(const TDesC8 &, TInt, TInt &)

TInt PlayEffect ( const TDesC8 & aData,
TInt aEffectIndex,
TInt & aEffectHandle
) [pure virtual]

Plays an effect defined in effect data buffer.

Synchronous method returns when the haptic command has been evaluated and the return value is valid.

Since
S60 5.1

Parameters

const TDesC8 & aData Reference to effect data buffer containing the definition of the effect to play.
TInt aEffectIndex Index of the effect to play. The index of the effect must be greater than or equal to 0 and less than the number of effects returned by GetEffectCount().
TInt & aEffectHandle Reference to the variable that receives a handle to the playing effect.

PlayEffect(const TDesC8 &, TInt, TInt &, TRequestStatus &)

void PlayEffect ( const TDesC8 & aData,
TInt aEffectIndex,
TInt & aEffectHandle,
TRequestStatus & aStatus
) [pure virtual]

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters

const TDesC8 & aData
TInt aEffectIndex
TInt & aEffectHandle
TRequestStatus & aStatus Request status. On completion contains: KErrNone, if successful, KErrArgument, if the data is invalid, KErrInUse when haptics is reserved for a higher or equal priority client, otherwise one of the other system-wide error codes.

PlayEffectRepeat(TInt, TInt, TUint8, TInt &)

TInt PlayEffectRepeat ( TInt aFileHandle,
TInt aEffectIndex,
TUint8 aRepeat,
TInt & aEffectHandle
) [pure virtual]

Repeatedly plays a Timeline effect defined in loaded effect data buffer.

The current implementation of PlayEffectRepeat() repeats only Timeline effects. If the given effect index refers to a simple effect, PlayEffectRepeat() ignores the aRepeat parameter and plays the simple effect once. In that case, PlayEffectRepeat() behaves like PlayEffect() . PlayEffectRepeat() does not return a warning when requested to repeat a simple effect.

Synchronous method returns when the haptic command has been evaluated and the return value is valid.

Since
S60 5.1

Parameters

TInt aFileHandle Handle to the loaded effect data.
TInt aEffectIndex Index of the effect to play. The index of the effect must be greater than or equal to 0 and less than the number of effects returned by GetEffectCount().
TUint8 aRepeat Number of times to repeat the effect. To play the effect indefinitely, set aRepeat to InfiniteRepeat(). To repeat the effect a finite number of times, set aRepeat to a value from 0 to InfiniteRepeat() - 1. The effect can be repeated at most InfiniteRepeat() - 1 times. Setting aRepeat to 0 plays the effect once (repeats the effect zero times) and is equivalent to calling PlayEffect(). To stop the effect before it has repeated the requested number of times or to stop an effect that is playing indefinitely, call StopPlayingEffect() or StopAllPlayingEffects()
TInt & aEffectHandle Reference to the variable that receives a handle to the playing effect.

PlayEffectRepeat(TInt, TInt, TUint8, TInt &, TRequestStatus &)

void PlayEffectRepeat ( TInt aFileHandle,
TInt aEffectIndex,
TUint8 aRepeat,
TInt & aEffectHandle,
TRequestStatus & aStatus
) [pure virtual]

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters

TInt aFileHandle
TInt aEffectIndex
TUint8 aRepeat
TInt & aEffectHandle
TRequestStatus & aStatus Request status. On completion contains: KErrNone, if successful, KErrInUse when haptics is reserved for a higher or equal priority client, otherwise one of the other system-wide error codes.

PlayEffectRepeat(const TDesC8 &, TInt, TUint8, TInt &)

TInt PlayEffectRepeat ( const TDesC8 & aData,
TInt aEffectIndex,
TUint8 aRepeat,
TInt & aEffectHandle
) [pure virtual]

Repeatedly plays a Timeline effect defined in effect data buffer.

The current implementation of PlayEffectRepeat() repeats only Timeline effects. If the given effect index refers to a simple effect, PlayEffectRepeat() ignores the aRepeat parameter and plays the simple effect once. In that case, PlayEffectRepeat() behaves similarly to PlayEffect() . PlayEffectRepeat() does not return a warning when requested to repeat a simple effect.

Synchronous method returns when the haptic command has been evaluated and the return value is valid.

Since
S60 5.1

Parameters

const TDesC8 & aData Reference to effect data buffer containing the definition of the effect to play.
TInt aEffectIndex Index of the effect to play. The index of the effect must be greater than or equal to 0 and less than the number of effects returned by GetEffectCount().
TUint8 aRepeat Number of times to repeat the effect. To play the effect indefinitely, set aRepeat to InfiniteRepeat(). To repeat the effect a finite number of times, set aRepeat to a value from 0 to InfiniteRepeat() - 1. The effect can be repeated at most InfiniteRepeat() - 1 times. Setting aRepeat to 0 plays the effect once (repeats the effect zero times) and is equivalent to calling PlayEffect(). To stop the effect before it has repeated the requested number of times or to stop an effect that is playing indefinitely, call StopPlayingEffect() or StopAllPlayingEffects()
TInt & aEffectHandle Reference to the variable that receives a handle to the playing effect.

PlayEffectRepeat(const TDesC8 &, TInt, TUint8, TInt &, TRequestStatus &)

void PlayEffectRepeat ( const TDesC8 & aData,
TInt aEffectIndex,
TUint8 aRepeat,
TInt & aEffectHandle,
TRequestStatus & aStatus
) [pure virtual]

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters

const TDesC8 & aData
TInt aEffectIndex
TUint8 aRepeat
TInt & aEffectHandle
TRequestStatus & aStatus Request status. On completion contains: KErrNone, if successful, KErrArgument, if the data is invalid, KErrInUse when haptics is reserved for a higher or equal priority client, otherwise one of the other system-wide error codes.

PlayMagSweepEffect(const CHWRMHaptics::THWRMHapticsMagSweepEffect &, TInt &)

TInt PlayMagSweepEffect ( const CHWRMHaptics::THWRMHapticsMagSweepEffect & aEffect,
TInt & aEffectHandle
) [pure virtual]

Plays a MagSweep effect given in the parameters defining the effect.

Synchronous method returns when the haptic command has been evaluated and the return value is valid.

THWRMHapticsMagSweepEffect for effect definition.
Since
S60 5.1

Parameters

const CHWRMHaptics::THWRMHapticsMagSweepEffect & aEffect Reference to a struct defining the effect parameters.
TInt & aEffectHandle Reference to the variable that receives a handle to the playing effect.

PlayMagSweepEffect(const CHWRMHaptics::THWRMHapticsMagSweepEffect &, TInt &, TRequestStatus &)

void PlayMagSweepEffect ( const CHWRMHaptics::THWRMHapticsMagSweepEffect & aEffect,
TInt & aEffectHandle,
TRequestStatus & aStatus
) [pure virtual]

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters

const CHWRMHaptics::THWRMHapticsMagSweepEffect & aEffect
TInt & aEffectHandle
TRequestStatus & aStatus Request status. On completion contains: KErrNone, if successful, KErrInUse when haptics is reserved for a higher or equal priority client, otherwise one of the other system-wide error codes.

PlayPeriodicEffect(const CHWRMHaptics::THWRMHapticsPeriodicEffect &, TInt &)

TInt PlayPeriodicEffect ( const CHWRMHaptics::THWRMHapticsPeriodicEffect & aEffect,
TInt & aEffectHandle
) [pure virtual]

Plays a Periodic effect given in the parameters defining the effect.

Synchronous method returns when the haptic command has been evaluated and the return value is valid.

THWRMHapticsPeriodicEffect for effect definition.
Since
S60 5.1

Parameters

const CHWRMHaptics::THWRMHapticsPeriodicEffect & aEffect Reference to a struct defining the effect parameters.
TInt & aEffectHandle Reference to the variable that receives a handle to the playing effect.

PlayPeriodicEffect(const CHWRMHaptics::THWRMHapticsPeriodicEffect &, TInt &, TRequestStatus &)

void PlayPeriodicEffect ( const CHWRMHaptics::THWRMHapticsPeriodicEffect & aEffect,
TInt & aEffectHandle,
TRequestStatus & aStatus
) [pure virtual]

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters

const CHWRMHaptics::THWRMHapticsPeriodicEffect & aEffect
TInt & aEffectHandle
TRequestStatus & aStatus Request status. On completion contains: KErrNone, if successful, KErrInUse when haptics is reserved for a higher or equal priority client, otherwise one of the other system-wide error codes.

PlayStreamingSample(TInt, const TDesC8 &)

TInt PlayStreamingSample ( TInt aEffectHandle,
const TDesC8 & aStreamingSample
) [pure virtual]

Plays a streaming sample given in the parameter defining the effect.

Streaming sample can only be played after calling CreateStreamingEffect() and by using the effecthandle it returns.

Synchronous method returns when the haptic command has been evaluated and the return value is valid.

Since
S60 5.1

Parameters

TInt aEffectHandle Handle to the streaming effect to play.
const TDesC8 & aStreamingSample Reference to streaming sample data containing the definition of the effect to play.

PlayStreamingSample(TInt, const TDesC8 &, TRequestStatus &)

void PlayStreamingSample ( TInt aEffectHandle,
const TDesC8 & aStreamingSample,
TRequestStatus & aStatus
) [pure virtual]

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters

TInt aEffectHandle
const TDesC8 & aStreamingSample
TRequestStatus & aStatus Request status. On completion contains: KErrNone, if successful, KErrInUse when haptics is reserved for a higher or equal priority client, otherwise one of the other system-wide error codes.

PlayStreamingSampleWithOffset(TInt, const TDesC8 &, TInt)

TInt PlayStreamingSampleWithOffset ( TInt aEffectHandle,
const TDesC8 & aStreamingSample,
TInt aOffsetTime
) [pure virtual]

Plays a streaming sample with a time offset given in the parameters defining the effect.

Client calls CreateStreamingEffect() to create a new streaming effect and gets a new handle for it; it should use that effect handle to play the streaming sample with this method.

Synchronous method returns when the haptic command has been evaluated and the return value is valid.

Since
S60 5.1

Parameters

TInt aEffectHandle Handle to the streaming effect to play.
const TDesC8 & aStreamingSample Reference to streaming sample data containing the definition of the effect to play.
TInt aOffsetTime For aOffsetTime values that are greater than 0, playback is delayed for aOffsetTime in milliseconds. For aOffsetTime values that are less than 0, sample playback begins in offset time in milliseconds into the current sample.

PlayStreamingSampleWithOffset(TInt, const TDesC8 &, TInt, TRequestStatus &)

void PlayStreamingSampleWithOffset ( TInt aEffectHandle,
const TDesC8 & aStreamingSample,
TInt aOffsetTime,
TRequestStatus & aStatus
) [pure virtual]

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters

TInt aEffectHandle
const TDesC8 & aStreamingSample
TInt aOffsetTime
TRequestStatus & aStatus Request status. On completion contains: KErrNone, if successful, KErrInUse when haptics is reserved for a higher or equal priority client, otherwise one of the other system-wide error codes.

ReleaseHaptics()

void ReleaseHaptics ( ) [pure virtual]

Releases haptics feature if it was previously reserved for this client.

If this client has not reserved haptics feature, does nothing. If haptics is on when it is released and no other client has a suspended reservation, haptics is stopped.

ReserveHapticsL()

void ReserveHapticsL ( ) [pure virtual]

Reserves haptics feature exclusively for this client. A higher priority client may cause lower priority client reservation to be temporarily suspended. The suspended client does not get any notification about suspension. If haptics is already reserved by a higher or equal priority client, reserving still succeeds, but reservation is immediately suspended. When the reservation is suspended, playing effects do not actually cause the effects to be played. Note: Unless the client has instantiated the Haptics API with the status observer, it does not receive any notifications about the fact that its effects are not actually played by the physical player when the client has been suspended by a higher priority reservation. Note also that even if haptics is reserved by some client, a higher priority client succeeds in playing its effects.

Calling this method is equal to call ReserveHapticsL(EFalse), i.e. foreground status is always used to control further reservations. However, this is a future feature, and not implemented in current version.

ReserveHapticsL(TBool)

void ReserveHapticsL ( TBool aForceNoCCoeEnv ) [pure virtual]

Reserves haptics feature exclusively for this client. A higher priority client may cause lower priority client reservation to be temporarily suspended. The suspended client does not get any notifications about suspension. If haptics is already reserved by a higher or equal priority client, reserving still succeeds, but reservation is immediately suspended. When the reservation is suspended, playing effects does not actually cause the effects to be played. Note: Unless the client has instantiated the Haptics API with the status observer, it does not receive any notifications about the fact that its effects are not actually played by the physical player when the client has been suspended by a higher priority reservation. Note also that even if haptics is reserved by some client, a higher priority client succeeds in playing its effects.

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.

Parameters

TBool aForceNoCCoeEnv (Note: This is a future feature, and not implemented in current version. You can think of it ETrue always.) If EFalse, then reservation requires that this client has the keyboard focus at the time of reservation and haptics is 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 does not require CCoeEnv to be present nor does it automatically reserve or release haptics by depending on the foreground or background status of the client. Only trusted clients are allowed to set this flag to ETrue. The client application is considered trusted if it has a priority defined in haptics policy file. The policy files can be modified by S60 licensees.

ResumePausedEffect(TInt)

TInt ResumePausedEffect ( TInt aEffectHandle ) [pure virtual]

Resumes playback on a paused effect from the point where the effect was paused.

Depending on the available slots, it is possible that all simple effects from a paused effect data buffer or streaming sample cannot be resumed. The API returns success when it is able to play one of these simple effects.

Since
S60 5.1

Parameters

TInt aEffectHandle Handle to the paused effect to resume. The handle to the effect must have been obtained by calling PlayMagSweepEffect(), PlayPeriodicEffect(), PlayEffect(), PlayEffectRepeat() or CreateStreamingEffect().

SetDeviceProperty(TInt, TInt)

TInt SetDeviceProperty ( TInt aDevicePropertyType,
TInt aDevicePropertyValue
) [pure virtual]

Sets a property of the haptics.

Some properties affect all haptics instances, some only the current instance of the haptics. More about that can be found in THWRMHapticsDevicePropertyTypes.

THWRMHapticsDevicePropertyTypes for a list of valid property types
Since
S60 5.1

Parameters

TInt aDevicePropertyType Property type for the property to be set.
TInt aDevicePropertyValue Value of the property to set.

SetDeviceProperty(TInt, const TDesC8 &)

TInt SetDeviceProperty ( TInt aDevicePropertyType,
const TDesC8 & aDevicePropertyValue
) [pure virtual]

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

Parameters

TInt aDevicePropertyType
const TDesC8 & aDevicePropertyValue

StopAllPlayingEffects()

TInt StopAllPlayingEffects ( ) [pure virtual]

Stops all playing and paused effects of a haptics instance.

Since
S60 5.1

StopPlayingEffect(TInt)

TInt StopPlayingEffect ( TInt aEffectHandle ) [pure virtual]

Stops a playing effect.

Since
S60 5.1

Parameters

TInt aEffectHandle Handle to the playing effect to stop. The handle to the effect must have been obtained by calling PlayMagSweepEffect(), PlayPeriodicEffect(), PlayEffect(), PlayEffectRepeat() or CreateStreamingEffect().

SupportedActuators(TUint32 &)

TInt SupportedActuators ( TUint32 & aActuators ) [pure virtual]

Method for getting a bitmask value of supported logical actuators.

Developer needs to evaluate the returned bitmask against THWRMLogicalActuators enumeration values to know the supported logical actuators.

THWRMLogicalActuators for a list of usable actuators.
Since
S60 5.1

Parameters

TUint32 & aActuators Bitmask of supported logical actuators.

Member Enumerations Documentation

Enum THWRMHapticsActuatorTypes

Actuator types.

To be used with GetDeviceCapability() .

Enumerators

EHWRMHapticsTypeERM = 0

Eccentric Rotating Mass actuator

EHWRMHapticsTypeLRA = 2

Linear Resonant actuator

Enum THWRMHapticsDeviceCapabilityTypes

Device's capability types.

Use TInt& aDeviceCapabilityValue overloaded version of the method GetDeviceCapability() unless otherwise mentioned.

Enumerators

EHWRMHapticsDeviceCategory = 0

Device category. See THWRMHapticsDeviceCategory enumeration defined later in this API header for possible values.

EHWRMHapticsMaxNestedRepeats

The maximum number of nested repeat bars supported for Timeline effects.

Any repeat bars nested beyond this level are played only once.

EHWRMHapticsNumActuators

Number of vibration actuators present in the device.

EHWRMHapticsActuatorType

Actuator type See THWRMHapticsActuatorType enumeration defined later in this API header for possible values.

EHWRMHapticsNumEffectSlots

Number of effect slots.

The number of effect slots represents the maximum number of simple effects that can play simultaneously. If an attempt is made to play more than this number of effects at the same time, some of the simple effects do not play.

EHWRMHapticsSupportedStyles

Supported effect styles, stored as a bitfield. See THWRMHapticsSupportedEffectStyles enumeration defined later in this API header for possible values.

EHWRMHapticsMinPeriod

Minimum period for Periodic effects.

EHWRMHapticsMaxPeriod

Maximum period for Periodic effects.

EHWRMHapticsMaxEffectDuration

Maximum duration for MagSweep and Periodic effects measured in milliseconds.

EHWRMHapticsSupportedEffects

Supported effect types. Stored as a bitfield. See THWRMHapticsSupportedEffectTypes enumeration defined later in this API header for possible values.

EHWRMHapticsDeviceName

Device name.

Use TDes8 & aDeviceCapabilityValue overloaded version of the method GetDeviceCapability() .

EHWRMHapticsMaxEnvelopeTime

Maximum start time or fade time in milliseconds for effect envelopes of MagSweep or periodic effects.

EHWRMHapticsAPIVersionNumber

Version number of the physical haptics player in the device in hexadecimal format.

The format is OxMMNNSSBB, where MM is the major version number, NN is the minor version number, SS is a special build number and BB is the VTMP build number. For example, for the hexadecimal format 0x02000053 the version number is 2.0.83

EHWRMHapticsMaxEffectDataSize = 14

Maximum size in bytes of effect data (buffer) that can be played on a non-tethered device.

Enum THWRMHapticsDeviceCategory

Device category.

Enumerators

EHWRMHapticsVirtual = 2
EHWRMHapticsEmbedded = 3

Enum THWRMHapticsDevicePropertyTypes

THWRMHapticsDevicePropertyTypes enumeration Use SetDeviceProperty() to set properties for the haptics and GetDeviceProperty() to get properties currently in use.

Enumerators

EHWRMHapticsLicensekey = 0

License key property. Usable with SetDeviceProperty() only. Use const TDesC8 & overloaded version of the method.

Setting this property to a valid license key unlocks the haptics subsystem in the device. Setting this property to an invalid license key locks the haptics in the device (for this client). The haptics in the device are locked from clients by default. When haptics is locked, all haptics related operations on the device, except for setting the license key and closing the device, fail. Haptics must be unlocked on a per instance basis.

EHWRMHapticsPriority

Property used to set/get the priority for effects to played for the given haptics instance (i.e., for the given client).

Use TInt overloaded version of the methods SetDeviceProperty() and GetDeviceProperty() to use this property.

Different haptics instances can use different priorities on the same physical device. The priority determines which haptics instance's effects are played when multiple haptics instances are attempting to play effects at the same time. The default priority is DefaultDevicePriority() . Priority values can range from KHWRMHapticsMinDevicePriority to KHWRMHapticsMaxDevicePriority. GetDeviceProperty() returns a value inside TInt& aDevicePropertyValue in the range of KHWRMHapticsMinDevicePriority to KHWRMHapticsMaxDevicePriority. If the client has not set the EHWRMHapticsPriority property GetDeviceProperty() returns a value of DefaultDevicePriority() .

EHWRMHapticsDisableEffects

Property used to disable effects for the client's haptics instance.

Use TBool overloaded version of the methods SetDeviceProperty() and GetDeviceProperty() to use this property.

When this property is set to true, any playing effects are immediately stopped and subsequent requests to play effects are ignored. Applies to the calling client's haptics instance only. When this property is set to false, subsequent requests to play effects are honored. The default value for this property is false.

EHWRMHapticsStrength

A property that reduces/increases the magnitude of all effects for a particular haptics instance.

Use TInt overloaded version of the methods SetDeviceProperty() and GetDeviceProperty() to use this property.

Strength values can vary from KHWRMHapticsMinStrength ("mute") to KHWRMHapticsMaxStrength. The default value for EHWRMHapticsStrength is KHWRMHapticsMaxStrength. If the EHWRMHapticsStrength property is not set, the default value is used. When reducing/increasing the magnitude of the effects by setting the EHWRMHapticsStrength property, it only applies to the haptics instance of the client which called the function. If there is a second haptics instance held by the same or a different client, it is not affected by the setting of the EHWRMHapticsStrength property of the first client's haptics instance.

Modifying the EHWRMHapticsStrength property of the haptics instance does not affect currently playing effects, only effects played or modified after calling the SetDeviceProperty() method using the new EHWRMHapticsStrength value.

EHWRMHapticsMasterStrength

A property that reduces/increases the magnitude of all effects for all haptics instances (whole device).

Use TInt overloaded version of the methods SetDeviceProperty() and GetDeviceProperty() to use this property.

Strength values can vary from KHWRMHapticsMinStrength ("mute") to KHWRMHapticsMaxStrength. The default value for Master Strength is KHWRMHapticsMaxStrength. If the client does not set the EHWRMHapticsMasterStrength property of the haptics instance, the default value is used. When reducing/increasing the magnitude of the effects, EHWRMHapticsMasterStrength property affects all playing effects on all haptics instances (whole device). This means that all the haptics instances, held by other clients are affected by the setting of EHWRMHapticsMasterStrength property of the first client's haptics instance.

The client which wants to set the EHWRMHapticsMasterStrength property must have a haptics instance that has a maximum effect priority. The haptics client instance must set itself to a maximum priority by calling SetDeviceProperty() using EHWRMHapticsPriority property type and KMaxDevicePriority value before changing the EHWRMHapticsMasterStrength property's value.

Note: A licensee license key, provided to licensees only, changes the EHWRMHapticsMasterStrength property. A call to SetDeviceProperty( EHWRMHapticsMasterStrength, aValue ) always returns KErrAccessDenied for haptics instances that are not using a licensee license key.

Enum THWRMHapticsEffectStates

Effect states.

As returned in a call to GetEffectState() .

Enumerators

EHWRMHapticsEffectNotPlaying = 0
EHWRMHapticsEffectPlaying
EHWRMHapticsEffectPaused

Enum THWRMHapticsEffectStyles

Effect styles

Used to specify Periodic or MagSweep effect style when calling PlayMagSweepEffect() , PlayPeriodicEffect() , ModifyPlayingMagSweepEffect() and ModifyPlayingPeriodicEffect() .

Enumerators

EHWRMHapticsStyleSmooth = 0
EHWRMHapticsStyleStrong
EHWRMHapticsStyleSharp

Enum THWRMHapticsEffectTypes

Effect types

Enumerators

EHWRMHapticsTypePeriodic = 0
EHWRMHapticsTypeMagSweep
EHWRMHapticsTypeTimeline
EHWRMHapticsTypeStreaming

Enum THWRMHapticsSupportedEffectStyles

Bitmask for supported effect styles.

To be used to analyze the value returned by GetDeviceCapability() .

Enumerators

EHWRMHapticsSupportSmooth = 1
EHWRMHapticsSupportStrong = 2
EHWRMHapticsSupportSharp = 4

Enum THWRMHapticsSupportedEffectTypes

Bitmask for effect support.

To be used to analyze value returned by GetDeviceCapability() .

Enumerators

EHWRMHapticsSupportPeriodic = 1
EHWRMHapticsSupportMagSweep = 2
EHWRMHapticsSupportTimeline = 4
EHWRMHapticsSupportStreaming = 8