epoc32/include/hwrmvibra.h
branchSymbian2
changeset 2 2fe1408b6811
parent 0 061f57f2323e
child 4 837f303aceeb
     1.1 --- a/epoc32/include/hwrmvibra.h	Tue Nov 24 13:55:44 2009 +0000
     1.2 +++ b/epoc32/include/hwrmvibra.h	Tue Mar 16 16:12:26 2010 +0000
     1.3 @@ -1,1 +1,721 @@
     1.4 -hwrmvibra.h
     1.5 +/*
     1.6 +* Copyright (c) 2002-2007 Nokia Corporation and/or its subsidiary(-ies). 
     1.7 +* All rights reserved.
     1.8 +* This component and the accompanying materials are made available
     1.9 +* 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
    1.10 +* which accompanies this distribution, and is available
    1.11 +* at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
    1.12 +*
    1.13 +* Initial Contributors:
    1.14 +* Nokia Corporation - initial contribution.
    1.15 +*
    1.16 +* Contributors:
    1.17 +*
    1.18 +* Description:  This file contains the header of the 
    1.19 +*                CHWRMVibra class.
    1.20 +*
    1.21 +*/
    1.22 +
    1.23 +
    1.24 +#ifndef HWRMVIBRA_H
    1.25 +#define HWRMVIBRA_H
    1.26 +
    1.27 +// INCLUDES
    1.28 +#include <e32base.h>
    1.29 +
    1.30 +// CONSTANTS
    1.31 +
    1.32 +/**
    1.33 +* Minimum allowed intensity setting for vibra. When intensity is negative, 
    1.34 +* the vibra motor rotates in the negative direction.
    1.35 +*/
    1.36 +const TInt KHWRMVibraMinIntensity = -100;
    1.37 +
    1.38 +/**
    1.39 +* Minimum allowed intensity setting for vibra pulse.
    1.40 +*/
    1.41 +const TInt KHWRMVibraMinPulseIntensity = 1;
    1.42 +
    1.43 +/**
    1.44 +* Maximum allowed intensity setting for vibra. When intensity is positive, 
    1.45 +* the vibra motor rotates in the positive direction. Value 0 effectively 
    1.46 +* stops the vibra.
    1.47 +*/
    1.48 +const TInt KHWRMVibraMaxIntensity = 100;
    1.49 +
    1.50 +/**
    1.51 +* Maximum allowed duration value in milliseconds. Maximum vibrating time 
    1.52 +* supported by device is declared in KVibraCtrlMaxTime cenrep-key.
    1.53 +*
    1.54 +* Note that duration probably has device specific
    1.55 +* maximum duration that is much lower.
    1.56 +*/
    1.57 +const TInt KHWRMVibraMaxDuration = (KMaxTInt / 1000) - 1;
    1.58 +
    1.59 +/**
    1.60 +* KHWRMVibraInfiniteDuration specifies, that vibrating should continue maximum 
    1.61 +* vibrating time supported by device if vibrating is not explicitly stopped.
    1.62 +*
    1.63 +*/
    1.64 +const TInt KHWRMVibraInfiniteDuration = 0;
    1.65 +
    1.66 +// FORWARD DECLARATIONS
    1.67 +class MHWRMVibraObserver;
    1.68 +class MHWRMVibraFeedbackObserver;
    1.69 +
    1.70 +// CLASS DECLARATIONS
    1.71 +
    1.72 +/**
    1.73 +* The class used to control the device vibra.
    1.74 +*
    1.75 +* HW Resource Manager Vibra API is a library API providing ability to control
    1.76 +* the device vibra. The API provides also methods to retrieve the current settings
    1.77 +* of the vibration feature in the user profile and the current status of the vibra. 
    1.78 +*
    1.79 +* The type of HW Resource Manager Vibra API is a synchronous method call meaning 
    1.80 +* the method call will block the client application. However, e.g. StartVibraL methods do 
    1.81 +* return right after device vibration has successfully been started. Callback is intended only
    1.82 +* for observing vibra and feedback on/off changes. The API is meant for all 
    1.83 +* applications which need to control the device vibra.
    1.84 +*
    1.85 +* The API consist of the classes CHWRMVibra, MHWRMVibraObserver and MHWRMVibraFeedbackObserver. 
    1.86 +* If the client requires up-to-date status information, it should also provide callback pointer
    1.87 +* of the MHWRMVibraObserver implementing class for the NewL-method and explicitly set feedback observer.
    1.88 +*
    1.89 +* Usage:
    1.90 +*
    1.91 +* @code
    1.92 +* #include <HWRMVibra.h>  // link against HWRMVibraClient.lib
    1.93 +*
    1.94 +* // A CHWRMVibra instance can be created by using NewL() or NewLC() methods. 
    1.95 +* // Up-to-date status information not required, no callbacks.
    1.96 +* CHWRMVibra* vibra = CHWRMVibra::NewL();
    1.97 +*
    1.98 +* // After this, vibra can be directly controlled via the provided class methods. 
    1.99 +* vibra->StartVibraL(5000); // Start vibra for five seconds
   1.100 +* vibra->StopVibraL(); // Immediately stop vibra
   1.101 +*
   1.102 +* // To clean up, delete the created object:
   1.103 +* delete vibra;
   1.104 +* @endcode
   1.105 +*
   1.106 +*  @lib HWRMVIBRACLIENT.DLL
   1.107 +*  @since S60 3.0
   1.108 +*/
   1.109 +class CHWRMVibra : public CBase
   1.110 +    {
   1.111 +    public: // enums
   1.112 +        /**
   1.113 +        * Vibration setting in the user profile.
   1.114 +        */
   1.115 +        enum TVibraModeState 
   1.116 +            {
   1.117 +            EVibraModeUnknown = 0, ///< Not initialized yet or there is an error condion.
   1.118 +            EVibraModeON,          ///< Vibration setting in the user profile is on.
   1.119 +            EVibraModeOFF          ///< Vibration setting in the user profile is off.
   1.120 +            };
   1.121 +
   1.122 +        /**
   1.123 +        * Status of the vibration feature
   1.124 +        */
   1.125 +        enum TVibraStatus 
   1.126 +            {
   1.127 +            EVibraStatusUnknown = 0, ///< Vibra is not initialized yet or status is uncertain 
   1.128 +                                     ///< because of an error condition.
   1.129 +            EVibraStatusNotAllowed,  ///< Vibra is set off in the user profile or some
   1.130 +                                     ///< application is specifically blocking vibra.
   1.131 +            EVibraStatusStopped,     ///< Vibra is stopped.
   1.132 +            EVibraStatusOn           ///< Vibra is on.
   1.133 +            };
   1.134 +            
   1.135 +        /**
   1.136 +        * Tactile feedback vibration setting in the user profile.
   1.137 +        */
   1.138 +        enum TVibraFeedbackModeState 
   1.139 +            {
   1.140 +            EVibraFeedbackModeUnknown = 0, ///< Not initialized yet or there is an error condion.
   1.141 +            EVibraFeedbackModeON,          ///< Feedback vibration setting in the user profile is on.
   1.142 +            EVibraFeedbackModeOFF          ///< Feedback vibration setting in the user profile is off.
   1.143 +            };
   1.144 +
   1.145 +    public:  // Constructors
   1.146 +        
   1.147 +        /**
   1.148 +        * Two-phased constructor.
   1.149 +        *
   1.150 +        * @return A pointer to a new instance of the CHWRMVibra class.
   1.151 +        *
   1.152 +        * @leave KErrNotSupported Device doesn't support vibration feature.
   1.153 +        * @leave KErrNoMemory There is a memory allocation failure. 
   1.154 +        */
   1.155 +        IMPORT_C static CHWRMVibra* NewL();
   1.156 +        
   1.157 +        /**
   1.158 +        * Two-phased constructor.
   1.159 +        * Leaves instance to cleanup stack.
   1.160 +        *
   1.161 +        * @return A pointer to a new instance of the CHWRMVibra class.
   1.162 +        *
   1.163 +        * @leave KErrNotSupported Device doesn't support vibration feature.
   1.164 +        * @leave KErrNoMemory There is a memory allocation failure. 
   1.165 +        */
   1.166 +        IMPORT_C static CHWRMVibra* NewLC();
   1.167 +
   1.168 +        /**
   1.169 +        * Two-phased constructor.
   1.170 +        * Use this method for creating a vibra client with callbacks.
   1.171 +        *
   1.172 +        * @param aCallback Pointer to callback instance
   1.173 +        * @return A pointer to a new instance of the CHWRMVibra class.
   1.174 +        *
   1.175 +        * @leave KErrNotSupported Device doesn't support vibration feature.
   1.176 +        * @leave KErrNoMemory There is a memory allocation failure. 
   1.177 +        */
   1.178 +        IMPORT_C static CHWRMVibra* NewL(MHWRMVibraObserver* aCallback);
   1.179 +        
   1.180 +        /**
   1.181 +        * Two-phased constructor. 
   1.182 +        * Use this method for creating a vibra client with callbacks.
   1.183 +        * Leaves instance to cleanup stack.
   1.184 +        *
   1.185 +        * @param aCallback Pointer to callback instance
   1.186 +        * @return A pointer to a new instance of the CHWRMVibra class.
   1.187 +        *
   1.188 +        * @leave KErrNotSupported Device doesn't support vibration feature.
   1.189 +        * @leave KErrNoMemory There is a memory allocation failure. 
   1.190 +        */
   1.191 +        IMPORT_C static CHWRMVibra* NewLC(MHWRMVibraObserver* aCallback);
   1.192 +
   1.193 +    public: // New functions
   1.194 +
   1.195 +    	/**
   1.196 +    	* Reserves vibration feature exclusively for this client.
   1.197 +    	* A higher priority (not process or thread priority, but the priority defined
   1.198 +    	* in the internal vibra policy of the HW Resource Manager) client may cause 
   1.199 +    	* lower priority client reservation to be temporarily suspended. Commands 
   1.200 +    	* can still be issued in suspended state, but they will not be acted upon 
   1.201 +    	* unless suspension is lifted within specified duration.
   1.202 +    	* The suspended client will not get any notification about suspension and
   1.203 +    	* neither from resumption of reservation.
   1.204 +    	* If vibra is already reserved by a higher or equal priority application, 
   1.205 +    	* reserving will still succeed, but reservation is immediately suspended.
   1.206 +    	*
   1.207 +    	* Calling this method is equal to call ReserveVibraL(EFalse, EFalse),
   1.208 +    	* i.e. any previously frozen state will not be restored and CCoeEnv
   1.209 +    	* background/foreground status is always used to control further reservations.
   1.210 +    	*
   1.211 +    	* @leave KErrAccessDenied No CCoeEnv present.
   1.212 +    	* @leave KErrNotReady Trying to reserve while on background.
   1.213 +        * @leave KErrNoMemory There is a memory allocation failure. 
   1.214 +    	*/
   1.215 +    	virtual void ReserveVibraL()=0;
   1.216 +    	
   1.217 +    	/**
   1.218 +    	* Reserves vibration feature exclusively for this client.
   1.219 +    	* A higher priority (not process or thread priority, but the priority defined
   1.220 +    	* in the internal vibra policy of the HW Resource Manager) client may cause 
   1.221 +    	* lower priority client reservation to be temporarily suspended. Commands 
   1.222 +    	* can still be issued in suspended state, but they will not be acted upon 
   1.223 +    	* unless suspension is lifted within specified duration.
   1.224 +    	* The suspended client will not get any notification about suspension and
   1.225 +    	* neither from resumption of reservation.
   1.226 +    	* If vibra is already reserved by a higher or equal priority application, 
   1.227 +    	* reserving will still succeed, but reservation is immediately suspended.
   1.228 +    	*
   1.229 +    	*
   1.230 +    	* @param aRestoreState If ETrue, the state frozen on last release will be
   1.231 +    	*                      restored upon successful reservation.
   1.232 +    	*                      I.e. if vibra was on when it was released by this 
   1.233 +        *                      client the last time, it would continue the vibrating
   1.234 +        *                      upon successful reservation.
   1.235 +    	*                      For the first reservation of each session this 
   1.236 +        *                      parameter is always considered EFalse regardless of 
   1.237 +        *                      what is supplied, as there is no previous frozen state
   1.238 +        *                      to restore.
   1.239 +    	* @param aForceNoCCoeEnv If EFalse, then reservation requires that this client
   1.240 +        *                        has the keyboard focus at the time of reservation and
   1.241 +        *                        vibra will be automatically released and re-reserved 
   1.242 +        *                        based on the keyboard focus status of this client. 
   1.243 +        *                        This also implies that CCoeEnv::Static() != NULL is 
   1.244 +        *                        required.
   1.245 +    	*                        If ETrue, the client will not require CCoeEnv to be 
   1.246 +        *                        present nor does it automatically reserve/release vibra 
   1.247 +    	*                        by depending on foreground/background status of the 
   1.248 +        *                        client.
   1.249 +    	*                        Only trusted clients are allowed to set this flag to
   1.250 +        *                        ETrue. A client is considered trusted if it has nonstandard
   1.251 +        *                        priority defined in the internal vibra policy of the 
   1.252 +        *                        HW Resource Manager. A client can be defined trusted
   1.253 +        *                        only by S60 or a product.
   1.254 +    	*
   1.255 +    	* @leave KErrAccessDenied Parameter aForceNoCCoeEnv is ETrue and client is not
   1.256 +    	*                         trusted.
   1.257 +    	* @leave KErrBadHandle Parameter aForceNoCCoeEnv is EFalse and no CCoeEnv present.
   1.258 +    	* @leave KErrNotReady Trying to reserve while on background and parameter 
   1.259 +        *                     aForceNoCCoeEnv is EFalse.
   1.260 +        * @leave KErrNoMemory There is a memory allocation failure. 
   1.261 +    	*/
   1.262 +    	virtual void ReserveVibraL(TBool aRestoreState, TBool aForceNoCCoeEnv)=0;
   1.263 +
   1.264 +    	/**
   1.265 +    	* Releases vibration feature if it was previously reserved for this client.
   1.266 +    	* If this client has not reserved vibration feature, does nothing.
   1.267 +    	* If vibra is on when it is released and no other client has a suspended 
   1.268 +    	* reservation, vibra is stopped.
   1.269 +    	*/
   1.270 +    	virtual void ReleaseVibra()=0;
   1.271 +
   1.272 +
   1.273 +        /**
   1.274 +        * Starts the device vibration feature with the product specific default
   1.275 +        * intensity.
   1.276 +        * If StartVibraL is called again before the first vibration completes
   1.277 +        * then the first vibration is interrupted and the second vibrations
   1.278 +        * starts immediately -- i.e. The periods of vibration are not cumulative.
   1.279 +        *
   1.280 +        * The vibration can be interrupted with the method StopVibraL before
   1.281 +        * the specified interval has elapsed. 
   1.282 +        *
   1.283 +        * Vibra settings of the vibration feature in the user profile 
   1.284 +        * must be active. 
   1.285 +        *
   1.286 +        * Note: The device may have implementation defined or hardware imposed
   1.287 +        *       limits to the duration of the vibration feature. In such 
   1.288 +        *       circumstances any vibration will cut off at that limit even if
   1.289 +        *       the duration parameter is greater than the limit.
   1.290 +        *
   1.291 +        * @param aDuration Duration of the vibration measured in milliseconds. 
   1.292 +        *                  A value of KHWRMVibraInfiniteDuration specifies that 
   1.293 +        *                  the vibration should continue indefinetely and should 
   1.294 +        *                  be stopped with a call to StopVibraL. Duration 
   1.295 +        *                  usually has device specific maximum value.
   1.296 +        *
   1.297 +        * @leave KErrArgument Duration is invalid.
   1.298 +        * @leave KErrAccessDenied Vibration setting in the user profile is not set.
   1.299 +        * @leave KErrBadHandle Vibra session has been invalidated.
   1.300 +        * @leave KErrLocked Vibra is locked down because too much continuous use
   1.301 +        *                   or explicitly blocked by for example some vibration 
   1.302 +        *                   sensitive accessory.
   1.303 +        * @leave KErrTimedOut Timeout occurred in controlling vibra.
   1.304 +        * @leave KErrInUse Vibra is not reserved to this client but it is
   1.305 +        *                  reserved to some other client.
   1.306 +        * @leave KErrNoMemory There is a memory allocation failure. 
   1.307 +        * @leave KErrGeneral There is a hardware error.
   1.308 +        *
   1.309 +        * @see MHWRMVibraObserver
   1.310 +        */
   1.311 +        virtual void StartVibraL(TInt aDuration)=0;
   1.312 +		
   1.313 +        /**
   1.314 +        * Starts the device vibration feature. If StartVibraL is called again before
   1.315 +        * the first vibration completes then the first vibration is interrupted
   1.316 +        * and the second vibrations starts immediately -- i.e. The periods of
   1.317 +        * vibration are not cumulative.
   1.318 +        *
   1.319 +        * The vibration can be interrupted with the method StopVibraL before
   1.320 +        * the specified interval has elapsed.
   1.321 +        *
   1.322 +        * Vibra settings of the vibration feature in the user profile 
   1.323 +        * must be active. 
   1.324 +        *
   1.325 +        * Note: The device may have implementation defined or hardware imposed
   1.326 +        *       limits to the duration of the vibration feature. In such 
   1.327 +        *       circumstances any vibration will cut off at that limit even if
   1.328 +        *       the duration parameter is greater than the limit.
   1.329 +        *
   1.330 +        * @param aDuration Duration of the vibration measured in milliseconds. 
   1.331 +        *                  A value of KHWRMVibraInfiniteDuration specifies that 
   1.332 +        *                  the vibration should continue indefinetely and should 
   1.333 +        *                  be stopped with a call to StopVibraL. Duration 
   1.334 +        *                  usually has device specific maximum value.
   1.335 +        * @param aIntensity Intensity of the vibra in decimal is KHWRMVibraMinIntensity
   1.336 +        *                   to KHWRMVibraMaxIntensity,
   1.337 +        *                   which shows the percentage of the vibra motor full
   1.338 +        *                   rotation speed. When intensity is negative, 
   1.339 +        *                   the vibra motor rotates in the negative direction.
   1.340 +        *                   When intensity is positive, the vibra motor rotates
   1.341 +        *                   in the positive direction. Value 0 stops the vibra.
   1.342 +        *                   NOTE: The device might have hardware-imposed limits
   1.343 +        *                         on supported vibra intensity values, so actual
   1.344 +        *                         effect might vary between different hardware.
   1.345 +        *
   1.346 +        * @leave KErrNotSupported The device doesn't support user-defined 
   1.347 +        *                         vibra intensity.
   1.348 +        * @leave KErrArgument One of the parameters is out of range.
   1.349 +        * @leave KErrAccessDenied Vibration setting in the user profile
   1.350 +        *                         is not set.
   1.351 +        * @leave KErrBadHandle Vibra session has been invalidated.
   1.352 +        * @leave KErrLocked Vibra is locked down because too much continuous use
   1.353 +        *                   or explicitly blocked by for example some vibration
   1.354 +        *                   sensitive accessory.
   1.355 +        * @leave KErrTimedOut Timeout occurred in controlling vibra.
   1.356 +        * @leave KErrInUse Vibra is not reserved to this client but it is
   1.357 +        *                  reserved to some other client.
   1.358 +        * @leave KErrNoMemory There is a memory allocation failure. 
   1.359 +        * @leave KErrGeneral There is a hardware error.
   1.360 +        *
   1.361 +        * @see MHWRMVibraObserver
   1.362 +        */
   1.363 +	    virtual void StartVibraL(TInt aDuration, TInt aIntensity)=0;
   1.364 +	    
   1.365 +	    /**
   1.366 +        * Interrupts the device vibration that is started with the StartVibraL
   1.367 +        * method immediately.
   1.368 +        *
   1.369 +        * @leave KErrBadHandle Vibra session has been invalidated.
   1.370 +        * @leave KErrTimedOut Timeout occurred in controlling vibra.
   1.371 +        * @leave KErrInUse Vibra is not reserved to this client but it is
   1.372 +        *                  reserved to some other client.
   1.373 +        * @leave KErrNoMemory There is a memory allocation failure. 
   1.374 +        * @leave KErrGeneral There is a hardware error.
   1.375 +        *
   1.376 +        * @see MHWRMVibraObserver
   1.377 +        */		
   1.378 +        virtual void StopVibraL()=0; 
   1.379 +		
   1.380 +        /**
   1.381 +        * This method retrieves the current settings of the vibration feature
   1.382 +        * in the user profile. The developer can check the Vibra settings 
   1.383 +        * in the profile and if there is no Vibra active but it is needed by 
   1.384 +        * the client application then the user can be informed.
   1.385 +        *
   1.386 +        * @return TVibraModeState indicating the current vibra mode setting.
   1.387 +        *
   1.388 +        * @see TVibraModeState
   1.389 +        * @see MHWRMVibraObserver
   1.390 +        */
   1.391 +        virtual TVibraModeState VibraSettings() const=0;
   1.392 +
   1.393 +        /**
   1.394 +        * This method retrieves the current vibra status. 
   1.395 +        *
   1.396 +        * @return TVibraStatus indicating the current vibra status
   1.397 +        * 
   1.398 +        * @see TVibraStatus
   1.399 +        * @see MHWRMVibraObserver
   1.400 +        */
   1.401 +        virtual TVibraStatus VibraStatus() const=0;
   1.402 +        
   1.403 +        /**
   1.404 +        * This method is intended only for firmware build time configured 
   1.405 +        * privileged clients.
   1.406 +        *
   1.407 +        * Executes a tactile feedback vibration pulse with product 
   1.408 +        * specific default intensity and duration.
   1.409 +        * If PulseVibraL is called before ongoing vibration completes and 
   1.410 +        * PulseVibraL calling client has higher priority than executing client,
   1.411 +        * pulse request is accepted. Also possible vibra-reservations are bypassed.
   1.412 +        * If client calling PulseVibraL has lower or equal priority 
   1.413 +        * than executing client, ongoing vibration is not affected.
   1.414 +        *
   1.415 +        * Tactile feedback vibration settings of the vibration feature in the 
   1.416 +        * user profile must be active. 
   1.417 +        *
   1.418 +        * Note: The device may have implementation defined or hardware imposed
   1.419 +        *       limits to the duration of the vibration feature. In such 
   1.420 +        *       circumstances any vibration will cut off at that limit even if
   1.421 +        *       the duration parameter is greater than the limit.
   1.422 +        *
   1.423 +        * @param aDuration Duration of the vibration measured in milliseconds. 
   1.424 +        *                  Duration can have maximum value
   1.425 +        *                  of KHWRMVibraMaxDuration.
   1.426 +        *
   1.427 +        * @leave KErrAccessDenied Vibration setting in the user profile is not set
   1.428 +        *                         or client is not privileged to use pulse feature. 
   1.429 +        * @leave KErrBadHandle Vibra session has been invalidated.
   1.430 +        * @leave KErrLocked Vibra is locked down because too much continuous use
   1.431 +        *                   or explicitly blocked by for example some vibration 
   1.432 +        *                   sensitive accessory.
   1.433 +        * @leave KErrTimedOut Timeout occurred in controlling vibra.
   1.434 +        * @leave KErrInUse Vibra is not reserved to this client but it is
   1.435 +        *                  reserved to some other client or ongoing vibration
   1.436 +        *                  has been requested by higher priority client.
   1.437 +        * @leave KErrNoMemory There is a memory allocation failure. 
   1.438 +        * @leave KErrGeneral There is a hardware error.
   1.439 +        *
   1.440 +        * @see MHWRMVibraFeedbackObserver
   1.441 +        */
   1.442 +        virtual void PulseVibraL()=0;
   1.443 +		
   1.444 +        /**
   1.445 +        * This method is intended only for firmware build time configured 
   1.446 +        * privileged clients.
   1.447 +        *
   1.448 +        * Executes a tactile feedback vibration pulse with product 
   1.449 +        * specific default intensity and specified duration.
   1.450 +        * If PulseVibraL is called before ongoing vibration completes and 
   1.451 +        * PulseVibraL calling client has higher priority than executing client,
   1.452 +        * pulse request is accepted. Also possible vibra-reservations are bypassed.
   1.453 +        * If client calling PulseVibraL has lower or equal priority 
   1.454 +        * than executing client, ongoing vibration is not affected.
   1.455 +        *
   1.456 +        * Tactile feedback vibration settings of the vibration feature in the 
   1.457 +        * user profile must be active. 
   1.458 +        *
   1.459 +        * Note: The device may have implementation defined or hardware imposed
   1.460 +        *       limits to the duration of the vibration feature. In such 
   1.461 +        *       circumstances any vibration will cut off at that limit even if
   1.462 +        *       the duration parameter is greater than the limit.
   1.463 +        *
   1.464 +        * @param aDuration Duration of the vibration measured in milliseconds. 
   1.465 +        *                  Duration can have maximum value
   1.466 +        *                  of KHWRMVibraMaxDuration.
   1.467 +        *
   1.468 +        * @leave KErrArgument One of the parameters is out of range.
   1.469 +        * @leave KErrAccessDenied Vibration setting in the user profile is not set
   1.470 +        *                         or client is not privileged to use pulse feature. 
   1.471 +        * @leave KErrBadHandle Vibra session has been invalidated.
   1.472 +        * @leave KErrLocked Vibra is locked down because too much continuous use
   1.473 +        *                   or explicitly blocked by for example some vibration 
   1.474 +        *                   sensitive accessory.
   1.475 +        * @leave KErrTimedOut Timeout occurred in controlling vibra.
   1.476 +        * @leave KErrInUse Vibra is not reserved to this client but it is
   1.477 +        *                  reserved to some other client or ongoing vibration
   1.478 +        *                  has been requested by higher priority client.
   1.479 +        * @leave KErrNoMemory There is a memory allocation failure. 
   1.480 +        * @leave KErrGeneral There is a hardware error.
   1.481 +        *
   1.482 +        * @see MHWRMVibraFeedbackObserver
   1.483 +        */
   1.484 +        virtual void PulseVibraL(TInt aDuration)=0;
   1.485 +		
   1.486 +        /**
   1.487 +        * This method is intended only for firmware build time configured 
   1.488 +        * privileged clients.
   1.489 +        *
   1.490 +        * Executes a tactile feedback vibration pulse.
   1.491 +        * If PulseVibraL is called before ongoing vibration completes and 
   1.492 +        * PulseVibraL calling client has higher priority than executing client,
   1.493 +        * pulse request is accepted. Also possible vibra-reservations are bypassed.
   1.494 +        * If client calling PulseVibraL has lower or equal priority 
   1.495 +        * than executing client, ongoing vibration is not affected.
   1.496 +        *
   1.497 +        * Tactile feedback vibration settings of the vibration feature in the 
   1.498 +        * user profile must be active. 
   1.499 +        *
   1.500 +        * Note: The device may have implementation defined or hardware imposed
   1.501 +        *       limits to the duration of the vibration feature. In such 
   1.502 +        *       circumstances any vibration will cut off at that limit even if
   1.503 +        *       the duration parameter is greater than the limit.
   1.504 +        *
   1.505 +        * @param aDuration Duration of the vibration measured in milliseconds. 
   1.506 +        *                  Duration can have maximum value
   1.507 +        *                  of KHWRMVibraMaxDuration.
   1.508 +        * @param aIntensity Intensity of the pulse in decimal is KHWRMVibraMinPulseIntensity
   1.509 +        *                   to KHWRMVibraMaxIntensity, which shows the percentage 
   1.510 +        *                   of the vibra motor full rotation speed. 
   1.511 +        *                   NOTE: The device might have hardware-imposed limits
   1.512 +        *                         on supported vibra intensity values, so actual
   1.513 +        *                         effect might vary between different hardware.
   1.514 +        *
   1.515 +        * @leave KErrNotSupported The device doesn't support user-defined 
   1.516 +        *                         vibra intensity.
   1.517 +        * @leave KErrArgument One of the parameters is out of range.
   1.518 +        * @leave KErrAccessDenied Vibration setting in the user profile is not set
   1.519 +        *                         or client is not privileged to use pulse feature. 
   1.520 +        * @leave KErrBadHandle Vibra session has been invalidated.
   1.521 +        * @leave KErrLocked Vibra is locked down because too much continuous use
   1.522 +        *                   or explicitly blocked by for example some vibration 
   1.523 +        *                   sensitive accessory.
   1.524 +        * @leave KErrTimedOut Timeout occurred in controlling vibra.
   1.525 +        * @leave KErrInUse Vibra is not reserved to this client but it is
   1.526 +        *                  reserved to some other client or ongoing vibration
   1.527 +        *                  has been requested by higher priority client.
   1.528 +        * @leave KErrNoMemory There is a memory allocation failure. 
   1.529 +        * @leave KErrGeneral There is a hardware error.
   1.530 +        *
   1.531 +        * @see MHWRMVibraFeedbackObserver
   1.532 +        */
   1.533 +        virtual void PulseVibraL(TInt aDuration, TInt aIntensity)=0;
   1.534 +		
   1.535 +        /**
   1.536 +        * Use this method for setting feedback observer.
   1.537 +        *
   1.538 +        * @param aCallback Pointer to callback instance
   1.539 +        */
   1.540 +        virtual void SetFeedbackObserver(MHWRMVibraFeedbackObserver* aCallback)=0;
   1.541 +
   1.542 +        /**
   1.543 +        * This method retrieves the current settings of the feedback vibration feature
   1.544 +        * in the user profile. The developer can check the feedback vibration settings 
   1.545 +        * in the profile and if there is no feedback vibration active but it is needed by 
   1.546 +        * the client application then the user can be informed. However, client needs to 
   1.547 +        * explicitly register to listen these changes via SetFeedbackObserver-method.
   1.548 +        *
   1.549 +        * @return TVibraFeedbackModeState indicating the current vibra feedback mode setting.
   1.550 +        *
   1.551 +        * @see TVibraFeedbackModeState
   1.552 +        * @see MHWRMVibraFeedbackObserver
   1.553 +        */
   1.554 +        virtual TVibraFeedbackModeState VibraFeedbackSettings() const=0;
   1.555 +    };
   1.556 +    
   1.557 +/**
   1.558 +* A callback interface for vibra status reporting.
   1.559 +*
   1.560 +* If the client requires up-to-date status information, the client needs 
   1.561 +* to derive a class from the MHWRMVibraObserver interface and implement 
   1.562 +* the VibraModeChanged() and VibraStatusChanged() methods. 
   1.563 +* 
   1.564 +* A callback object header example:
   1.565 +*
   1.566 +* @code 
   1.567 +* // INCLUDES
   1.568 +* #include <HWRMVibra.h> // Link against HWRMVibraClient.lib.
   1.569 +*
   1.570 +* class CTest : public CBase, 
   1.571 +*               public MHWRMVibraObserver    
   1.572 +*    {
   1.573 +*    public:
   1.574 +*        CTest();
   1.575 +*        ~CTest();
   1.576 +*                       
   1.577 +*        void ConstructL();
   1.578 +*        static CTest* NewL();
   1.579 +*                
   1.580 +*        // from MHWRMVibraObserver
   1.581 +*        virtual void VibraModeChanged(CHWRMVibra::TVibraModeState aStatus);
   1.582 +*        virtual void VibraStatusChanged(CHWRMVibra::TVibraStatus aStatus);
   1.583 +*
   1.584 +*    private:
   1.585 +*        CHWRMVibra* iVibra;
   1.586 +*    };
   1.587 +* @endcode
   1.588 +*
   1.589 +* A callback method implementation example:
   1.590 +*
   1.591 +* @code
   1.592 +* void CTest::VibraStatusChanged(CHWRMVibra::TVibraStatus aStatus)
   1.593 +*    {
   1.594 +*    switch ( aStatus )
   1.595 +*        {
   1.596 +*        case CHWRMVibra::EVibraStatusUnknown:
   1.597 +*            RDebug::Print(_L("### Vibra state changed: EVibraStatusUnknown"));
   1.598 +*            break;
   1.599 +*        case CHWRMVibra::EVibraStatusNotAllowed:
   1.600 +*            RDebug::Print(_L("### Vibra state changed: EVibraStatusNotAllowed"));
   1.601 +*            break;
   1.602 +*        case CHWRMVibra::EVibraStatusStopped:
   1.603 +*            RDebug::Print(_L("### Vibra state changed: EVibraStatusStopped"));
   1.604 +*            break;
   1.605 +*        case CHWRMVibra::EVibraStatusOn:
   1.606 +*            RDebug::Print(_L("### Vibra state changed: EVibraStatusOn"));
   1.607 +*            break;
   1.608 +*        default:
   1.609 +*            RDebug::Print(_L("### Vibra state changed: UNDEFINED !"));
   1.610 +*            break;
   1.611 +*        }
   1.612 +*    }
   1.613 +* @endcode
   1.614 +*
   1.615 +* @since S60 3.0
   1.616 +*/
   1.617 +class MHWRMVibraObserver
   1.618 +    {    
   1.619 +    public:
   1.620 +        
   1.621 +        /** 
   1.622 +        * Called when the vibration setting in the user profile is changed.
   1.623 +        *
   1.624 +        * @param aStatus Indicates the new setting.
   1.625 +        *
   1.626 +        * @see CHWRMVibra::TVibraModeState
   1.627 +        */
   1.628 +        virtual void VibraModeChanged(CHWRMVibra::TVibraModeState aStatus) = 0;
   1.629 +        
   1.630 +        /** 
   1.631 +        * Called when the device vibration feature state changes
   1.632 +        *
   1.633 +        * @param aStatus Indicates vibra status.
   1.634 +        *
   1.635 +        * @see CHWRMVibra::TVibraStatus
   1.636 +		*/
   1.637 +        virtual void VibraStatusChanged(CHWRMVibra::TVibraStatus aStatus) = 0;
   1.638 +	};
   1.639 +
   1.640 +/**
   1.641 +* A callback interface for tactile feedback vibra mode reporting.
   1.642 +*
   1.643 +* If the client requires up-to-date status information, the client needs 
   1.644 +* to derive a class from the MHWRMVibraFeedbackObserver interface and implement 
   1.645 +* the VibraFeedbackModeChanged() method. In order to register for callback, client
   1.646 +* needs to call SetFeedbackObserver-method.
   1.647 +* 
   1.648 +* A callback object header example:
   1.649 +*
   1.650 +* @code 
   1.651 +* // INCLUDES
   1.652 +* #include <HWRMVibra.h> // Link against HWRMVibraClient.lib.
   1.653 +*
   1.654 +* class CTest : public CBase, 
   1.655 +*               public MHWRMVibraFeedbackObserver    
   1.656 +*    {
   1.657 +*    public:
   1.658 +*        CTest();
   1.659 +*        ~CTest();
   1.660 +*                       
   1.661 +*        void ConstructL();
   1.662 +*        static CTest* NewL();
   1.663 +*                
   1.664 +*        // from MHWRMVibraFeedbackObserver
   1.665 +*        virtual void VibraFeedbackModeChanged(CHWRMVibra::TVibraFeedbackModeState aMode);
   1.666 +*
   1.667 +*    private:
   1.668 +*        CHWRMVibra* iVibra;
   1.669 +*    };
   1.670 +* @endcode
   1.671 +*
   1.672 +* A callback method implementation example:
   1.673 +*
   1.674 +* @code
   1.675 +* 
   1.676 +* #include <HWRMVibra.h>  // link against HWRMVibraClient.lib
   1.677 +*
   1.678 +* // A CHWRMVibra instance can be created by using NewL() or NewLC() methods. 
   1.679 +* CHWRMVibra* vibra = CHWRMVibra::NewL();
   1.680 +*
   1.681 +* // Request notification of feedback setting change
   1.682 +* vibra->SetFeedbackObserver(this); 
   1.683 +*
   1.684 +* // To clean up, delete the created object:
   1.685 +* delete vibra;
   1.686 +* 
   1.687 +* void CTest::VibraFeedbackModeChanged(CHWRMVibra::TVibraFeedbackModeState aMode)
   1.688 +*    {
   1.689 +*    switch ( aMode )
   1.690 +*        {
   1.691 +*        case CHWRMVibra::EVibraFeedbackModeUnknown:
   1.692 +*            RDebug::Print(_L("### Feedback vibration mode : EVibraFeedbackModeUnknown"));
   1.693 +*            break;
   1.694 +*        case CHWRMVibra::EVibraFeedbackModeON:
   1.695 +*            RDebug::Print(_L("### Feedback vibration mode : EVibraFeedbackModeON"));
   1.696 +*            break;
   1.697 +*        case CHWRMVibra::EVibraFeedbackModeOFF:
   1.698 +*            RDebug::Print(_L("### Feedback vibration mode : EVibraFeedbackModeOFF"));
   1.699 +*            break;
   1.700 +*        default:
   1.701 +*            break;
   1.702 +*        }
   1.703 +*    }
   1.704 +* @endcode
   1.705 +*
   1.706 +* @since S60 5.0
   1.707 +*/
   1.708 +class MHWRMVibraFeedbackObserver
   1.709 +    {    
   1.710 +    public:
   1.711 +        
   1.712 +        /** 
   1.713 +        * Called when the tactile feedback vibration setting in the user profile is changed.
   1.714 +        *
   1.715 +        * @param aMode Indicates the new setting.
   1.716 +        *
   1.717 +        * @see CHWRMVibra::TVibraFeedbackModeState
   1.718 +        */
   1.719 +        virtual void VibraFeedbackModeChanged(CHWRMVibra::TVibraFeedbackModeState aMode) = 0;
   1.720 +	};
   1.721 +
   1.722 +
   1.723 +#endif      // HWRMVIBRA_H   
   1.724 +            
   1.725 +// End of File