/*

* Copyright (c) 2006-2009 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:

*

*/

#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.

*

* @publishedAll

* @released

*/

const TInt KHWRMVibraMinIntensity = -100;

/**

* Minimum allowed intensity setting for vibra pulse.

*

* @publishedAll

* @released

*/

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.

* @publishedAll

* @released

*/

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.

*

* @publishedAll

* @released

*/

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

/**

* KHWRMVibraInfiniteDuration specifies, that vibrating should continue maximum 

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

*

*

* @publishedAll

* @released

*/

const TInt KHWRMVibraInfiniteDuration = 0;

class MHWRMVibraObserver;

class MHWRMVibraFeedbackObserver;

/**

* 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. The API is meant for all 

* applications which need to control the device vibra.

*

* The API consist of the classes CHWRMVibra and MHWRMVibraObserver. If the client

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

* of the MHWRMVibraObserver implementing class for the NewL-method.

*

* Usage:

*

* @code

* #include <hwrmvibra.h> 

*

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

*

* @publishedAll

* @released

*/

class CHWRMVibra : public CBase

    {

    public: // enums

        /**

        * Vibration setting in the user profile.

        */

        enum TVibraModeState 

            {

            /**

            Not initialized yet or there is an error condion.

            */

            EVibraModeUnknown = 0, 

            /**

            Vibration setting in the user profile is on.

            */

            EVibraModeON,          

            /**

            Vibration setting in the user profile is off.

            */

            EVibraModeOFF        

            };

        /**

        * Status of the vibration feature

        */

        enum TVibraStatus 

            {

            /**

            Vibra is not initialized yet or status is uncertain because of an error condition.

            */

            EVibraStatusUnknown = 0, 

            /**

            Vibra is set off in the user profile or some application is specifically blocking vibra.

            */ 

            EVibraStatusNotAllowed,  

            /**

            Vibra is stopped.

            */            

            EVibraStatusStopped,     

            /**

            Vibra is on.

            */

            EVibraStatusOn          

            };

        /**

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

        /**

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

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

    	* 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 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 0 specifies that the vibration should

        *                  continue indefinetely and should be stopped with a 

        *                  call to StopVibraL. Duration can have maximum value

        *                  of KHWRMVibraMaxDuration.

        *

        * @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 0 specifies that the vibration should

        *                  continue indefinitly and should be stopped with a 

        *                  call to StopVibraL.  Duration can have maximum value

        *                  of KHWRMVibraMaxDuration.

        * @param aIntensity Intensity of the vibra in decimal is -100 to 100,

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

        *

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

        * @param aIntensity Intensity of the pulse in decimal is KHWRMVibraMinPulseIntensity

        *                   to KHWRMVibraMaxIntensity, which shows the percentage 

        *                   of the vibra motor full rotation speed. 

        *                   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

        *                         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, TInt aIntensity)=0;

        /**

        * Use this method for setting feedback observer.

        *

        * @param aCallback Pointer to callback instance

        */

        virtual void SetFeedbackObserver(MHWRMVibraFeedbackObserver* aCallback)=0;

        /**

        * This method retrieves the current settings of the feedback vibration feature

        * in the user profile. The developer can check the feedback vibration settings 

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

        * the client application then the user can be informed. However, client needs to 

        * explicitly register to listen these changes via SetFeedbackObserver-method.

        *

        * @return TVibraFeedbackModeState indicating the current vibra feedback mode setting.

        *

        * @see TVibraFeedbackModeState

        * @see MHWRMVibraFeedbackObserver

        */

        virtual TVibraFeedbackModeState VibraFeedbackSettings() const=0;

    };

/**

* A callback interface for vibra status reporting.

*

* If the client requires up-to-date status information, the client needs 

* to derive a class from the MHWRMVibraObserver interface and implement 

* the VibraModeChanged() and VibraStatusChanged() methods. 

* 

* A callback object header example:

*

* @code 

* // INCLUDES

* #include <hwrmvibra.h> // Link against HWRMVibraClient.lib.

*

* class CTest : public CBase, 

*               public MHWRMVibraObserver    

*    {

*    public:

*        CTest();

*        ~CTest();

*                       

*        void ConstructL();

*        static CTest* NewL();

*                

*        // from MHWRMVibraObserver

*        virtual void VibraModeChanged(CHWRMVibra::TVibraModeState aStatus);

*        virtual void VibraStatusChanged(CHWRMVibra::TVibraStatus aStatus);

*

*    private:

*        CHWRMVibra* iVibra;

*    };

* @endcode

*

* A callback method implementation example:

*

* @code

* void CTest::VibraStatusChanged(CHWRMVibra::TVibraStatus aStatus)

*    {

*    switch ( aStatus )

*        {

*        case CHWRMVibra::EVibraStatusUnknown:

*            RDebug::Print(_L("### Vibra state changed: EVibraStatusUnknown"));

*            break;

*        case CHWRMVibra::EVibraStatusNotAllowed:

*            RDebug::Print(_L("### Vibra state changed: EVibraStatusNotAllowed"));

*            break;

*        case CHWRMVibra::EVibraStatusStopped:

*            RDebug::Print(_L("### Vibra state changed: EVibraStatusStopped"));

*            break;

*        case CHWRMVibra::EVibraStatusOn:

*            RDebug::Print(_L("### Vibra state changed: EVibraStatusOn"));

*            break;

*        default:

*            RDebug::Print(_L("### Vibra state changed: UNDEFINED !"));

*            break;

*        }

*    }

* @endcode

*

* @publishedAll

* @released

*/

class MHWRMVibraObserver

    {    

    public:

        /** 

        * Called when the vibration setting in the user profile is changed.

        *

        * @param aStatus Indicates the new setting.

        *

        * @see CHWRMVibra::TVibraModeState

        */

        virtual void VibraModeChanged(CHWRMVibra::TVibraModeState aStatus) = 0;

        /** 

        * Called when the device vibration feature state changes

        *

        * @param aStatus Indicates vibra status.

        *

        * @see CHWRMVibra::TVibraStatus

		*/

        virtual void VibraStatusChanged(CHWRMVibra::TVibraStatus aStatus) = 0;

	};

/**

*

* @publishedAll

* @released

*/

class MHWRMVibraFeedbackObserver

    {    

    public:

        /** 

        * Called when the tactile feedback vibration setting in the user profile is changed.

        *

        * @param aMode Indicates the new setting.

        *

        * @see CHWRMVibra::TVibraFeedbackModeState

        */

        virtual void VibraFeedbackModeChanged(CHWRMVibra::TVibraFeedbackModeState aMode) = 0;

	};

#endif      // HWRMVIBRA_H   

// End of File