--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/epoc32/include/hwrmhaptics.h Tue Mar 16 16:12:26 2010 +0000
@@ -0,0 +1,1713 @@
+/*
+* 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