epoc32/include/hwrmvibra.h
author William Roberts <williamr@symbian.org>
Tue, 16 Mar 2010 16:12:26 +0000 (2010-03-16)
branchSymbian2
changeset 2 2fe1408b6811
parent 0 061f57f2323e
child 4 837f303aceeb
permissions -rw-r--r--
Final list of Symbian^2 public API header files
williamr@2
     1
/*
williamr@2
     2
* Copyright (c) 2002-2007 Nokia Corporation and/or its subsidiary(-ies). 
williamr@2
     3
* All rights reserved.
williamr@2
     4
* This component and the accompanying materials are made available
williamr@2
     5
* 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
williamr@2
     6
* which accompanies this distribution, and is available
williamr@2
     7
* at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
williamr@2
     8
*
williamr@2
     9
* Initial Contributors:
williamr@2
    10
* Nokia Corporation - initial contribution.
williamr@2
    11
*
williamr@2
    12
* Contributors:
williamr@2
    13
*
williamr@2
    14
* Description:  This file contains the header of the 
williamr@2
    15
*                CHWRMVibra class.
williamr@2
    16
*
williamr@2
    17
*/
williamr@2
    18
williamr@2
    19
williamr@2
    20
#ifndef HWRMVIBRA_H
williamr@2
    21
#define HWRMVIBRA_H
williamr@2
    22
williamr@2
    23
// INCLUDES
williamr@2
    24
#include <e32base.h>
williamr@2
    25
williamr@2
    26
// CONSTANTS
williamr@2
    27
williamr@2
    28
/**
williamr@2
    29
* Minimum allowed intensity setting for vibra. When intensity is negative, 
williamr@2
    30
* the vibra motor rotates in the negative direction.
williamr@2
    31
*/
williamr@2
    32
const TInt KHWRMVibraMinIntensity = -100;
williamr@2
    33
williamr@2
    34
/**
williamr@2
    35
* Minimum allowed intensity setting for vibra pulse.
williamr@2
    36
*/
williamr@2
    37
const TInt KHWRMVibraMinPulseIntensity = 1;
williamr@2
    38
williamr@2
    39
/**
williamr@2
    40
* Maximum allowed intensity setting for vibra. When intensity is positive, 
williamr@2
    41
* the vibra motor rotates in the positive direction. Value 0 effectively 
williamr@2
    42
* stops the vibra.
williamr@2
    43
*/
williamr@2
    44
const TInt KHWRMVibraMaxIntensity = 100;
williamr@2
    45
williamr@2
    46
/**
williamr@2
    47
* Maximum allowed duration value in milliseconds. Maximum vibrating time 
williamr@2
    48
* supported by device is declared in KVibraCtrlMaxTime cenrep-key.
williamr@2
    49
*
williamr@2
    50
* Note that duration probably has device specific
williamr@2
    51
* maximum duration that is much lower.
williamr@2
    52
*/
williamr@2
    53
const TInt KHWRMVibraMaxDuration = (KMaxTInt / 1000) - 1;
williamr@2
    54
williamr@2
    55
/**
williamr@2
    56
* KHWRMVibraInfiniteDuration specifies, that vibrating should continue maximum 
williamr@2
    57
* vibrating time supported by device if vibrating is not explicitly stopped.
williamr@2
    58
*
williamr@2
    59
*/
williamr@2
    60
const TInt KHWRMVibraInfiniteDuration = 0;
williamr@2
    61
williamr@2
    62
// FORWARD DECLARATIONS
williamr@2
    63
class MHWRMVibraObserver;
williamr@2
    64
class MHWRMVibraFeedbackObserver;
williamr@2
    65
williamr@2
    66
// CLASS DECLARATIONS
williamr@2
    67
williamr@2
    68
/**
williamr@2
    69
* The class used to control the device vibra.
williamr@2
    70
*
williamr@2
    71
* HW Resource Manager Vibra API is a library API providing ability to control
williamr@2
    72
* the device vibra. The API provides also methods to retrieve the current settings
williamr@2
    73
* of the vibration feature in the user profile and the current status of the vibra. 
williamr@2
    74
*
williamr@2
    75
* The type of HW Resource Manager Vibra API is a synchronous method call meaning 
williamr@2
    76
* the method call will block the client application. However, e.g. StartVibraL methods do 
williamr@2
    77
* return right after device vibration has successfully been started. Callback is intended only
williamr@2
    78
* for observing vibra and feedback on/off changes. The API is meant for all 
williamr@2
    79
* applications which need to control the device vibra.
williamr@2
    80
*
williamr@2
    81
* The API consist of the classes CHWRMVibra, MHWRMVibraObserver and MHWRMVibraFeedbackObserver. 
williamr@2
    82
* If the client requires up-to-date status information, it should also provide callback pointer
williamr@2
    83
* of the MHWRMVibraObserver implementing class for the NewL-method and explicitly set feedback observer.
williamr@2
    84
*
williamr@2
    85
* Usage:
williamr@2
    86
*
williamr@2
    87
* @code
williamr@2
    88
* #include <HWRMVibra.h>  // link against HWRMVibraClient.lib
williamr@2
    89
*
williamr@2
    90
* // A CHWRMVibra instance can be created by using NewL() or NewLC() methods. 
williamr@2
    91
* // Up-to-date status information not required, no callbacks.
williamr@2
    92
* CHWRMVibra* vibra = CHWRMVibra::NewL();
williamr@2
    93
*
williamr@2
    94
* // After this, vibra can be directly controlled via the provided class methods. 
williamr@2
    95
* vibra->StartVibraL(5000); // Start vibra for five seconds
williamr@2
    96
* vibra->StopVibraL(); // Immediately stop vibra
williamr@2
    97
*
williamr@2
    98
* // To clean up, delete the created object:
williamr@2
    99
* delete vibra;
williamr@2
   100
* @endcode
williamr@2
   101
*
williamr@2
   102
*  @lib HWRMVIBRACLIENT.DLL
williamr@2
   103
*  @since S60 3.0
williamr@2
   104
*/
williamr@2
   105
