diff -r 666f914201fb -r 2fe1408b6811 epoc32/include/hwrmhaptics.h --- /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 +#include +#include +#include + +/** 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 // link against hwrmhapticsclient.lib + * #include // 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