/*

 * 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