Instantiating with and without observers

First the developer must create an instance of the haptics by calling the static NewL() method. The NewL() method takes pointers to MHWRMHapticsObserver and MHWRMHapticsActuatorObserver as arguments. These can be set to NULL if the developer does not want to observe haptics-related status change notifications.

              
               // CMyClass example myclass.h file
               

               

               #include <hwrmhaptics.h>
               

               

               

               class CMyClass : public MHWRMHapticsObserver, MHWRMHapticsActuatorObserver
               

                   {
               

                   public:
               

               

                       static CMyClass NewL();
               

                       ~CMyClass();
               

               

                   public:
               

               

                       /**
               

                        * Inherited from MHWRMHapticsObserver
               

                        */
               

               

                       /**
               

                        * Notification of status changes of the haptics feature itself
               

                        * such as e.g. EHWRMHapticsStatusOn or EHWRMHapticsStatusStopped
               

                        */
               

                       void HapticsStatusChangedL( THWRMHapticsStatus aStatus );
               

               

                   /**
               

                        * Notification of the completion of playing of an effect
               

                        */
               

                       void EffectCompletedL( TInt aError, TInt aEffectHandle );
               

               

                  public: 
               

               

                       /**
               

                        * Inherited from MHWRMHapticsActuatorObserver
               

                        */
               

               

                       /**
               

                        * Notification of logical actuator related event. Currently
               

                        * there are events defined for attaching an actuator, 
               

                        * detaching an actuator, and for enabling and disabling one
               

                        */
               

                       void ActuatorEventL( THWRMActuatorEvents aEvent, THWRMLogicalActuators aActuator );
               

               

                   private:
               

                     
               

                       CMyClass();
               

                       void ConstructL();
               

                       void InitializeActuatorL( const TDesC8& aLicenseKey );
               

               

                   private:
               

               

                       CHWRMHaptics* iHaptics;
               

                   };
               

               

               // ...
               

               

               // ------------------------------------------
               

               

               // CMyClass example *.cpp file
               

               

               #include "myclass.h"
               

               

               void CMyClass::ConstructL()
               

                   {
               

                   // Instantiating with no observers
               

                   iHaptics = CHWRMHaptics::NewL( NULL, NULL );
               

                   
               

                   // Example for instantiating with haptics status observer
               

                   CHWRMHaptics* haptics1 = CHWRMHaptics::NewL( this, NULL );
               

                   CleanupStack::PushL( haptics1 );
               

               

                   // Example for instantiating with both haptics status observer and actuator observer
               

                   CHWRMHaptics* haptics2 = CHWRMHaptics::NewL( this, this );
               

                   CleanupStack::PushL( haptics2 );
               

               

                   // ... 
               

               

                   CleanupStack::PopAndDestroy( haptics2 );
               

                   CleanupStack::PopAndDestroy( haptics1 );
               

                   }
              
             

• MHWRMHapticsActuatorObserver
• MHWRMHapticsObserver
• NULL
• NewL()

Checking supported logical actuators

Checking which logical actuators are supported in the device is done by calling the SupportedActuators() method. As a parameter, the method takes a reference to a TUint32 variable, which contains a bitmask of supported logical actuators. The bitmask is populated using THWRMLogicalActuators enumerations, and can be evaluated using bitwise operators with these enumerations. An example is shown below.

              
               ...
               

               

               // Variable for receiving the bitmask of logical actuators supported in the device.
               

               TUint32 suppActuators( 0 );
               

               

               User::LeaveIfError( iHaptics->SupportedActuators( suppActuators ) );
               

               

               // Check the returned bitmask against logical actuators enumerations
               

               // and choose the most suitable for the given application, e.g.
               

               if ( EHWRMLogicalActuatorGame & suppActuators )
               

                   {
               

                   // Open the most suitable supported actuator (see next section)
               

                   }
               

               else if ( EHWRMLogicalActuatorDevice & suppActuators )
               

                   {
               

                   // Open the second most suitable supported actuator 
               

                   }
               

               // etc.
              
             

• SupportedActuators()
• THWRMLogicalActuators
• TUint32

Opening a supported logical actuator

