/*

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

* All rights reserved.

* This component and the accompanying materials are made available

* under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members

* which accompanies this distribution, and is available

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

*

* Initial Contributors:

* Nokia Corporation - initial contribution.

*

* Contributors:

*

* Description:  This file contains the header of the 

*                CHWRMVibra class.

*

*/

#ifndef HWRMVIBRA_H

#define HWRMVIBRA_H

// INCLUDES

#include <e32base.h>

// CONSTANTS

/**

* Minimum allowed intensity setting for vibra. When intensity is negative, 

* the vibra motor rotates in the negative direction.

*/

const TInt KHWRMVibraMinIntensity = -100;

/**

* Minimum allowed intensity setting for vibra pulse.

*/

const TInt KHWRMVibraMinPulseIntensity = 1;

/**

* Maximum allowed intensity setting for vibra. When intensity is positive, 

* the vibra motor rotates in the positive direction. Value 0 effectively 

* stops the vibra.

*/

const TInt KHWRMVibraMaxIntensity = 100;

/**

* Maximum allowed duration value in milliseconds. Maximum vibrating time 

* supported by device is declared in KVibraCtrlMaxTime cenrep-key.

*

* Note that duration probably has device specific

* maximum duration that is much lower.

*/

const TInt KHWRMVibraMaxDuration = (KMaxTInt / 1000) - 1;

/**

* KHWRMVibraInfiniteDuration specifies, that vibrating should continue maximum 

* vibrating time supported by device if vibrating is not explicitly stopped.

*

*/

const TInt KHWRMVibraInfiniteDuration = 0;

// FORWARD DECLARATIONS

class MHWRMVibraObserver;

class MHWRMVibraFeedbackObserver;

// CLASS DECLARATIONS

/**

* The class used to control the device vibra.

*

* HW Resource Manager Vibra API is a library API providing ability to control

* the device vibra. The API provides also methods to retrieve the current settings

* of the vibration feature in the user profile and the current status of the vibra. 

*

* The type of HW Resource Manager Vibra API is a synchronous method call meaning 

* the method call will block the client application. However, e.g. StartVibraL methods do 

* return right after device vibration has successfully been started. Callback is intended only

* for observing vibra and feedback on/off changes. The API is meant for all 

* applications which need to control the device vibra.

*

* The API consist of the classes CHWRMVibra, MHWRMVibraObserver and MHWRMVibraFeedbackObserver. 

* If the client requires up-to-date status information, it should also provide callback pointer

* of the MHWRMVibraObserver implementing class for the NewL-method and explicitly set feedback observer.

*

* Usage:

*

* @code

* #include <HWRMVibra.h>  // link against HWRMVibraClient.lib

*

* // A CHWRMVibra instance can be created by using NewL() or NewLC() methods. 

* // Up-to-date status information not required, no callbacks.

* CHWRMVibra* vibra = CHWRMVibra::NewL();

*

* // After this, vibra can be directly controlled via the provided class methods. 

* vibra->StartVibraL(5000); // Start vibra for five seconds

* vibra->StopVibraL(); // Immediately stop vibra

*

* // To clean up, delete the created object:

* delete vibra;

* @endcode

*

*  @lib HWRMVIBRACLIENT.DLL

*  @since S60 3.0

*/