class CHWRMVibra : public CBase
williamr@2
   106
    {
williamr@2
   107
    public: // enums
williamr@2
   108
        /**
williamr@2
   109
        * Vibration setting in the user profile.
williamr@2
   110
        */
williamr@2
   111
        enum TVibraModeState 
williamr@2
   112
            {
williamr@2
   113
            EVibraModeUnknown = 0, ///< Not initialized yet or there is an error condion.
williamr@2
   114
            EVibraModeON,          ///< Vibration setting in the user profile is on.
williamr@2
   115
            EVibraModeOFF          ///< Vibration setting in the user profile is off.
williamr@2
   116
            };
williamr@2
   117
williamr@2
   118
        /**
williamr@2
   119
        * Status of the vibration feature
williamr@2
   120
        */
williamr@2
   121
        enum TVibraStatus 
williamr@2
   122
            {
williamr@2
   123
            EVibraStatusUnknown = 0, ///< Vibra is not initialized yet or status is uncertain 
williamr@2
   124
                                     ///< because of an error condition.
williamr@2
   125
            EVibraStatusNotAllowed,  ///< Vibra is set off in the user profile or some
williamr@2
   126
                                     ///< application is specifically blocking vibra.
williamr@2
   127
            EVibraStatusStopped,     ///< Vibra is stopped.
williamr@2
   128
            EVibraStatusOn           ///< Vibra is on.
williamr@2
   129
            };
williamr@2
   130
            
williamr@2
   131
        /**
williamr@2
   132
        * Tactile feedback vibration setting in the user profile.
williamr@2
   133
        */
williamr@2
   134
        enum TVibraFeedbackModeState 
williamr@2
   135
            {
williamr@2
   136
            EVibraFeedbackModeUnknown = 0, ///< Not initialized yet or there is an error condion.
williamr@2
   137
            EVibraFeedbackModeON,          ///< Feedback vibration setting in the user profile is on.
williamr@2
   138
            EVibraFeedbackModeOFF          ///< Feedback vibration setting in the user profile is off.
williamr@2
   139
            };
williamr@2
   140
williamr@2
   141
    public:  // Constructors
williamr@2
   142
        
williamr@2
   143
        /**
williamr@2
   144
        * Two-phased constructor.
williamr@2
   145
        *
williamr@2
   146
        * @return A pointer to a new instance of the CHWRMVibra class.
williamr@2
   147
        *
williamr@2
   148
        * @leave KErrNotSupported Device doesn't support vibration feature.
williamr@2
   149
        * @leave KErrNoMemory There is a memory allocation failure. 
williamr@2
   150
        */
williamr@2
   151
        IMPORT_C static CHWRMVibra* NewL();
williamr@2
   152
        
williamr@2
   153
        /**
williamr@2
   154
        * Two-phased constructor.
williamr@2
   155
        * Leaves instance to cleanup stack.
williamr@2
   156
        *
williamr@2
   157
        * @return A pointer to a new instance of the CHWRMVibra class.
williamr@2
   158
        *
williamr@2
   159
        * @leave KErrNotSupported Device doesn't support vibration feature.
williamr@2
   160
        * @leave KErrNoMemory There is a memory allocation failure. 
williamr@2
   161
        */
williamr@2
   162
        IMPORT_C static CHWRMVibra* NewLC();
williamr@2
   163
williamr@2
   164
        /**
williamr@2
   165
        * Two-phased constructor.
williamr@2
   166
        * Use this method for creating a vibra client with callbacks.
williamr@2
   167
        *
williamr@2
   168
        * @param aCallback Pointer to callback instance
williamr@2
   169
        * @return A pointer to a new instance of the CHWRMVibra class.
williamr@2
   170
        *
williamr@2
   171
        * @leave KErrNotSupported Device doesn't support vibration feature.
williamr@2
   172
        * @leave KErrNoMemory There is a memory allocation failure. 
williamr@2
   173
        */
williamr@2
   174
        IMPORT_C static CHWRMVibra* NewL(MHWRMVibraObserver* aCallback);
williamr@2
   175
        
williamr@2
   176
        /**
williamr@2
   177
        * Two-phased constructor. 
williamr@2
   178
        * Use this method for creating a vibra client with callbacks.
williamr@2
   179
        * Leaves instance to cleanup stack.
williamr@2
   180
        *
williamr@2
   181
        * @param aCallback Pointer to callback instance
williamr@2
   182
        * @return A pointer to a new instance of the CHWRMVibra class.
williamr@2
   183
        *
williamr@2
   184
        * @leave KErrNotSupported Device doesn't support vibration feature.
williamr@2
   185
        * @leave KErrNoMemory There is a memory allocation failure. 
williamr@2
   186
        */
williamr@2
   187
        IMPORT_C static CHWRMVibra* NewLC(MHWRMVibraObserver* aCallback);
williamr@2
   188
williamr@2
   189
    public: // New functions
williamr@2
   190
williamr@2
   191
    	/**
williamr@2
   192
    	* Reserves vibration feature exclusively for this client.
williamr@2
   193
    	* A higher priority (not process or thread priority, but the priority defined
williamr@2
   194
    	* in the internal vibra policy of the HW Resource Manager) client may cause 
williamr@2
   195
    	* lower priority client reservation to be temporarily suspended. Commands 
williamr@2
   196
    	* can still be issued in suspended state, but they will not be acted upon 
williamr@2
   197
    	* unless suspension is lifted within specified duration.
williamr@2
   198
    	* The suspended client will not get any notification about suspension and
williamr@2
   199
    	* neither from resumption of reservation.
williamr@2
   200
    	* If vibra is already reserved by a higher or equal priority application, 
williamr@2
   201
    	* reserving will still succeed, but reservation is immediately suspended.
williamr@2
   202
    	*
williamr@2
   203
    	* Calling this method is equal to call ReserveVibraL(EFalse, EFalse),
williamr@2
   204
    	* i.e. any previously frozen state will not be restored and CCoeEnv
williamr@2
   205
    	* background/foreground status is always used to control further reservations.
williamr@2
   206
    	*
williamr@2
   207
    	* @leave KErrAccessDenied No CCoeEnv present.
williamr@2
   208
    	* @leave KErrNotReady Trying to reserve while on background.
williamr@2
   209
        * @leave KErrNoMemory There is a memory allocation failure. 
williamr@2
   210
    	*/
williamr@2
   211
    	virtual void ReserveVibraL()=0;
williamr@2
   212
    	
williamr@2
   213
    	/**
williamr@2
   214
    	* Reserves vibration feature exclusively for this client.
williamr@2
   215
    	* A higher priority (not process or thread priority, but the priority defined
williamr@2
   216
    	* in the internal vibra policy of the HW Resource Manager) client may cause 
williamr@2
   217
    	* lower priority client reservation to be temporarily suspended. Commands 
williamr@2
   218
    	* can still be issued in suspended state, but they will not be acted upon 
williamr@2
   219
    	* unless suspension is lifted within specified duration.
williamr@2
   220
    	* The suspended client will not get any notification about suspension and
williamr@2
   221
    	* neither from resumption of reservation.
williamr@2
   222
    	* If vibra is already reserved by a higher or equal priority application, 
williamr@2
   223
    	* reserving will still succeed, but reservation is immediately suspended.
williamr@2
   224
    	*
williamr@2
   225
    	*
williamr@2
   226
    	* @param aRestoreState If ETrue, the state frozen on last release will be
williamr@2
   227
    	*                      restored upon successful reservation.
williamr@2
   228
    	*                      I.e. if vibra was on when it was released by this 
williamr@2
   229
        *                      client the last time, it would continue the vibrating
williamr@2
   230
        *                      upon successful reservation.
williamr@2
   231
    	*                      For the first reservation of each session this 
williamr@2
   232
        *                      parameter is always considered EFalse regardless of 
williamr@2
   233
        *                      what is supplied, as there is no previous frozen state
williamr@2
   234
        *                      to restore.
williamr@2
   235
    	* @param aForceNoCCoeEnv If EFalse, then reservation requires that this client
williamr@2
   236
        *                        has the keyboard focus at the time of reservation and
williamr@2
   237
        *                        vibra will be automatically released and re-reserved 
williamr@2
   238
        *                        based on the keyboard focus status of this client. 
williamr@2
   239
        *                        This also implies that CCoeEnv::Static() != NULL is 
williamr@2
   240
        *                        required.
williamr@2
   241
    	*                        If ETrue, the client will not require CCoeEnv to be 
williamr@2
   242
        *                        present nor does it automatically reserve/release vibra 
williamr@2
   243
    	*                        by depending on foreground/background status of the 
williamr@2
   244
        *                        client.
williamr@2
   245
    	*                        Only trusted clients are allowed to set this flag to
williamr@2
   246
        *                        ETrue. A client is considered trusted if it has nonstandard
williamr@2
   247
        *                        priority defined in the internal vibra policy of the 
williamr@2
   248
        *                        HW Resource Manager. A client can be defined trusted
williamr@2
   249
        *                        only by S60 or a product.
williamr@2
   250
    	*
williamr@2
   251
    	* @leave KErrAccessDenied Parameter aForceNoCCoeEnv is ETrue and client is not
williamr@2
   252
    	*                         trusted.
williamr@2
   253
    	* @leave KErrBadHandle Parameter aForceNoCCoeEnv is EFalse and no CCoeEnv present.
williamr@2
   254
    	* @leave KErrNotReady Trying to reserve while on background and parameter 
williamr@2
   255
        *                     aForceNoCCoeEnv is EFalse.
williamr@2
   256
        * @leave KErrNoMemory There is a memory allocation failure. 
williamr@2
   257
    	*/
williamr@2
   258
    	virtual void ReserveVibraL(TBool aRestoreState, TBool aForceNoCCoeEnv)=0;
williamr@2
   259
williamr@2
   260
    	/**
williamr@2
   261
    	* Releases vibration feature if it was previously reserved for this client.
williamr@2
   262
    	* If this client has not reserved vibration feature, does nothing.
williamr@2
   263
    	* If vibra is on when it is released and no other client has a suspended 
williamr@2
   264
    	* reservation, vibra is stopped.
williamr@2
   265
    	*/
williamr@2
   266
    	virtual void ReleaseVibra()=0;
williamr@2
   267
williamr@2
   268
williamr@2
   269
        /**
williamr@2
   270
        * Starts the device vibration feature with the product specific default
williamr@2
   271
        * intensity.
williamr@2
   272
        * If StartVibraL is called again before the first vibration completes
williamr@2
   273
        * then the first vibration is interrupted and the second vibrations
williamr@2
   274
        * starts immediately -- i.e. The periods of vibration are not cumulative.
williamr@2
   275
        *
williamr@2
   276
        * The vibration can be interrupted with the method StopVibraL before
williamr@2
   277
        * the specified interval has elapsed. 
williamr@2
   278
        *
williamr@2
   279
        * Vibra settings of the vibration feature in the user profile 
williamr@2
   280
        * must be active. 
williamr@2
   281
        *
williamr@2
   282
        * Note: The device may have implementation defined or hardware imposed
williamr@2
   283
        *       limits to the duration of the vibration feature. In such 
williamr@2
   284
        *       circumstances any vibration will cut off at that limit even if
williamr@2
   285
        *       the duration parameter is greater than the limit.
williamr@2
   286
        *
williamr@2
   287
        * @param aDuration Duration of the vibration measured in milliseconds. 
williamr@2
   288
        *                  A value of KHWRMVibraInfiniteDuration specifies that 
williamr@2
   289
        *                  the vibration should continue indefinetely and should 
williamr@2
   290
        *                  be stopped with a call to StopVibraL. Duration 
williamr@2
   291
        *                  usually has device specific maximum value.
williamr@2
   292
        *
williamr@2
   293
        * @leave KErrArgument Duration is invalid.
williamr@2
   294
        * @leave KErrAccessDenied Vibration setting in the user profile is not set.
williamr@2
   295
        * @leave KErrBadHandle Vibra session has been invalidated.
williamr@2
   296
        * @leave KErrLocked Vibra is locked down because too much continuous use
williamr@2
   297
        *                   or explicitly blocked by for example some vibration 
williamr@2
   298
        *                   sensitive accessory.
williamr@2
   299
        * @leave KErrTimedOut Timeout occurred in controlling vibra.
williamr@2
   300
        * @leave KErrInUse Vibra is not reserved to this client but it is
williamr@2
   301
        *                  reserved to some other client.
williamr@2
   302
        * @leave KErrNoMemory There is a memory allocation failure. 
williamr@2
   303
        * @leave KErrGeneral There is a hardware error.
williamr@2
   304
        *
williamr@2
   305
        * @see MHWRMVibraObserver
williamr@2
   306
        */
williamr@2
   307
        virtual void StartVibraL(TInt aDuration)=0;
williamr@2
   308
		
williamr@2
   309
        /**
williamr@2
   310
        * Starts the device vibration feature. If StartVibraL is called again before
williamr@2
   311
        * the first vibration completes then the first vibration is interrupted
williamr@2
   312
        * and the second vibrations starts immediately -- i.e. The periods of
williamr@2
   313
        * vibration are not cumulative.
williamr@2
   314
        *
williamr@2
   315
        * The vibration can be interrupted with the method StopVibraL before
williamr@2
   316
        * the specified interval has elapsed.
williamr@2
   317
        *
williamr@2
   318
        * Vibra settings of the vibration feature in the user profile 
williamr@2
   319
        * must be active. 
williamr@2
   320
        *
williamr@2
   321
        * Note: The device may have implementation defined or hardware imposed
williamr@2
   322
        *       limits to the duration of the vibration feature. In such 
williamr@2
   323
        *       circumstances any vibration will cut off at that limit even if
williamr@2
   324
        *       the duration parameter is greater than the limit.
williamr@2
   325
        *
williamr@2
   326
        * @param aDuration Duration of the vibration measured in milliseconds. 
williamr@2
   327
        *                  A value of KHWRMVibraInfiniteDuration specifies that 
williamr@2
   328
        *                  the vibration should continue indefinetely and should 
williamr@2
   329
        *                  be stopped with a call to StopVibraL. Duration 
williamr@2
   330
        *                  usually has device specific maximum value.
williamr@2
   331
        * @param aIntensity Intensity of the vibra in decimal is KHWRMVibraMinIntensity
williamr@2
   332
        *                   to KHWRMVibraMaxIntensity,
williamr@2
   333
        *                   which shows the percentage of the vibra motor full
williamr@2
   334
        *                   rotation speed. When intensity is negative, 
williamr@2
   335
        *                   the vibra motor rotates in the negative direction.
williamr@2
   336
        *                   When intensity is positive, the vibra motor rotates
williamr@2
   337
        *                   in the positive direction. Value 0 stops the vibra.
williamr@2
   338
        *                   NOTE: The device might have hardware-imposed limits
williamr@2
   339
        *                         on supported vibra intensity values, so actual
williamr@2
   340
        *                         effect might vary between different hardware.
williamr@2
   341
        *
williamr@2
   342
        * @leave KErrNotSupported The device doesn't support user-defined 
williamr@2
   343
        *                         vibra intensity.
williamr@2
   344
        * @leave KErrArgument One of the parameters is out of range.
williamr@2
   345
        * @leave KErrAccessDenied Vibration setting in the user profile
williamr@2
   346
        *                         is not set.
williamr@2
   347
        * @leave KErrBadHandle Vibra session has been invalidated.
williamr@2
   348
        * @leave KErrLocked Vibra is locked down because too much continuous use
williamr@2
   349
        *                   or explicitly blocked by for example some vibration
williamr@2
   350
        *                   sensitive accessory.
williamr@2
   351
        * @leave KErrTimedOut Timeout occurred in controlling vibra.
williamr@2
   352
        * @leave KErrInUse Vibra is not reserved to this client but it is
williamr@2
   353
        *                  reserved to some other client.
williamr@2
   354
        * @leave KErrNoMemory There is a memory allocation failure. 
williamr@2
   355
        * @leave KErrGeneral There is a hardware error.
williamr@2
   356
        *
williamr@2
   357
        * @see MHWRMVibraObserver
williamr@2
   358
        */
williamr@2
   359
	    virtual void StartVibraL(TInt aDuration, TInt aIntensity)=0;
williamr@2
   360
	    
williamr@2
   361
	    /**
williamr@2
   362
        * Interrupts the device vibration that is started with the StartVibraL
williamr@2
   363
        * method immediately.
williamr@2
   364
        *
williamr@2
   365
        * @leave KErrBadHandle Vibra session has been invalidated.
williamr@2
   366
        * @leave KErrTimedOut Timeout occurred in controlling vibra.
williamr@2
   367
        * @leave KErrInUse Vibra is not reserved to this client but it is
williamr@2
   368
        *                  reserved to some other client.
williamr@2
   369
        * @leave KErrNoMemory There is a memory allocation failure. 
williamr@2
   370
        * @leave KErrGeneral There is a hardware error.
williamr@2
   371
        *
williamr@2
   372
        * @see MHWRMVibraObserver
williamr@2
   373
        */		
williamr@2
   374
        virtual void StopVibraL()=0; 
williamr@2
   375
		
williamr@2
   376
        /**
williamr@2
   377
        * This method retrieves the current settings of the vibration feature
williamr@2
   378
        * in the user profile. The developer can check the Vibra settings 
williamr@2
   379
        * in the profile and if there is no Vibra active but it is needed by 
williamr@2
   380
        * the client application then the user can be informed.
williamr@2
   381
        *
williamr@2
   382
        * @return TVibraModeState indicating the current vibra mode setting.
williamr@2
   383
        *
williamr@2
   384
        * @see TVibraModeState
williamr@2
   385
        * @see MHWRMVibraObserver
williamr@2
   386
        */
williamr@2
   387
        virtual TVibraModeState VibraSettings() const=0;
williamr@2
   388
williamr@2
   389
        /**
williamr@2
   390
        * This method retrieves the current vibra status. 
williamr@2
   391
        *
williamr@2
   392
        * @return TVibraStatus indicating the current vibra status
williamr@2
   393
        * 
williamr@2
   394
        * @see TVibraStatus
williamr@2
   395
        * @see MHWRMVibraObserver
williamr@2
   396
        */
williamr@2
   397
        virtual TVibraStatus VibraStatus() const=0;
williamr@2
   398
        
williamr@2
   399
        /**
williamr@2
   400
        * This method is intended only for firmware build time configured 
williamr@2
   401
        * privileged clients.
williamr@2
   402
        *
williamr@2
   403
        * Executes a tactile feedback vibration pulse with product 
williamr@2
   404
        * specific default intensity and duration.
williamr@2
   405
        * If PulseVibraL is called before ongoing vibration completes and 
williamr@2
   406
        * PulseVibraL calling client has higher priority than executing client,
williamr@2
   407
        * pulse request is accepted. Also possible vibra-reservations are bypassed.
williamr@2
   408
        * If client calling PulseVibraL has lower or equal priority 
williamr@2
   409
        * than executing client, ongoing vibration is not affected.
williamr@2
   410
        *
williamr@2
   411
        * Tactile feedback vibration settings of the vibration feature in the 
williamr@2
   412
        * user profile must be active. 
williamr@2
   413
        *
williamr@2
   414
        * Note: The device may have implementation defined or hardware imposed
williamr@2
   415
        *       limits to the duration of the vibration feature. In such 
williamr@2
   416
        *       circumstances any vibration will cut off at that limit even if
williamr@2
   417
        *       the duration parameter is greater than the limit.
williamr@2
   418
        *
williamr@2
   419
        * @param aDuration Duration of the vibration measured in milliseconds. 
williamr@2
   420
        *                  Duration can have maximum value
williamr@2
   421
        *                  of KHWRMVibraMaxDuration.
williamr@2
   422
        *
williamr@2
   423
        * @leave KErrAccessDenied Vibration setting in the user profile is not set
williamr@2
   424
        *                         or client is not privileged to use pulse feature. 
williamr@2
   425
        * @leave KErrBadHandle Vibra session has been invalidated.
williamr@2
   426
        * @leave KErrLocked Vibra is locked down because too much continuous use
williamr@2
   427
        *                   or explicitly blocked by for example some vibration 
williamr@2
   428
        *                   sensitive accessory.
williamr@2
   429
        * @leave KErrTimedOut Timeout occurred in controlling vibra.
williamr@2
   430
        * @leave KErrInUse Vibra is not reserved to this client but it is
williamr@2
   431
        *                  reserved to some other client or ongoing vibration
williamr@2
   432
        *                  has been requested by higher priority client.
williamr@2
   433
        * @leave KErrNoMemory There is a memory allocation failure. 
williamr@2
   434
        * @leave KErrGeneral There is a hardware error.
williamr@2
   435
        *
williamr@2
   436
        * @see MHWRMVibraFeedbackObserver
williamr@2
   437
        */
williamr@2
   438
        virtual void PulseVibraL()=0;
williamr@2
   439
		
williamr@2
   440
        /**
williamr@2
   441
        * This method is intended only for firmware build time configured 
williamr@2
   442
        * privileged clients.
williamr@2
   443
        *
williamr@2
   444
        * Executes a tactile feedback vibration pulse with product 
williamr@2
   445
        * specific default intensity and specified duration.
williamr@2
   446
        * If PulseVibraL is called before ongoing vibration completes and 
williamr@2
   447
        * PulseVibraL calling client has higher priority than executing client,
williamr@2
   448
        * pulse request is accepted. Also possible vibra-reservations are bypassed.
williamr@2
   449
        * If client calling PulseVibraL has lower or equal priority 
williamr@2
   450
        * than executing client, ongoing vibration is not affected.
williamr@2
   451
        *
williamr@2
   452
        * Tactile feedback vibration settings of the vibration feature in the 
williamr@2
   453
        * user profile must be active. 
williamr@2
   454
        *
williamr@2
   455
        * Note: The device may have implementation defined or hardware imposed
williamr@2
   456
        *       limits to the duration of the vibration feature. In such 
williamr@2
   457
        *       circumstances any vibration will cut off at that limit even if
williamr@2
   458
        *       the duration parameter is greater than the limit.
williamr@2
   459
        *
williamr@2
   460
        * @param aDuration Duration of the vibration measured in milliseconds. 
williamr@2
   461
        *                  Duration can have maximum value
williamr@2
   462
        *                  of KHWRMVibraMaxDuration.
williamr@2
   463
        *
williamr@2
   464
        * @leave KErrArgument One of the parameters is out of range.
williamr@2
   465
        * @leave KErrAccessDenied Vibration setting in the user profile is not set
williamr@2
   466
        *                         or client is not privileged to use pulse feature. 
williamr@2
   467
        * @leave KErrBadHandle Vibra session has been invalidated.
williamr@2
   468
        * @leave KErrLocked Vibra is locked down because too much continuous use
williamr@2
   469
        *                   or explicitly blocked by for example some vibration 
williamr@2
   470
        *                   sensitive accessory.
williamr@2
   471
        * @leave KErrTimedOut Timeout occurred in controlling vibra.
williamr@2
   472
        * @leave KErrInUse Vibra is not reserved to this client but it is
williamr@2
   473
        *                  reserved to some other client or ongoing vibration
williamr@2
   474
        *                  has been requested by higher priority client.
williamr@2
   475
        * @leave KErrNoMemory There is a memory allocation failure. 
williamr@2
   476
        * @leave KErrGeneral There is a hardware error.
williamr@2
   477
        *
williamr@2
   478
        * @see MHWRMVibraFeedbackObserver
williamr@2
   479
        */
williamr@2
   480
        virtual void PulseVibraL(TInt aDuration)=0;
williamr@2
   481
		
williamr@2
   482
        /**
williamr@2
   483
        * This method is intended only for firmware build time configured 
williamr@2
   484
        * privileged clients.
williamr@2
   485
        *
williamr@2
   486
        * Executes a tactile feedback vibration pulse.
williamr@2
   487
        * If PulseVibraL is called before ongoing vibration completes and 
williamr@2
   488
        * PulseVibraL calling client has higher priority than executing client,
williamr@2
   489
        * pulse request is accepted. Also possible vibra-reservations are bypassed.
williamr@2
   490
        * If client calling PulseVibraL has lower or equal priority 
williamr@2
   491
        * than executing client, ongoing vibration is not affected.
williamr@2
   492
        *
williamr@2
   493
        * Tactile feedback vibration settings of the vibration feature in the 
williamr@2
   494
        * user profile must be active. 
williamr@2
   495
        *
williamr@2
   496
        * Note: The device may have implementation defined or hardware imposed
williamr@2
   497
        *       limits to the duration of the vibration feature. In such 
williamr@2
   498
        *       circumstances any vibration will cut off at that limit even if
williamr@2
   499
        *       the duration parameter is greater than the limit.
williamr@2
   500
        *
williamr@2
   501
        * @param aDuration Duration of the vibration measured in milliseconds. 
williamr@2
   502
        *                  Duration can have maximum value
williamr@2
   503
        *                  of KHWRMVibraMaxDuration.
williamr@2
   504
        * @param aIntensity Intensity of the pulse in decimal is KHWRMVibraMinPulseIntensity
williamr@2
   505
        *                   to KHWRMVibraMaxIntensity, which shows the percentage 
williamr@2
   506
        *                   of the vibra motor full rotation speed. 
williamr@2
   507
        *                   NOTE: The device might have hardware-imposed limits
williamr@2
   508
        *                         on supported vibra intensity values, so actual
williamr@2
   509
        *                         effect might vary between different hardware.
williamr@2
   510
        *
williamr@2
   511
        * @leave KErrNotSupported The device doesn't support user-defined 
williamr@2
   512
        *                         vibra intensity.
williamr@2
   513
        * @leave KErrArgument One of the parameters is out of range.
williamr@2
   514
        * @leave KErrAccessDenied Vibration setting in the user profile is not set
williamr@2
   515
        *                         or client is not privileged to use pulse feature. 
williamr@2
   516
        * @leave KErrBadHandle Vibra session has been invalidated.
williamr@2
   517
        * @leave KErrLocked Vibra is locked down because too much continuous use
williamr@2
   518
        *                   or explicitly blocked by for example some vibration 
williamr@2
   519
        *                   sensitive accessory.
williamr@2
   520
        * @leave KErrTimedOut Timeout occurred in controlling vibra.
williamr@2
   521
        * @leave KErrInUse Vibra is not reserved to this client but it is
williamr@2
   522
        *                  reserved to some other client or ongoing vibration
williamr@2
   523
        *                  has been requested by higher priority client.
williamr@2
   524
        * @leave KErrNoMemory There is a memory allocation failure. 
williamr@2
   525
        * @leave KErrGeneral There is a hardware error.
williamr@2
   526
        *
williamr@2
   527
        * @see MHWRMVibraFeedbackObserver
williamr@2
   528
        */
williamr@2
   529
        virtual void PulseVibraL(TInt aDuration, TInt aIntensity)=0;
williamr@2
   530
		
williamr@2
   531
        /**
williamr@2
   532
        * Use this method for setting feedback observer.
williamr@2
   533
        *
williamr@2
   534
        * @param aCallback Pointer to callback instance
williamr@2
   535
        */
williamr@2
   536
        virtual void SetFeedbackObserver(MHWRMVibraFeedbackObserver* aCallback)=0;
williamr@2
   537
williamr@2
   538
        /**
williamr@2
   539
        * This method retrieves the current settings of the feedback vibration feature
williamr@2
   540
        * in the user profile. The developer can check the feedback vibration settings 
williamr@2
   541
        * in the profile and if there is no feedback vibration active but it is needed by 
williamr@2
   542
        * the client application then the user can be informed. However, client needs to 
williamr@2
   543
        * explicitly register to listen these changes via SetFeedbackObserver-method.
williamr@2
   544
        *
williamr@2
   545
        * @return TVibraFeedbackModeState indicating the current vibra feedback mode setting.
williamr@2
   546
        *
williamr@2
   547
        * @see TVibraFeedbackModeState
williamr@2
   548
        * @see MHWRMVibraFeedbackObserver
williamr@2
   549
        */
williamr@2
   550
        virtual TVibraFeedbackModeState VibraFeedbackSettings() const=0;
williamr@2
   551
    };