Opening the actuator is done by calling the OpenActuatorL() method. Immediately after opening an actuator, it is necessary to set a license key for the haptics in order to unlock the Haptics API's full functionality. The license key is set by calling the SetDeviceProperty() method for the EHWRMHapticsLicensekey property. The property value must be set to a platform-dependent license key issued by Forum Nokia.

              
               // Note: License keys are 32 bytes long data buffers of TUint8 data
               

               void CMyClass::InitializeActuatorL( const TDesC8& aLicenseKey )
               

                   {
               

                   // open a supported logical actuator
               

                   iHaptics->OpenActuatorL( EHWRMLogicalActuatorGame );
               

               

                   // set the license key for the opened logical actuator
               

                   TInt licenseErr( 0 );
               

                   licenseErr = iHaptics->SetDeviceProperty( CHWRMHaptics::EHWRMHapticsLicensekey, aLicenseKey );
               

               

                   if( licenseErr == KErrAccessDenied )
               

                       {
               

                       // the license key was wrong
               

                       }
               

                   }
              
             

• EHWRMHapticsLicensekey
• OpenActuatorL()
• SetDeviceProperty()

Checking the capabilities of a supported logical actuator

In some cases the application may need to enquire the capabilities of an actuator. For example, it needs to take specific actions depending on, e.g., such capabilities as the number of effect slots or the minimum period for periodic effects.

The capabilities of a supported logical actuator are checked by calling the GetDeviceCapability() method with one of the THWRMHapticsDeviceCapabilityTypes enumerations as the first parameter. A reference to a variable into which the returned capability value is to be stored is given as the second parameter. Depending on the capability in question, the returned capability value can be an integer or a descriptor containing an 8-bit data buffer. The GetDeviceCapability() method has overloaded versions where the second parameter is either a TInt& reference or a TDes8& reference.

              
               // Example: fetching the actuator's minimum period value and name
               

               TInt minPeriod( 0 ); // variable to receive the mimimun period for periodic effects
               

               User::LeaveIfError( iHaptics->GetDeviceCapability( CHWRMHaptics::EHWRMHapticsMinPeriod, minPeriod ) );
               

                   
               

               RBuf8 name;
               

               name.CreateL( iHaptics->MaxDeviceNameLength() );
               

               CleanupClosePushL( name );
               

               User::LeaveIfError( iHaptics->GetDeviceCapability( CHWRMHaptics::EHWRMHapticsDeviceName, name ) );
               

               

               // ... 
               

               

               CleanupStack::PopAndDestroy( &name );
              
             

• GetDeviceCapability()
• TDes8&
• THWRMHapticsDeviceCapabilityTypes
• TInt&

Checking and setting the haptics properties

The Haptics API provides means for getting and setting some of the haptics properties. The available properties are defined in the THWRMHapticsDevicePropertyType enumeration. These include such items as the already demonstrated license key, various strength and priority settings, and a setting that determines whether the effect playing is disabled or not. Successfully setting some of these can require a prior setting of the OEM license key. The example below shows how to get and set the strength property.

              
               // the actuator has been opened and the license key has been set successfully.
               

               

               TInt strength;
               

               User::LeaveIfError( iHaptics->GetDeviceProperty( CHWRMHaptics::EHWRMHapticsStrength, strength ) );
               

               

               // E.g., forcing the value to meet the threshold criteria.
               

               // This setting has an impact on all effects of this client
               

               if ( strength < 5000 )
               

                  {
               

                  User::LeaveIfError( iHaptics->SetDeviceProperty( CHWRMHaptics::EHWRMHapticsStrength, 5000 ) );
               

                  }
              
             

• THWRMHapticsDevicePropertyType

Reserving haptics

The Haptics API allows a client to exclusively reserve the haptics feature. This may be feasible, e.g., in game applications where the haptic effects from other sources than the game itself may be undesirable. It is possible for a higher priority client application to override previous reservation made by a lower priority application. This new reservation suspends the current reservation until the higher priority reservation is released.

Note: The suspension applies only to the use of the haptics feature, i.e., except for the haptics, the suspended application can continue its processing normally.

There are two kinds of reservations: one in which the foreground/background status of the application determines whether the reservation is applied, and one in which the reservation is forced and held by the reserving application regardless of its foreground/background status. Only trusted applications may reserve the haptics in the forced mode. The client application is considered trusted if it has a priority defined in the haptics policy file. The policy files can be modified by the Symbian device manufacturers.

              
               // Reserving the haptics
               

               TBool forcedReserve( EFalse );
               

               TRAPD( err, iHaptics->ReserveHapticsL( forcedReserve ) );
               

               if ( !err )
               

                  {
               

                  // haptics is now reserved for this application..
               

                  // ...
               

               

                  // Release the reservation
               

                  iHaptics->ReleaseHaptics(); // always succeeds 
               

                  }
              
             

