/*

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

#include <e32std.h>

/**

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