/*

 * Copyright (c) 2008 Nokia Corporation and/or its subsidiary(-ies). 

 * All rights reserved.

 * This component and the accompanying materials are made available

 * under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members

 * which accompanies this distribution, and is available

 * at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".

 *

 * Initial Contributors:

 * Nokia Corporation - initial contribution.

 *

 * Contributors:

 *

 * Description:  This file contains the header of the CHWRMHaptics class.

 *

 */

 #ifndef C_HWRMHAPTICS_H

 #define C_HWRMHAPTICS_H

 #include <e32base.h>

 #include <hwrmlogicalactuators.h>

 #include <hwrmhapticsobserver.h>

 #include <hwrmhapticsactuatorobserver.h>

 /** Minimum magnitude value. */

 const TInt KHWRMHapticsMinMagnitude = 0;

 /** Maximum magnitude value. */

 const TInt KHWRMHapticsMaxMagnitude = 10000;

 /**

 * Minimum device priority.

 *

 * To be used with SetDeviceProperty().

 */

 const TInt KHWRMHapticsMinDevicePriority = 0;

 /**

 * Maximum device priority.

 *

 * To be used with SetDeviceProperty().

 */

 const TInt KHWRMHapticsMaxDevicePriority = 15;

 /** Minimum strength value. */

 const TInt KHWRMHapticsMinStrength = 0;

 /** Maximum strength value. */

 const TInt KHWRMHapticsMaxStrength = 10000;

  /**

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

  *

  * @code

  *

  * // ===================================================================

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

  *

  * THWRMHapticsPeriodicEffect periodicEff;

  *

  * periodicEff.iDuration = 5000;

  * periodicEff.iMagnitude = 5000;

  * periodicEff.iPeriod = minPeriod;

  * periodicEff.iStyle = 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;

  *

  * @endcode

  *

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

  *

  * @lib hwrmhapticsclient.dll

  * @since S60 5.1

  */

  class CHWRMHaptics : public CBase

   {

 public:

     /**

     * Defines the paramaters used in a magsweep effect.

     *

     * Used by

     * PlayMagSweepEffect(),

     * ModifyPlayingMagSweepEffect(),

     * GetMagSweepEffectDefinition().

     */

     struct THWRMHapticsMagSweepEffect

         {

         /**

         * Duration of the effect. Unit is milliseconds.

         *

         * To specify an infinite duration, the effect duration

         * should be set to a value returned by InfiniteDuration().

         * For a finite duration, the effect duration is clamped to a value

         * from 0 to the value returned by GetDeviceCapability()

         * for the EHWRMHapticsMaxEffectDuration capability type.

         */

         TInt iDuration;

         /**

         * Magnitude of the effect.

         *

         * The effect magnitude is clamped to a value from 

         * KHWRMHapticsMinMagnitude to KHWRMHapticsMaxMagnitude.

         */

         TInt iMagnitude;

         /**

         * Style of the effect.

         *

         * Can be one of THWRMHapticsEffectStyles.

         */

         TInt iStyle;

         /**

         * Attack time of the effect. Unit is milliseconds.

         *

         * The attack time is clamped to a value from 0 to the value returned

         * by GetDeviceCapability() for the EHWRMHapticsMaxEnvelopeTime

         * capability type.

         */

         TInt iAttackTime;

         /**

         * Attack level of the effect.

         *

         * The attack level is clamped to a value from KHWRMHapticsMinMagnitude

         * to KHWRMHapticsMaxMagnitude.

         */

         TInt iAttackLevel;

         /**

         * Fade time of the effect. Unit is milliseconds.

         *

         * The fade time is clamped to a value from 0 to the value returned

         * by GetDeviceCapability() for the EHWRMHapticsMaxEnvelopeTime

         * capability type.

         */

         TInt iFadeTime;

         /**

         * Fade level of the effect.

         *

         * The fade level is clamped to a value from KHWRMHapticsMinMagnitude

         * to KHWRMHapticsMaxMagnitude inclusive.

         */

         TInt iFadeLevel;

         };

     /**

     * Defines the parameters used in a periodic effect.

     *

     * Used by

     * PlayPeriodicEffect(),

     * ModifyPlayingPeriodicEffect(),

     * GetPeriodicEffectDefinition().

     */

     struct THWRMHapticsPeriodicEffect

         {

         /**

         * Duration of the effect. Unit is milliseconds.

         *

         * To specify an infinite duration, the effect duration

         * should be set to InfiniteDuration().

         * For a finite duration, the effect duration is clamped to a value

         * from 0 to the value returned by GetDeviceCapability()

         * for the EHWRMHapticsMaxEffectDuration capability type.

         */

         TInt iDuration;

         /**

         * Magnitude of the effect.

         *

         * The effect magnitude is clamped to a value from

         * KHWRMHapticsMinMagnitude to KHWRMHapticsMaxMagnitude.

         */

         TInt iMagnitude;

         /**

         * Period of the effect. Unit is milliseconds.

         *

         * The period is clamped to a value returned by GetDeviceCapability()

         * for EHWRMHapticsMinPeriod capability type to the value returned

         * by GetDeviceCapability() for the EHWRMHapticsMaxEnvelopeTime

         * capability type.

         */

         TInt iPeriod;

         /**

         * Style of the effect.

         *

         * Can be one of THWRMHapticsEffectStyles.

         */

         TInt iStyle;

         /**

         * Attack time of the effect. Unit is milliseconds.

         *

         * The attack time is clamped to a value from 0 to the value returned

         * by GetDeviceCapability() for the EHWRMHapticsMaxEnvelopeTime

         * capability type.

         */

         TInt iAttackTime;

         /**

         * Attack level of the effect.

         *

         * The attack level is clamped to a value from KHWRMHapticsMinMagnitude

         * to KHWRMHapticsMaxMagnitude.

         */

         TInt iAttackLevel;

         /**

         * Fade time of the effect. Unit is milliseconds.

         *

         * The fade time is clamped to a value from 0 to the value returned

         * by GetDeviceCapability() for the EHWRMHapticsMaxEnvelopeTime

         * capability type.

         */

         TInt iFadeTime;

         /**

         * Fade level of the effect.

         *

         * The fade level is clamped to a value from KHWRMHapticsMinMagnitude

         * to KHWRMHapticsMaxMagnitude.

         */

         TInt iFadeLevel;

         };

     /**

     * THWRMHapticsDevicePropertyTypes enumeration

     * Use SetDeviceProperty() to set properties for the haptics

     * and GetDeviceProperty() to get properties currently in use.

     */

     enum THWRMHapticsDevicePropertyTypes

         {

         /**

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

         */

         EHWRMHapticsLicensekey = 0,

         /**

         * 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().

         */

         EHWRMHapticsPriority,

         /**

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

         */

         EHWRMHapticsDisableEffects,

         /**

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

         */

         EHWRMHapticsStrength,

         /**

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

         */

         EHWRMHapticsMasterStrength

         };

     /**

     * Device's capability types.

     *

     * Use TInt& aDeviceCapabilityValue overloaded version of the

     * method GetDeviceCapability() unless otherwise mentioned.

     */

     enum THWRMHapticsDeviceCapabilityTypes

         {

         /**

         * Device category. See THWRMHapticsDeviceCategory enumeration defined

         * later in this API header for possible values.

         */

         EHWRMHapticsDeviceCategory = 0,

         /**

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

         *

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

         */

         EHWRMHapticsMaxNestedRepeats,

         /**

         * Number of vibration actuators present in the device.

         */

         EHWRMHapticsNumActuators,

         /**

         * Actuator type See THWRMHapticsActuatorType enumeration defined

         * later in this API header for possible values.

         */

         EHWRMHapticsActuatorType,

         /**

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

         */

         EHWRMHapticsNumEffectSlots,

         /**

         * Supported effect styles, stored as a bitfield. See

         * THWRMHapticsSupportedEffectStyles enumeration defined later in this

         * API header for possible values.

         */

         EHWRMHapticsSupportedStyles,

         /**

         * Minimum period for Periodic effects.

         */

         EHWRMHapticsMinPeriod,

         /**

         * Maximum period for Periodic effects.

         */

         EHWRMHapticsMaxPeriod,

         /**

         * Maximum duration for MagSweep and Periodic effects measured

         * in milliseconds.

         */

         EHWRMHapticsMaxEffectDuration,

         /**

         * Supported effect types. Stored as a bitfield. See 

         * THWRMHapticsSupportedEffectTypes enumeration defined later in this

         * API header for possible values.

         */

         EHWRMHapticsSupportedEffects,

         /**

         * Device name.

         *

         * Use TDes8& aDeviceCapabilityValue overloaded version of the

         * method GetDeviceCapability().

         */

         EHWRMHapticsDeviceName,

         /**

         * Maximum start time or fade time in milliseconds for

         * effect envelopes of MagSweep or periodic effects.

         */

         EHWRMHapticsMaxEnvelopeTime,

         /**

         * 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

         */

         EHWRMHapticsAPIVersionNumber,

         /**

         * Maximum size in bytes of effect data (buffer) that can be played

         * on a non-tethered device. 

         */

         EHWRMHapticsMaxEffectDataSize = 14

         };

     /**

     * Device category.

     */

     enum THWRMHapticsDeviceCategory

         {

         EHWRMHapticsVirtual = 2,

         EHWRMHapticsEmbedded = 3,

         };

     /**

     * Bitmask for effect support.

     *

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

     */

     enum THWRMHapticsSupportedEffectTypes

         {

         EHWRMHapticsSupportPeriodic = 1,

         EHWRMHapticsSupportMagSweep = 2,

         EHWRMHapticsSupportTimeline = 4,

         EHWRMHapticsSupportStreaming = 8

         };

     /**

     * Effect types

     */

     enum THWRMHapticsEffectTypes

         {

         EHWRMHapticsTypePeriodic = 0,

         EHWRMHapticsTypeMagSweep,

         EHWRMHapticsTypeTimeline,

         EHWRMHapticsTypeStreaming

         };

     /**

     * Bitmask for supported effect styles.

     *

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

     */

     enum THWRMHapticsSupportedEffectStyles

         {

         EHWRMHapticsSupportSmooth = 1,

         EHWRMHapticsSupportStrong = 2,

         EHWRMHapticsSupportSharp  = 4

         };

     /**

     * Effect styles

     *

     * Used to specify Periodic or MagSweep effect style when calling

     * PlayMagSweepEffect(),

     * PlayPeriodicEffect(),

     * ModifyPlayingMagSweepEffect() and

     * ModifyPlayingPeriodicEffect().

     */

     enum THWRMHapticsEffectStyles

         {

         EHWRMHapticsStyleSmooth = 0,

         EHWRMHapticsStyleStrong,

         EHWRMHapticsStyleSharp

         };

     /**

     * Actuator types.

     *

     * To be used with GetDeviceCapability().

     */

     enum THWRMHapticsActuatorTypes

         {

         /**

         * Eccentric Rotating Mass actuator

         */

         EHWRMHapticsTypeERM = 0,

         /**

         * Linear Resonant actuator

         */

         EHWRMHapticsTypeLRA = 2

         };

     /**

     * Effect states.

     *

     * As returned in a call to GetEffectState().

     */

     enum THWRMHapticsEffectStates

         {

         EHWRMHapticsEffectNotPlaying = 0,

         EHWRMHapticsEffectPlaying,

         EHWRMHapticsEffectPaused

         };

     /**

     * Two-phased constructor.

     * Use this method for creating a haptics instance with callbacks.

     *

     * @param aHapticsCallback Pointer to callback instance. Can be NULL.

     * @param aActuatorCallback Pointer to callback instance. Can be NULL.

     *

     * @return A pointer to a new instance of the CHWRMHaptics class.

     *

     * @since S60 5.1

     */

     IMPORT_C static CHWRMHaptics* NewL( 

         MHWRMHapticsObserver* aHapticsCallback,

         MHWRMHapticsActuatorObserver* aActuatorCallback );

     /**

     * @overload

     *

     * @param[out] aStatus Request status. On completion contains:

     *                     KErrNone, if successful,

     *                     otherwise one of the other system-wide error codes.

     */

     IMPORT_C static CHWRMHaptics* NewL( 

         MHWRMHapticsObserver* aHapticsCallback,

         MHWRMHapticsActuatorObserver* aActuatorCallback,

         TRequestStatus& aStatus );

     /**

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

     *

     * @param aActuator Enumeration of the type of logical actuator the client

     *                  wants to use.

     *

     * @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.

     *

     * @see THWRMLogicalActuators for a list of usable actuators.

     *

     * @since S60 5.1

     */

     virtual void OpenActuatorL( THWRMLogicalActuators aActuator ) = 0;

     /**

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

     *

     * @param[out] aActuators Bitmask of supported logical actuators.

     *

     * @return TInt KErrNone, if successful, otherwise one of the other

     *              system-wide error codes.

     *

     * @see THWRMLogicalActuators for a list of usable actuators.

     *

     * @since S60 5.1

     */

     virtual TInt SupportedActuators( TUint32& aActuators ) = 0;

     /**

     * 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. CCoeEnv background/foreground status is always used

     * to control further reservations.

     */

     virtual void ReserveHapticsL() = 0;

     /**

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

     *

     * @param aForceNoCCoeEnv 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.

     *

     * @leave KErrAccessDenied Parameter aForceNoCCoeEnv is ETrue

     *                         and client is not trusted.

     * @leave KErrBadHandle Parameter aForceNoCCoeEnv is EFalse

     *                      and no CCoeEnv present.

     * @leave KErrNotReady Trying to reserve while on background and parameter

     *                     aForceNoCCoeEnv is EFalse.

     * @leave KErrNoMemory There is a memory allocation failure.

     */

     virtual void ReserveHapticsL( TBool aForceNoCCoeEnv ) = 0;

     /**

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

     */

     virtual void ReleaseHaptics() = 0;

     /**

     * This method retrieves the current haptics status.

     *

     * @return THWRMHapticsStatus indicating the current haptics status

     *

     * @see THWRMHapticsStatus

     */

     virtual MHWRMHapticsObserver::THWRMHapticsStatus HapticsStatus() const=0;

     /**

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

     *

     * @param[in] aDevicePropertyType Property type for the

     *            property to be set.

     * @param[in] aDevicePropertyValue Value of the property to set.

     *

     * @return TInt KErrNone if successful, otherwise one of the other

     *              system-wide error codes.

     *

     * @see THWRMHapticsDevicePropertyTypes for a list of valid property types

     *

     * @since S60 5.1

     */

     virtual TInt SetDeviceProperty( TInt aDevicePropertyType,

                                     TInt aDevicePropertyValue ) = 0;

     /**

     * @overload

     */

     virtual TInt SetDeviceProperty( TInt aDevicePropertyType,

                                     const TDesC8& aDevicePropertyValue ) = 0;

     /**

     * Gets a property value of the haptics.

     *

     * @param[in] aDevicePropertyType Property type for the property to get.

     * @param[out] aDevicePropertyValue Reference to the variable that 

     *                                  receives the requested property

     *                                  value of the device.

     *

     * @return TInt KErrNone if successful, otherwise one of the other

     *              system-wide error codes.

     *

     * @see THWRMHapticsDevicePropertyTypes for a list of the valid property

     *      types.

     *

     * @since S60 5.1

     */

     virtual TInt GetDeviceProperty( TInt aDevicePropertyType,

                                     TInt& aDevicePropertyValue ) = 0;

     /**

     * @overload

     *

     * @return KErrNone if successful, 

     *         KErrArgument if the length of the given string is less 

     *         than MaxPropertyStringLength(), 

     *         otherwise one of the other system-wide error codes.

     */

     virtual TInt GetDeviceProperty( TInt aDevicePropertyType,

                                     TDes8& aDevicePropertyValue ) = 0;

     /**

     * Gets a capability value of the haptics.

     *

     * @param[in] aDeviceCapabilityType Capability type of the

     *                                  capability to get.

     * @param[out] aDeviceCapabilityValue Reference to the variable that 

     *                                    receives the requested capability

     *                                    value of the device.

     *

     * @return TInt KErrNone if successful, 

     *              KErrNotReady if no actuator has been opened,

     *              otherwise one of the other system-wide error codes.

     *

     * @see THWRMHapticsDeviceCapabilityTypes

     *

     * @since S60 5.1

     */

     virtual TInt GetDeviceCapability( TInt aDeviceCapabilityType,

                                       TInt& aDeviceCapabilityValue ) = 0;

     /**

     * @overload

     * 

     * @return 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.

     */

     virtual TInt GetDeviceCapability( TInt aDeviceCapabilityType,

                                       TDes8& aDeviceCapabilityValue ) = 0;

     /**

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

     *

     * @param[in] aEffectHandle Handle to the effect which must have been

     *                          obtained by calling

     *                          PlayMagSweepEffect(),

     *                          PlayPeriodicEffect(),

     *                          PlayEffect(),

     *                          PlayEffectRepeat() or

     *                          CreateStreamingEffect()

     * @param[out] aEffectState Pointer to the variable that receives

     *                          the status bits of the effect.

     *

     * @return TInt KErrNone if successful, otherwise one of the other

     *              system-wide error codes.

     *

     * @see THWRMHapticsEffectStates for a list of valid effect states.

     *

     * @since S60 5.1

     */

     virtual TInt GetEffectState( TInt aEffectHandle, TInt& aEffectState ) = 0;

     /**

     * 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().

     *

     * @param[out] aEffectHandle Reference to the variable that receives

     *                           a handle to the streaming effect.

     *

     * @return TInt KErrNone if successful, otherwise one of the other

     *              system-wide error codes.

     *

     * @since S60 5.1

     */

     virtual TInt CreateStreamingEffect( TInt& aEffectHandle ) = 0;

     /**

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

     *

     * @param[in] aEffectHandle Handle to the streaming effect to play.

     * @param[in] aStreamingSample Reference to streaming sample data

     *                             containing the definition of

     *                             the effect to play.

     *

     * @return TInt KErrNone if successful, otherwise one of the other

     *              system-wide error codes.

     * @return TInt KErrInUse when haptics is reserved for a higher or 

     *              equal priority client.

     *

     * @since S60 5.1

     */

     virtual TInt PlayStreamingSample( TInt aEffectHandle,

                                       const TDesC8& aStreamingSample ) = 0;

     /**

     * @overload

     *

     * @param[out] 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.

     */

     virtual void PlayStreamingSample( TInt aEffectHandle,

                                       const TDesC8& aStreamingSample,

                                       TRequestStatus& aStatus ) = 0;

     /**

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

     *

     * @param[in] aEffectHandle Handle to the streaming effect to play.

     * @param[in] aStreamingSample Reference to streaming sample data

     *                             containing the definition of the

     *                             effect to play.

     * @param[in] 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.

     *

     * @return TInt KErrNone if successful, otherwise one of the other

     *              system-wide error codes.

     * @return TInt KErrInUse when haptics is reserved for a higher or 

     *              equal priority client.

     *

     * @since S60 5.1

     */

     virtual TInt PlayStreamingSampleWithOffset( TInt aEffectHandle,

         const TDesC8& aStreamingSample,

         TInt aOffsetTime ) = 0;

     /**

     * @overload

     *

     * @param[out] 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.

     */

     virtual void PlayStreamingSampleWithOffset( TInt aEffectHandle,

         const TDesC8& aStreamingSample,

         TInt aOffsetTime,

         TRequestStatus& aStatus ) = 0;

     /**

     * Destroys a streaming effect previously created in a successful

     * call to CreateStreamingEffect().

     *

     * @param[in] aEffectHandle Handle to the streaming effect to destroy.

     *

     * @return TInt KErrNone if successful, otherwise one of the other

     *              system-wide error codes.

     *

     * @since S60 5.1

     */

     virtual TInt DestroyStreamingEffect( TInt aEffectHandle ) = 0;

     /**

     * Modifies a playing MagSweep effect.

     *

     * Synchronous method returns when the haptic command has been evaluated

     * and the return value is valid.

     *

     * @param[in] aEffectHandle Handle to the playing MagSweep effect

     *                          to modify. The handle to the effect must have

     *                          been obtained by calling

     *                          PlayMagSweepEffect(),

     *                          PlayEffect() or

     *                          PlayEffectRepeat().

     * @param[in] aEffect Reference to a struct defining the effect parameters.

     *

     * @return TInt KErrNone if successful, otherwise one of the other

     *              system-wide error codes.

     *

     * @see THWRMHapticsMagSweepEffect for effect definition.

     *

     * @since S60 5.1

     */

     virtual TInt ModifyPlayingMagSweepEffect( TInt aEffectHandle,

         const CHWRMHaptics::THWRMHapticsMagSweepEffect& aEffect ) = 0;

     /**

     * @overload

     *

     * @param[out] aStatus Request status. On completion contains:

     *                     KErrNone, if successful,

     *                     otherwise one of the other system-wide error codes.

     */

     virtual void ModifyPlayingMagSweepEffect( TInt aEffectHandle,

         const CHWRMHaptics::THWRMHapticsMagSweepEffect& aEffect,

         TRequestStatus& aStatus ) = 0;

     /**

     * Modifies a playing periodic effect.

     *

     * Synchronous method returns when the haptic command has been evaluated

     * and the return value is valid.

     *

     * @param[in] aEffectHandle Handle to the playing periodic effect

     *                          to modify. The handle to the effect must have

     *                          been obtained by calling

     *                          PlayPeriodicEffect(),

     *                          PlayEffect() or

     *                          PlayEffectRepeat().

     * @param[in] aEffect Reference to a struct defining the effect parameters.

     *

     * @return TInt KErrNone if successful, otherwise one of the other

     *              system-wide error codes.

     *

     * @see THWRMHapticsPeriodicEffect for effect definition.

     *

     * @since S60 5.1

     */

     virtual TInt ModifyPlayingPeriodicEffect( TInt aEffectHandle,

         const CHWRMHaptics::THWRMHapticsPeriodicEffect& aEffect ) = 0;

     /**

     * @overload

     *

     * @param[out] aStatus Request status. On completion contains:

     *                     KErrNone, if successful,

     *                     otherwise one of the other system-wide error codes.

     */

     virtual void ModifyPlayingPeriodicEffect( TInt aEffectHandle,

         const CHWRMHaptics::THWRMHapticsPeriodicEffect& aEffect,

         TRequestStatus& aStatus ) = 0;

     /**

     * Load effect data defined in effect data buffer (obtained e.g. from a

     * file containing the effect data).

     *

     * @param[in] aData Reference to allocated effect data buffer.

     *

     * @param[out] 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.

     *

     * @return TInt KErrNone if successful, otherwise one of the other

     *              system-wide error codes.

     * @return TInt KErrArgument if the effect data is invalid.

     *

     * @since S60 5.1

     */

     virtual TInt LoadEffectData( const TDesC8& aData, TInt& aFileHandle ) = 0;

     /**

     * Delete loaded effect data referenced by file handle.

     *

     * @param[in] aFileHandle Handle to file.

     *

     * @return TInt KErrNone if successful, otherwise one of the other

     *              system-wide error codes.

     *

     * @since S60 5.1

     */

     virtual TInt DeleteEffectData( TInt aFileHandle ) = 0;

     /**

     * Delete all loaded effect datas.

     *

     * @return TInt KErrNone if successful, otherwise one of the other

     *              system-wide error codes.

     *

     * @since S60 5.1

     */

     virtual TInt DeleteAllEffectData() = 0;

     /**

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

     *

     * @param[in] aFileHandle Handle to the loaded effect data.

     *

     * @param[in] 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().

     * @param[out] aEffectHandle Reference to the variable that receives

     *                           a handle to the playing effect.

     *

     * @return TInt KErrNone if successful, otherwise one of the other

     *              system-wide error codes.

     * @return TInt KErrInUse when haptics is reserved for a higher or 

     *              equal priority client.

     *

     * @since S60 5.1

     */

     virtual TInt PlayEffect( TInt aFileHandle, 

                              TInt aEffectIndex, 

                              TInt& aEffectHandle ) = 0;

     /**

     * @overload

     *

     * @param[out] 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.

     */

     virtual void PlayEffect( TInt aFileHandle,

                              TInt aEffectIndex,

                              TInt& aEffectHandle,

                              TRequestStatus& aStatus ) = 0;

     /**

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

     *

     * @param[in] aFileHandle Handle to the loaded effect data.

     * @param[in] 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().

     * @param[in] 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()

     * @param[out] aEffectHandle Reference to the variable that receives

     *                           a handle to the playing effect.

     *

     * @return TInt KErrNone if successful, otherwise one of the other

     *              system-wide error codes.

     * @return TInt KErrInUse when haptics is reserved for a higher or 

     *              equal priority client.

     *

     * @since S60 5.1

     */

     virtual TInt PlayEffectRepeat( TInt aFileHandle,

                                    TInt aEffectIndex,

                                    TUint8 aRepeat,

                                    TInt& aEffectHandle ) = 0;

     /**

     * @overload

     *

     * @param[out] 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.

     */

     virtual void PlayEffectRepeat( TInt  aFileHandle,

                                    TInt aEffectIndex,

                                    TUint8 aRepeat,

                                    TInt& aEffectHandle,

                                    TRequestStatus& aStatus ) = 0;

     /**

     * Plays an effect defined in effect data buffer.

     *

     * Synchronous method returns when the haptic command has been evaluated

     * and the return value is valid.

     *

     * @param[in] aData Reference to effect data buffer containing the 

     *                  definition of the effect to play.

     * @param[in] 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().

     * @param[out] aEffectHandle Reference to the variable that receives

     *                           a handle to the playing effect.

     *

     * @return TInt KErrNone if successful, otherwise one of the other

     *              system-wide error codes.

     * @return TInt KErrArgument if the data is invalid.

     * @return TInt KErrInUse when haptics is reserved for a higher or 

     *              equal priority client.

     *

     * @since S60 5.1

     */

     virtual TInt PlayEffect( const TDesC8& aData,

                              TInt aEffectIndex,

                              TInt& aEffectHandle ) = 0;

     /**

     * @overload

     *

     * @param[out] 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.

     */

     virtual void PlayEffect( const TDesC8& aData,

                              TInt aEffectIndex,

                              TInt& aEffectHandle,

                              TRequestStatus& aStatus ) = 0;

     /**

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

     *

     * @param[in] aData Reference to effect data buffer containing the

     *                  definition of the effect to play.

     * @param[in] 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().

     * @param[in] 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()

     * @param[out] aEffectHandle Reference to the variable that receives

     *                           a handle to the playing effect.

     *

     * @return TInt KErrNone if successful, otherwise one of the other

     *              system-wide error codes.

     * @return TInt KErrArgument if the data is invalid.

     * @return TInt KErrInUse when haptics is reserved for a higher or 

     *              equal priority client.

     *

     * @since S60 5.1

     */

     virtual TInt PlayEffectRepeat( const TDesC8& aData,

                                    TInt aEffectIndex,

                                    TUint8 aRepeat,

                                    TInt& aEffectHandle )=0;

     /**

     * @overload

     *

     * @param[out] 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.

     */

     virtual void PlayEffectRepeat( const TDesC8& aData,

                                    TInt aEffectIndex,

                                    TUint8 aRepeat,

                                    TInt& aEffectHandle,

                                    TRequestStatus& aStatus )=0;

     /**

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

     *

     * @param[in] aEffect Reference to a struct defining the effect parameters.

     * @param[out] aEffectHandle Reference to the variable that receives

     *                           a handle to the playing effect.

     *

     * @return TInt KErrNone if successful, otherwise one of the other

     *              system-wide error codes.

     * @return TInt KErrInUse when haptics is reserved for a higher or 

     *              equal priority client.

     *

     * @see THWRMHapticsMagSweepEffect for effect definition.

     *

     * @since S60 5.1

     */

     virtual TInt PlayMagSweepEffect(

         const CHWRMHaptics::THWRMHapticsMagSweepEffect& aEffect,

         TInt& aEffectHandle ) = 0;

     /**

     * @overload

     *

     * @param[out] 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.

     */

     virtual void PlayMagSweepEffect(

         const CHWRMHaptics::THWRMHapticsMagSweepEffect& aEffect,

         TInt& aEffectHandle,

         TRequestStatus& aStatus ) = 0;

     /**

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

     *

     * @param[in] aEffect Reference to a struct defining the effect parameters.

     * @param[out] aEffectHandle Reference to the variable that receives

     *                           a handle to the playing effect.

     *

     * @return TInt KErrNone if successful, otherwise one of the other

     *              system-wide error codes.

     * @return TInt KErrInUse when haptics is reserved for a higher or 

     *              equal priority client.

     *

     * @see THWRMHapticsPeriodicEffect for effect definition.

     *

     * @since S60 5.1

     */

     virtual TInt PlayPeriodicEffect(

         const CHWRMHaptics::THWRMHapticsPeriodicEffect& aEffect,

         TInt& aEffectHandle ) = 0;

     /**

     * @overload

     *

     * @param[out] 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.

     */

     virtual void PlayPeriodicEffect(

         const CHWRMHaptics::THWRMHapticsPeriodicEffect& aEffect,

         TInt& aEffectHandle,

         TRequestStatus& aStatus ) = 0;

     /**

     * Pauses a playing effect.

     *

     * @param[in] 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().

     *

     * @return TInt KErrNone if successful, otherwise one of the other

     *              system-wide error codes.

     *

     * @since S60 5.1

     */

      virtual TInt PausePlayingEffect( TInt aEffectHandle ) = 0;

     /**

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

     *

     * @param[in] 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().

     *

     * @return TInt KErrNone if successful, otherwise one of the other

     *              system-wide error codes.

     *

     * @since S60 5.1

     */

     virtual TInt ResumePausedEffect( TInt aEffectHandle ) = 0;

     /**

     * Stops a playing effect.

     *

     * @param[in] 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().

     *

     * @return TInt KErrNone if successful, otherwise one of the other

     *              system-wide error codes.

     *

     * @since S60 5.1

     */

     virtual TInt StopPlayingEffect( TInt aEffectHandle ) = 0;

     /**

     * Stops all playing and paused effects of a haptics instance.

     *

     * @return TInt KErrNone if successful, otherwise one of the other

     *              system-wide error codes.

     *

     * @since S60 5.1

     */

     virtual TInt StopAllPlayingEffects() = 0;

     /**

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

     *

     * @param[in] aFileHandle Handle to the loaded effect data buffer.

     * @param[out] aCount Number of effects in the effect data buffer.

     *

     * @return TInt KErrNone if successful, otherwise one of the other

     *              system-wide error codes.

     *

     * @since S60 5.1

     */

     virtual TInt GetEffectCount ( TInt aFileHandle,

                                   TInt& aCount ) const = 0;

     /**

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

     *

     * @param[in] aFileHandle Handle to the loaded effect data buffer.

     * @param[in] aEffectIndex Effect for which the duration is wanted.

     * @param[out] aEffectDuration Reference to the variable that receives

     *                             the requested effect's duration value.

     *                             Duration is in milliseconds.

     *

     * @return TInt KErrNone if successful, otherwise one of the other

     *              system-wide error codes.

     * @since S60 5.1

     */

     virtual TInt GetEffectDuration ( TInt aFileHandle,

                                      TInt aEffectIndex,

                                      TInt& aEffectDuration ) const = 0;

     /**

     * Gets the index of an effect defined in a loaded effect data buffer

     * from the name of the effect.

     *

     * @param[in] aFileHandle Handle to the loaded effect data buffer.

     * @param[in] aEffectName Name of the effect for which the index is wanted.

     * @param[out] aEffectIndex Reference to the variable that receives

     *             the requested effect's index value.

     *

     * @return TInt KErrNone if successful, otherwise one of the other

     *              system-wide error codes.

     *

     * @since S60 5.1

     */

     virtual TInt GetEffectIndexFromName ( TInt aFileHandle,

                                           const TDesC8& aEffectName,

                                           TInt& aEffectIndex ) const = 0;

     /**

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

     *

     * @param[in] aFileHandle Handle to loaded effect data buffer.

     * @param[in] aEffectIndex Index of an effect for which a type is wanted.

     * @param[out] aEffectType Reference to the variable that receives

     *                         the requested effect's type value.

     *

     * @return TInt KErrNone if successful, otherwise one of the other

     *              system-wide error codes.

     *

     * @since S60 5.1

     */

     virtual TInt GetEffectType( TInt aFileHandle,

                                 TInt aEffectIndex,

                                 TInt& aEffectType ) const = 0;

     /**

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

     *

     * @param[in] aFileHandle Handle to the loaded effect data buffer.

     * @param[in] aEffectIndex Index of an effect for which a name is wanted.

     * @param[out] 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().

     *

     * @return TInt KErrNone if successful, otherwise one of the other

     *              system-wide error codes.

     *

     * @since S60 5.1

     */

     virtual TInt GetEffectName( TInt aFileHandle,

                                 TInt aEffectIndex,

                                 TDes8& aEffectName ) const = 0;

     /**

     * Gets the parameters of a MagSweep effect defined in a loaded effect data

     * buffer.

     *

     * @param[in] aFileHandle Handle to the loaded effect data buffer.

     * @param[in] aEffectIndex Index of an effect for which a definition is

     *                         wanted.

     * @param[out] aEffect Reference to the variable that receives

     *                     the effect definition.

     *

     * @return TInt KErrNone if successful, otherwise one of the other

     *              system-wide error codes.

     *

     * @see THWRMHapticsMagSweepEffect for effect definition.

     *

     * @since S60 5.1

     */

     virtual TInt GetMagSweepEffectDefinition( 

         TInt aFileHandle,

         TInt aEffectIndex,

         CHWRMHaptics::THWRMHapticsMagSweepEffect& aEffect ) const = 0;

     /**

     * Gets the parameters of a periodic effect defined in a loaded effect data

     * buffer.

     *

     * @param[in] aFileHandle Handle to the loaded effect data buffer.

     * @param[in] aEffectIndex Index of an effect for which a definition is wanted.

     * @param[out] aEffect Reference to the variable that receives

     *                     the effect definition.

     *

     * @return TInt KErrNone if successful, otherwise one of the other

     *              system-wide error codes.

     *

     * @see THWRMHapticsPeriodicEffect for effect definition.

     *

     * @since S60 5.1

     */

     virtual TInt GetPeriodicEffectDefinition( 

         TInt aFileHandle,

         TInt aEffectIndex,

         CHWRMHaptics::THWRMHapticsPeriodicEffect& aEffect ) const = 0;

     /**

     * Gets the value that represents infinite repeats. Method may be used

     * only after an actuator has been opened successfully.

     *

     * @return TInt Value that represents infinite repeats. KErrNotReady, if

     * an actuator has not been opened.

     */

     virtual TInt InfiniteRepeat() const = 0;

     /**

     * Gets the value that represents infinite duration. Method may be used

     * only after an actuator has been opened successfully.

     *

     * @return TInt Value that represents infinite duration. KErrNotReady, if

     * an actuator has not been opened.

     */

     virtual TInt InfiniteDuration() const = 0;

     /**

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

     *

     * @return TInt Maximum effect name length. KErrNotReady, if

     * an actuator has not been opened.

     */

     virtual TInt MaxEffectNameLength() const = 0;

     /** 

     * Gets the maximum device name length.  Method may be used

     * only after an actuator has been opened successfully.

     *

     * @return TInt Maximum device name length. KErrNotReady, if

     * an actuator has not been opened.

     */

     virtual TInt MaxDeviceNameLength() const = 0;

     /**

     * Gets the maximum capability string length. Method may be used

     * only after an actuator has been opened successfully.

     *

     * @return TInt Maximum capability string length. KErrNotReady, if

     * an actuator has not been opened.

     */

     virtual TInt MaxCapabilityStringLength() const = 0;

     /**

     * Gets the maximum property string length. Method may be used

     * only after an actuator has been opened successfully.

     *

     * @return TInt Maximum property string length. KErrNotReady, if

     * an actuator has not been opened.

     */

     virtual TInt MaxPropertyStringLength() const = 0;

     /**

     * Gets the maximum streaming sample size. Method may be used

     * only after an actuator has been opened successfully.

     *

     * @return TInt Maximum streaming sample size. KErrNotReady, if

     * an actuator has not been opened.

     */

     virtual TInt MaxStreamingSampleSize() const = 0;

     /**

     * Gets the default device priority. Method may be used

     * only after an actuator has been opened successfully.

     *

     * @return TInt Default device property. KErrNotReady, if

     * an actuator has not been opened.

     */

     virtual TInt DefaultDevicePriority() const = 0;

     };

 #endif