Simple effects

There are two types of simple effects: magnitude sweep effects and period effects. Magnitude sweep effects vibrate at a magnitude and device-dependent constant rate (vibration frequency). Periodic effects allow the period of vibration (frequency) to be explicitly controlled independently of magnitude.

Both magnitude sweep and periodic effects have a set of envelope parameters that control the duration and strength of the vibration. They are defined in THWRMHapticsMagSweepEffect and THWRMHapticsPeriodicEffect structs. Effects can be formed at run-time by creating and filling in structs with effect-specific data, and then played by calling the PlayMagSweepEffect() and PlayPeriodicEffect() methods with the created structs as arguments. There are different effect styles (defined in THWRMHapticsEffectStyles enumeration) that have an impact on the feel of the effects.

The example below shows how magnitude sweep and periodic effects are formed and played. It also shows a couple of ways to stop playing effects before their defined playing duration expires.

              
               /**
               

               * Defining magnitude sweep effect parameters
               

               */
               

               

               CHWRMHaptics::THWRMHapticsMagSweepEffect magSweepEff;
               

                
               

               magSweepEff.iDuration = 5000;                // Duration of the effect in milliseconds.
               

               magSweepEff.iMagnitude = KHWRMHapticsMaxMagnitude/2;       // Magnitude, 50% of maximum
               

               magSweepEff.iStyle = CHWRMHaptics::EHWRMHapticsStyleSharp; // Style of the effect.
               

               

               magSweepEff.iAttackTime = 250;               // Time to ramp up from the level of magnitude defined
               

                                                            // in iAttackLevel to the magnitude defined in iMagnitude
               

                                                            // in the beginning of the effect.
               

               

               magSweepEff.iAttackLevel = KHWRMHapticsMaxMagnitude; // Attack level ranges from KHWRMHapticsMinMagnitude 
               

                                                                    // to KHWRMHapticsMaxMagnitude.
               

               

               magsWeepEff.iFadeTime = 250;                 // Time ramp down the effect to the level of magnitude 
               

                                                            // defined by iFadeLevel in the end of the effect.
               

               

               magsweepEff.iFadeLevel = 0;                  // Fade level of attack level ranges from KHWRMHapticsMinMagnitude 
               

                                                            // to KHWRMHapticsMaxMagnitude.
               

               

               /**
               

               * Playing a MagSweep effect and stopping it
               

               */
               

               

               // Variable whose reference is given as an argument to PlayMagSweepEffect. 
               

               // The reference is used to return handle for the playing effect.
               

               TInt magSweepHandle ( 0 );
               

               iHaptics->PlayMagSweepEffect( magSweepEff, magSweepHandle );
               

               

               // This delay is just an example. The effect is stopped after a delay
               

               TTimeIntervalMicroSeconds32 delay( 2000000 );
               

               User::After( delay );
               

               

               // Use the effect handle to define which effect to stop
               

               iHaptics->StopPlayingEffect( magSweepHandle );
               

               

               /**
               

               * Playing a Periodic effect and stopping all playing effects
               

               */
               

               

               CHWRMHaptics::THWRMHapticsPeriodicEffect periodicEff;
               

                
               

               // This example shows how to define infinite playing duration
               

               periodicEff.iDuration = iHaptics->InfiniteDuration();
               

               periodicEff.iMagnitude = KHWRMHapticsMaxMagnitude/4; // 25% of maximum
               

               // Struct for defining periodic effects has an extra data member that can be used 
               

               // to define the period of vibration in milliseconds.  
               

               periodicEff.iPeriod = 200;
               

               periodicEff.iStyle = CHWRMHaptics::EHWRMHapticsStyleSmooth;
               

               periodicEff.iAttackTime = 250;
               

               periodicEff.iAttackLevel = 0;
               

               periodicEff.iFadeTime = 250;
               

               periodicEff.iFadeLevel = 0;
               

               

               TInt periodicHandle( 0 );
               

               iHaptics->PlayPeriodicEffect( periodicEff, periodicHandle );
               

               

               TTimeIntervalMicroSeconds32 delay( 1000000 );
               

               User::After( delay );
               

               

               // There's a special API method for stopping all playing effects of
               

               // the client application. 
               

               iHaptics->StopAllPlayingEffects();
              
             