williamr@2
   552
    
williamr@2
   553
/**
williamr@2
   554
* A callback interface for vibra status reporting.
williamr@2
   555
*
williamr@2
   556
* If the client requires up-to-date status information, the client needs 
williamr@2
   557
* to derive a class from the MHWRMVibraObserver interface and implement 
williamr@2
   558
* the VibraModeChanged() and VibraStatusChanged() methods. 
williamr@2
   559
* 
williamr@2
   560
* A callback object header example:
williamr@2
   561
*
williamr@2
   562
* @code 
williamr@2
   563
* // INCLUDES
williamr@2
   564
* #include <HWRMVibra.h> // Link against HWRMVibraClient.lib.
williamr@2
   565
*
williamr@2
   566
* class CTest : public CBase, 
williamr@2
   567
*               public MHWRMVibraObserver    
williamr@2
   568
*    {
williamr@2
   569
*    public:
williamr@2
   570
*        CTest();
williamr@2
   571
*        ~CTest();
williamr@2
   572
*                       
williamr@2
   573
*        void ConstructL();
williamr@2
   574
*        static CTest* NewL();
williamr@2
   575
*                
williamr@2
   576
*        // from MHWRMVibraObserver
williamr@2
   577
*        virtual void VibraModeChanged(CHWRMVibra::TVibraModeState aStatus);
williamr@2
   578
*        virtual void VibraStatusChanged(CHWRMVibra::TVibraStatus aStatus);
williamr@2
   579
*
williamr@2
   580
*    private:
williamr@2
   581
*        CHWRMVibra* iVibra;
williamr@2
   582
*    };
williamr@2
   583
* @endcode
williamr@2
   584
*
williamr@2
   585
* A callback method implementation example:
williamr@2
   586
*
williamr@2
   587
* @code
williamr@2
   588
* void CTest::VibraStatusChanged(CHWRMVibra::TVibraStatus aStatus)
williamr@2
   589
*    {
williamr@2
   590
*    switch ( aStatus )
williamr@2
   591
*        {
williamr@2
   592
*        case CHWRMVibra::EVibraStatusUnknown:
williamr@2
   593
*            RDebug::Print(_L("### Vibra state changed: EVibraStatusUnknown"));
williamr@2
   594
*            break;
williamr@2
   595
*        case CHWRMVibra::EVibraStatusNotAllowed:
williamr@2
   596
*            RDebug::Print(_L("### Vibra state changed: EVibraStatusNotAllowed"));
williamr@2
   597
*            break;
williamr@2
   598
*        case CHWRMVibra::EVibraStatusStopped:
williamr@2
   599
*            RDebug::Print(_L("### Vibra state changed: EVibraStatusStopped"));
williamr@2
   600
*            break;
williamr@2
   601
*        case CHWRMVibra::EVibraStatusOn:
williamr@2
   602
*            RDebug::Print(_L("### Vibra state changed: EVibraStatusOn"));
williamr@2
   603
*            break;
williamr@2
   604
*        default:
williamr@2
   605
*            RDebug::Print(_L("### Vibra state changed: UNDEFINED !"));
williamr@2
   606
*            break;
williamr@2
   607
*        }
williamr@2
   608
*    }
williamr@2
   609
* @endcode
williamr@2
   610
*
williamr@2
   611
* @since S60 3.0
williamr@2
   612
*/
williamr@2
   613
