diff -r 000000000000 -r 4e1aa6a622a0 resourcemgmt/vibractrl/inc/vibractrl.h --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/resourcemgmt/vibractrl/inc/vibractrl.h Tue Feb 02 00:53:00 2010 +0200 @@ -0,0 +1,261 @@ +/* +* Copyright (c) 2003-2005 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: Vibra Control API +* +*/ + + +#ifndef VIBRA_CTRL_H__ +#define VIBRA_CTRL_H__ + +// INCLUDES +#include +#include + +/** + * Interface that is used to control the device vibration feature. + * This class provides the ability to control the device vibration feature. + * Vibration might be used in a game to signal a collision or explosion or for + * giving tactile feedback to gaming events, such as a ball hitting + * a wall (shaking). + * + * @lib VibraCtrl.DLL + * @since 2.0 + * @deprecated since Series 60 3.0 - Use HWRM Vibra API instead (HWRMVibra.h) + */ +class CVibraControl : public CBase + { + public: + /** + * Vibration setting in the user profile. + * @deprecated since Series 60 3.0 + */ + enum TVibraModeState + { + EVibraModeON = 0, // Vibration setting in the user profile is on. + EVibraModeOFF, // Vibration setting in the user profile is off. + EVibraModeUnknown // For debugging/development and signalling an error condition. + }; + + /** + * Status of the vibrating setting request. + * @deprecated since Series 60 3.0 + */ + enum TVibraRequestStatus + { + EVibraRequestOK = 0, // Request is OK. + EVibraRequestFail, // Request has failed. + EVibraRequestNotAllowed, // Vibra is set off in the user profile + EVibraRequestStopped, // Vibra is stopped + EVibraRequestUnableToStop,// Unable to stop vibra + EVibraRequestUnknown // For debugging/development and signalling an error condition. + }; + + /** + * Internal panic codes. + * @deprecated since Series 60 3.0 + */ + enum TVibraCtrlPanic + { + EPanicUnableToGetVibraSetting, + EPanicVibraGeneral + }; + + public: + /** + * Destructor. + * @deprecated since Series 60 3.0 + */ + virtual ~CVibraControl(); + + /** + * Starts the device vibration feature with factory-defined intensity. + * The method does not block, but returns immediately so that the + * vibration happens simultaneously as the game continues to run. + * If StartVibra 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 StopVibra before + * the specified interval has elasped. + * + * Vibra settings of the vibration feature in the user profile + * must be active. If no, vibration is not activated. + * + * 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 StopVibra. + * @exception KErrGeneral Unable to start vibra. + * KErrNotSupported Device doesn't support vibration feature. + * @see MVibraControlObserver + * @deprecated since Series 60 3.0 + */ + virtual void StartVibraL(TUint16 aDuration) = 0; + + /** + * Interrupts the device vibration that is started with the StartVibra + * method immediately. + * + * @exception KErrNotSupported Device doesn't support vibration feature. + * @see MVibraControlObserver + * @deprecated since Series 60 3.0 + */ + virtual void StopVibraL(void) = 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 game then the user can be informed, or asked if he wants to enable + * the Vibra during the game. + * @return TVibraModeState with the possible states EvibraModeON, + * EVibraModeOFF or, + * if an error occurs, EVibraModeUnknown + * @deprecated since Series 60 3.0 + */ + virtual TVibraModeState VibraSettings(void) const = 0; + + /** + * Starts the device vibration feature. The method does not block, + * but returns immediately so that the vibration happens simultaneously + * as the game continues to run. If StartVibra 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 StopVibra before + * the specified interval has elasped. + * + * Vibra settings of the vibration feature in the user profile + * must be active. If no, vibration is not activated. + * + * 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 StopVibra. + * @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. + * @exception KErrGeneral Unable to start vibra. + * KErrNotSupported Device doesn't support user-defined + * intensity or vibration feature is not supported. + * KErrArgument One of the parameters is out of range. + * @see MVibraControlObserver + * @deprecated since Series 60 3.0 + */ + virtual void StartVibraL(TUint16 aDuration, TInt aIntensity) = 0; + + protected: + /** + * C++ default constructor. + * @see VibraFactory + * @deprecated since Series 60 3.0 + */ + CVibraControl(); + }; + +/** +* An interface the developer implements for handling notifies events. +* +* @lib VibraCtrl.DLL +* @since 2.0 +* @deprecated since Series 60 3.0 - Use HWRM Vibra API instead (HWRMVibra.h) +*/ +class MVibraControlObserver + { + public: + /** + * Called when the vibration setting in the user profile is changed. + * @param aStatus Indicates the new setting. + * @deprecated since Series 60 3.0 + */ + virtual void VibraModeStatus(CVibraControl::TVibraModeState aStatus) = 0; + /** + * Called when the device vibration feature is requested. + * @param aStatus Indicates vibra request status. + * @deprecated since Series 60 3.0 + */ + virtual void VibraRequestStatus(CVibraControl::TVibraRequestStatus aStatus) = 0; + }; + +/** +* Factory to create instance of the VibraControl. +* +* @lib VibraCtrl.DLL +* @since 2.0 +* @deprecated since Series 60 3.0 - Use HWRM Vibra API instead (HWRMVibra.h) +*/ +class VibraFactory + { + public: + /** + * Create a CVibraControl object without notify handling. + * @deprecated since Series 60 3.0 + */ + IMPORT_C static CVibraControl* NewL(); + + /** + * Create a CVibraControl Object using notify handling + * The clients of this code will be notified about every change + * of the vibration setting in the user profile via the + * MvibraControlObserver interface. + * + * @param aCallback A reference to a class implementing + * the MVibraControlObserver interface. + * If aCallback is NULL, notify handling is + * not enabled. + * @see MVibraControlObserver + * @deprecated since Series 60 3.0 + */ + IMPORT_C static CVibraControl* NewL(MVibraControlObserver* aCallback); + + /** + * Create a CVibraControl Object using notify handling + * The clients of this code will be notified about every change + * of the vibration setting in the user profile via the + * MvibraControlObserver interface. The object is left to cleanup stack. + * + * @param aCallback A reference to a class implementing + * the MVibraControlObserver interface. + * If aCallback is NULL, notify handling is + * not enabled. + * @see MVibraControlObserver + * @deprecated since Series 60 3.0 + */ + IMPORT_C static CVibraControl* NewLC(MVibraControlObserver* aCallback); + + private: + /** + * C++ default constructor. + * @deprecated since Series 60 3.0 + */ + VibraFactory(); + }; + +#endif // VIBRA_CTRL_H__