class CHWRMVibra : public CBase

    {

    public: // enums

        /**

        * Vibration setting in the user profile.

        */

        enum TVibraModeState 

            {

            EVibraModeUnknown = 0, ///< Not initialized yet or there is an error condion.

            EVibraModeON,          ///< Vibration setting in the user profile is on.

            EVibraModeOFF          ///< Vibration setting in the user profile is off.

            };

        /**

        * Status of the vibration feature

        */

        enum TVibraStatus 

            {

            EVibraStatusUnknown = 0, ///< Vibra is not initialized yet or status is uncertain 

                                     ///< because of an error condition.

            EVibraStatusNotAllowed,  ///< Vibra is set off in the user profile or some

                                     ///< application is specifically blocking vibra.

            EVibraStatusStopped,     ///< Vibra is stopped.

            EVibraStatusOn           ///< Vibra is on.

            };

        /**

        * Tactile feedback vibration setting in the user profile.

        */

        enum TVibraFeedbackModeState 

            {

            EVibraFeedbackModeUnknown = 0, ///< Not initialized yet or there is an error condion.

            EVibraFeedbackModeON,          ///< Feedback vibration setting in the user profile is on.

            EVibraFeedbackModeOFF          ///< Feedback vibration setting in the user profile is off.

            };

    public:  // Constructors

        /**

        * Two-phased constructor.

        *

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

        *

        * @leave KErrNotSupported Device doesn't support vibration feature.

        * @leave KErrNoMemory There is a memory allocation failure. 

        */

        IMPORT_C static CHWRMVibra* NewL();

        /**

        * Two-phased constructor.

        * Leaves instance to cleanup stack.

        *

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

        *

        * @leave KErrNotSupported Device doesn't support vibration feature.

        * @leave KErrNoMemory There is a memory allocation failure. 

        */

        IMPORT_C static CHWRMVibra* NewLC();

        /**

        * Two-phased constructor.

        * Use this method for creating a vibra client with callbacks.

        *

        * @param aCallback Pointer to callback instance

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

        *

        * @leave KErrNotSupported Device doesn't support vibration feature.

        * @leave KErrNoMemory There is a memory allocation failure. 

        */

        IMPORT_C static CHWRMVibra* NewL(MHWRMVibraObserver* aCallback);

        /**

        * Two-phased constructor. 

        * Use this method for creating a vibra client with callbacks.

        * Leaves instance to cleanup stack.

        *

        * @param aCallback Pointer to callback instance

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

        *

        * @leave KErrNotSupported Device doesn't support vibration feature.

        * @leave KErrNoMemory There is a memory allocation failure. 

        */

        IMPORT_C static CHWRMVibra* NewLC(MHWRMVibraObserver* aCallback);

    public: // New functions

    	/**

    	* Reserves vibration feature exclusively for this client.

    	* A higher priority (not process or thread priority, but the priority defined

    	* in the internal vibra policy of the HW Resource Manager) client may cause 

    	* lower priority client reservation to be temporarily suspended. Commands 

    	* can still be issued in suspended state, but they will not be acted upon 

    	* unless suspension is lifted within specified duration.

    	* The suspended client will not get any notification about suspension and

    	* neither from resumption of reservation.

    	* If vibra is already reserved by a higher or equal priority application, 

    	* reserving will still succeed, but reservation is immediately suspended.

    	*

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

    	* i.e. any previously frozen state will not be restored and CCoeEnv

    	* background/foreground status is always used to control further reservations.

    	*

    	* @leave KErrAccessDenied No CCoeEnv present.

    	* @leave KErrNotReady Trying to reserve while on background.

        * @leave KErrNoMemory There is a memory allocation failure. 

    	*/

    	virtual void ReserveVibraL()=0;

    	/**

    	* Reserves vibration feature exclusively for this client.

    	* A higher priority (not process or thread priority, but the priority defined

    	* in the internal vibra policy of the HW Resource Manager) client may cause 

    	* lower priority client reservation to be temporarily suspended. Commands 

    	* can still be issued in suspended state, but they will not be acted upon 

    	* unless suspension is lifted within specified duration.

    	* The suspended client will not get any notification about suspension and

    	* neither from resumption of reservation.

    	* If vibra is already reserved by a higher or equal priority application, 

    	* reserving will still succeed, but reservation is immediately suspended.

    	*

    	*

    	* @param aRestoreState If ETrue, the state frozen on last release will be

    	*                      restored upon successful reservation.

    	*                      I.e. if vibra was on when it was released by this 

        *                      client the last time, it would continue the vibrating

        *                      upon successful reservation.

    	*                      For the first reservation of each session this 

        *                      parameter is always considered EFalse regardless of 

        *                      what is supplied, as there is no previous frozen state

        *                      to restore.

    	* @param aForceNoCCoeEnv If EFalse, then reservation requires that this client

        *                        has the keyboard focus at the time of reservation and

        *                        vibra will be automatically released and re-reserved 

        *                        based on the keyboard focus status of this client. 

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

        *                        required.

    	*                        If ETrue, the client will not require CCoeEnv to be 

        *                        present nor does it automatically reserve/release vibra 

    	*                        by depending on foreground/background status of the 

        *                        client.

    	*                        Only trusted clients are allowed to set this flag to

        *                        ETrue. A client is considered trusted if it has nonstandard

        *                        priority defined in the internal vibra policy of the 

        *                        HW Resource Manager. A client can be defined trusted

        *                        only by S60 or a product.

    	*

    	* @leave KErrAccessDenied Parameter aForceNoCCoeEnv is ETrue and client is not

    	*                         trusted.

    	* @leave KErrBadHandle Parameter aForceNoCCoeEnv is EFalse and no CCoeEnv present.

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

        *                     aForceNoCCoeEnv is EFalse.

        * @leave KErrNoMemory There is a memory allocation failure. 

    	*/

    	virtual void ReserveVibraL(TBool aRestoreState, TBool aForceNoCCoeEnv)=0;

    	/**

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

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

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

    	* reservation, vibra is stopped.

    	*/

    	virtual void ReleaseVibra()=0;

        /**

        * Starts the device vibration feature with the product specific default

        * intensity.

        * If StartVibraL is called again before the first vibration completes

        * then the first vibration is interrupted and the second vibrations

        * starts immediately -- i.e. The periods of vibration are not cumulative.

        *

        * The vibration can be interrupted with the method StopVibraL before

        * the specified interval has elapsed. 

        *

        * Vibra settings of the vibration feature in the user profile 

        * must be active. 

        *

        * Note: The device may have implementation defined or hardware imposed

        *       limits to the duration of the vibration feature. In such 

        *       circumstances any vibration will cut off at that limit even if

        *       the duration parameter is greater than the limit.

        *

        * @param aDuration Duration of the vibration measured in milliseconds. 

        *                  A value of KHWRMVibraInfiniteDuration specifies that 

        *                  the vibration should continue indefinetely and should 

        *                  be stopped with a call to StopVibraL. Duration 

        *                  usually has device specific maximum value.

        *

        * @leave KErrArgument Duration is invalid.

        * @leave KErrAccessDenied Vibration setting in the user profile is not set.

        * @leave KErrBadHandle Vibra session has been invalidated.

        * @leave KErrLocked Vibra is locked down because too much continuous use

        *                   or explicitly blocked by for example some vibration 

        *                   sensitive accessory.

        * @leave KErrTimedOut Timeout occurred in controlling vibra.

        * @leave KErrInUse Vibra is not reserved to this client but it is

        *                  reserved to some other client.

        * @leave KErrNoMemory There is a memory allocation failure. 

        * @leave KErrGeneral There is a hardware error.

        *

        * @see MHWRMVibraObserver

        */

        virtual void StartVibraL(TInt aDuration)=0;

        /**

        * Starts the device vibration feature. If StartVibraL is called again before

        * the first vibration completes then the first vibration is interrupted

        * and the second vibrations starts immediately -- i.e. The periods of

        * vibration are not cumulative.

        *

        * The vibration can be interrupted with the method StopVibraL before

        * the specified interval has elapsed.

        *

        * Vibra settings of the vibration feature in the user profile 

        * must be active. 

        *

        * Note: The device may have implementation defined or hardware imposed

        *       limits to the duration of the vibration feature. In such 

        *       circumstances any vibration will cut off at that limit even if

        *       the duration parameter is greater than the limit.

        *

        * @param aDuration Duration of the vibration measured in milliseconds. 

        *                  A value of KHWRMVibraInfiniteDuration specifies that 

        *                  the vibration should continue indefinetely and should 

        *                  be stopped with a call to StopVibraL. Duration 

        *                  usually has device specific maximum value.

        * @param aIntensity Intensity of the vibra in decimal is KHWRMVibraMinIntensity

        *                   to KHWRMVibraMaxIntensity,

        *                   which shows the percentage of the vibra motor full

        *                   rotation speed. When intensity is negative, 

        *                   the vibra motor rotates in the negative direction.

        *                   When intensity is positive, the vibra motor rotates

        *                   in the positive direction. Value 0 stops the vibra.

        *                   NOTE: The device might have hardware-imposed limits

        *                         on supported vibra intensity values, so actual

        *                         effect might vary between different hardware.

        *

        * @leave KErrNotSupported The device doesn't support user-defined 

        *                         vibra intensity.

        * @leave KErrArgument One of the parameters is out of range.

        * @leave KErrAccessDenied Vibration setting in the user profile

        *                         is not set.

        * @leave KErrBadHandle Vibra session has been invalidated.

        * @leave KErrLocked Vibra is locked down because too much continuous use

        *                   or explicitly blocked by for example some vibration

        *                   sensitive accessory.

        * @leave KErrTimedOut Timeout occurred in controlling vibra.

        * @leave KErrInUse Vibra is not reserved to this client but it is

        *                  reserved to some other client.

        * @leave KErrNoMemory There is a memory allocation failure. 

        * @leave KErrGeneral There is a hardware error.

        *

        * @see MHWRMVibraObserver

        */

	    virtual void StartVibraL(TInt aDuration, TInt aIntensity)=0;

	    /**

        * Interrupts the device vibration that is started with the StartVibraL

        * method immediately.

        *

        * @leave KErrBadHandle Vibra session has been invalidated.

        * @leave KErrTimedOut Timeout occurred in controlling vibra.

        * @leave KErrInUse Vibra is not reserved to this client but it is

        *                  reserved to some other client.

        * @leave KErrNoMemory There is a memory allocation failure. 

        * @leave KErrGeneral There is a hardware error.

        *

        * @see MHWRMVibraObserver

        */		

        virtual void StopVibraL()=0; 

        /**

        * This method retrieves the current settings of the vibration feature

        * in the user profile. The developer can check the Vibra settings 

        * in the profile and if there is no Vibra active but it is needed by 

        * the client application then the user can be informed.

        *

        * @return TVibraModeState indicating the current vibra mode setting.

        *

        * @see TVibraModeState

        * @see MHWRMVibraObserver

        */

        virtual TVibraModeState VibraSettings() const=0;

        /**

        * This method retrieves the current vibra status. 

        *

        * @return TVibraStatus indicating the current vibra status

        * 

        * @see TVibraStatus

        * @see MHWRMVibraObserver

        */

        virtual TVibraStatus VibraStatus() const=0;

        /**

        * This method is intended only for firmware build time configured 

        * privileged clients.

        *

        * Executes a tactile feedback vibration pulse with product 

        * specific default intensity and duration.

        * If PulseVibraL is called before ongoing vibration completes and 

        * PulseVibraL calling client has higher priority than executing client,

        * pulse request is accepted. Also possible vibra-reservations are bypassed.

        * If client calling PulseVibraL has lower or equal priority 

        * than executing client, ongoing vibration is not affected.

        *

        * Tactile feedback vibration settings of the vibration feature in the 

        * user profile must be active. 

        *

        * Note: The device may have implementation defined or hardware imposed

        *       limits to the duration of the vibration feature. In such 

        *       circumstances any vibration will cut off at that limit even if

        *       the duration parameter is greater than the limit.

        *

        * @param aDuration Duration of the vibration measured in milliseconds. 

        *                  Duration can have maximum value

        *                  of KHWRMVibraMaxDuration.

        *

        * @leave KErrAccessDenied Vibration setting in the user profile is not set

        *                         or client is not privileged to use pulse feature. 

        * @leave KErrBadHandle Vibra session has been invalidated.

        * @leave KErrLocked Vibra is locked down because too much continuous use

        *                   or explicitly blocked by for example some vibration 

        *                   sensitive accessory.

        * @leave KErrTimedOut Timeout occurred in controlling vibra.

        * @leave KErrInUse Vibra is not reserved to this client but it is

        *                  reserved to some other client or ongoing vibration

        *                  has been requested by higher priority client.

        * @leave KErrNoMemory There is a memory allocation failure. 

        * @leave KErrGeneral There is a hardware error.

        *

        * @see MHWRMVibraFeedbackObserver

        */

        virtual void PulseVibraL()=0;

        /**

        * This method is intended only for firmware build time configured 

        * privileged clients.

        *

        * Executes a tactile feedback vibration pulse with product 

        * specific default intensity and specified duration.

        * If PulseVibraL is called before ongoing vibration completes and 

        * PulseVibraL calling client has higher priority than executing client,

        * pulse request is accepted. Also possible vibra-reservations are bypassed.

        * If client calling PulseVibraL has lower or equal priority 

        * than executing client, ongoing vibration is not affected.

        *

        * Tactile feedback vibration settings of the vibration feature in the 

        * user profile must be active. 

        *

        * Note: The device may have implementation defined or hardware imposed

        *       limits to the duration of the vibration feature. In such 

        *       circumstances any vibration will cut off at that limit even if

        *       the duration parameter is greater than the limit.

        *

        * @param aDuration Duration of the vibration measured in milliseconds. 

        *                  Duration can have maximum value

        *                  of KHWRMVibraMaxDuration.

        *

        * @leave KErrArgument One of the parameters is out of range.

        * @leave KErrAccessDenied Vibration setting in the user profile is not set

        *                         or client is not privileged to use pulse feature. 

        * @leave KErrBadHandle Vibra session has been invalidated.

        * @leave KErrLocked Vibra is locked down because too much continuous use

        *                   or explicitly blocked by for example some vibration 

        *                   sensitive accessory.

        * @leave KErrTimedOut Timeout occurred in controlling vibra.

        * @leave KErrInUse Vibra is not reserved to this client but it is

        *                  reserved to some other client or ongoing vibration

        *                  has been requested by higher priority client.

        * @leave KErrNoMemory There is a memory allocation failure. 

        * @leave KErrGeneral There is a hardware error.

        *

        * @see MHWRMVibraFeedbackObserver

        */

        virtual void PulseVibraL(TInt aDuration)=0;

        /**

        * This method is intended only for firmware build time configured 

        * privileged clients.

        *

        * Executes a tactile feedback vibration pulse.

        * If PulseVibraL is called before ongoing vibration completes and 

        * PulseVibraL calling client has higher priority than executing client,

        * pulse request is accepted. Also possible vibra-reservations are bypassed.

        * If client calling PulseVibraL has lower or equal priority 

        * than executing client, ongoing vibration is not affected.

        *

        * Tactile feedback vibration settings of the vibration feature in the 

        * user profile must be active. 

        *