class MHWRMVibraObserver
williamr@2
   614
    {    
williamr@2
   615
    public:
williamr@2
   616
        
williamr@2
   617
        /** 
williamr@2
   618
        * Called when the vibration setting in the user profile is changed.
williamr@2
   619
        *
williamr@2
   620
        * @param aStatus Indicates the new setting.
williamr@2
   621
        *
williamr@2
   622
        * @see CHWRMVibra::TVibraModeState
williamr@2
   623
        */
williamr@2
   624
        virtual void VibraModeChanged(CHWRMVibra::TVibraModeState aStatus) = 0;
williamr@2
   625
        
williamr@2
   626
        /** 
williamr@2
   627
        * Called when the device vibration feature state changes
williamr@2
   628
        *
williamr@2
   629
        * @param aStatus Indicates vibra status.
williamr@2
   630
        *
williamr@2
   631
        * @see CHWRMVibra::TVibraStatus
williamr@2
   632
		*/
williamr@2
   633
        virtual void VibraStatusChanged(CHWRMVibra::TVibraStatus aStatus) = 0;
williamr@2
   634
	};
williamr@2
   635
williamr@2
   636
/**
williamr@2
   637
* A callback interface for tactile feedback vibra mode reporting.
williamr@2
   638
*
williamr@2
   639
* If the client requires up-to-date status information, the client needs 
williamr@2
   640
* to derive a class from the MHWRMVibraFeedbackObserver interface and implement 
williamr@2
   641
* the VibraFeedbackModeChanged() method. In order to register for callback, client
williamr@2
   642
* needs to call SetFeedbackObserver-method.
williamr@2
   643
* 
williamr@2
   644
* A callback object header example:
williamr@2
   645
*
williamr@2
   646
* @code 
williamr@2
   647
* // INCLUDES
williamr@2
   648
* #include <HWRMVibra.h> // Link against HWRMVibraClient.lib.
williamr@2
   649
*
williamr@2
   650
* class CTest : public CBase, 
williamr@2
   651
*               public MHWRMVibraFeedbackObserver    
williamr@2
   652
*    {
williamr@2
   653
*    public:
williamr@2
   654
*        CTest();
williamr@2
   655
*        ~CTest();
williamr@2
   656
*                       
williamr@2
   657
*        void ConstructL();
williamr@2
   658
*        static CTest* NewL();
williamr@2
   659
*                
williamr@2
   660
*        // from MHWRMVibraFeedbackObserver
williamr@2
   661
*        virtual void VibraFeedbackModeChanged(CHWRMVibra::TVibraFeedbackModeState aMode);
williamr@2
   662
*
williamr@2
   663
*    private:
williamr@2
   664
*        CHWRMVibra* iVibra;
williamr@2
   665
*    };
williamr@2
   666
* @endcode
williamr@2
   667
*
williamr@2
   668
* A callback method implementation example:
williamr@2
   669
*
williamr@2
   670
* @code
williamr@2
   671
* 
williamr@2
   672
* #include <HWRMVibra.h>  // link against HWRMVibraClient.lib
williamr@2
   673
*
williamr@2
   674
* // A CHWRMVibra instance can be created by using NewL() or NewLC() methods. 
williamr@2
   675
* CHWRMVibra* vibra = CHWRMVibra::NewL();
williamr@2
   676
*
williamr@2
   677
* // Request notification of feedback setting change
williamr@2
   678
* vibra->SetFeedbackObserver(this); 
williamr@2
   679
*
williamr@2
   680
* // To clean up, delete the created object:
williamr@2
   681
* delete vibra;
williamr@2
   682
* 
williamr@2
   683
* void CTest::VibraFeedbackModeChanged(CHWRMVibra::TVibraFeedbackModeState aMode)
williamr@2
   684
*    {
williamr@2
   685
*    switch ( aMode )
williamr@2
   686
*        {
williamr@2
   687
*        case CHWRMVibra::EVibraFeedbackModeUnknown:
williamr@2
   688
*            RDebug::Print(_L("### Feedback vibration mode : EVibraFeedbackModeUnknown"));
williamr@2
   689
*            break;
williamr@2
   690
*        case CHWRMVibra::EVibraFeedbackModeON:
williamr@2
   691
*            RDebug::Print(_L("### Feedback vibration mode : EVibraFeedbackModeON"));
williamr@2
   692
*            break;
williamr@2
   693
*        case CHWRMVibra::EVibraFeedbackModeOFF:
williamr@2
   694
*            RDebug::Print(_L("### Feedback vibration mode : EVibraFeedbackModeOFF"));
williamr@2
   695
*            break;
williamr@2
   696
*        default:
williamr@2
   697
*            break;
williamr@2
   698
*        }
williamr@2
   699
*    }
williamr@2
   700
* @endcode
williamr@2
   701
*
williamr@2
   702
* @since S60 5.0
williamr@2
   703
*/
williamr@2
   704
class MHWRMVibraFeedbackObserver
williamr@2
   705
    {    
williamr@2
   706
    public:
williamr@2
   707
        
williamr@2
   708
        /** 
williamr@2
   709
        * Called when the tactile feedback vibration setting in the user profile is changed.
williamr@2
   710
        *
williamr@2
   711
        * @param aMode Indicates the new setting.
williamr@2
   712
        *
williamr@2
   713
        * @see CHWRMVibra::TVibraFeedbackModeState
williamr@2
   714
        */
williamr@2
   715
        virtual void VibraFeedbackModeChanged(CHWRMVibra::TVibraFeedbackModeState aMode) = 0;
williamr@2
   716
	};
williamr@2
   717
williamr@2
   718
williamr@2
   719
#endif      // HWRMVIBRA_H   
williamr@2
   720
            
williamr@2
   721
// End of File