/*
* 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.
*
* 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
*
* @since S60 3.0
*/
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;
};
/**
* A callback interface for tactile feedback vibra mode reporting.
*
* If the client requires up-to-date status information, the client needs
* to derive a class from the MHWRMVibraFeedbackObserver interface and implement
* the VibraFeedbackModeChanged() method. In order to register for callback, client
* needs to call SetFeedbackObserver-method.
*
* A callback object header example:
*
* @code
* // INCLUDES
* #include <HWRMVibra.h> // Link against HWRMVibraClient.lib.
*
* class CTest : public CBase,
* public MHWRMVibraFeedbackObserver
* {
* public:
* CTest();
* ~CTest();
*
* void ConstructL();
* static CTest* NewL();
*
* // from MHWRMVibraFeedbackObserver
* virtual void VibraFeedbackModeChanged(CHWRMVibra::TVibraFeedbackModeState aMode);
*
* private:
* CHWRMVibra* iVibra;
* };
* @endcode
*
* A callback method implementation example:
*
* @code
*
* #include <HWRMVibra.h> // link against HWRMVibraClient.lib
*
* // A CHWRMVibra instance can be created by using NewL() or NewLC() methods.
* CHWRMVibra* vibra = CHWRMVibra::NewL();
*
* // Request notification of feedback setting change
* vibra->SetFeedbackObserver(this);
*
* // To clean up, delete the created object:
* delete vibra;
*
* void CTest::VibraFeedbackModeChanged(CHWRMVibra::TVibraFeedbackModeState aMode)
* {
* switch ( aMode )
* {
* case CHWRMVibra::EVibraFeedbackModeUnknown:
* RDebug::Print(_L("### Feedback vibration mode : EVibraFeedbackModeUnknown"));
* break;
* case CHWRMVibra::EVibraFeedbackModeON:
* RDebug::Print(_L("### Feedback vibration mode : EVibraFeedbackModeON"));
* break;
* case CHWRMVibra::EVibraFeedbackModeOFF:
* RDebug::Print(_L("### Feedback vibration mode : EVibraFeedbackModeOFF"));
* break;
* default:
* break;
* }
* }
* @endcode
*
* @since S60 5.0
*/
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