• PlayMagSweepEffect()
• PlayPeriodicEffect()
• THWRMHapticsEffectStyles
• THWRMHapticsMagSweepEffect
• THWRMHapticsPeriodicEffect

Modifying a currently playing simple effect

The Haptics API provides methods for modifying simple effects that are already playing. The parameters that are used to modify an effect are the same as those used to play the effect, except that the effect handle obtained from initially playing the effect is passed as an input argument to the modify method.

              
               /**
               

               * Playing a MagSweep effect and modifying it.
               

               */
               

               magSweepEff.iDuration = 6000;                        // duration in milliseconds
               

               magSweepEff.iMagnitude = KHWRMHapticsMaxMagnitude/5; // 20% magnitude of the max magnitude.
               

               

               TInt magSweepHandle( 0 );
               

               haptics->PlayMagSweepEffect( magSweepEff, magSweepHandle );
               

               

               // this delay is just an example
               

               // effect duration was 6 secs, so wait 2 secs to allow the effect to start playing
               

               TTimeIntervalMicroSeconds32 delay( 2000000 ); 
               

               User::After( delay );
               

               

               magSweepEff.iMagnitude = KHWRMHapticsMaxMagnitude/2; // change the magnitude of the effect
               

               

               User::LeaveIfError( haptics->ModifyPlayingMagSweepEffect( magSweepHandle, magSweepEff ) );
              
             

Streaming effects

The streaming effect functionality is designed for using haptics with streaming media applications. When using the streaming functionality, the application periodically supplies small samples of effect data to be rendered by calling the PlayStreamingSample() method. Streaming effects allow for proper multimedia synchronization over arbitrary time spans.

              
               /**
               

               * Creating a streaming effect, playing streaming samples
               

               * and destroying a streaming effect
               

               */
               

               

               // Variable whose reference is given as an argument to CreateStreamingEffect.
               

               // The reference is used to return a handle to the created streaming effect.
               

               TInt streamingHandle( 0 );
               

               User::LeaveIfError( iHaptics->CreateStreamingEffect( streamingHandle ) );
               

               

               ...
               

               

               // Example of a function that gets called when a new streaming sample is ready.
               

               void StreamingDataUpdated( const TDesC8& aData, TInt aStreamingHandle )
               

                   {
               

                   // PlayStreamingSample method is called with the handle obtained from creation of
               

                   // the streaming effect above and with the new data sample
               

                   iHaptics->PlayStreamingSample( aStreamingHandle, aData );
               

                   }
               

               

               ...
               

               

               // Eventually the streaming effect should be destroyed to release any reserved resources.
               

               iHaptics->DestroyStreamingEffect( streamingHandle );
              
             

• PlayStreamingSample()

Effect data buffers

The Haptics API provides methods for playing effects defined in effect data buffers. An effect data buffer is a binary buffer that contains effect definitions and additional metadata relating to those effects. The buffer can contain just simple effects or simple effects and timeline effects that are constructed from those simple effects scheduled over time.

Effect data buffers provide an alternative way of defining simple effects, besides using the Haptics API methods to programmatically create haptic effects with parameter values. The Haptics API does not provide functions to explicitly define timeline effects. Therefore the effect data buffers are the only way to present timeline effects to the Haptics API.

There are two ways to play effects from effect data buffers. Either by directly calling a PlayEffect() variant that takes as an argument a descriptor containing the data, or by first loading the data buffer to the Haptics system ( LoadEffectFile() ) and then using a variant of PlayEffect() that does not take the data buffer as an argument but instead uses the previously loaded data. The call to LoadEffectFile() returns a file handle to the caller. The handle is then given as an argument to the play method, thus allowing the haptics system to distinguish from which loaded effect data buffer to play the effect. The example below shows both of these alternatives. Note that it is possible to load data from several data buffers into the Haptics system. The file handles returned from the LoadEffectData() call are used to distinguish between the effects defined in different loaded buffers.

