1 /*

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

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

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

     6 * which accompanies this distribution, and is available

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

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

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

    15 *

    16 */

    17 

    18 

    19 #ifndef C_HWRMHAPTICS_H

    20 #define C_HWRMHAPTICS_H

    21 

    22 #include <e32base.h>

    23 #include <hwrmlogicalactuators.h>

    24 #include <hwrmhapticsobserver.h>

    25 #include <hwrmhapticsactuatorobserver.h>

    26 

    27 /** Minimum magnitude value. */

    28 const TInt KHWRMHapticsMinMagnitude = 0;

    29 

    30 /** Maximum magnitude value. */

    31 const TInt KHWRMHapticsMaxMagnitude = 10000;

    32 

    33 /**

    34 * Minimum device priority.

    35 *

    36 * To be used with SetDeviceProperty().

    37 */

    38 const TInt KHWRMHapticsMinDevicePriority = 0;

    39 

    40 /**

    41 * Maximum device priority.

    42 *

    43 * To be used with SetDeviceProperty().

    44 */

    45 const TInt KHWRMHapticsMaxDevicePriority = 15;

    46 

    47 

    48 /** Minimum strength value. */

    49 const TInt KHWRMHapticsMinStrength = 0;

    50 

    51 /** Maximum strength value. */

    52 const TInt KHWRMHapticsMaxStrength = 10000;

    53 

    54 

    55  /**

    56  * The class used to control the device's haptics feature.

    57  *

    58  * The Haptics API provides the ability to control the device's haptics feature.

    59  * The API provides methods for receiving the current status and effect

    60  * completion of the haptics. The API provides synchronous and asynchronous

    61  * versions of playing methods due to the nature of effect playing

    62  * where multiple calls may be made to play effects.

    63  * Synchronous methods are provided for other API functionality.

    64  * They will block the calling client during their execution.

    65  * The API is meant for all applications which need to control the

    66  * device's haptics feature.

    67  *

    68  * The API consist of the class CHWRMHaptics and related observer classes:

    69  * MHWRMHapticsObserver and MHWRMHapticsActuatorObserver. If the client

    70  * requires up-to-date status information, it can be achieved by deriving

    71  * the client from MHWRMHapticsObserver or MHWRMHapticsActuatorObserver or 

    72  * from both and providing a callback pointer(s) of the implementing class

    73  * for the NewL() method.

    74  *

    75  * @code

    76  *

    77  * // ===================================================================

    78  * // Usage example 1:

    79  * //    - Setting the license key.

    80  * //    - Playing a periodic effect

    81  * //    - Preconditions:

    82  * //        - Haptics feature must be enabled by the system.

    83  * // ===================================================================

    84  *

    85  * #include <hwrmhaptics.h>          // link against hwrmhapticsclient.lib

    86  * #include <hwrmlogicalactuators.h> // enumeration of logical actuators

    87  *

    88  * TInt minPeriod( 0 );

    89  * TInt effectHandle( 0 );

    90  * TInt suppAct( 0 );

    91  *

    92  * CHWRMHaptics* haptics = CHWRMHaptics::NewL( NULL, NULL );

    93  *

    94  * haptics->SupportedActuators( suppAct );

    95  *

    96  * if( EHWRMLogicalActuatorDevice & suppAct )

    97  *     {

    98  *     haptics->OpenActuatorL( EHWRMLogicalActuatorDevice )

    99  *     }

   100  * else if ( EHWRMLogicalActuatorAny & suppAct )

   101  *     {

   102  *     haptics->OpenActuatorL( EHWRMLogicalActuatorAny )

   103  *     }

   104  *

   105  *

   106  * // 3rd party developers can obtain the license key from Forum Nokia

   107  * _LIT8( KLicenseKey,"_this_value_must_be_32_in_length" );

   108  *

   109  * User::LeaveIfError(

   110  *     haptics->SetDeviceProperty( 

   111  *         THWRMHapticsDevicePropertyTypes::EHWRMHapticsLicenseKey,

   112  *         KLicenseKey ) );

   113  *

   114  * // --> now playing effects is possible

   115  *

   116  * THWRMHapticsPeriodicEffect periodicEff;

   117  *

   118  * periodicEff.iDuration = 5000;

   119  * periodicEff.iMagnitude = 5000;

   120  * periodicEff.iPeriod = minPeriod;

   121  * periodicEff.iStyle = EHWRMHapticsStyleSharp;

   122  * periodicEff.iAttackTime = 250;

   123  * periodicEff.iAttackLevel = 10000;

   124  * periodicEff.iFadeTime = 250;

   125  * periodicEff.iFadeLevel = 0;

   126  *

   127  * haptics->PlayPeriodicEffect( periodicEff, effectHandle );

   128  *

   129  * // ... something happened in the application and it has lost focus

   130  * // so stop the effect immediately

   131  *

   132  * haptics->StopPlayingEffect( effectHandle );

   133  *

   134  * // ================================================================

   135  * // Usage example 2:

   136  * //    - Loading effect data from a file and playing effects from the

   137  * //      loaded data.

   138  * //    - Preconditions:

   139  * //        - license key is set

   140  * //    - Recommended usage style:

   141  * //        - Effect data file can contain definition(s) of periodic

   142  * //          effects, magsweep effects or a combination of these basic

   143  * //          types called timeline effects, which call basic effects in

   144  * //          sequence thus forming new more complex effects.

   145  * //        - Load the effect data once in the client application.

   146  * //        - Play effects from the loaded data using the effectIndex

   147  * // ================================================================

   148  *

   149  * // Use S60 FileSystem to load the effect data file to a buffer

   150  *

   151  * ...

   152  *

   153  * // Effect data has been read into a descriptor by the user.

   154  * // Load the effect data to be used by the haptic subsystem.

   155  * TInt fileHandle( 0 );

   156  * User::LeaveIfError( haptics->LoadEffectData( data, fileHandle ) );

   157  * 

   158  * TInt effectIndex = 0;

   159  * TInt hapticsStatus = haptics->PlayEffect( fileHandle,

   160  *                                              effectIndex,

   161  *                                              effectHandle );

   162  *                                                

   163  * hapticsStatus = haptics->DeleteEffectData( fileHandle );

   164  *

   165  * if( KErrNone != hapticsStatus )

   166  *     {

   167  *     // do some error handling...

   168  *     }

   169  *

   170  * delete haptics;

   171  * haptics = NULL;

   172  *

   173  * @endcode

   174  *

   175  * Common error codes returned by the Haptics API methods.

   176  *

   177  * KErrArgument Argument is invalid, e.g., malformatted effect data, or too

   178  *              large magnitude value.

   179  * KErrAccessDenied The license key is not set when trying to use some

   180  *                  haptics method.

   181  * KErrNoMemory There is insufficient memory available for the method to 

   182  *              complete.

   183  * KErrNotReady Initialization has not been done properly when trying to use

   184  *              a haptics method.

   185  *

   186  * @lib hwrmhapticsclient.dll

   187  * @since S60 5.1

   188  */

   189 

   190  class CHWRMHaptics : public CBase

   191   {

   192 public:

   193 

   194     /**

   195     * Defines the paramaters used in a magsweep effect.

   196     *

   197     * Used by

   198     * PlayMagSweepEffect(),

   199     * ModifyPlayingMagSweepEffect(),

   200     * GetMagSweepEffectDefinition().

   201     */

   202     struct THWRMHapticsMagSweepEffect

   203         {

   204         /**

   205         * Duration of the effect. Unit is milliseconds.

   206         *

   207         * To specify an infinite duration, the effect duration

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

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

   210         * from 0 to the value returned by GetDeviceCapability()

   211         * for the EHWRMHapticsMaxEffectDuration capability type.

   212         */

   213         TInt iDuration;

   214 

   215         /**

   216         * Magnitude of the effect.

   217         *

   218         * The effect magnitude is clamped to a value from 

   219         * KHWRMHapticsMinMagnitude to KHWRMHapticsMaxMagnitude.

   220         */

   221         TInt iMagnitude;

   222 

   223         /**

   224         * Style of the effect.

   225         *

   226         * Can be one of THWRMHapticsEffectStyles.

   227         */

   228         TInt iStyle;

   229 

   230         /**

   231         * Attack time of the effect. Unit is milliseconds.

   232         *

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

   234         * by GetDeviceCapability() for the EHWRMHapticsMaxEnvelopeTime

   235         * capability type.

   236         */

   237         TInt iAttackTime;

   238 

   239         /**

   240         * Attack level of the effect.

   241         *

   242         * The attack level is clamped to a value from KHWRMHapticsMinMagnitude

   243         * to KHWRMHapticsMaxMagnitude.

   244         */

   245         TInt iAttackLevel;

   246 

   247         /**

   248         * Fade time of the effect. Unit is milliseconds.

   249         *

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

   251         * by GetDeviceCapability() for the EHWRMHapticsMaxEnvelopeTime

   252         * capability type.

   253         */

   254         TInt iFadeTime;

   255 

   256         /**

   257         * Fade level of the effect.

   258         *

   259         * The fade level is clamped to a value from KHWRMHapticsMinMagnitude

   260         * to KHWRMHapticsMaxMagnitude inclusive.

   261         */

   262         TInt iFadeLevel;

   263         };

   264 

   265     /**

   266     * Defines the parameters used in a periodic effect.

   267     *

   268     * Used by

   269     * PlayPeriodicEffect(),

   270     * ModifyPlayingPeriodicEffect(),

   271     * GetPeriodicEffectDefinition().

   272     */

   273     struct THWRMHapticsPeriodicEffect

   274         {

   275         /**

   276         * Duration of the effect. Unit is milliseconds.

   277         *

   278         * To specify an infinite duration, the effect duration

   279         * should be set to InfiniteDuration().

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

   281         * from 0 to the value returned by GetDeviceCapability()

   282         * for the EHWRMHapticsMaxEffectDuration capability type.

   283         */

   284         TInt iDuration;

   285 

   286         /**

   287         * Magnitude of the effect.

   288         *

   289         * The effect magnitude is clamped to a value from

   290         * KHWRMHapticsMinMagnitude to KHWRMHapticsMaxMagnitude.

   291         */

   292         TInt iMagnitude;

   293 

   294         /**

   295         * Period of the effect. Unit is milliseconds.

   296         *

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

   298         * for EHWRMHapticsMinPeriod capability type to the value returned

   299         * by GetDeviceCapability() for the EHWRMHapticsMaxEnvelopeTime

   300         * capability type.

   301         */

   302         TInt iPeriod;

   303 

   304         /**

   305         * Style of the effect.

   306         *

   307         * Can be one of THWRMHapticsEffectStyles.

   308         */

   309         TInt iStyle;

   310 

   311         /**

   312         * Attack time of the effect. Unit is milliseconds.

   313         *

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

   315         * by GetDeviceCapability() for the EHWRMHapticsMaxEnvelopeTime

   316         * capability type.

   317         */

   318         TInt iAttackTime;

   319 

   320         /**

   321         * Attack level of the effect.

   322         *

   323         * The attack level is clamped to a value from KHWRMHapticsMinMagnitude

   324         * to KHWRMHapticsMaxMagnitude.

   325         */

   326         TInt iAttackLevel;

   327 

   328         /**

   329         * Fade time of the effect. Unit is milliseconds.

   330         *

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

   332         * by GetDeviceCapability() for the EHWRMHapticsMaxEnvelopeTime

   333         * capability type.

   334         */

   335         TInt iFadeTime;

   336 

   337         /**

   338         * Fade level of the effect.

   339         *

   340         * The fade level is clamped to a value from KHWRMHapticsMinMagnitude

   341         * to KHWRMHapticsMaxMagnitude.

   342         */

   343         TInt iFadeLevel;

   344         };

   345 

   346     /**

   347     * THWRMHapticsDevicePropertyTypes enumeration

   348     * Use SetDeviceProperty() to set properties for the haptics

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

   350     */

   351     enum THWRMHapticsDevicePropertyTypes

   352         {

   353         /**

   354         * License key property. Usable with SetDeviceProperty() only.

   355         * Use const TDesC8& overloaded version of the method.

   356         *

   357         * Setting this property to a valid license key unlocks the haptics

   358         * subsystem in the device. Setting this property to an invalid

   359         * license key locks the haptics in the device (for this client). 

   360         * The haptics in the device are locked from clients by default.

   361         * When haptics is locked, all haptics related operations on the 

   362         * device, except for setting the license key and closing the device,

   363         * fail.

   364         * Haptics must be unlocked on a per instance basis.

   365         */

   366         EHWRMHapticsLicensekey = 0,

   367 

   368         /**

   369         * Property used to set/get the priority for effects to played for

   370         * the given haptics instance (i.e., for the given client).

   371         *

   372         * Use TInt overloaded version of the methods SetDeviceProperty()and

   373         * GetDeviceProperty() to use this property.

   374         *

   375         * Different haptics instances can use different priorities

   376         * on the same physical device. The priority determines which haptics

   377         * instance's effects are played when multiple haptics instances

   378         * are attempting to play effects at the same time.

   379         * The default priority is DefaultDevicePriority().

   380         * Priority values can range from KHWRMHapticsMinDevicePriority

   381         * to KHWRMHapticsMaxDevicePriority.

   382         * GetDeviceProperty() returns a value inside

   383         * TInt& aDevicePropertyValue in the range of 

   384         * KHWRMHapticsMinDevicePriority

   385         * to KHWRMHapticsMaxDevicePriority. If the client has not set

   386         * the EHWRMHapticsPriority property GetDeviceProperty() returns

   387         * a value of DefaultDevicePriority().

   388         */

   389         EHWRMHapticsPriority,

   390 

   391         /**

   392         * Property used to disable effects for the client's haptics instance.

   393         *

   394         * Use TBool overloaded version of the methods SetDeviceProperty() and

   395         * GetDeviceProperty() to use this property.

   396         *

   397         * When this property is set to true, any playing effects are

   398         * immediately stopped and subsequent requests to play

   399         * effects are ignored. Applies to the calling client's

   400         * haptics instance only. When this property is set to false,

   401         * subsequent requests to play effects are honored.

   402         * The default value for this property is false.

   403         */

   404         EHWRMHapticsDisableEffects,

   405 

   406         /**

   407         * A property that reduces/increases the magnitude of all effects

   408         * for a particular haptics instance.

   409         *

   410         * Use TInt overloaded version of the methods SetDeviceProperty()and

   411         * GetDeviceProperty() to use this property.

   412 

   413         * Strength values can vary from KHWRMHapticsMinStrength ("mute")

   414         * to KHWRMHapticsMaxStrength.

   415         * The default value for EHWRMHapticsStrength is 

   416         * KHWRMHapticsMaxStrength. If the EHWRMHapticsStrength property is

   417         * not set, the default value is used.

   418         * When reducing/increasing the magnitude of the effects by setting

   419         * the EHWRMHapticsStrength property, it only applies to the haptics

   420         * instance of the client which called the function. If there is a

   421         * second haptics instance held by the same or a different client,

   422         * it is not affected by the setting of the EHWRMHapticsStrength

   423         * property of the first client's haptics instance.

   424         *

   425         * Modifying the EHWRMHapticsStrength property of the haptics instance

   426         * does not affect currently playing effects, only effects played or

   427         * modified after calling the SetDeviceProperty() method using the new

   428         * EHWRMHapticsStrength value.

   429         */

   430         EHWRMHapticsStrength,

   431 

   432         /**

   433         * A property that reduces/increases the magnitude of all effects

   434         * for all haptics instances (whole device).

   435         *

   436         * Use TInt overloaded version of the methods SetDeviceProperty()and

   437         * GetDeviceProperty() to use this property.

   438         *

   439         * Strength values can vary from KHWRMHapticsMinStrength ("mute")

   440         * to KHWRMHapticsMaxStrength.

   441         * The default value for Master Strength is KHWRMHapticsMaxStrength.

   442         * If the client does not set the EHWRMHapticsMasterStrength property

   443         * of the haptics instance, the default value is used.

   444         * When reducing/increasing the magnitude of the effects,

   445         * EHWRMHapticsMasterStrength property affects all playing effects on

   446         * all haptics instances (whole device).

   447         * This means that all the haptics instances, held by other

   448         * clients are affected by the setting of EHWRMHapticsMasterStrength

   449         * property of the first client's haptics instance.

   450         *

   451         * The client which wants to set the EHWRMHapticsMasterStrength

   452         * property must have a haptics instance that has a maximum effect

   453         * priority.

   454         * The haptics client instance must set itself to a maximum priority

   455         * by calling SetDeviceProperty() using EHWRMHapticsPriority property

   456         * type and KMaxDevicePriority value before changing the

   457         * EHWRMHapticsMasterStrength property's value.

   458         *

   459         * Note: A licensee license key, provided to licensees only,

   460         * changes the EHWRMHapticsMasterStrength property.

   461         * A call to SetDeviceProperty( EHWRMHapticsMasterStrength, aValue )

   462         * always returns KErrAccessDenied for haptics instances that are

   463         * not using a licensee license key.

   464         */

   465         EHWRMHapticsMasterStrength

   466         };

   467 

   468     /**

   469     * Device's capability types.

   470     *

   471     * Use TInt& aDeviceCapabilityValue overloaded version of the

   472     * method GetDeviceCapability() unless otherwise mentioned.

   473     */

   474     enum THWRMHapticsDeviceCapabilityTypes

   475         {

   476         /**

   477         * Device category. See THWRMHapticsDeviceCategory enumeration defined

   478         * later in this API header for possible values.

   479         */

   480         EHWRMHapticsDeviceCategory = 0,

   481 

   482         /**

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

   484         *

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

   486         */

   487         EHWRMHapticsMaxNestedRepeats,

   488 

   489         /**

   490         * Number of vibration actuators present in the device.

   491         */

   492         EHWRMHapticsNumActuators,

   493 

   494         /**

   495         * Actuator type See THWRMHapticsActuatorType enumeration defined

   496         * later in this API header for possible values.

   497         */

   498         EHWRMHapticsActuatorType,

   499 

   500         /**

   501         * Number of effect slots.

   502         *

   503         * The number of effect slots represents the maximum number

   504         * of simple effects that can play simultaneously.

   505         * If an attempt is made to play more than this number of effects

   506         * at the same time, some of the simple effects do not play.

   507         */

   508         EHWRMHapticsNumEffectSlots,

   509 

   510         /**

   511         * Supported effect styles, stored as a bitfield. See

   512         * THWRMHapticsSupportedEffectStyles enumeration defined later in this

   513         * API header for possible values.

   514         */

   515         EHWRMHapticsSupportedStyles,

   516 

   517         /**

   518         * Minimum period for Periodic effects.

   519         */

   520         EHWRMHapticsMinPeriod,

   521 

   522         /**

   523         * Maximum period for Periodic effects.

   524         */

   525         EHWRMHapticsMaxPeriod,

   526 

   527         /**

   528         * Maximum duration for MagSweep and Periodic effects measured

   529         * in milliseconds.

   530         */

   531         EHWRMHapticsMaxEffectDuration,

   532 

   533         /**

   534         * Supported effect types. Stored as a bitfield. See 

   535         * THWRMHapticsSupportedEffectTypes enumeration defined later in this

   536         * API header for possible values.

   537         */

   538         EHWRMHapticsSupportedEffects,

   539 

   540         /**

   541         * Device name.

   542         *

   543         * Use TDes8& aDeviceCapabilityValue overloaded version of the

   544         * method GetDeviceCapability().

   545         */

   546         EHWRMHapticsDeviceName,

   547 

   548         /**

   549         * Maximum start time or fade time in milliseconds for

   550         * effect envelopes of MagSweep or periodic effects.

   551         */

   552         EHWRMHapticsMaxEnvelopeTime,

   553 

   554         /**

   555         * Version number of the physical haptics player in the device in

   556         * hexadecimal format.

   557         *

   558         * The format is OxMMNNSSBB, where MM is the major

   559         * version number, NN is the minor version number,

   560         * SS is a special build number and BB is the VTMP build number.

   561         * For example, for the hexadecimal format 0x02000053 the version

   562         * number is 2.0.83

   563         */

   564         EHWRMHapticsAPIVersionNumber,

   565 

   566         /**

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

   568         * on a non-tethered device. 

   569         */

   570         EHWRMHapticsMaxEffectDataSize = 14

   571         };

   572 

   573     /**

   574     * Device category.

   575     */

   576     enum THWRMHapticsDeviceCategory

   577         {

   578         EHWRMHapticsVirtual = 2,

   579         EHWRMHapticsEmbedded = 3,

   580         };

   581 

   582     /**

   583     * Bitmask for effect support.

   584     *

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

   586     */

   587     enum THWRMHapticsSupportedEffectTypes

   588         {

   589         EHWRMHapticsSupportPeriodic = 1,

   590         EHWRMHapticsSupportMagSweep = 2,

   591         EHWRMHapticsSupportTimeline = 4,

   592         EHWRMHapticsSupportStreaming = 8

   593         };

   594 

   595     /**

   596     * Effect types

   597     */

   598     enum THWRMHapticsEffectTypes

   599         {

   600         EHWRMHapticsTypePeriodic = 0,

   601         EHWRMHapticsTypeMagSweep,

   602         EHWRMHapticsTypeTimeline,

   603         EHWRMHapticsTypeStreaming

   604         };

   605 

   606     /**

   607     * Bitmask for supported effect styles.

   608     *

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

   610     */

   611     enum THWRMHapticsSupportedEffectStyles

   612         {

   613         EHWRMHapticsSupportSmooth = 1,

   614         EHWRMHapticsSupportStrong = 2,

   615         EHWRMHapticsSupportSharp  = 4

   616         };

   617 

   618     /**

   619     * Effect styles

   620     *

   621     * Used to specify Periodic or MagSweep effect style when calling

   622     * PlayMagSweepEffect(),

   623     * PlayPeriodicEffect(),

   624     * ModifyPlayingMagSweepEffect() and

   625     * ModifyPlayingPeriodicEffect().

   626     */

   627     enum THWRMHapticsEffectStyles

   628         {

   629         EHWRMHapticsStyleSmooth = 0,

   630         EHWRMHapticsStyleStrong,

   631         EHWRMHapticsStyleSharp

   632         };

   633 

   634     /**

   635     * Actuator types.

   636     *

   637     * To be used with GetDeviceCapability().

   638     */

   639     enum THWRMHapticsActuatorTypes

   640         {

   641         /**

   642         * Eccentric Rotating Mass actuator

   643         */

   644         EHWRMHapticsTypeERM = 0,

   645 

   646         /**

   647         * Linear Resonant actuator

   648         */

   649         EHWRMHapticsTypeLRA = 2

   650         };

   651 

   652     /**

   653     * Effect states.

   654     *

   655     * As returned in a call to GetEffectState().

   656     */

   657     enum THWRMHapticsEffectStates

   658         {

   659         EHWRMHapticsEffectNotPlaying = 0,

   660         EHWRMHapticsEffectPlaying,

   661         EHWRMHapticsEffectPaused

   662         };

   663 

   664     /**

   665     * Two-phased constructor.

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

   667     *

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

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

   670     *

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

   672     *

   673     * @since S60 5.1

   674     */

   675     IMPORT_C static CHWRMHaptics* NewL( 

   676         MHWRMHapticsObserver* aHapticsCallback,

   677         MHWRMHapticsActuatorObserver* aActuatorCallback );

   678     

   679     /**

   680     * @overload

   681     *

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

   683     *                     KErrNone, if successful,

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

   685     */

   686     IMPORT_C static CHWRMHaptics* NewL( 

   687         MHWRMHapticsObserver* aHapticsCallback,

   688         MHWRMHapticsActuatorObserver* aActuatorCallback,

   689         TRequestStatus& aStatus );

   690 

   691     /**

   692     * Method for opening a logical actuator for use.

   693     *

   694     * This method must be called before using any other methods of this class,

   695     * except when using GetXXX methods.

   696     * The Haptics API supports a limited number of instances of CHWRMHaptics 

   697     * class.

   698     * If all instances are currently in use, the next attempt to call

   699     * OpenActuatorL() from any client fails.

   700     * Applications should not use more instances than necessary as this

   701     * may prevent other applications from instantiating the CHWRMHaptics

   702     * class.

   703     *

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

   705     *                  wants to use.

   706     *

   707     * @leave TInt KErrNotSupported, if the used logical actuator is not

   708     *              supported by the system.

   709     * @leave TInt KErrAlreadyExists, if the used logical actuator is already

   710     *              opened.

   711     * @leave TInt KErrInUse, if some other actuator is already opened.

   712     * @leave TInt KErrArgument, if aActuator is not valid enumeration value.

   713     *

   714     * @see THWRMLogicalActuators for a list of usable actuators.

   715     *

   716     * @since S60 5.1

   717     */

   718     virtual void OpenActuatorL( THWRMLogicalActuators aActuator ) = 0;

   719 

   720     /**

   721     * Method for getting a bitmask value of supported logical actuators.

   722     *

   723     * Developer needs to evaluate the returned bitmask against

   724     * THWRMLogicalActuators enumeration values to know the

   725     * supported logical actuators.

   726     *

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

   728     *

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

   730     *              system-wide error codes.

   731     *

   732     * @see THWRMLogicalActuators for a list of usable actuators.

   733     *

   734     * @since S60 5.1

   735     */

   736     virtual TInt SupportedActuators( TUint32& aActuators ) = 0;

   737 

   738     /**

   739     * Reserves haptics feature exclusively for this client.

   740     * A higher priority client may cause lower priority client reservation

   741     * to be temporarily suspended. The suspended client does not get 

   742     * any notification about suspension. If haptics is already reserved 

   743     * by a higher or equal priority client, reserving still succeeds,

   744     * but reservation is immediately suspended. When the reservation 

   745     * is suspended, playing effects do not actually cause the effects to be 

   746     * played. 

   747     * Note: Unless the client has instantiated the Haptics API with the status

   748     * observer, it does not receive any notifications about the fact that its 

   749     * effects are not actually played by the physical player when the client

   750     * has been suspended by a higher priority reservation.

   751     * Note also that even if haptics is reserved by some client, a higher 

   752     * priority client succeeds in playing its effects.

   753     *

   754     * Calling this method is equal to call ReserveHapticsL(EFalse),

   755     * i.e. CCoeEnv background/foreground status is always used

   756     * to control further reservations.

   757     */

   758     virtual void ReserveHapticsL() = 0;

   759 

   760     /**

   761     * Reserves haptics feature exclusively for this client.

   762     * A higher priority client may cause lower priority client reservation

   763     * to be temporarily suspended. The suspended client does not get 

   764     * any notifications about suspension. If haptics is already reserved 

   765     * by a higher or equal priority client, reserving still succeeds,

   766     * but reservation is immediately suspended. When the reservation 

   767     * is suspended, playing effects does not actually cause the effects to be 

   768     * played.

   769     * Note: Unless the client has instantiated the Haptics API with the status

   770     * observer, it does not receive any notifications about the fact that its 

   771     * effects are not actually played by the physical player when the client

   772     * has been suspended by a higher priority reservation.

   773     * Note also that even if haptics is reserved by some client, a higher 

   774     * priority client succeeds in playing its effects.

   775     *

   776     * @param aForceNoCCoeEnv If EFalse, then reservation requires that

   777     *                        this client has the keyboard focus at the time of

   778     *                        reservation and haptics is automatically

   779     *                        released and re-reserved based on the keyboard

   780     *                        focus status of this client.

   781     *                        This also implies that CCoeEnv::Static() != NULL

   782     *                        is required.

   783     *                        If ETrue, the client does not require CCoeEnv to

   784     *                        be present nor does it automatically reserve or

   785     *                        release haptics by depending on the foreground or

   786     *                        background status of the client. Only trusted

   787     *                        clients are allowed to set this flag to ETrue.

   788     *                        The client application is considered trusted if 

   789     *                it has a priority defined in haptics policy file.                              *                The policy files can be modified by S60 licensees.

   790     *

   791     * @leave KErrAccessDenied Parameter aForceNoCCoeEnv is ETrue

   792     *                         and client is not trusted.

   793     * @leave KErrBadHandle Parameter aForceNoCCoeEnv is EFalse

   794     *                      and no CCoeEnv present.

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

   796     *                     aForceNoCCoeEnv is EFalse.

   797     * @leave KErrNoMemory There is a memory allocation failure.

   798     */

   799     virtual void ReserveHapticsL( TBool aForceNoCCoeEnv ) = 0;

   800 

   801     /**

   802     * Releases haptics feature if it was previously reserved for this client.

   803     *

   804     * If this client has not reserved haptics feature, does nothing.

   805     * If haptics is on when it is released and no other client has a suspended

   806     * reservation, haptics is stopped.

   807     */

   808     virtual void ReleaseHaptics() = 0;

   809 

   810     /**

   811     * This method retrieves the current haptics status.

   812     *

   813     * @return THWRMHapticsStatus indicating the current haptics status

   814     *

   815     * @see THWRMHapticsStatus

   816     */

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

   818 

   819     /**

   820     * Sets a property of the haptics.

   821     *

   822     * Some properties affect all haptics instances, some only

   823     * the current instance of the haptics. More about that can be found

   824     * in THWRMHapticsDevicePropertyTypes.

   825     *

   826     * @param[in] aDevicePropertyType Property type for the

   827     *            property to be set.

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

   829     *

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

   831     *              system-wide error codes.

   832     *

   833     * @see THWRMHapticsDevicePropertyTypes for a list of valid property types

   834     *

   835     * @since S60 5.1

   836     */

   837     virtual TInt SetDeviceProperty( TInt aDevicePropertyType,

   838                                     TInt aDevicePropertyValue ) = 0;

   839 

   840     /**

   841     * @overload

   842     */

   843     virtual TInt SetDeviceProperty( TInt aDevicePropertyType,

   844                                     const TDesC8& aDevicePropertyValue ) = 0;

   845 

   846     /**

   847     * Gets a property value of the haptics.

   848     *

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

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

   851     *                                  receives the requested property

   852     *                                  value of the device.

   853     *

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

   855     *              system-wide error codes.

   856     *

   857     * @see THWRMHapticsDevicePropertyTypes for a list of the valid property

   858     *      types.

   859     *

   860     * @since S60 5.1

   861     */

   862     virtual TInt GetDeviceProperty( TInt aDevicePropertyType,

   863                                     TInt& aDevicePropertyValue ) = 0;

   864 

   865     /**

   866     * @overload

   867     *

   868     * @return KErrNone if successful, 

   869     *         KErrArgument if the length of the given string is less 

   870     *         than MaxPropertyStringLength(), 

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

   872     */

   873     virtual TInt GetDeviceProperty( TInt aDevicePropertyType,

   874                                     TDes8& aDevicePropertyValue ) = 0;

   875 

   876     /**

   877     * Gets a capability value of the haptics.

   878     *

   879     * @param[in] aDeviceCapabilityType Capability type of the

   880     *                                  capability to get.

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

   882     *                                    receives the requested capability

   883     *                                    value of the device.

   884     *

   885     * @return TInt KErrNone if successful, 

   886     *              KErrNotReady if no actuator has been opened,

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

   888     *

   889     * @see THWRMHapticsDeviceCapabilityTypes

   890     *

   891     * @since S60 5.1

   892     */

   893     virtual TInt GetDeviceCapability( TInt aDeviceCapabilityType,

   894                                       TInt& aDeviceCapabilityValue ) = 0;

   895 

   896     /**

   897     * @overload

   898     * 

   899     * @return TInt KErrNone if successful, 

   900     *              KErrNotReady if no actuator has been opened,

   901     *              KErrArgument if the length of the given string is less 

   902     *              than MaxCapabilityStringLength(), 

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

   904     */

   905     virtual TInt GetDeviceCapability( TInt aDeviceCapabilityType,

   906                                       TDes8& aDeviceCapabilityValue ) = 0;

   907 

   908     /**

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

   910     *

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

   912     *                          obtained by calling

   913     *                          PlayMagSweepEffect(),

   914     *                          PlayPeriodicEffect(),

   915     *                          PlayEffect(),

   916     *                          PlayEffectRepeat() or

   917     *                          CreateStreamingEffect()

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

   919     *                          the status bits of the effect.

   920     *

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

   922     *              system-wide error codes.

   923     *

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

   925     *

   926     * @since S60 5.1

   927     */

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

   929 

   930     /**

   931     * Creates a streaming effect.

   932     *

   933     * Client calls CreateStreamingEffect() to create a new streaming

   934     * effect and gets a new handle for it; it should use that effect handle

   935     * to play a streaming sample by calling PlayStreamingSample().

   936     *

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

   938     *                           a handle to the streaming effect.

   939     *

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

   941     *              system-wide error codes.

   942     *

   943     * @since S60 5.1

   944     */

   945     virtual TInt CreateStreamingEffect( TInt& aEffectHandle ) = 0;

   946 

   947     /**

   948     * Plays a streaming sample given in the parameter defining the effect.

   949     *

   950     * Streaming sample can only be played after calling

   951     * CreateStreamingEffect() and by using the effecthandle it returns.

   952     *

   953     * Synchronous method returns when the haptic command has been evaluated

   954     * and the return value is valid.

   955     *

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

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

   958     *                             containing the definition of

   959     *                             the effect to play.

   960     *

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

   962     *              system-wide error codes.

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

   964     *              equal priority client.

   965     *

   966     * @since S60 5.1

   967     */

   968     virtual TInt PlayStreamingSample( TInt aEffectHandle,

   969                                       const TDesC8& aStreamingSample ) = 0;

   970     /**

   971     * @overload

   972     *

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

   974     *                     KErrNone, if successful,

   975     *                     KErrInUse when haptics is reserved for a higher or 

   976     *                     equal priority client,

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

   978     */

   979     virtual void PlayStreamingSample( TInt aEffectHandle,

   980                                       const TDesC8& aStreamingSample,

   981                                       TRequestStatus& aStatus ) = 0;

   982 

   983     /**

   984     * Plays a streaming sample with a time offset given in the parameters

   985     * defining the effect.

   986     *

   987     * Client calls CreateStreamingEffect() to create a new streaming

   988     * effect and gets a new handle for it; it should use that effect handle

   989     * to play the streaming sample with this method.

   990     *

   991     * Synchronous method returns when the haptic command has been evaluated

   992     * and the return value is valid.

   993     *

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

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

   996     *                             containing the definition of the

   997     *                             effect to play.

   998     * @param[in] aOffsetTime For aOffsetTime values that are greater than 0,

   999     *                        playback is delayed for aOffsetTime

  1000     *                        in milliseconds.

  1001     *                        For aOffsetTime values that are less than 0,

  1002     *                        sample playback begins in offset time

  1003     *                        in milliseconds into the current sample.

  1004     *

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

  1006     *              system-wide error codes.

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

  1008     *              equal priority client.

  1009     *

  1010     * @since S60 5.1

  1011     */

  1012     virtual TInt PlayStreamingSampleWithOffset( TInt aEffectHandle,

  1013         const TDesC8& aStreamingSample,

  1014         TInt aOffsetTime ) = 0;

  1015 

  1016     /**

  1017     * @overload

  1018     *

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

  1020     *                     KErrNone, if successful,

  1021     *                     KErrInUse when haptics is reserved for a higher or 

  1022     *                     equal priority client,

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

  1024     */

  1025     virtual void PlayStreamingSampleWithOffset( TInt aEffectHandle,

  1026         const TDesC8& aStreamingSample,

  1027         TInt aOffsetTime,

  1028         TRequestStatus& aStatus ) = 0;

  1029 

  1030     /**

  1031     * Destroys a streaming effect previously created in a successful

  1032     * call to CreateStreamingEffect().

  1033     *

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

  1035     *

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

  1037     *              system-wide error codes.

  1038     *

  1039     * @since S60 5.1

  1040     */

  1041     virtual TInt DestroyStreamingEffect( TInt aEffectHandle ) = 0;

  1042 

  1043     /**

  1044     * Modifies a playing MagSweep effect.

  1045     *

  1046     * Synchronous method returns when the haptic command has been evaluated

  1047     * and the return value is valid.

  1048     *

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

  1050     *                          to modify. The handle to the effect must have

  1051     *                          been obtained by calling

  1052     *                          PlayMagSweepEffect(),

  1053     *                          PlayEffect() or

  1054     *                          PlayEffectRepeat().

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

  1056     *

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

  1058     *              system-wide error codes.

  1059     *

  1060     * @see THWRMHapticsMagSweepEffect for effect definition.

  1061     *

  1062     * @since S60 5.1

  1063     */

  1064     virtual TInt ModifyPlayingMagSweepEffect( TInt aEffectHandle,

  1065         const CHWRMHaptics::THWRMHapticsMagSweepEffect& aEffect ) = 0;

  1066 

  1067     /**

  1068     * @overload

  1069     *

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

  1071     *                     KErrNone, if successful,

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

  1073     */

  1074     virtual void ModifyPlayingMagSweepEffect( TInt aEffectHandle,

  1075         const CHWRMHaptics::THWRMHapticsMagSweepEffect& aEffect,

  1076         TRequestStatus& aStatus ) = 0;

  1077 

  1078     /**

  1079     * Modifies a playing periodic effect.

  1080     *

  1081     * Synchronous method returns when the haptic command has been evaluated

  1082     * and the return value is valid.

  1083     *

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

  1085     *                          to modify. The handle to the effect must have

  1086     *                          been obtained by calling

  1087     *                          PlayPeriodicEffect(),

  1088     *                          PlayEffect() or

  1089     *                          PlayEffectRepeat().

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

  1091     *

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

  1093     *              system-wide error codes.

  1094     *

  1095     * @see THWRMHapticsPeriodicEffect for effect definition.

  1096     *

  1097     * @since S60 5.1

  1098     */

  1099     virtual TInt ModifyPlayingPeriodicEffect( TInt aEffectHandle,

  1100         const CHWRMHaptics::THWRMHapticsPeriodicEffect& aEffect ) = 0;

  1101 

  1102     /**

  1103     * @overload

  1104     *

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

  1106     *                     KErrNone, if successful,

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

  1108     */

  1109     virtual void ModifyPlayingPeriodicEffect( TInt aEffectHandle,

  1110         const CHWRMHaptics::THWRMHapticsPeriodicEffect& aEffect,

  1111         TRequestStatus& aStatus ) = 0;

  1112 

  1113 

  1114     /**

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

  1116     * file containing the effect data).

  1117     *

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

  1119     *

  1120     * @param[out] aFileHandle On return contains a handle to the passed

  1121     *                         effect data. This handle is haptics specific,

  1122     *                         i.e., it is not a file system handle but just

  1123     *                         a handle to the loaded effect data buffer.

  1124     *

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

  1126     *              system-wide error codes.

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

  1128     *

  1129     * @since S60 5.1

  1130     */

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

  1132 

  1133     /**

  1134     * Delete loaded effect data referenced by file handle.