| 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 S60 5.1
| 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().
TInt KErrNone if successful, otherwise one of the other system-wide error codes.
S60 5.1
| TInt & aEffectHandle | Reference to the variable that receives a handle to the streaming effect. |
| TInt | DefaultDevicePriority | ( | ) | const [pure virtual] |
Gets the default device priority. Method may be used only after an actuator has been opened successfully.
TInt Default device property. KErrNotReady, if an actuator has not been opened.
| TInt | DeleteAllEffectData | ( | ) | [pure virtual] |
Delete all loaded effect datas.
TInt KErrNone if successful, otherwise one of the other system-wide error codes.
S60 5.1
| TInt | DeleteEffectData | ( | TInt | aFileHandle | ) | [pure virtual] |
Delete loaded effect data referenced by file handle.
TInt KErrNone if successful, otherwise one of the other system-wide error codes.
S60 5.1
| TInt aFileHandle | Handle to file. |
| TInt | DestroyStreamingEffect | ( | TInt | aEffectHandle | ) | [pure virtual] |
Destroys a streaming effect previously created in a successful call to CreateStreamingEffect().
TInt KErrNone if successful, otherwise one of the other system-wide error codes.
S60 5.1
| TInt aEffectHandle | Handle to the streaming effect to destroy. |
| TInt | GetDeviceCapability | ( | TInt | aDeviceCapabilityType, |
| TInt & | aDeviceCapabilityValue | |||
| ) | [pure virtual] | |||
Gets a capability value of the haptics.
TInt KErrNone if successful, KErrNotReady if no actuator has been opened, otherwise one of the other system-wide error codes.
THWRMHapticsDeviceCapabilityTypes
S60 5.1
| 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. TInt KErrNone if successful, KErrNotReady if no actuator has been opened, KErrArgument if the length of the given string is less than MaxCapabilityStringLength(), otherwise one of the other system-wide error codes.
| TInt | GetDeviceProperty | ( | TInt | aDevicePropertyType, |
| TInt & | aDevicePropertyValue | |||
| ) | [pure virtual] | |||
Gets a property value of the haptics.
TInt KErrNone if successful, otherwise one of the other system-wide error codes.
THWRMHapticsDevicePropertyTypes for a list of the valid property types.
S60 5.1
| 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. KErrNone if successful, KErrArgument if the length of the given string is less than MaxPropertyStringLength(), otherwise one of the other system-wide error codes.
| TInt | GetEffectCount | ( | TInt | aFileHandle, |
| TInt & | aCount | |||
| ) | const [pure virtual] | |||
Get a number of effects defined in a loaded effect data buffer.
TInt KErrNone if successful, otherwise one of the other system-wide error codes.
S60 5.1
| TInt | GetEffectDuration | ( | TInt | aFileHandle, |
| TInt | aEffectIndex, | |||
| TInt & | aEffectDuration | |||
| ) | const [pure virtual] | |||
Get the duration of an effect defined in a loaded effect data buffer.
TInt KErrNone if successful, otherwise one of the other system-wide error codes.
S60 5.1
| 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.
TInt KErrNone if successful, otherwise one of the other system-wide error codes.
S60 5.1
| TInt | GetEffectName | ( | TInt | aFileHandle, |
| TInt | aEffectIndex, | |||
| TDes8 & | aEffectName | |||
| ) | const [pure virtual] | |||
Gets the name of an effect defined in a loaded effect data buffer.
TInt KErrNone if successful, otherwise one of the other system-wide error codes.
S60 5.1
| 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(). |
| TInt | GetEffectState | ( | TInt | aEffectHandle, |
| TInt & | aEffectState | |||
| ) | [pure virtual] | |||
Retrieves the status of an effect (playing, not playing, paused).
TInt KErrNone if successful, otherwise one of the other system-wide error codes.
THWRMHapticsEffectStates for a list of valid effect states.
S60 5.1
| TInt | GetEffectType | ( | TInt | aFileHandle, |
| TInt | aEffectIndex, | |||
| TInt & | aEffectType | |||
| ) | const [pure virtual] | |||
Gets the type of an effect defined in loaded effect data buffer.
TInt KErrNone if successful, otherwise one of the other system-wide error codes.
S60 5.1
| 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.
TInt KErrNone if successful, otherwise one of the other system-wide error codes.
THWRMHapticsMagSweepEffect for effect definition.
S60 5.1
| 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. |
| 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.
TInt KErrNone if successful, otherwise one of the other system-wide error codes.
THWRMHapticsPeriodicEffect for effect definition.
S60 5.1
| 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. |
| MHWRMHapticsObserver::THWRMHapticsStatus | HapticsStatus | ( | ) | const [pure virtual] |
This method retrieves the current haptics status.
THWRMHapticsStatus indicating the current haptics status
THWRMHapticsStatus
| TInt | InfiniteDuration | ( | ) | const [pure virtual] |
Gets the value that represents infinite duration. Method may be used only after an actuator has been opened successfully.
TInt Value that represents infinite duration. KErrNotReady, if an actuator has not been opened.
| TInt | InfiniteRepeat | ( | ) | const [pure virtual] |
Gets the value that represents infinite repeats. Method may be used only after an actuator has been opened successfully.
TInt Value that represents infinite repeats. KErrNotReady, if an actuator has not been opened.
| 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).
TInt KErrNone if successful, otherwise one of the other system-wide error codes.
TInt KErrArgument if the effect data is invalid.
S60 5.1
| TInt | MaxCapabilityStringLength | ( | ) | const [pure virtual] |
Gets the maximum capability string length. Method may be used only after an actuator has been opened successfully.
TInt Maximum capability string length. KErrNotReady, if an actuator has not been opened.
| TInt | MaxDeviceNameLength | ( | ) | const [pure virtual] |
Gets the maximum device name length. Method may be used only after an actuator has been opened successfully.
TInt Maximum device name length. KErrNotReady, if an actuator has not been opened.
| 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.
TInt Maximum effect name length. KErrNotReady, if an actuator has not been opened.
| TInt | MaxPropertyStringLength | ( | ) | const [pure virtual] |
Gets the maximum property string length. Method may be used only after an actuator has been opened successfully.
TInt Maximum property string length. KErrNotReady, if an actuator has not been opened.
| TInt | MaxStreamingSampleSize | ( | ) | const [pure virtual] |
Gets the maximum streaming sample size. Method may be used only after an actuator has been opened successfully.
TInt Maximum streaming sample size. KErrNotReady, if an actuator has not been opened.
| 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.
TInt KErrNone if successful, otherwise one of the other system-wide error codes.
THWRMHapticsMagSweepEffect for effect definition.
S60 5.1
| 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. |
| 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.
| 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. |
| 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.
TInt KErrNone if successful, otherwise one of the other system-wide error codes.
THWRMHapticsPeriodicEffect for effect definition.
S60 5.1
| 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. |
| 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.
| 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. |
| IMPORT_C CHWRMHaptics * | NewL | ( | MHWRMHapticsObserver * | aHapticsCallback, |
| MHWRMHapticsActuatorObserver * | aActuatorCallback | |||
| ) | [static] | |||
Two-phased constructor. Use this method for creating a haptics instance with callbacks.
A pointer to a new instance of the CHWRMHaptics class.
S60 5.1
| MHWRMHapticsObserver * aHapticsCallback | Pointer to callback instance. Can be NULL. |
| MHWRMHapticsActuatorObserver * aActuatorCallback | Pointer to callback instance. Can be NULL. |
| 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.
| MHWRMHapticsObserver * aHapticsCallback | |
| MHWRMHapticsActuatorObserver * aActuatorCallback | |
| TRequestStatus & aStatus | Request status. On completion contains: KErrNone, if successful, otherwise one of the other system-wide error codes. |
| 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.
S60 5.1
| THWRMLogicalActuators aActuator | Enumeration of the type of logical actuator the client wants to use. |
| TInt | PausePlayingEffect | ( | TInt | aEffectHandle | ) | [pure virtual] |
Pauses a playing effect.
TInt KErrNone if successful, otherwise one of the other system-wide error codes.
S60 5.1
| 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(). |
| 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.
TInt KErrNone if successful, otherwise one of the other system-wide error codes.
TInt KErrInUse when haptics is reserved for a higher or equal priority client.
S60 5.1
| 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. |
| 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.
| 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. |
| 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.
TInt KErrNone if successful, otherwise one of the other system-wide error codes.
TInt KErrArgument if the data is invalid.
TInt KErrInUse when haptics is reserved for a higher or equal priority client.
S60 5.1
| 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. |
| 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.
| 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. |
| 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.
TInt KErrNone if successful, otherwise one of the other system-wide error codes.
TInt KErrInUse when haptics is reserved for a higher or equal priority client.
S60 5.1
| 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. |
| 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.
| 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. |
| 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.
TInt KErrNone if successful, otherwise one of the other system-wide error codes.
TInt KErrArgument if the data is invalid.
TInt KErrInUse when haptics is reserved for a higher or equal priority client.
S60 5.1
| 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. |
| 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.
| 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. |
| 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.
TInt KErrNone if successful, otherwise one of the other system-wide error codes.
TInt KErrInUse when haptics is reserved for a higher or equal priority client.
THWRMHapticsMagSweepEffect for effect definition.
S60 5.1
| 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. |
| 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.
| 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. |
| 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.
TInt KErrNone if successful, otherwise one of the other system-wide error codes.
TInt KErrInUse when haptics is reserved for a higher or equal priority client.
THWRMHapticsPeriodicEffect for effect definition.
S60 5.1
| 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. |
| 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.
| 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. |
| 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.
TInt KErrNone if successful, otherwise one of the other system-wide error codes.
TInt KErrInUse when haptics is reserved for a higher or equal priority client.
S60 5.1
| 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.
| 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. |
| 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.
TInt KErrNone if successful, otherwise one of the other system-wide error codes.
TInt KErrInUse when haptics is reserved for a higher or equal priority client.
S60 5.1
| 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. |
| 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.
| 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. |
| 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.
| 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.
| 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.
| 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. |
| 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.
TInt KErrNone if successful, otherwise one of the other system-wide error codes.
S60 5.1
| 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(). |
| 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.
TInt KErrNone if successful, otherwise one of the other system-wide error codes.
THWRMHapticsDevicePropertyTypes for a list of valid property types
S60 5.1
| 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.
| TInt | StopAllPlayingEffects | ( | ) | [pure virtual] |
Stops all playing and paused effects of a haptics instance.
TInt KErrNone if successful, otherwise one of the other system-wide error codes.
S60 5.1
| TInt | StopPlayingEffect | ( | TInt | aEffectHandle | ) | [pure virtual] |
Stops a playing effect.
TInt KErrNone if successful, otherwise one of the other system-wide error codes.
S60 5.1
| 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(). |
| 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.
TInt KErrNone, if successful, otherwise one of the other system-wide error codes.
THWRMLogicalActuators for a list of usable actuators.
S60 5.1
| TUint32 & aActuators | Bitmask of supported logical actuators. |
Actuator types.
To be used with GetDeviceCapability().
| EHWRMHapticsTypeERM = 0 |
Eccentric Rotating Mass actuator |
| EHWRMHapticsTypeLRA = 2 |
Linear Resonant actuator |
Device's capability types.
Use TInt& aDeviceCapabilityValue overloaded version of the method GetDeviceCapability() unless otherwise mentioned.
| 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. |
Device category.
| EHWRMHapticsVirtual = 2 | |
| EHWRMHapticsEmbedded = 3 |
THWRMHapticsDevicePropertyTypes enumeration Use SetDeviceProperty() to set properties for the haptics and GetDeviceProperty() to get properties currently in use.
| 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. |
Effect states.
As returned in a call to GetEffectState().
| EHWRMHapticsEffectNotPlaying = 0 | |
| EHWRMHapticsEffectPlaying | |
| EHWRMHapticsEffectPaused |
Effect styles
Used to specify Periodic or MagSweep effect style when calling PlayMagSweepEffect(), PlayPeriodicEffect(), ModifyPlayingMagSweepEffect() and ModifyPlayingPeriodicEffect().
| EHWRMHapticsStyleSmooth = 0 | |
| EHWRMHapticsStyleStrong | |
| EHWRMHapticsStyleSharp |
Effect types
| EHWRMHapticsTypePeriodic = 0 | |
| EHWRMHapticsTypeMagSweep | |
| EHWRMHapticsTypeTimeline | |
| EHWRMHapticsTypeStreaming |
Bitmask for supported effect styles.
To be used to analyze the value returned by GetDeviceCapability().
| EHWRMHapticsSupportSmooth = 1 | |
| EHWRMHapticsSupportStrong = 2 | |
| EHWRMHapticsSupportSharp = 4 |
Bitmask for effect support.
To be used to analyze value returned by GetDeviceCapability().
| EHWRMHapticsSupportPeriodic = 1 | |
| EHWRMHapticsSupportMagSweep = 2 | |
| EHWRMHapticsSupportTimeline = 4 | |
| EHWRMHapticsSupportStreaming = 8 |