Once the data from an effect data buffer has been loaded into the Haptics system, there are methods for enquiring various attributes of the effects contained within the loaded data. The GetEffectCount() method returns the number of individual effects within the data. GetEffectType() , GetEffectDuration() and GetEffectName() methods are used (with index of the effect given as an argument) to get effect-specific information. For magnitude sweep and periodic effects, it is possible to get the whole effect definition by calling GetMagSweepEffectDefinition() or GetPeriodicEffectDefinition() . There is also a useful GetEffectIndexFromName() method that can be used to get the index of an effect within the effect data buffer from the effect's name as shown in the example below.

              
               /**
               

               * Preparing to use an effect file.
               

               */
               

               

               RFs fs;
               

               CleanupClosePushL( fs );
               

               User::LeaveIfError( fs.Connect() );
               

               _LIT( KPathToEffectDataFolder, "C://SomePathTo//EffectDataFolder//" );
               

               fs.SetSessionPath( KPathToEffectDataFolder );
               

               

               RFile file;
               

               CleanupClosePushL( file );
               

               _LIT( KFileName, "ExampleEffectsFile" );
               

               User::LeaveIfError( file.Open( fs, KFileName, EFileRead ) );
               

               

               TInt fileSize( 0 );
               

               User::LeaveIfError( file.Size( fileSize ) );
               

               

               HBufC8* dataBuffer = HBufC8::NewLC( fileSize );
               

               TPtr8 readBuf = dataBuffer->Des();
               

               User::LeaveIfError( file.Read( readBuf ) );
               

               

               /**
               

               * Load effect data buffer first. Then play an effect from it.
               

               */
               

               

               // A variable into which a handle for the loaded data is stored. A reference to
               

               // this variable is given as an argument to LoadEffectFile for the Haptics to assign.
               

               TInt fileHandle( 0 );
               

               User::LeaveIfError( iHaptics->LoadEffectFile( *dataBuffer, fileHandle ) );
               

               

               TInt effectIndex( 1 );  // index of the effect inside the data that we want to play;
               

               TInt effectHandle( 0 ); // variable to receive the effect handle of the playing effect
               

               

               iHaptics->PlayEffect( fileHandle, effectIndex, effectHandle );
               

               

               // Often the index of an individual effect inside the data is not known beforehand. It can be queried
               

               // using the effect's name
               

               _LIT( KEffectName, "ExampleEffect" );
               

               User::LeaveIfError( iHaptics->GetEffectIndexFromName( fileHandle, KEffectName, effectIndex ) );
               

               iHaptics->PlayEffect( fileHandle, effectIndex, effectHandle );
               

               

               /**
               

               * Effects can also be played directly (without first loading the effect data buffer to Haptics)
               

               * by giving a reference to a descriptor containing the data buffer as an argument.
               

               */
               

               

               iHaptics->PlayEffect( *dataBuffer, effectIndex, effectHandle );
               

               

               CleanupStack::PopAndDestroy( dataBuffer );
               

               CleanupStack::PopAndDestroy( &file );
               

               CleanupStack::PopAndDestroy( &fs );
               

               //...
               

               // Eventually the loaded data should be deleted to release reserved resources
               

               // Note: Actually the resources are released also when client closes the haptics
               

               iHaptics->DeleteEffectData( fileHandle ); // or iHaptics->DeleteAllEffectData() to delete all datas
               

                                                         // loaded by this application. 
              
             

Note: For timeline effects there is also a method called PlayEffectRepeat() that can be used to request repeated playing of an effect. The number of repeats is given as an argument. If a timeline effect needs to be repeated infinite times, the value returned from a call to the Haptics API's InfiniteRepeat() method must be used as a repeat argument. For other types of effects than timeline effects, the repeat method plays the effect just once (i.e., for non-timeline effects this is equivalent to the normal PlayEffect() method).

• GetEffectCount()
• GetEffectDuration()
• GetEffectIndexFromName()
• GetEffectName()
• GetEffectType()
• GetMagSweepEffectDefinition()
• GetPeriodicEffectDefinition()
• InfiniteRepeat()
• LoadEffectData()
• LoadEffectFile()
• PlayEffect()
• PlayEffectRepeat()

Pausing and resuming playing of effects

It is possible to pause an effect during its playing and then later resume the playing using the Haptics API's methods PausePlayingEffect() and ResumePausedEffect() respectively as shown in the example below. After resuming the previously paused effect, its playing is continued from the point where it was paused.

              
               // we have started the playing of a longish effect and have stored its handle to the effectHandle variable
               

               // First, pause the playing of the effect
               

               User::LeaveIfError( iHaptics->PausePlayingEffect( effectHandle ) );
               

               

               // Then, resume the playing
               

               User::LeaveIfError( iHaptics->ResumePausedEffect( effectHandle ) );
              
             

• PausePlayingEffect()
• ResumePausedEffect()