API_REF/Public_API: comparison epoc32/include/hwrmvibra.h

equal deleted inserted replaced

-:e1b950c65cb4
+:837f303aceeb
 /*
-* Copyright (c) 2002-2007 Nokia Corporation and/or its subsidiary(-ies).
+* 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 the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members
+* under the terms of "Eclipse Public License v1.0"
 * which accompanies this distribution, and is available
-* at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
+* at the URL "http://www.eclipse.org/legal/epl-v10.html".
 *
 * Initial Contributors:
 * Nokia Corporation - initial contribution.
 *
 * Contributors:
 *
-* Description:  This file contains the header of the
+* Description:
-*                CHWRMVibra class.
+*
-*
+*/
-*/
 #ifndef HWRMVIBRA_H
 #define HWRMVIBRA_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;
-// 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
+* the method call will block the client application. The API is meant for all
-* 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.
+* The API consist of the classes CHWRMVibra and MHWRMVibraObserver. If the client
-* If the client requires up-to-date status information, it should also provide callback pointer
+* 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.
+* of the MHWRMVibraObserver implementing class for the NewL-method.
 *
 * Usage:
 *
 * @code
-* #include <HWRMVibra.h>  // link against HWRMVibraClient.lib
+* #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();
 *
 *
 * // To clean up, delete the created object:
 * delete vibra;
 * @endcode
 *
-*  @lib HWRMVIBRACLIENT.DLL
+* @publishedAll
-*  @since S60 3.0
+* @released
 */
 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.
+Not initialized yet or there is an error condion.
-EVibraModeOFF          ///< Vibration setting in the user profile is off.
+*/
+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
 {
-EVibraStatusUnknown = 0, ///< Vibra is not initialized yet or status is uncertain
+/**
-///< because of an error condition.
+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.
+EVibraStatusUnknown = 0,
-EVibraStatusStopped,     ///< Vibra is stopped.
+/**
-EVibraStatusOn           ///< Vibra is on.
+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:
-public:  // Constructors
 /**
 * Two-phased constructor.
 *
 * @return A pointer to a new instance of the CHWRMVibra class.
 *
 public: // New functions
 	/**
 	* Reserves vibration feature exclusively for this client.
-	* A higher priority (not process or thread priority, but the priority defined
+	* A higher priority client may cause lower priority client reservation
-	* in the internal vibra policy of the HW Resource Manager) client may cause
+	* to be temporarily suspended. Commands can still be issued in suspended
-	* lower priority client reservation to be temporarily suspended. Commands
+	* state, but they will not be acted upon unless suspension is lifted
-	* can still be issued in suspended state, but they will not be acted upon
+	* within specified duration.
-	* unless suspension is lifted within specified duration.
+	* The suspended client will not get any notification about suspension.
-	* 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
 	*/
 	virtual void ReserveVibraL()=0;
 	/**
 	* Reserves vibration feature exclusively for this client.
-	* A higher priority (not process or thread priority, but the priority defined
+	* A higher priority client may cause lower priority client reservation
-	* in the internal vibra policy of the HW Resource Manager) client may cause
+	* to be temporarily suspended. Commands can still be issued in suspended
-	* lower priority client reservation to be temporarily suspended. Commands
+	* state, but they will not be acted upon unless suspension is lifted
-	* can still be issued in suspended state, but they will not be acted upon
+	* within specified duration.
-	* unless suspension is lifted within specified duration.
+	* The suspended client will not get any notification about suspension.
-	* 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
 *                        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.
+*                        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
 *       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
+*                  A value of 0 specifies that the vibration should
-*                  the vibration should continue indefinetely and should
+*                  continue indefinetely and should be stopped with a
-*                  be stopped with a call to StopVibraL. Duration
+*                  call to StopVibraL. Duration can have maximum value
-*                  usually has device specific 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
 *       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
+*                  A value of 0 specifies that the vibration should
-*                  the vibration should continue indefinetely and should
+*                  continue indefinitly and should be stopped with a
-*                  be stopped with a call to StopVibraL. Duration
+*                  call to StopVibraL.  Duration can have maximum value
-*                  usually has device specific maximum value.
+*                  of KHWRMVibraMaxDuration.
-* @param aIntensity Intensity of the vibra in decimal is KHWRMVibraMinIntensity
+* @param aIntensity Intensity of the vibra in decimal is -100 to 100,
-*                   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.
 *                   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
 *
 * A callback object header example:
 *
 * @code
 * // INCLUDES
-* #include <HWRMVibra.h> // Link against HWRMVibraClient.lib.
+* #include <hwrmvibra.h> // Link against HWRMVibraClient.lib.
 *
 * class CTest : public CBase,
 *               public MHWRMVibraObserver
 *    {
 *    public:
 *            break;
 *        }
 *    }
 * @endcode
 *
-* @since S60 3.0
+* @publishedAll
+* @released
 */
 class MHWRMVibraObserver
 {
 public:
 		*/
 virtual void VibraStatusChanged(CHWRMVibra::TVibraStatus aStatus) = 0;
 	};
 /**
-* A callback interface for tactile feedback vibra mode reporting.
+*
-*
+* @publishedAll
-* If the client requires up-to-date status information, the client needs
+* @released
-* 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:

branch	Symbian3
changeset 4	837f303aceeb
parent 2	2fe1408b6811