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