williamr@2: /* williamr@2: * Copyright (c) 2008 Nokia Corporation and/or its subsidiary(-ies). williamr@2: * All rights reserved. williamr@2: * This component and the accompanying materials are made available williamr@4: * under the terms of "Eclipse Public License v1.0" williamr@2: * which accompanies this distribution, and is available williamr@4: * at the URL "http://www.eclipse.org/legal/epl-v10.html". williamr@2: * williamr@2: * Initial Contributors: williamr@2: * Nokia Corporation - initial contribution. williamr@2: * williamr@2: * Contributors: williamr@2: * williamr@2: * Description: This file contains the header of the CHWRMHaptics class. williamr@2: * williamr@2: */ williamr@2: williamr@2: williamr@2: #ifndef C_HWRMHAPTICS_H williamr@2: #define C_HWRMHAPTICS_H williamr@2: williamr@2: #include williamr@2: #include williamr@2: #include williamr@2: #include williamr@2: williamr@2: /** Minimum magnitude value. */ williamr@2: const TInt KHWRMHapticsMinMagnitude = 0; williamr@2: williamr@2: /** Maximum magnitude value. */ williamr@2: const TInt KHWRMHapticsMaxMagnitude = 10000; williamr@2: williamr@2: /** williamr@2: * Minimum device priority. williamr@2: * williamr@2: * To be used with SetDeviceProperty(). williamr@2: */ williamr@2: const TInt KHWRMHapticsMinDevicePriority = 0; williamr@2: williamr@2: /** williamr@2: * Maximum device priority. williamr@2: * williamr@2: * To be used with SetDeviceProperty(). williamr@2: */ williamr@2: const TInt KHWRMHapticsMaxDevicePriority = 15; williamr@2: williamr@2: williamr@2: /** Minimum strength value. */ williamr@2: const TInt KHWRMHapticsMinStrength = 0; williamr@2: williamr@2: /** Maximum strength value. */ williamr@2: const TInt KHWRMHapticsMaxStrength = 10000; williamr@2: williamr@2: williamr@2: /** williamr@2: * The class used to control the device's haptics feature. williamr@2: * williamr@2: * The Haptics API provides the ability to control the device's haptics feature. williamr@2: * The API provides methods for receiving the current status and effect williamr@2: * completion of the haptics. The API provides synchronous and asynchronous williamr@2: * versions of playing methods due to the nature of effect playing williamr@2: * where multiple calls may be made to play effects. williamr@2: * Synchronous methods are provided for other API functionality. williamr@2: * They will block the calling client during their execution. williamr@2: * The API is meant for all applications which need to control the williamr@2: * device's haptics feature. williamr@2: * williamr@2: * The API consist of the class CHWRMHaptics and related observer classes: williamr@2: * MHWRMHapticsObserver and MHWRMHapticsActuatorObserver. If the client williamr@2: * requires up-to-date status information, it can be achieved by deriving williamr@2: * the client from MHWRMHapticsObserver or MHWRMHapticsActuatorObserver or williamr@2: * from both and providing a callback pointer(s) of the implementing class williamr@2: * for the NewL() method. williamr@2: * williamr@2: * @code williamr@2: * williamr@2: * // =================================================================== williamr@2: * // Usage example 1: williamr@2: * // - Setting the license key. williamr@2: * // - Playing a periodic effect williamr@2: * // - Preconditions: williamr@2: * // - Haptics feature must be enabled by the system. williamr@2: * // =================================================================== williamr@2: * williamr@2: * #include // link against hwrmhapticsclient.lib williamr@2: * #include // enumeration of logical actuators williamr@2: * williamr@2: * TInt minPeriod( 0 ); williamr@2: * TInt effectHandle( 0 ); williamr@2: * TInt suppAct( 0 ); williamr@2: * williamr@2: * CHWRMHaptics* haptics = CHWRMHaptics::NewL( NULL, NULL ); williamr@2: * williamr@2: * haptics->SupportedActuators( suppAct ); williamr@2: * williamr@2: * if( EHWRMLogicalActuatorDevice & suppAct ) williamr@2: * { williamr@4: * haptics->OpenActuatorL( EHWRMLogicalActuatorDevice ); williamr@2: * } williamr@2: * else if ( EHWRMLogicalActuatorAny & suppAct ) williamr@2: * { williamr@4: * haptics->OpenActuatorL( EHWRMLogicalActuatorAny ); williamr@2: * } williamr@2: * williamr@2: * williamr@2: * // 3rd party developers can obtain the license key from Forum Nokia williamr@2: * _LIT8( KLicenseKey,"_this_value_must_be_32_in_length" ); williamr@2: * williamr@2: * User::LeaveIfError( williamr@2: * haptics->SetDeviceProperty( williamr@2: * THWRMHapticsDevicePropertyTypes::EHWRMHapticsLicenseKey, williamr@2: * KLicenseKey ) ); williamr@2: * williamr@2: * // --> now playing effects is possible williamr@2: * williamr@4: * CHWRMHaptics::THWRMHapticsPeriodicEffect periodicEff; williamr@2: * williamr@2: * periodicEff.iDuration = 5000; williamr@2: * periodicEff.iMagnitude = 5000; williamr@2: * periodicEff.iPeriod = minPeriod; williamr@4: * periodicEff.iStyle = CHWRMHaptics::EHWRMHapticsStyleSharp; williamr@2: * periodicEff.iAttackTime = 250; williamr@2: * periodicEff.iAttackLevel = 10000; williamr@2: * periodicEff.iFadeTime = 250; williamr@2: * periodicEff.iFadeLevel = 0; williamr@2: * williamr@2: * haptics->PlayPeriodicEffect( periodicEff, effectHandle ); williamr@2: * williamr@2: * // ... something happened in the application and it has lost focus williamr@2: * // so stop the effect immediately williamr@2: * williamr@2: * haptics->StopPlayingEffect( effectHandle ); williamr@2: * williamr@2: * // ================================================================ williamr@2: * // Usage example 2: williamr@2: * // - Loading effect data from a file and playing effects from the williamr@2: * // loaded data. williamr@2: * // - Preconditions: williamr@2: * // - license key is set williamr@2: * // - Recommended usage style: williamr@2: * // - Effect data file can contain definition(s) of periodic williamr@2: * // effects, magsweep effects or a combination of these basic williamr@2: * // types called timeline effects, which call basic effects in williamr@2: * // sequence thus forming new more complex effects. williamr@2: * // - Load the effect data once in the client application. williamr@2: * // - Play effects from the loaded data using the effectIndex williamr@2: * // ================================================================ williamr@2: * williamr@2: * // Use S60 FileSystem to load the effect data file to a buffer williamr@2: * williamr@2: * ... williamr@2: * williamr@2: * // Effect data has been read into a descriptor by the user. williamr@2: * // Load the effect data to be used by the haptic subsystem. williamr@2: * TInt fileHandle( 0 ); williamr@2: * User::LeaveIfError( haptics->LoadEffectData( data, fileHandle ) ); williamr@2: * williamr@2: * TInt effectIndex = 0; williamr@2: * TInt hapticsStatus = haptics->PlayEffect( fileHandle, williamr@2: * effectIndex, williamr@2: * effectHandle ); williamr@2: * williamr@2: * hapticsStatus = haptics->DeleteEffectData( fileHandle ); williamr@2: * williamr@2: * if( KErrNone != hapticsStatus ) williamr@2: * { williamr@2: * // do some error handling... williamr@2: * } williamr@2: * williamr@2: * delete haptics; williamr@2: * haptics = NULL; williamr@2: * williamr@2: * @endcode williamr@2: * williamr@2: * Common error codes returned by the Haptics API methods. williamr@2: * williamr@2: * KErrArgument Argument is invalid, e.g., malformatted effect data, or too williamr@2: * large magnitude value. williamr@2: * KErrAccessDenied The license key is not set when trying to use some williamr@2: * haptics method. williamr@2: * KErrNoMemory There is insufficient memory available for the method to williamr@2: * complete. williamr@2: * KErrNotReady Initialization has not been done properly when trying to use williamr@2: * a haptics method. williamr@2: * williamr@2: * @lib hwrmhapticsclient.dll williamr@2: * @since S60 5.1 williamr@2: */ williamr@2: williamr@2: class CHWRMHaptics : public CBase williamr@2: { williamr@2: public: williamr@2: williamr@2: /** williamr@2: * Defines the paramaters used in a magsweep effect. williamr@2: * williamr@2: * Used by williamr@2: * PlayMagSweepEffect(), williamr@2: * ModifyPlayingMagSweepEffect(), williamr@2: * GetMagSweepEffectDefinition(). williamr@2: */ williamr@2: struct THWRMHapticsMagSweepEffect williamr@2: { williamr@2: /** williamr@2: * Duration of the effect. Unit is milliseconds. williamr@2: * williamr@2: * To specify an infinite duration, the effect duration williamr@2: * should be set to a value returned by InfiniteDuration(). williamr@2: * For a finite duration, the effect duration is clamped to a value williamr@2: * from 0 to the value returned by GetDeviceCapability() williamr@2: * for the EHWRMHapticsMaxEffectDuration capability type. williamr@2: */ williamr@2: TInt iDuration; williamr@2: williamr@2: /** williamr@2: * Magnitude of the effect. williamr@2: * williamr@2: * The effect magnitude is clamped to a value from williamr@2: * KHWRMHapticsMinMagnitude to KHWRMHapticsMaxMagnitude. williamr@2: */ williamr@2: TInt iMagnitude; williamr@2: williamr@2: /** williamr@2: * Style of the effect. williamr@2: * williamr@2: * Can be one of THWRMHapticsEffectStyles. williamr@2: */ williamr@2: TInt iStyle; williamr@2: williamr@2: /** williamr@2: * Attack time of the effect. Unit is milliseconds. williamr@2: * williamr@2: * The attack time is clamped to a value from 0 to the value returned williamr@2: * by GetDeviceCapability() for the EHWRMHapticsMaxEnvelopeTime williamr@2: * capability type. williamr@2: */ williamr@2: TInt iAttackTime; williamr@2: williamr@2: /** williamr@2: * Attack level of the effect. williamr@2: * williamr@2: * The attack level is clamped to a value from KHWRMHapticsMinMagnitude williamr@2: * to KHWRMHapticsMaxMagnitude. williamr@2: */ williamr@2: TInt iAttackLevel; williamr@2: williamr@2: /** williamr@2: * Fade time of the effect. Unit is milliseconds. williamr@2: * williamr@2: * The fade time is clamped to a value from 0 to the value returned williamr@2: * by GetDeviceCapability() for the EHWRMHapticsMaxEnvelopeTime williamr@2: * capability type. williamr@2: */ williamr@2: TInt iFadeTime; williamr@2: williamr@2: /** williamr@2: * Fade level of the effect. williamr@2: * williamr@2: * The fade level is clamped to a value from KHWRMHapticsMinMagnitude williamr@2: * to KHWRMHapticsMaxMagnitude inclusive. williamr@2: */ williamr@2: TInt iFadeLevel; williamr@2: }; williamr@2: williamr@2: /** williamr@2: * Defines the parameters used in a periodic effect. williamr@2: * williamr@2: * Used by williamr@2: * PlayPeriodicEffect(), williamr@2: * ModifyPlayingPeriodicEffect(), williamr@2: * GetPeriodicEffectDefinition(). williamr@2: */ williamr@2: struct THWRMHapticsPeriodicEffect williamr@2: { williamr@2: /** williamr@2: * Duration of the effect. Unit is milliseconds. williamr@2: * williamr@2: * To specify an infinite duration, the effect duration williamr@2: * should be set to InfiniteDuration(). williamr@2: * For a finite duration, the effect duration is clamped to a value williamr@2: * from 0 to the value returned by GetDeviceCapability() williamr@2: * for the EHWRMHapticsMaxEffectDuration capability type. williamr@2: */ williamr@2: TInt iDuration; williamr@2: williamr@2: /** williamr@2: * Magnitude of the effect. williamr@2: * williamr@2: * The effect magnitude is clamped to a value from williamr@2: * KHWRMHapticsMinMagnitude to KHWRMHapticsMaxMagnitude. williamr@2: */ williamr@2: TInt iMagnitude; williamr@2: williamr@2: /** williamr@2: * Period of the effect. Unit is milliseconds. williamr@2: * williamr@2: * The period is clamped to a value returned by GetDeviceCapability() williamr@2: * for EHWRMHapticsMinPeriod capability type to the value returned williamr@2: * by GetDeviceCapability() for the EHWRMHapticsMaxEnvelopeTime williamr@2: * capability type. williamr@2: */ williamr@2: TInt iPeriod; williamr@2: williamr@2: /** williamr@2: * Style of the effect. williamr@2: * williamr@2: * Can be one of THWRMHapticsEffectStyles. williamr@2: */ williamr@2: TInt iStyle; williamr@2: williamr@2: /** williamr@2: * Attack time of the effect. Unit is milliseconds. williamr@2: * williamr@2: * The attack time is clamped to a value from 0 to the value returned williamr@2: * by GetDeviceCapability() for the EHWRMHapticsMaxEnvelopeTime williamr@2: * capability type. williamr@2: */ williamr@2: TInt iAttackTime; williamr@2: williamr@2: /** williamr@2: * Attack level of the effect. williamr@2: * williamr@2: * The attack level is clamped to a value from KHWRMHapticsMinMagnitude williamr@2: * to KHWRMHapticsMaxMagnitude. williamr@2: */ williamr@2: TInt iAttackLevel; williamr@2: williamr@2: /** williamr@2: * Fade time of the effect. Unit is milliseconds. williamr@2: * williamr@2: * The fade time is clamped to a value from 0 to the value returned williamr@2: * by GetDeviceCapability() for the EHWRMHapticsMaxEnvelopeTime williamr@2: * capability type. williamr@2: */ williamr@2: TInt iFadeTime; williamr@2: williamr@2: /** williamr@2: * Fade level of the effect. williamr@2: * williamr@2: * The fade level is clamped to a value from KHWRMHapticsMinMagnitude williamr@2: * to KHWRMHapticsMaxMagnitude. williamr@2: */ williamr@2: TInt iFadeLevel; williamr@2: }; williamr@2: williamr@2: /** williamr@2: * THWRMHapticsDevicePropertyTypes enumeration williamr@2: * Use SetDeviceProperty() to set properties for the haptics williamr@2: * and GetDeviceProperty() to get properties currently in use. williamr@2: */ williamr@2: enum THWRMHapticsDevicePropertyTypes williamr@2: { williamr@2: /** williamr@2: * License key property. Usable with SetDeviceProperty() only. williamr@2: * Use const TDesC8& overloaded version of the method. williamr@2: * williamr@2: * Setting this property to a valid license key unlocks the haptics williamr@2: * subsystem in the device. Setting this property to an invalid williamr@2: * license key locks the haptics in the device (for this client). williamr@2: * The haptics in the device are locked from clients by default. williamr@2: * When haptics is locked, all haptics related operations on the williamr@2: * device, except for setting the license key and closing the device, williamr@2: * fail. williamr@2: * Haptics must be unlocked on a per instance basis. williamr@2: */ williamr@2: EHWRMHapticsLicensekey = 0, williamr@2: williamr@2: /** williamr@2: * Property used to set/get the priority for effects to played for williamr@2: * the given haptics instance (i.e., for the given client). williamr@2: * williamr@2: * Use TInt overloaded version of the methods SetDeviceProperty()and williamr@2: * GetDeviceProperty() to use this property. williamr@2: * williamr@2: * Different haptics instances can use different priorities williamr@2: * on the same physical device. The priority determines which haptics williamr@2: * instance's effects are played when multiple haptics instances williamr@2: * are attempting to play effects at the same time. williamr@2: * The default priority is DefaultDevicePriority(). williamr@2: * Priority values can range from KHWRMHapticsMinDevicePriority williamr@2: * to KHWRMHapticsMaxDevicePriority. williamr@2: * GetDeviceProperty() returns a value inside williamr@2: * TInt& aDevicePropertyValue in the range of williamr@2: * KHWRMHapticsMinDevicePriority williamr@2: * to KHWRMHapticsMaxDevicePriority. If the client has not set williamr@2: * the EHWRMHapticsPriority property GetDeviceProperty() returns williamr@2: * a value of DefaultDevicePriority(). williamr@2: */ williamr@2: EHWRMHapticsPriority, williamr@2: williamr@2: /** williamr@2: * Property used to disable effects for the client's haptics instance. williamr@2: * williamr@2: * Use TBool overloaded version of the methods SetDeviceProperty() and williamr@2: * GetDeviceProperty() to use this property. williamr@2: * williamr@2: * When this property is set to true, any playing effects are williamr@2: * immediately stopped and subsequent requests to play williamr@2: * effects are ignored. Applies to the calling client's williamr@2: * haptics instance only. When this property is set to false, williamr@2: * subsequent requests to play effects are honored. williamr@2: * The default value for this property is false. williamr@2: */ williamr@2: EHWRMHapticsDisableEffects, williamr@2: williamr@2: /** williamr@2: * A property that reduces/increases the magnitude of all effects williamr@2: * for a particular haptics instance. williamr@2: * williamr@2: * Use TInt overloaded version of the methods SetDeviceProperty()and williamr@2: * GetDeviceProperty() to use this property. williamr@2: williamr@2: * Strength values can vary from KHWRMHapticsMinStrength ("mute") williamr@2: * to KHWRMHapticsMaxStrength. williamr@2: * The default value for EHWRMHapticsStrength is williamr@2: * KHWRMHapticsMaxStrength. If the EHWRMHapticsStrength property is williamr@2: * not set, the default value is used. williamr@2: * When reducing/increasing the magnitude of the effects by setting williamr@2: * the EHWRMHapticsStrength property, it only applies to the haptics williamr@2: * instance of the client which called the function. If there is a williamr@2: * second haptics instance held by the same or a different client, williamr@2: * it is not affected by the setting of the EHWRMHapticsStrength williamr@2: * property of the first client's haptics instance. williamr@2: * williamr@2: * Modifying the EHWRMHapticsStrength property of the haptics instance williamr@2: * does not affect currently playing effects, only effects played or williamr@2: * modified after calling the SetDeviceProperty() method using the new williamr@2: * EHWRMHapticsStrength value. williamr@2: */ williamr@2: EHWRMHapticsStrength, williamr@2: williamr@2: /** williamr@2: * A property that reduces/increases the magnitude of all effects williamr@2: * for all haptics instances (whole device). williamr@2: * williamr@2: * Use TInt overloaded version of the methods SetDeviceProperty()and williamr@2: * GetDeviceProperty() to use this property. williamr@2: * williamr@2: * Strength values can vary from KHWRMHapticsMinStrength ("mute") williamr@2: * to KHWRMHapticsMaxStrength. williamr@2: * The default value for Master Strength is KHWRMHapticsMaxStrength. williamr@2: * If the client does not set the EHWRMHapticsMasterStrength property williamr@2: * of the haptics instance, the default value is used. williamr@2: * When reducing/increasing the magnitude of the effects, williamr@2: * EHWRMHapticsMasterStrength property affects all playing effects on williamr@2: * all haptics instances (whole device). williamr@2: * This means that all the haptics instances, held by other williamr@2: * clients are affected by the setting of EHWRMHapticsMasterStrength williamr@2: * property of the first client's haptics instance. williamr@2: * williamr@2: * The client which wants to set the EHWRMHapticsMasterStrength williamr@2: * property must have a haptics instance that has a maximum effect williamr@2: * priority. williamr@2: * The haptics client instance must set itself to a maximum priority williamr@2: * by calling SetDeviceProperty() using EHWRMHapticsPriority property williamr@2: * type and KMaxDevicePriority value before changing the williamr@2: * EHWRMHapticsMasterStrength property's value. williamr@2: * williamr@2: * Note: A licensee license key, provided to licensees only, williamr@2: * changes the EHWRMHapticsMasterStrength property. williamr@2: * A call to SetDeviceProperty( EHWRMHapticsMasterStrength, aValue ) williamr@2: * always returns KErrAccessDenied for haptics instances that are williamr@2: * not using a licensee license key. williamr@2: */ williamr@2: EHWRMHapticsMasterStrength williamr@2: }; williamr@2: williamr@2: /** williamr@2: * Device's capability types. williamr@2: * williamr@2: * Use TInt& aDeviceCapabilityValue overloaded version of the williamr@2: * method GetDeviceCapability() unless otherwise mentioned. williamr@2: */ williamr@2: enum THWRMHapticsDeviceCapabilityTypes williamr@2: { williamr@2: /** williamr@2: * Device category. See THWRMHapticsDeviceCategory enumeration defined williamr@2: * later in this API header for possible values. williamr@2: */ williamr@2: EHWRMHapticsDeviceCategory = 0, williamr@2: williamr@2: /** williamr@2: * The maximum number of nested repeat bars supported for Timeline effects. williamr@2: * williamr@2: * Any repeat bars nested beyond this level are played only once. williamr@2: */ williamr@2: EHWRMHapticsMaxNestedRepeats, williamr@2: williamr@2: /** williamr@2: * Number of vibration actuators present in the device. williamr@2: */ williamr@2: EHWRMHapticsNumActuators, williamr@2: williamr@2: /** williamr@2: * Actuator type See THWRMHapticsActuatorType enumeration defined williamr@2: * later in this API header for possible values. williamr@2: */ williamr@2: EHWRMHapticsActuatorType, williamr@2: williamr@2: /** williamr@2: * Number of effect slots. williamr@2: * williamr@2: * The number of effect slots represents the maximum number williamr@2: * of simple effects that can play simultaneously. williamr@2: * If an attempt is made to play more than this number of effects williamr@2: * at the same time, some of the simple effects do not play. williamr@2: */ williamr@2: EHWRMHapticsNumEffectSlots, williamr@2: williamr@2: /** williamr@2: * Supported effect styles, stored as a bitfield. See williamr@2: * THWRMHapticsSupportedEffectStyles enumeration defined later in this williamr@2: * API header for possible values. williamr@2: */ williamr@2: EHWRMHapticsSupportedStyles, williamr@2: williamr@2: /** williamr@2: * Minimum period for Periodic effects. williamr@2: */ williamr@2: EHWRMHapticsMinPeriod, williamr@2: williamr@2: /** williamr@2: * Maximum period for Periodic effects. williamr@2: */ williamr@2: EHWRMHapticsMaxPeriod, williamr@2: williamr@2: /** williamr@2: * Maximum duration for MagSweep and Periodic effects measured williamr@2: * in milliseconds. williamr@2: */ williamr@2: EHWRMHapticsMaxEffectDuration, williamr@2: williamr@2: /** williamr@2: * Supported effect types. Stored as a bitfield. See williamr@2: * THWRMHapticsSupportedEffectTypes enumeration defined later in this williamr@2: * API header for possible values. williamr@2: */ williamr@2: EHWRMHapticsSupportedEffects, williamr@2: williamr@2: /** williamr@2: * Device name. williamr@2: * williamr@2: * Use TDes8& aDeviceCapabilityValue overloaded version of the williamr@2: * method GetDeviceCapability(). williamr@2: */ williamr@2: EHWRMHapticsDeviceName, williamr@2: williamr@2: /** williamr@2: * Maximum start time or fade time in milliseconds for williamr@2: * effect envelopes of MagSweep or periodic effects. williamr@2: */ williamr@2: EHWRMHapticsMaxEnvelopeTime, williamr@2: williamr@2: /** williamr@2: * Version number of the physical haptics player in the device in williamr@2: * hexadecimal format. williamr@2: * williamr@2: * The format is OxMMNNSSBB, where MM is the major williamr@2: * version number, NN is the minor version number, williamr@2: * SS is a special build number and BB is the VTMP build number. williamr@2: * For example, for the hexadecimal format 0x02000053 the version williamr@2: * number is 2.0.83 williamr@2: */ williamr@2: EHWRMHapticsAPIVersionNumber, williamr@2: williamr@2: /** williamr@2: * Maximum size in bytes of effect data (buffer) that can be played williamr@2: * on a non-tethered device. williamr@2: */ williamr@2: EHWRMHapticsMaxEffectDataSize = 14 williamr@2: }; williamr@2: williamr@2: /** williamr@2: * Device category. williamr@2: */ williamr@2: enum THWRMHapticsDeviceCategory williamr@2: { williamr@2: EHWRMHapticsVirtual = 2, williamr@2: EHWRMHapticsEmbedded = 3, williamr@2: }; williamr@2: williamr@2: /** williamr@2: * Bitmask for effect support. williamr@2: * williamr@2: * To be used to analyze value returned by GetDeviceCapability(). williamr@2: */ williamr@2: enum THWRMHapticsSupportedEffectTypes williamr@2: { williamr@2: EHWRMHapticsSupportPeriodic = 1, williamr@2: EHWRMHapticsSupportMagSweep = 2, williamr@2: EHWRMHapticsSupportTimeline = 4, williamr@2: EHWRMHapticsSupportStreaming = 8 williamr@2: }; williamr@2: williamr@2: /** williamr@2: * Effect types williamr@2: */ williamr@2: enum THWRMHapticsEffectTypes williamr@2: { williamr@2: EHWRMHapticsTypePeriodic = 0, williamr@2: EHWRMHapticsTypeMagSweep, williamr@2: EHWRMHapticsTypeTimeline, williamr@2: EHWRMHapticsTypeStreaming williamr@2: }; williamr@2: williamr@2: /** williamr@2: * Bitmask for supported effect styles. williamr@2: * williamr@2: * To be used to analyze the value returned by GetDeviceCapability(). williamr@2: */ williamr@2: enum THWRMHapticsSupportedEffectStyles williamr@2: { williamr@2: EHWRMHapticsSupportSmooth = 1, williamr@2: EHWRMHapticsSupportStrong = 2, williamr@2: EHWRMHapticsSupportSharp = 4 williamr@2: }; williamr@2: williamr@2: /** williamr@2: * Effect styles williamr@2: * williamr@2: * Used to specify Periodic or MagSweep effect style when calling williamr@2: * PlayMagSweepEffect(), williamr@2: * PlayPeriodicEffect(), williamr@2: * ModifyPlayingMagSweepEffect() and williamr@2: * ModifyPlayingPeriodicEffect(). williamr@2: */ williamr@2: enum THWRMHapticsEffectStyles williamr@2: { williamr@2: EHWRMHapticsStyleSmooth = 0, williamr@2: EHWRMHapticsStyleStrong, williamr@2: EHWRMHapticsStyleSharp williamr@2: }; williamr@2: williamr@2: /** williamr@2: * Actuator types. williamr@2: * williamr@2: * To be used with GetDeviceCapability(). williamr@2: */ williamr@2: enum THWRMHapticsActuatorTypes williamr@2: { williamr@2: /** williamr@2: * Eccentric Rotating Mass actuator williamr@2: */ williamr@2: EHWRMHapticsTypeERM = 0, williamr@2: williamr@2: /** williamr@2: * Linear Resonant actuator williamr@2: */ williamr@2: EHWRMHapticsTypeLRA = 2 williamr@2: }; williamr@2: williamr@2: /** williamr@2: * Effect states. williamr@2: * williamr@2: * As returned in a call to GetEffectState(). williamr@2: */ williamr@2: enum THWRMHapticsEffectStates williamr@2: { williamr@2: EHWRMHapticsEffectNotPlaying = 0, williamr@2: EHWRMHapticsEffectPlaying, williamr@2: EHWRMHapticsEffectPaused williamr@2: }; williamr@2: williamr@2: /** williamr@2: * Two-phased constructor. williamr@2: * Use this method for creating a haptics instance with callbacks. williamr@2: * williamr@2: * @param aHapticsCallback Pointer to callback instance. Can be NULL. williamr@2: * @param aActuatorCallback Pointer to callback instance. Can be NULL. williamr@2: * williamr@2: * @return A pointer to a new instance of the CHWRMHaptics class. williamr@2: * williamr@2: * @since S60 5.1 williamr@2: */ williamr@2: IMPORT_C static CHWRMHaptics* NewL( williamr@2: MHWRMHapticsObserver* aHapticsCallback, williamr@2: MHWRMHapticsActuatorObserver* aActuatorCallback ); williamr@2: williamr@2: /** williamr@2: * @overload williamr@2: * williamr@2: * @param[out] aStatus Request status. On completion contains: williamr@2: * KErrNone, if successful, williamr@2: * otherwise one of the other system-wide error codes. williamr@2: */ williamr@2: IMPORT_C static CHWRMHaptics* NewL( williamr@2: MHWRMHapticsObserver* aHapticsCallback, williamr@2: MHWRMHapticsActuatorObserver* aActuatorCallback, williamr@2: TRequestStatus& aStatus ); williamr@2: williamr@2: /** williamr@2: * Method for opening a logical actuator for use. williamr@2: * williamr@2: * This method must be called before using any other methods of this class, williamr@2: * except when using GetXXX methods. williamr@2: * The Haptics API supports a limited number of instances of CHWRMHaptics williamr@2: * class. williamr@2: * If all instances are currently in use, the next attempt to call williamr@2: * OpenActuatorL() from any client fails. williamr@2: * Applications should not use more instances than necessary as this williamr@2: * may prevent other applications from instantiating the CHWRMHaptics williamr@2: * class. williamr@2: * williamr@2: * @param aActuator Enumeration of the type of logical actuator the client williamr@2: * wants to use. williamr@2: * williamr@2: * @leave TInt KErrNotSupported, if the used logical actuator is not williamr@2: * supported by the system. williamr@2: * @leave TInt KErrAlreadyExists, if the used logical actuator is already williamr@2: * opened. williamr@2: * @leave TInt KErrInUse, if some other actuator is already opened. williamr@2: * @leave TInt KErrArgument, if aActuator is not valid enumeration value. williamr@2: * williamr@2: * @see THWRMLogicalActuators for a list of usable actuators. williamr@2: * williamr@2: * @since S60 5.1 williamr@2: */ williamr@2: virtual void OpenActuatorL( THWRMLogicalActuators aActuator ) = 0; williamr@2: williamr@2: /** williamr@2: * Method for getting a bitmask value of supported logical actuators. williamr@2: * williamr@2: * Developer needs to evaluate the returned bitmask against williamr@2: * THWRMLogicalActuators enumeration values to know the williamr@2: * supported logical actuators. williamr@2: * williamr@2: * @param[out] aActuators Bitmask of supported logical actuators. williamr@2: * williamr@2: * @return TInt KErrNone, if successful, otherwise one of the other williamr@2: * system-wide error codes. williamr@2: * williamr@2: * @see THWRMLogicalActuators for a list of usable actuators. williamr@2: * williamr@2: * @since S60 5.1 williamr@2: */ williamr@2: virtual TInt SupportedActuators( TUint32& aActuators ) = 0; williamr@2: williamr@2: /** williamr@2: * Reserves haptics feature exclusively for this client. williamr@2: * A higher priority client may cause lower priority client reservation williamr@2: * to be temporarily suspended. The suspended client does not get williamr@2: * any notification about suspension. If haptics is already reserved williamr@2: * by a higher or equal priority client, reserving still succeeds, williamr@2: * but reservation is immediately suspended. When the reservation williamr@2: * is suspended, playing effects do not actually cause the effects to be williamr@2: * played. williamr@2: * Note: Unless the client has instantiated the Haptics API with the status williamr@2: * observer, it does not receive any notifications about the fact that its williamr@2: * effects are not actually played by the physical player when the client williamr@2: * has been suspended by a higher priority reservation. williamr@2: * Note also that even if haptics is reserved by some client, a higher williamr@2: * priority client succeeds in playing its effects. williamr@2: * williamr@2: * Calling this method is equal to call ReserveHapticsL(EFalse), williamr@4: * i.e. foreground status is always used to control further reservations. williamr@4: * However, this is a future feature, and not implemented in current version. williamr@2: */ williamr@2: virtual void ReserveHapticsL() = 0; williamr@2: williamr@2: /** williamr@2: * Reserves haptics feature exclusively for this client. williamr@2: * A higher priority client may cause lower priority client reservation williamr@2: * to be temporarily suspended. The suspended client does not get williamr@2: * any notifications about suspension. If haptics is already reserved williamr@2: * by a higher or equal priority client, reserving still succeeds, williamr@2: * but reservation is immediately suspended. When the reservation williamr@2: * is suspended, playing effects does not actually cause the effects to be williamr@2: * played. williamr@2: * Note: Unless the client has instantiated the Haptics API with the status williamr@2: * observer, it does not receive any notifications about the fact that its williamr@2: * effects are not actually played by the physical player when the client williamr@2: * has been suspended by a higher priority reservation. williamr@2: * Note also that even if haptics is reserved by some client, a higher williamr@2: * priority client succeeds in playing its effects. williamr@2: * williamr@4: * @param aForceNoCCoeEnv (Note: This is a future feature, and not williamr@4: * implemented in current version. You can think of williamr@4: * it ETrue always.) williamr@4: * If EFalse, then reservation requires that williamr@2: * this client has the keyboard focus at the time of williamr@2: * reservation and haptics is automatically williamr@2: * released and re-reserved based on the keyboard williamr@2: * focus status of this client. williamr@2: * This also implies that CCoeEnv::Static() != NULL williamr@2: * is required. williamr@2: * If ETrue, the client does not require CCoeEnv to williamr@2: * be present nor does it automatically reserve or williamr@2: * release haptics by depending on the foreground or williamr@2: * background status of the client. Only trusted williamr@2: * clients are allowed to set this flag to ETrue. williamr@2: * The client application is considered trusted if williamr@4: * it has a priority defined in haptics policy file. williamr@4: * The policy files can be modified by S60 licensees. williamr@2: * williamr@2: * @leave KErrAccessDenied Parameter aForceNoCCoeEnv is ETrue williamr@2: * and client is not trusted. williamr@2: * @leave KErrBadHandle Parameter aForceNoCCoeEnv is EFalse williamr@2: * and no CCoeEnv present. williamr@2: * @leave KErrNotReady Trying to reserve while on background and parameter williamr@2: * aForceNoCCoeEnv is EFalse. williamr@2: * @leave KErrNoMemory There is a memory allocation failure. williamr@2: */ williamr@2: virtual void ReserveHapticsL( TBool aForceNoCCoeEnv ) = 0; williamr@2: williamr@2: /** williamr@2: * Releases haptics feature if it was previously reserved for this client. williamr@2: * williamr@2: * If this client has not reserved haptics feature, does nothing. williamr@2: * If haptics is on when it is released and no other client has a suspended williamr@2: * reservation, haptics is stopped. williamr@2: */ williamr@2: virtual void ReleaseHaptics() = 0; williamr@2: williamr@2: /** williamr@2: * This method retrieves the current haptics status. williamr@2: * williamr@2: * @return THWRMHapticsStatus indicating the current haptics status williamr@2: * williamr@2: * @see THWRMHapticsStatus williamr@2: */ williamr@2: virtual MHWRMHapticsObserver::THWRMHapticsStatus HapticsStatus() const=0; williamr@2: williamr@2: /** williamr@2: * Sets a property of the haptics. williamr@2: * williamr@2: * Some properties affect all haptics instances, some only williamr@2: * the current instance of the haptics. More about that can be found williamr@2: * in THWRMHapticsDevicePropertyTypes. williamr@2: * williamr@2: * @param[in] aDevicePropertyType Property type for the williamr@2: * property to be set. williamr@2: * @param[in] aDevicePropertyValue Value of the property to set. williamr@2: * williamr@2: * @return TInt KErrNone if successful, otherwise one of the other williamr@2: * system-wide error codes. williamr@2: * williamr@2: * @see THWRMHapticsDevicePropertyTypes for a list of valid property types williamr@2: * williamr@2: * @since S60 5.1 williamr@2: */ williamr@2: virtual TInt SetDeviceProperty( TInt aDevicePropertyType, williamr@2: TInt aDevicePropertyValue ) = 0; williamr@2: williamr@2: /** williamr@2: * @overload williamr@2: */ williamr@2: virtual TInt SetDeviceProperty( TInt aDevicePropertyType, williamr@2: const TDesC8& aDevicePropertyValue ) = 0; williamr@2: williamr@2: /** williamr@2: * Gets a property value of the haptics. williamr@2: * williamr@2: * @param[in] aDevicePropertyType Property type for the property to get. williamr@2: * @param[out] aDevicePropertyValue Reference to the variable that williamr@2: * receives the requested property williamr@2: * value of the device. williamr@2: * williamr@2: * @return TInt KErrNone if successful, otherwise one of the other williamr@2: * system-wide error codes. williamr@2: * williamr@2: * @see THWRMHapticsDevicePropertyTypes for a list of the valid property williamr@2: * types. williamr@2: * williamr@2: * @since S60 5.1 williamr@2: */ williamr@2: virtual TInt GetDeviceProperty( TInt aDevicePropertyType, williamr@2: TInt& aDevicePropertyValue ) = 0; williamr@2: williamr@2: /** williamr@2: * @overload williamr@2: * williamr@2: * @return KErrNone if successful, williamr@2: * KErrArgument if the length of the given string is less williamr@2: * than MaxPropertyStringLength(), williamr@2: * otherwise one of the other system-wide error codes. williamr@2: */ williamr@2: virtual TInt GetDeviceProperty( TInt aDevicePropertyType, williamr@2: TDes8& aDevicePropertyValue ) = 0; williamr@2: williamr@2: /** williamr@2: * Gets a capability value of the haptics. williamr@2: * williamr@2: * @param[in] aDeviceCapabilityType Capability type of the williamr@2: * capability to get. williamr@2: * @param[out] aDeviceCapabilityValue Reference to the variable that williamr@2: * receives the requested capability williamr@2: * value of the device. williamr@2: * williamr@2: * @return TInt KErrNone if successful, williamr@2: * KErrNotReady if no actuator has been opened, williamr@2: * otherwise one of the other system-wide error codes. williamr@2: * williamr@2: * @see THWRMHapticsDeviceCapabilityTypes williamr@2: * williamr@2: * @since S60 5.1 williamr@2: */ williamr@2: virtual TInt GetDeviceCapability( TInt aDeviceCapabilityType, williamr@2: TInt& aDeviceCapabilityValue ) = 0; williamr@2: williamr@2: /** williamr@2: * @overload williamr@2: * williamr@2: * @return TInt KErrNone if successful, williamr@2: * KErrNotReady if no actuator has been opened, williamr@2: * KErrArgument if the length of the given string is less williamr@2: * than MaxCapabilityStringLength(), williamr@2: * otherwise one of the other system-wide error codes. williamr@2: */ williamr@2: virtual TInt GetDeviceCapability( TInt aDeviceCapabilityType, williamr@2: TDes8& aDeviceCapabilityValue ) = 0; williamr@2: williamr@2: /** williamr@2: * Retrieves the status of an effect (playing, not playing, paused). williamr@2: * williamr@2: * @param[in] aEffectHandle Handle to the effect which must have been williamr@2: * obtained by calling williamr@2: * PlayMagSweepEffect(), williamr@2: * PlayPeriodicEffect(), williamr@2: * PlayEffect(), williamr@2: * PlayEffectRepeat() or williamr@2: * CreateStreamingEffect() williamr@2: * @param[out] aEffectState Pointer to the variable that receives williamr@2: * the status bits of the effect. williamr@2: * williamr@2: * @return TInt KErrNone if successful, otherwise one of the other williamr@2: * system-wide error codes. williamr@2: * williamr@2: * @see THWRMHapticsEffectStates for a list of valid effect states. williamr@2: * williamr@2: * @since S60 5.1 williamr@2: */ williamr@2: virtual TInt GetEffectState( TInt aEffectHandle, TInt& aEffectState ) = 0; williamr@2: williamr@2: /** williamr@2: * Creates a streaming effect. williamr@2: * williamr@2: * Client calls CreateStreamingEffect() to create a new streaming williamr@2: * effect and gets a new handle for it; it should use that effect handle williamr@2: * to play a streaming sample by calling PlayStreamingSample(). williamr@2: * williamr@2: * @param[out] aEffectHandle Reference to the variable that receives williamr@2: * a handle to the streaming effect. williamr@2: * williamr@2: * @return TInt KErrNone if successful, otherwise one of the other williamr@2: * system-wide error codes. williamr@2: * williamr@2: * @since S60 5.1 williamr@2: */ williamr@2: virtual TInt CreateStreamingEffect( TInt& aEffectHandle ) = 0; williamr@2: williamr@2: /** williamr@2: * Plays a streaming sample given in the parameter defining the effect. williamr@2: * williamr@2: * Streaming sample can only be played after calling williamr@2: * CreateStreamingEffect() and by using the effecthandle it returns. williamr@2: * williamr@2: * Synchronous method returns when the haptic command has been evaluated williamr@2: * and the return value is valid. williamr@2: * williamr@2: * @param[in] aEffectHandle Handle to the streaming effect to play. williamr@2: * @param[in] aStreamingSample Reference to streaming sample data williamr@2: * containing the definition of williamr@2: * the effect to play. williamr@2: * williamr@2: * @return TInt KErrNone if successful, otherwise one of the other williamr@2: * system-wide error codes. williamr@2: * @return TInt KErrInUse when haptics is reserved for a higher or williamr@2: * equal priority client. williamr@2: * williamr@2: * @since S60 5.1 williamr@2: */ williamr@2: virtual TInt PlayStreamingSample( TInt aEffectHandle, williamr@2: const TDesC8& aStreamingSample ) = 0; williamr@2: /** williamr@2: * @overload williamr@2: * williamr@2: * @param[out] aStatus Request status. On completion contains: williamr@2: * KErrNone, if successful, williamr@2: * KErrInUse when haptics is reserved for a higher or williamr@2: * equal priority client, williamr@2: * otherwise one of the other system-wide error codes. williamr@2: */ williamr@2: virtual void PlayStreamingSample( TInt aEffectHandle, williamr@2: const TDesC8& aStreamingSample, williamr@2: TRequestStatus& aStatus ) = 0; williamr@2: williamr@2: /** williamr@2: * Plays a streaming sample with a time offset given in the parameters williamr@2: * defining the effect. williamr@2: * williamr@2: * Client calls CreateStreamingEffect() to create a new streaming williamr@2: * effect and gets a new handle for it; it should use that effect handle williamr@2: * to play the streaming sample with this method. williamr@2: * williamr@2: * Synchronous method returns when the haptic command has been evaluated williamr@2: * and the return value is valid. williamr@2: * williamr@2: * @param[in] aEffectHandle Handle to the streaming effect to play. williamr@2: * @param[in] aStreamingSample Reference to streaming sample data williamr@2: * containing the definition of the williamr@2: * effect to play. williamr@2: * @param[in] aOffsetTime For aOffsetTime values that are greater than 0, williamr@2: * playback is delayed for aOffsetTime williamr@2: * in milliseconds. williamr@2: * For aOffsetTime values that are less than 0, williamr@2: * sample playback begins in offset time williamr@2: * in milliseconds into the current sample. williamr@2: * williamr@2: * @return TInt KErrNone if successful, otherwise one of the other williamr@2: * system-wide error codes. williamr@2: * @return TInt KErrInUse when haptics is reserved for a higher or williamr@2: * equal priority client. williamr@2: * williamr@2: * @since S60 5.1 williamr@2: */ williamr@2: virtual TInt PlayStreamingSampleWithOffset( TInt aEffectHandle, williamr@2: const TDesC8& aStreamingSample, williamr@2: TInt aOffsetTime ) = 0; williamr@2: williamr@2: /** williamr@2: * @overload williamr@2: * williamr@2: * @param[out] aStatus Request status. On completion contains: williamr@2: * KErrNone, if successful, williamr@2: * KErrInUse when haptics is reserved for a higher or williamr@2: * equal priority client, williamr@2: * otherwise one of the other system-wide error codes. williamr@2: */ williamr@2: virtual void PlayStreamingSampleWithOffset( TInt aEffectHandle, williamr@2: const TDesC8& aStreamingSample, williamr@2: TInt aOffsetTime, williamr@2: TRequestStatus& aStatus ) = 0; williamr@2: williamr@2: /** williamr@2: * Destroys a streaming effect previously created in a successful williamr@2: * call to CreateStreamingEffect(). williamr@2: * williamr@2: * @param[in] aEffectHandle Handle to the streaming effect to destroy. williamr@2: * williamr@2: * @return TInt KErrNone if successful, otherwise one of the other williamr@2: * system-wide error codes. williamr@2: * williamr@2: * @since S60 5.1 williamr@2: */ williamr@2: virtual TInt DestroyStreamingEffect( TInt aEffectHandle ) = 0; williamr@2: williamr@2: /** williamr@2: * Modifies a playing MagSweep effect. williamr@2: * williamr@2: * Synchronous method returns when the haptic command has been evaluated williamr@2: * and the return value is valid. williamr@2: * williamr@2: * @param[in] aEffectHandle Handle to the playing MagSweep effect williamr@2: * to modify. The handle to the effect must have williamr@2: * been obtained by calling williamr@2: * PlayMagSweepEffect(), williamr@2: * PlayEffect() or williamr@2: * PlayEffectRepeat(). williamr@2: * @param[in] aEffect Reference to a struct defining the effect parameters. williamr@2: * williamr@2: * @return TInt KErrNone if successful, otherwise one of the other williamr@2: * system-wide error codes. williamr@2: * williamr@2: * @see THWRMHapticsMagSweepEffect for effect definition. williamr@2: * williamr@2: * @since S60 5.1 williamr@2: */ williamr@2: virtual TInt ModifyPlayingMagSweepEffect( TInt aEffectHandle, williamr@2: const CHWRMHaptics::THWRMHapticsMagSweepEffect& aEffect ) = 0; williamr@2: williamr@2: /** williamr@2: * @overload williamr@2: * williamr@2: * @param[out] aStatus Request status. On completion contains: williamr@2: * KErrNone, if successful, williamr@2: * otherwise one of the other system-wide error codes. williamr@2: */ williamr@2: virtual void ModifyPlayingMagSweepEffect( TInt aEffectHandle, williamr@2: const CHWRMHaptics::THWRMHapticsMagSweepEffect& aEffect, williamr@2: TRequestStatus& aStatus ) = 0; williamr@2: williamr@2: /** williamr@2: * Modifies a playing periodic effect. williamr@2: * williamr@2: * Synchronous method returns when the haptic command has been evaluated williamr@2: * and the return value is valid. williamr@2: * williamr@2: * @param[in] aEffectHandle Handle to the playing periodic effect williamr@2: * to modify. The handle to the effect must have williamr@2: * been obtained by calling williamr@2: * PlayPeriodicEffect(), williamr@2: * PlayEffect() or williamr@2: * PlayEffectRepeat(). williamr@2: * @param[in] aEffect Reference to a struct defining the effect parameters. williamr@2: * williamr@2: * @return TInt KErrNone if successful, otherwise one of the other williamr@2: * system-wide error codes. williamr@2: * williamr@2: * @see THWRMHapticsPeriodicEffect for effect definition. williamr@2: * williamr@2: * @since S60 5.1 williamr@2: */ williamr@2: virtual TInt ModifyPlayingPeriodicEffect( TInt aEffectHandle, williamr@2: const CHWRMHaptics::THWRMHapticsPeriodicEffect& aEffect ) = 0; williamr@2: williamr@2: /** williamr@2: * @overload williamr@2: * williamr@2: * @param[out] aStatus Request status. On completion contains: williamr@2: * KErrNone, if successful, williamr@2: * otherwise one of the other system-wide error codes. williamr@2: */ williamr@2: virtual void ModifyPlayingPeriodicEffect( TInt aEffectHandle, williamr@2: const CHWRMHaptics::THWRMHapticsPeriodicEffect& aEffect, williamr@2: TRequestStatus& aStatus ) = 0; williamr@2: williamr@2: williamr@2: /** williamr@2: * Load effect data defined in effect data buffer (obtained e.g. from a williamr@2: * file containing the effect data). williamr@2: * williamr@2: * @param[in] aData Reference to allocated effect data buffer. williamr@2: * williamr@2: * @param[out] aFileHandle On return contains a handle to the passed williamr@2: * effect data. This handle is haptics specific, williamr@2: * i.e., it is not a file system handle but just williamr@2: * a handle to the loaded effect data buffer. williamr@2: * williamr@2: * @return TInt KErrNone if successful, otherwise one of the other williamr@2: * system-wide error codes. williamr@2: * @return TInt KErrArgument if the effect data is invalid. williamr@2: * williamr@2: * @since S60 5.1 williamr@2: */ williamr@2: virtual TInt LoadEffectData( const TDesC8& aData, TInt& aFileHandle ) = 0; williamr@2: williamr@2: /** williamr@2: * Delete loaded effect data referenced by file handle. williamr@2: * williamr@2: * @param[in] aFileHandle Handle to file. williamr@2: * williamr@2: * @return TInt KErrNone if successful, otherwise one of the other williamr@2: * system-wide error codes. williamr@2: * williamr@2: * @since S60 5.1 williamr@2: */ williamr@2: virtual TInt DeleteEffectData( TInt aFileHandle ) = 0; williamr@2: williamr@2: /** williamr@2: * Delete all loaded effect datas. williamr@2: * williamr@2: * @return TInt KErrNone if successful, otherwise one of the other williamr@2: * system-wide error codes. williamr@2: * williamr@2: * @since S60 5.1 williamr@2: */ williamr@2: virtual TInt DeleteAllEffectData() = 0; williamr@2: williamr@2: /** williamr@2: * Plays an effect defined in loaded effect data buffer. williamr@2: * williamr@2: * Synchronous method returns when the haptic command has been evaluated williamr@2: * and the return value is valid. williamr@2: * williamr@2: * @param[in] aFileHandle Handle to the loaded effect data. williamr@2: * williamr@2: * @param[in] aEffectIndex Index of the effect to play. The index of the williamr@2: * effect must be greater than or equal to 0 and williamr@2: * less than the number of effects returned by williamr@2: * GetEffectCount(). williamr@2: * @param[out] aEffectHandle Reference to the variable that receives williamr@2: * a handle to the playing effect. williamr@2: * williamr@2: * @return TInt KErrNone if successful, otherwise one of the other williamr@2: * system-wide error codes. williamr@2: * @return TInt KErrInUse when haptics is reserved for a higher or williamr@2: * equal priority client. williamr@2: * williamr@2: * @since S60 5.1 williamr@2: */ williamr@2: virtual TInt PlayEffect( TInt aFileHandle, williamr@2: TInt aEffectIndex, williamr@2: TInt& aEffectHandle ) = 0; williamr@2: williamr@2: /** williamr@2: * @overload williamr@2: * williamr@2: * @param[out] aStatus Request status. On completion contains: williamr@2: * KErrNone, if successful, williamr@2: * KErrInUse when haptics is reserved for a higher or williamr@2: * equal priority client, williamr@2: * otherwise one of the other system-wide error codes. williamr@2: */ williamr@2: virtual void PlayEffect( TInt aFileHandle, williamr@2: TInt aEffectIndex, williamr@2: TInt& aEffectHandle, williamr@2: TRequestStatus& aStatus ) = 0; williamr@2: williamr@2: /** williamr@2: * Repeatedly plays a Timeline effect defined in loaded effect data buffer. williamr@2: * williamr@2: * The current implementation of PlayEffectRepeat() repeats only williamr@2: * Timeline effects. If the given effect index refers to a simple effect, williamr@2: * PlayEffectRepeat() ignores the aRepeat parameter and plays the williamr@2: * simple effect once. In that case, PlayEffectRepeat() behaves williamr@2: * like PlayEffect(). PlayEffectRepeat() does not return a warning williamr@2: * when requested to repeat a simple effect. williamr@2: * williamr@2: * Synchronous method returns when the haptic command has been evaluated williamr@2: * and the return value is valid. williamr@2: * williamr@2: * @param[in] aFileHandle Handle to the loaded effect data. williamr@2: * @param[in] aEffectIndex Index of the effect to play. The index of the williamr@2: * effect must be greater than or equal to 0 and williamr@2: * less than the number of effects returned by williamr@2: * GetEffectCount(). williamr@2: * @param[in] aRepeat Number of times to repeat the effect. To play the williamr@2: * effect indefinitely, set aRepeat to williamr@2: * InfiniteRepeat(). To repeat the effect a williamr@2: * finite number of times, set aRepeat to a value from williamr@2: * 0 to InfiniteRepeat() - 1. williamr@2: * The effect can be repeated at most williamr@2: * InfiniteRepeat() - 1 times. williamr@2: * Setting aRepeat to 0 plays the effect once (repeats williamr@2: * the effect zero times) and is equivalent to calling williamr@2: * PlayEffect(). williamr@2: * To stop the effect before it has williamr@2: * repeated the requested number of times or to stop williamr@2: * an effect that is playing indefinitely, call williamr@2: * StopPlayingEffect() or StopAllPlayingEffects() williamr@2: * @param[out] aEffectHandle Reference to the variable that receives williamr@2: * a handle to the playing effect. williamr@2: * williamr@2: * @return TInt KErrNone if successful, otherwise one of the other williamr@2: * system-wide error codes. williamr@2: * @return TInt KErrInUse when haptics is reserved for a higher or williamr@2: * equal priority client. williamr@2: * williamr@2: * @since S60 5.1 williamr@2: */ williamr@2: virtual TInt PlayEffectRepeat( TInt aFileHandle, williamr@2: TInt aEffectIndex, williamr@2: TUint8 aRepeat, williamr@2: TInt& aEffectHandle ) = 0; williamr@2: williamr@2: /** williamr@2: * @overload williamr@2: * williamr@2: * @param[out] aStatus Request status. On completion contains: williamr@2: * KErrNone, if successful, williamr@2: * KErrInUse when haptics is reserved for a higher or williamr@2: * equal priority client, williamr@2: * otherwise one of the other system-wide error codes. williamr@2: */ williamr@2: virtual void PlayEffectRepeat( TInt aFileHandle, williamr@2: TInt aEffectIndex, williamr@2: TUint8 aRepeat, williamr@2: TInt& aEffectHandle, williamr@2: TRequestStatus& aStatus ) = 0; williamr@2: williamr@2: /** williamr@2: * Plays an effect defined in effect data buffer. williamr@2: * williamr@2: * Synchronous method returns when the haptic command has been evaluated williamr@2: * and the return value is valid. williamr@2: * williamr@2: * @param[in] aData Reference to effect data buffer containing the williamr@2: * definition of the effect to play. williamr@2: * @param[in] aEffectIndex Index of the effect to play. The index of the williamr@2: * effect must be greater than or equal to 0 and williamr@2: * less than the number of effects returned by williamr@2: * GetEffectCount(). williamr@2: * @param[out] aEffectHandle Reference to the variable that receives williamr@2: * a handle to the playing effect. williamr@2: * williamr@2: * @return TInt KErrNone if successful, otherwise one of the other williamr@2: * system-wide error codes. williamr@2: * @return TInt KErrArgument if the data is invalid. williamr@2: * @return TInt KErrInUse when haptics is reserved for a higher or williamr@2: * equal priority client. williamr@2: * williamr@2: * @since S60 5.1 williamr@2: */ williamr@2: virtual TInt PlayEffect( const TDesC8& aData, williamr@2: TInt aEffectIndex, williamr@2: TInt& aEffectHandle ) = 0; williamr@2: williamr@2: /** williamr@2: * @overload williamr@2: * williamr@2: * @param[out] aStatus Request status. On completion contains: williamr@2: * KErrNone, if successful, williamr@2: * KErrArgument, if the data is invalid, williamr@2: * KErrInUse when haptics is reserved for a higher or williamr@2: * equal priority client, williamr@2: * otherwise one of the other system-wide error codes. williamr@2: */ williamr@2: virtual void PlayEffect( const TDesC8& aData, williamr@2: TInt aEffectIndex, williamr@2: TInt& aEffectHandle, williamr@2: TRequestStatus& aStatus ) = 0; williamr@2: williamr@2: /** williamr@2: * Repeatedly plays a Timeline effect defined in effect data buffer. williamr@2: * williamr@2: * The current implementation of PlayEffectRepeat() repeats only williamr@2: * Timeline effects. If the given effect index refers to a simple effect, williamr@2: * PlayEffectRepeat() ignores the aRepeat parameter and plays the williamr@2: * simple effect once. In that case, PlayEffectRepeat() behaves williamr@2: * similarly to PlayEffect(). PlayEffectRepeat() does not return a warning williamr@2: * when requested to repeat a simple effect. williamr@2: * williamr@2: * Synchronous method returns when the haptic command has been evaluated williamr@2: * and the return value is valid. williamr@2: * williamr@2: * @param[in] aData Reference to effect data buffer containing the williamr@2: * definition of the effect to play. williamr@2: * @param[in] aEffectIndex Index of the effect to play. The index of the williamr@2: * effect must be greater than or equal to 0 and williamr@2: * less than the number of effects returned by williamr@2: * GetEffectCount(). williamr@2: * @param[in] aRepeat Number of times to repeat the effect. To play the williamr@2: * effect indefinitely, set aRepeat to williamr@2: * InfiniteRepeat(). To repeat the effect a williamr@2: * finite number of times, set aRepeat to a value from williamr@2: * 0 to InfiniteRepeat() - 1. The effect can williamr@2: * be repeated at most InfiniteRepeat() - 1 williamr@2: * times. williamr@2: * Setting aRepeat to 0 plays the effect once (repeats williamr@2: * the effect zero times) and is equivalent to calling williamr@2: * PlayEffect(). williamr@2: * To stop the effect before it has williamr@2: * repeated the requested number of times or to stop williamr@2: * an effect that is playing indefinitely, call williamr@2: * StopPlayingEffect() or StopAllPlayingEffects() williamr@2: * @param[out] aEffectHandle Reference to the variable that receives williamr@2: * a handle to the playing effect. williamr@2: * williamr@2: * @return TInt KErrNone if successful, otherwise one of the other williamr@2: * system-wide error codes. williamr@2: * @return TInt KErrArgument if the data is invalid. williamr@2: * @return TInt KErrInUse when haptics is reserved for a higher or williamr@2: * equal priority client. williamr@2: * williamr@2: * @since S60 5.1 williamr@2: */ williamr@2: virtual TInt PlayEffectRepeat( const TDesC8& aData, williamr@2: TInt aEffectIndex, williamr@2: TUint8 aRepeat, williamr@2: TInt& aEffectHandle )=0; williamr@2: williamr@2: /** williamr@2: * @overload williamr@2: * williamr@2: * @param[out] aStatus Request status. On completion contains: williamr@2: * KErrNone, if successful, williamr@2: * KErrArgument, if the data is invalid, williamr@2: * KErrInUse when haptics is reserved for a higher or williamr@2: * equal priority client, williamr@2: * otherwise one of the other system-wide error codes. williamr@2: */ williamr@2: virtual void PlayEffectRepeat( const TDesC8& aData, williamr@2: TInt aEffectIndex, williamr@2: TUint8 aRepeat, williamr@2: TInt& aEffectHandle, williamr@2: TRequestStatus& aStatus )=0; williamr@2: williamr@2: /** williamr@2: * Plays a MagSweep effect given in the parameters defining the effect. williamr@2: * williamr@2: * Synchronous method returns when the haptic command has been evaluated williamr@2: * and the return value is valid. williamr@2: * williamr@2: * @param[in] aEffect Reference to a struct defining the effect parameters. williamr@2: * @param[out] aEffectHandle Reference to the variable that receives williamr@2: * a handle to the playing effect. williamr@2: * williamr@2: * @return TInt KErrNone if successful, otherwise one of the other williamr@2: * system-wide error codes. williamr@2: * @return TInt KErrInUse when haptics is reserved for a higher or williamr@2: * equal priority client. williamr@2: * williamr@2: * @see THWRMHapticsMagSweepEffect for effect definition. williamr@2: * williamr@2: * @since S60 5.1 williamr@2: */ williamr@2: virtual TInt PlayMagSweepEffect( williamr@2: const CHWRMHaptics::THWRMHapticsMagSweepEffect& aEffect, williamr@2: TInt& aEffectHandle ) = 0; williamr@2: williamr@2: /** williamr@2: * @overload williamr@2: * williamr@2: * @param[out] aStatus Request status. On completion contains: williamr@2: * KErrNone, if successful, williamr@2: * KErrInUse when haptics is reserved for a higher or williamr@2: * equal priority client, williamr@2: * otherwise one of the other system-wide error codes. williamr@2: */ williamr@2: virtual void PlayMagSweepEffect( williamr@2: const CHWRMHaptics::THWRMHapticsMagSweepEffect& aEffect, williamr@2: TInt& aEffectHandle, williamr@2: TRequestStatus& aStatus ) = 0; williamr@2: williamr@2: /** williamr@2: * Plays a Periodic effect given in the parameters defining the effect. williamr@2: * williamr@2: * Synchronous method returns when the haptic command has been evaluated williamr@2: * and the return value is valid. williamr@2: * williamr@2: * @param[in] aEffect Reference to a struct defining the effect parameters. williamr@2: * @param[out] aEffectHandle Reference to the variable that receives williamr@2: * a handle to the playing effect. williamr@2: * williamr@2: * @return TInt KErrNone if successful, otherwise one of the other williamr@2: * system-wide error codes. williamr@2: * @return TInt KErrInUse when haptics is reserved for a higher or williamr@2: * equal priority client. williamr@2: * williamr@2: * @see THWRMHapticsPeriodicEffect for effect definition. williamr@2: * williamr@2: * @since S60 5.1 williamr@2: */ williamr@2: virtual TInt PlayPeriodicEffect( williamr@2: const CHWRMHaptics::THWRMHapticsPeriodicEffect& aEffect, williamr@2: TInt& aEffectHandle ) = 0; williamr@2: williamr@2: /** williamr@2: * @overload williamr@2: * williamr@2: * @param[out] aStatus Request status. On completion contains: williamr@2: * KErrNone, if successful, williamr@2: * KErrInUse when haptics is reserved for a higher or williamr@2: * equal priority client, williamr@2: * otherwise one of the other system-wide error codes. williamr@2: */ williamr@2: virtual void PlayPeriodicEffect( williamr@2: const CHWRMHaptics::THWRMHapticsPeriodicEffect& aEffect, williamr@2: TInt& aEffectHandle, williamr@2: TRequestStatus& aStatus ) = 0; williamr@2: williamr@2: /** williamr@2: * Pauses a playing effect. williamr@2: * williamr@2: * @param[in] aEffectHandle Handle to the playing effect to pause. williamr@2: * The handle to the effect must have been williamr@2: * obtained by calling williamr@2: * PlayMagSweepEffect(), williamr@2: * PlayPeriodicEffect() , williamr@2: * PlayEffect() , williamr@2: * PlayEffectRepeat() or williamr@2: * CreateStreamingEffect(). williamr@2: * williamr@2: * @return TInt KErrNone if successful, otherwise one of the other williamr@2: * system-wide error codes. williamr@2: * williamr@2: * @since S60 5.1 williamr@2: */ williamr@2: virtual TInt PausePlayingEffect( TInt aEffectHandle ) = 0; williamr@2: williamr@2: /** williamr@2: * Resumes playback on a paused effect from the point where williamr@2: * the effect was paused. williamr@2: * williamr@2: * Depending on the available slots, it is possible that all simple williamr@2: * effects from a paused effect data buffer or streaming sample cannot williamr@2: * be resumed. The API returns success when it is able to play one of williamr@2: * these simple effects. williamr@2: * williamr@2: * @param[in] aEffectHandle Handle to the paused effect to resume. williamr@2: * The handle to the effect must have been williamr@2: * obtained by calling williamr@2: * PlayMagSweepEffect(), williamr@2: * PlayPeriodicEffect(), williamr@2: * PlayEffect(), williamr@2: * PlayEffectRepeat() or williamr@2: * CreateStreamingEffect(). williamr@2: * williamr@2: * @return TInt KErrNone if successful, otherwise one of the other williamr@2: * system-wide error codes. williamr@2: * williamr@2: * @since S60 5.1 williamr@2: */ williamr@2: virtual TInt ResumePausedEffect( TInt aEffectHandle ) = 0; williamr@2: williamr@2: /** williamr@2: * Stops a playing effect. williamr@2: * williamr@2: * @param[in] aEffectHandle Handle to the playing effect to stop. williamr@2: * The handle to the effect must have been williamr@2: * obtained by calling williamr@2: * PlayMagSweepEffect(), williamr@2: * PlayPeriodicEffect(), williamr@2: * PlayEffect(), williamr@2: * PlayEffectRepeat() or williamr@2: * CreateStreamingEffect(). williamr@2: * williamr@2: * @return TInt KErrNone if successful, otherwise one of the other williamr@2: * system-wide error codes. williamr@2: * williamr@2: * @since S60 5.1 williamr@2: */ williamr@2: virtual TInt StopPlayingEffect( TInt aEffectHandle ) = 0; williamr@2: williamr@2: /** williamr@2: * Stops all playing and paused effects of a haptics instance. williamr@2: * williamr@2: * @return TInt KErrNone if successful, otherwise one of the other williamr@2: * system-wide error codes. williamr@2: * williamr@2: * @since S60 5.1 williamr@2: */ williamr@2: virtual TInt StopAllPlayingEffects() = 0; williamr@2: williamr@2: /** williamr@2: * Get a number of effects defined in a loaded effect data buffer. williamr@2: * williamr@2: * @param[in] aFileHandle Handle to the loaded effect data buffer. williamr@2: * @param[out] aCount Number of effects in the effect data buffer. williamr@2: * williamr@2: * @return TInt KErrNone if successful, otherwise one of the other williamr@2: * system-wide error codes. williamr@2: * williamr@2: * @since S60 5.1 williamr@2: */ williamr@2: virtual TInt GetEffectCount ( TInt aFileHandle, williamr@2: TInt& aCount ) const = 0; williamr@2: williamr@2: /** williamr@2: * Get the duration of an effect defined in a loaded effect data buffer. williamr@2: * williamr@2: * @param[in] aFileHandle Handle to the loaded effect data buffer. williamr@2: * @param[in] aEffectIndex Effect for which the duration is wanted. williamr@2: * @param[out] aEffectDuration Reference to the variable that receives williamr@2: * the requested effect's duration value. williamr@2: * Duration is in milliseconds. williamr@2: * williamr@2: * @return TInt KErrNone if successful, otherwise one of the other williamr@2: * system-wide error codes. williamr@2: * @since S60 5.1 williamr@2: */ williamr@2: virtual TInt GetEffectDuration ( TInt aFileHandle, williamr@2: TInt aEffectIndex, williamr@2: TInt& aEffectDuration ) const = 0; williamr@2: williamr@2: /** williamr@2: * Gets the index of an effect defined in a loaded effect data buffer williamr@2: * from the name of the effect. williamr@2: * williamr@2: * @param[in] aFileHandle Handle to the loaded effect data buffer. williamr@2: * @param[in] aEffectName Name of the effect for which the index is wanted. williamr@2: * @param[out] aEffectIndex Reference to the variable that receives williamr@2: * the requested effect's index value. williamr@2: * williamr@2: * @return TInt KErrNone if successful, otherwise one of the other williamr@2: * system-wide error codes. williamr@2: * williamr@2: * @since S60 5.1 williamr@2: */ williamr@2: virtual TInt GetEffectIndexFromName ( TInt aFileHandle, williamr@2: const TDesC8& aEffectName, williamr@2: TInt& aEffectIndex ) const = 0; williamr@2: williamr@2: /** williamr@2: * Gets the type of an effect defined in loaded effect data buffer. williamr@2: * williamr@2: * @param[in] aFileHandle Handle to loaded effect data buffer. williamr@2: * @param[in] aEffectIndex Index of an effect for which a type is wanted. williamr@2: * @param[out] aEffectType Reference to the variable that receives williamr@2: * the requested effect's type value. williamr@2: * williamr@2: * @return TInt KErrNone if successful, otherwise one of the other williamr@2: * system-wide error codes. williamr@2: * williamr@2: * @since S60 5.1 williamr@2: */ williamr@2: virtual TInt GetEffectType( TInt aFileHandle, williamr@2: TInt aEffectIndex, williamr@2: TInt& aEffectType ) const = 0; williamr@2: williamr@2: /** williamr@2: * Gets the name of an effect defined in a loaded effect data buffer. williamr@2: * williamr@2: * @param[in] aFileHandle Handle to the loaded effect data buffer. williamr@2: * @param[in] aEffectIndex Index of an effect for which a name is wanted. williamr@2: * @param[out] aEffectName Reference to the variable that receives williamr@2: * the requested effect's name. Note that the williamr@2: * descriptor's size must be at least the size williamr@2: * given from MaxPropertyStringLength(). williamr@2: * williamr@2: * @return TInt KErrNone if successful, otherwise one of the other williamr@2: * system-wide error codes. williamr@2: * williamr@2: * @since S60 5.1 williamr@2: */ williamr@2: virtual TInt GetEffectName( TInt aFileHandle, williamr@2: TInt aEffectIndex, williamr@2: TDes8& aEffectName ) const = 0; williamr@2: williamr@2: /** williamr@2: * Gets the parameters of a MagSweep effect defined in a loaded effect data williamr@2: * buffer. williamr@2: * williamr@2: * @param[in] aFileHandle Handle to the loaded effect data buffer. williamr@2: * @param[in] aEffectIndex Index of an effect for which a definition is williamr@2: * wanted. williamr@2: * @param[out] aEffect Reference to the variable that receives williamr@2: * the effect definition. williamr@2: * williamr@2: * @return TInt KErrNone if successful, otherwise one of the other williamr@2: * system-wide error codes. williamr@2: * williamr@2: * @see THWRMHapticsMagSweepEffect for effect definition. williamr@2: * williamr@2: * @since S60 5.1 williamr@2: */ williamr@2: virtual TInt GetMagSweepEffectDefinition( williamr@2: TInt aFileHandle, williamr@2: TInt aEffectIndex, williamr@2: CHWRMHaptics::THWRMHapticsMagSweepEffect& aEffect ) const = 0; williamr@2: williamr@2: /** williamr@2: * Gets the parameters of a periodic effect defined in a loaded effect data williamr@2: * buffer. williamr@2: * williamr@2: * @param[in] aFileHandle Handle to the loaded effect data buffer. williamr@2: * @param[in] aEffectIndex Index of an effect for which a definition is wanted. williamr@2: * @param[out] aEffect Reference to the variable that receives williamr@2: * the effect definition. williamr@2: * williamr@2: * @return TInt KErrNone if successful, otherwise one of the other williamr@2: * system-wide error codes. williamr@2: * williamr@2: * @see THWRMHapticsPeriodicEffect for effect definition. williamr@2: * williamr@2: * @since S60 5.1 williamr@2: */ williamr@2: virtual TInt GetPeriodicEffectDefinition( williamr@2: TInt aFileHandle, williamr@2: TInt aEffectIndex, williamr@2: CHWRMHaptics::THWRMHapticsPeriodicEffect& aEffect ) const = 0; williamr@2: williamr@2: /** williamr@2: * Gets the value that represents infinite repeats. Method may be used williamr@2: * only after an actuator has been opened successfully. williamr@2: * williamr@2: * @return TInt Value that represents infinite repeats. KErrNotReady, if williamr@2: * an actuator has not been opened. williamr@2: */ williamr@2: virtual TInt InfiniteRepeat() const = 0; williamr@2: williamr@2: /** williamr@2: * Gets the value that represents infinite duration. Method may be used williamr@2: * only after an actuator has been opened successfully. williamr@2: * williamr@2: * @return TInt Value that represents infinite duration. KErrNotReady, if williamr@2: * an actuator has not been opened. williamr@2: */ williamr@2: virtual TInt InfiniteDuration() const = 0; williamr@2: williamr@2: /** williamr@2: * Gets the maximum length of an effect name stored in a loaded williamr@2: * effect data file. Method may be used only after an actuator williamr@2: * has been opened successfully. williamr@2: * williamr@2: * @return TInt Maximum effect name length. KErrNotReady, if williamr@2: * an actuator has not been opened. williamr@2: */ williamr@2: virtual TInt MaxEffectNameLength() const = 0; williamr@2: williamr@2: /** williamr@2: * Gets the maximum device name length. Method may be used williamr@2: * only after an actuator has been opened successfully. williamr@2: * williamr@2: * @return TInt Maximum device name length. KErrNotReady, if williamr@2: * an actuator has not been opened. williamr@2: */ williamr@2: virtual TInt MaxDeviceNameLength() const = 0; williamr@2: williamr@2: /** williamr@2: * Gets the maximum capability string length. Method may be used williamr@2: * only after an actuator has been opened successfully. williamr@2: * williamr@2: * @return TInt Maximum capability string length. KErrNotReady, if williamr@2: * an actuator has not been opened. williamr@2: */ williamr@2: virtual TInt MaxCapabilityStringLength() const = 0; williamr@2: williamr@2: /** williamr@2: * Gets the maximum property string length. Method may be used williamr@2: * only after an actuator has been opened successfully. williamr@2: * williamr@2: * @return TInt Maximum property string length. KErrNotReady, if williamr@2: * an actuator has not been opened. williamr@2: */ williamr@2: virtual TInt MaxPropertyStringLength() const = 0; williamr@2: williamr@2: /** williamr@2: * Gets the maximum streaming sample size. Method may be used williamr@2: * only after an actuator has been opened successfully. williamr@2: * williamr@2: * @return TInt Maximum streaming sample size. KErrNotReady, if williamr@2: * an actuator has not been opened. williamr@2: */ williamr@2: virtual TInt MaxStreamingSampleSize() const = 0; williamr@2: williamr@2: /** williamr@2: * Gets the default device priority. Method may be used williamr@2: * only after an actuator has been opened successfully. williamr@2: * williamr@2: * @return TInt Default device property. KErrNotReady, if williamr@2: * an actuator has not been opened. williamr@2: */ williamr@2: virtual TInt DefaultDevicePriority() const = 0; williamr@2: }; williamr@2: williamr@2: #endif