/*

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

* All rights reserved.

* This component and the accompanying materials are made available

* under the terms of "Eclipse Public License v1.0"

* which accompanies this distribution, and is available

* at the URL "http://www.eclipse.org/legal/epl-v10.html".

*

* Initial Contributors:

* Nokia Corporation - initial contribution.

*

* Contributors:

*

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

*

*/

#ifndef C_HWRMHAPTICS_H

#define C_HWRMHAPTICS_H

#include <e32base.h>

#include <hwrmlogicalactuators.h>

#include <hwrmhapticsobserver.h>

#include <hwrmhapticsactuatorobserver.h>

/** Minimum magnitude value. */

const TInt KHWRMHapticsMinMagnitude = 0;

/** Maximum magnitude value. */

const TInt KHWRMHapticsMaxMagnitude = 10000;

/**

* Minimum device priority.

*

* To be used with SetDeviceProperty().

*/

const TInt KHWRMHapticsMinDevicePriority = 0;

/**

* Maximum device priority.

*

* To be used with SetDeviceProperty().

*/

const TInt KHWRMHapticsMaxDevicePriority = 15;

/** Minimum strength value. */

const TInt KHWRMHapticsMinStrength = 0;

/** Maximum strength value. */

const TInt KHWRMHapticsMaxStrength = 10000;

 /**

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

 *

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

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

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

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

 * where multiple calls may be made to play effects.

 * Synchronous methods are provided for other API functionality.

 * They will block the calling client during their execution.

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

 * device's haptics feature.

 *

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

 * MHWRMHapticsObserver and MHWRMHapticsActuatorObserver. If the client

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

 * the client from MHWRMHapticsObserver or MHWRMHapticsActuatorObserver or 

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

 * for the NewL() method.

 *

 * @code

 *

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

 * // Usage example 1:

 * //    - Setting the license key.

 * //    - Playing a periodic effect

 * //    - Preconditions:

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

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

 *

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

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

 *

 * TInt minPeriod( 0 );

 * TInt effectHandle( 0 );

 * TInt suppAct( 0 );

 *

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

 *

 * haptics->SupportedActuators( suppAct );

 *

 * if( EHWRMLogicalActuatorDevice & suppAct )

 *     {

 *     haptics->OpenActuatorL( EHWRMLogicalActuatorDevice );

 *     }

 * else if ( EHWRMLogicalActuatorAny & suppAct )

 *     {

 *     haptics->OpenActuatorL( EHWRMLogicalActuatorAny );

 *     }

 *

 *

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

 * _LIT8( KLicenseKey,"_this_value_must_be_32_in_length" );

 *

 * User::LeaveIfError(

 *     haptics->SetDeviceProperty( 

 *         THWRMHapticsDevicePropertyTypes::EHWRMHapticsLicenseKey,

 *         KLicenseKey ) );

 *

 * // --> now playing effects is possible

 *

 * CHWRMHaptics::THWRMHapticsPeriodicEffect periodicEff;

 *

 * periodicEff.iDuration = 5000;

 * periodicEff.iMagnitude = 5000;

 * periodicEff.iPeriod = minPeriod;

 * periodicEff.iStyle = CHWRMHaptics::EHWRMHapticsStyleSharp;

 * periodicEff.iAttackTime = 250;

 * periodicEff.iAttackLevel = 10000;

 * periodicEff.iFadeTime = 250;

 * periodicEff.iFadeLevel = 0;

 *

 * haptics->PlayPeriodicEffect( periodicEff, effectHandle );

 *

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

 * // so stop the effect immediately

 *

 * haptics->StopPlayingEffect( effectHandle );

 *

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

 * // Usage example 2:

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

 * //      loaded data.

 * //    - Preconditions:

 * //        - license key is set

 * //    - Recommended usage style:

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

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

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

 * //          sequence thus forming new more complex effects.

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

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

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

 *

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

 *

 * ...

 *

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

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

 * TInt fileHandle( 0 );

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

 * 

 * TInt effectIndex = 0;

 * TInt hapticsStatus = haptics->PlayEffect( fileHandle,

 *                                              effectIndex,

 *                                              effectHandle );

 *                                                

 * hapticsStatus = haptics->DeleteEffectData( fileHandle );

 *

 * if( KErrNone != hapticsStatus )

 *     {

 *     // do some error handling...

 *     }

 *

 * delete haptics;

 * haptics = NULL;

 *

 * @endcode

 *

 * Common error codes returned by the Haptics API methods.

 *

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

 *              large magnitude value.

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

 *                  haptics method.

 * KErrNoMemory There is insufficient memory available for the method to 

 *              complete.

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

 *              a haptics method.

 *

 * @lib hwrmhapticsclient.dll

 * @since S60 5.1

 */

 class CHWRMHaptics : public CBase

  {

public:

    /**

    * Defines the paramaters used in a magsweep effect.

    *

    * Used by

    * PlayMagSweepEffect(),

    * ModifyPlayingMagSweepEffect(),

    * GetMagSweepEffectDefinition().

    */

    struct THWRMHapticsMagSweepEffect

        {

        /**

        * Duration of the effect. Unit is milliseconds.

        *

        * To specify an infinite duration, the effect duration

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

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

        * from 0 to the value returned by GetDeviceCapability()

        * for the EHWRMHapticsMaxEffectDuration capability type.

        */

        TInt iDuration;

        /**

        * Magnitude of the effect.

        *

        * The effect magnitude is clamped to a value from 

        * KHWRMHapticsMinMagnitude to KHWRMHapticsMaxMagnitude.

        */

        TInt iMagnitude;

        /**

        * Style of the effect.

        *

        * Can be one of THWRMHapticsEffectStyles.

        */

        TInt iStyle;

        /**

        * Attack time of the effect. Unit is milliseconds.

        *

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

        * by GetDeviceCapability() for the EHWRMHapticsMaxEnvelopeTime

        * capability type.

        */

        TInt iAttackTime;

        /**

        * Attack level of the effect.

        *

        * The attack level is clamped to a value from KHWRMHapticsMinMagnitude

        * to KHWRMHapticsMaxMagnitude.

        */

        TInt iAttackLevel;

        /**

        * Fade time of the effect. Unit is milliseconds.

        *

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

        * by GetDeviceCapability() for the EHWRMHapticsMaxEnvelopeTime

        * capability type.

        */

        TInt iFadeTime;

        /**

        * Fade level of the effect.

        *

        * The fade level is clamped to a value from KHWRMHapticsMinMagnitude

        * to KHWRMHapticsMaxMagnitude inclusive.

        */

        TInt iFadeLevel;

        };

    /**

    * Defines the parameters used in a periodic effect.

    *

    * Used by

    * PlayPeriodicEffect(),

    * ModifyPlayingPeriodicEffect(),

    * GetPeriodicEffectDefinition().

    */

    struct THWRMHapticsPeriodicEffect

        {

        /**

        * Duration of the effect. Unit is milliseconds.

        *

        * To specify an infinite duration, the effect duration

        * should be set to InfiniteDuration().

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

        * from 0 to the value returned by GetDeviceCapability()

        * for the EHWRMHapticsMaxEffectDuration capability type.

        */

        TInt iDuration;

        /**

        * Magnitude of the effect.

        *

        * The effect magnitude is clamped to a value from

        * KHWRMHapticsMinMagnitude to KHWRMHapticsMaxMagnitude.

        */

        TInt iMagnitude;

        /**

        * Period of the effect. Unit is milliseconds.

        *

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

        * for EHWRMHapticsMinPeriod capability type to the value returned

        * by GetDeviceCapability() for the EHWRMHapticsMaxEnvelopeTime

        * capability type.

        */

        TInt iPeriod;

        /**

        * Style of the effect.

        *

        * Can be one of THWRMHapticsEffectStyles.

        */

        TInt iStyle;

        /**

        * Attack time of the effect. Unit is milliseconds.

        *

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

        * by GetDeviceCapability() for the EHWRMHapticsMaxEnvelopeTime

        * capability type.

        */

        TInt iAttackTime;

        /**

        * Attack level of the effect.

        *

        * The attack level is clamped to a value from KHWRMHapticsMinMagnitude

        * to KHWRMHapticsMaxMagnitude.

        */

        TInt iAttackLevel;

        /**

        * Fade time of the effect. Unit is milliseconds.

        *

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

        * by GetDeviceCapability() for the EHWRMHapticsMaxEnvelopeTime

        * capability type.

        */

        TInt iFadeTime;

        /**

        * Fade level of the effect.

        *

        * The fade level is clamped to a value from KHWRMHapticsMinMagnitude

        * to KHWRMHapticsMaxMagnitude.

        */

        TInt iFadeLevel;

        };

    /**

    * THWRMHapticsDevicePropertyTypes enumeration

    * Use SetDeviceProperty() to set properties for the haptics

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

    */

    enum THWRMHapticsDevicePropertyTypes

        {

        /**

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

        * Use const TDesC8& overloaded version of the method.

        *

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

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

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

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

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

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

        * fail.

        * Haptics must be unlocked on a per instance basis.

        */

        EHWRMHapticsLicensekey = 0,

        /**

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

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

        *

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

        * GetDeviceProperty() to use this property.

        *

        * Different haptics instances can use different priorities

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

        * instance's effects are played when multiple haptics instances

        * are attempting to play effects at the same time.

        * The default priority is DefaultDevicePriority().

        * Priority values can range from KHWRMHapticsMinDevicePriority

        * to KHWRMHapticsMaxDevicePriority.

        * GetDeviceProperty() returns a value inside

        * TInt& aDevicePropertyValue in the range of 

        * KHWRMHapticsMinDevicePriority

        * to KHWRMHapticsMaxDevicePriority. If the client has not set

        * the EHWRMHapticsPriority property GetDeviceProperty() returns

        * a value of DefaultDevicePriority().

        */

        EHWRMHapticsPriority,

        /**

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

        *

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

        * GetDeviceProperty() to use this property.

        *

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

        * immediately stopped and subsequent requests to play

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

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

        * subsequent requests to play effects are honored.

        * The default value for this property is false.

        */

        EHWRMHapticsDisableEffects,

        /**

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

        * for a particular haptics instance.

        *

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

        * GetDeviceProperty() to use this property.

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

        * to KHWRMHapticsMaxStrength.

        * The default value for EHWRMHapticsStrength is 

        * KHWRMHapticsMaxStrength. If the EHWRMHapticsStrength property is

        * not set, the default value is used.

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

        * the EHWRMHapticsStrength property, it only applies to the haptics

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

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

        * it is not affected by the setting of the EHWRMHapticsStrength

        * property of the first client's haptics instance.

        *

        * Modifying the EHWRMHapticsStrength property of the haptics instance

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

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

        * EHWRMHapticsStrength value.

        */

        EHWRMHapticsStrength,

        /**

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

        * for all haptics instances (whole device).

        *

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

        * GetDeviceProperty() to use this property.

        *

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

        * to KHWRMHapticsMaxStrength.

        * The default value for Master Strength is KHWRMHapticsMaxStrength.

        * If the client does not set the EHWRMHapticsMasterStrength property

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

        * When reducing/increasing the magnitude of the effects,

        * EHWRMHapticsMasterStrength property affects all playing effects on

        * all haptics instances (whole device).

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

        * clients are affected by the setting of EHWRMHapticsMasterStrength

        * property of the first client's haptics instance.

        *

        * The client which wants to set the EHWRMHapticsMasterStrength

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

        * priority.

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

        * by calling SetDeviceProperty() using EHWRMHapticsPriority property

        * type and KMaxDevicePriority value before changing the

        * EHWRMHapticsMasterStrength property's value.

        *

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

        * changes the EHWRMHapticsMasterStrength property.

        * A call to SetDeviceProperty( EHWRMHapticsMasterStrength, aValue )

        * always returns KErrAccessDenied for haptics instances that are

        * not using a licensee license key.

        */

        EHWRMHapticsMasterStrength

        };

    /**

    * Device's capability types.

    *

    * Use TInt& aDeviceCapabilityValue overloaded version of the

    * method GetDeviceCapability() unless otherwise mentioned.

    */

    enum THWRMHapticsDeviceCapabilityTypes

        {

        /**

        * Device category. See THWRMHapticsDeviceCategory enumeration defined

        * later in this API header for possible values.

        */

        EHWRMHapticsDeviceCategory = 0,

        /**

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

        *

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

        */

        EHWRMHapticsMaxNestedRepeats,

        /**

        * Number of vibration actuators present in the device.

        */

        EHWRMHapticsNumActuators,

        /**

        * Actuator type See THWRMHapticsActuatorType enumeration defined

        * later in this API header for possible values.

        */

        EHWRMHapticsActuatorType,

        /**

        * Number of effect slots.

        *

        * The number of effect slots represents the maximum number

        * of simple effects that can play simultaneously.

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

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

        */

        EHWRMHapticsNumEffectSlots,

        /**

        * Supported effect styles, stored as a bitfield. See

        * THWRMHapticsSupportedEffectStyles enumeration defined later in this

        * API header for possible values.

        */

        EHWRMHapticsSupportedStyles,

        /**

        * Minimum period for Periodic effects.

        */

        EHWRMHapticsMinPeriod,

        /**

        * Maximum period for Periodic effects.

        */

        EHWRMHapticsMaxPeriod,

        /**

        * Maximum duration for MagSweep and Periodic effects measured

        * in milliseconds.