2 * Copyright (c) 2002-2007 Nokia Corporation and/or its subsidiary(-ies).
4 * This component and the accompanying materials are made available
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
6 * which accompanies this distribution, and is available
7 * at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
9 * Initial Contributors:
10 * Nokia Corporation - initial contribution.
14 * Description: This file contains the header of the
29 * Minimum allowed intensity setting for vibra. When intensity is negative,
30 * the vibra motor rotates in the negative direction.
32 const TInt KHWRMVibraMinIntensity = -100;
35 * Minimum allowed intensity setting for vibra pulse.
37 const TInt KHWRMVibraMinPulseIntensity = 1;
40 * Maximum allowed intensity setting for vibra. When intensity is positive,
41 * the vibra motor rotates in the positive direction. Value 0 effectively
44 const TInt KHWRMVibraMaxIntensity = 100;
47 * Maximum allowed duration value in milliseconds. Maximum vibrating time
48 * supported by device is declared in KVibraCtrlMaxTime cenrep-key.
50 * Note that duration probably has device specific
51 * maximum duration that is much lower.
53 const TInt KHWRMVibraMaxDuration = (KMaxTInt / 1000) - 1;
56 * KHWRMVibraInfiniteDuration specifies, that vibrating should continue maximum
57 * vibrating time supported by device if vibrating is not explicitly stopped.
60 const TInt KHWRMVibraInfiniteDuration = 0;
62 // FORWARD DECLARATIONS
63 class MHWRMVibraObserver;
64 class MHWRMVibraFeedbackObserver;
69 * The class used to control the device vibra.
71 * HW Resource Manager Vibra API is a library API providing ability to control
72 * the device vibra. The API provides also methods to retrieve the current settings
73 * of the vibration feature in the user profile and the current status of the vibra.
75 * The type of HW Resource Manager Vibra API is a synchronous method call meaning
76 * the method call will block the client application. However, e.g. StartVibraL methods do
77 * return right after device vibration has successfully been started. Callback is intended only
78 * for observing vibra and feedback on/off changes. The API is meant for all
79 * applications which need to control the device vibra.
81 * The API consist of the classes CHWRMVibra, MHWRMVibraObserver and MHWRMVibraFeedbackObserver.
82 * If the client requires up-to-date status information, it should also provide callback pointer
83 * of the MHWRMVibraObserver implementing class for the NewL-method and explicitly set feedback observer.
88 * #include <HWRMVibra.h> // link against HWRMVibraClient.lib
90 * // A CHWRMVibra instance can be created by using NewL() or NewLC() methods.
91 * // Up-to-date status information not required, no callbacks.
92 * CHWRMVibra* vibra = CHWRMVibra::NewL();
94 * // After this, vibra can be directly controlled via the provided class methods.
95 * vibra->StartVibraL(5000); // Start vibra for five seconds
96 * vibra->StopVibraL(); // Immediately stop vibra
98 * // To clean up, delete the created object:
102 * @lib HWRMVIBRACLIENT.DLL
105 class CHWRMVibra : public CBase
109 * Vibration setting in the user profile.
113 EVibraModeUnknown = 0, ///< Not initialized yet or there is an error condion.
114 EVibraModeON, ///< Vibration setting in the user profile is on.
115 EVibraModeOFF ///< Vibration setting in the user profile is off.
119 * Status of the vibration feature
123 EVibraStatusUnknown = 0, ///< Vibra is not initialized yet or status is uncertain
124 ///< because of an error condition.
125 EVibraStatusNotAllowed, ///< Vibra is set off in the user profile or some
126 ///< application is specifically blocking vibra.
127 EVibraStatusStopped, ///< Vibra is stopped.
128 EVibraStatusOn ///< Vibra is on.
132 * Tactile feedback vibration setting in the user profile.
134 enum TVibraFeedbackModeState
136 EVibraFeedbackModeUnknown = 0, ///< Not initialized yet or there is an error condion.
137 EVibraFeedbackModeON, ///< Feedback vibration setting in the user profile is on.
138 EVibraFeedbackModeOFF ///< Feedback vibration setting in the user profile is off.
141 public: // Constructors
144 * Two-phased constructor.
146 * @return A pointer to a new instance of the CHWRMVibra class.
148 * @leave KErrNotSupported Device doesn't support vibration feature.
149 * @leave KErrNoMemory There is a memory allocation failure.
151 IMPORT_C static CHWRMVibra* NewL();
154 * Two-phased constructor.
155 * Leaves instance to cleanup stack.
157 * @return A pointer to a new instance of the CHWRMVibra class.
159 * @leave KErrNotSupported Device doesn't support vibration feature.
160 * @leave KErrNoMemory There is a memory allocation failure.
162 IMPORT_C static CHWRMVibra* NewLC();
165 * Two-phased constructor.
166 * Use this method for creating a vibra client with callbacks.
168 * @param aCallback Pointer to callback instance
169 * @return A pointer to a new instance of the CHWRMVibra class.
171 * @leave KErrNotSupported Device doesn't support vibration feature.
172 * @leave KErrNoMemory There is a memory allocation failure.
174 IMPORT_C static CHWRMVibra* NewL(MHWRMVibraObserver* aCallback);
177 * Two-phased constructor.
178 * Use this method for creating a vibra client with callbacks.
179 * Leaves instance to cleanup stack.
181 * @param aCallback Pointer to callback instance
182 * @return A pointer to a new instance of the CHWRMVibra class.
184 * @leave KErrNotSupported Device doesn't support vibration feature.
185 * @leave KErrNoMemory There is a memory allocation failure.
187 IMPORT_C static CHWRMVibra* NewLC(MHWRMVibraObserver* aCallback);
189 public: // New functions
192 * Reserves vibration feature exclusively for this client.
193 * A higher priority (not process or thread priority, but the priority defined
194 * in the internal vibra policy of the HW Resource Manager) client may cause
195 * lower priority client reservation to be temporarily suspended. Commands
196 * can still be issued in suspended state, but they will not be acted upon
197 * unless suspension is lifted within specified duration.
198 * The suspended client will not get any notification about suspension and
199 * neither from resumption of reservation.
200 * If vibra is already reserved by a higher or equal priority application,
201 * reserving will still succeed, but reservation is immediately suspended.
203 * Calling this method is equal to call ReserveVibraL(EFalse, EFalse),
204 * i.e. any previously frozen state will not be restored and CCoeEnv
205 * background/foreground status is always used to control further reservations.
207 * @leave KErrAccessDenied No CCoeEnv present.
208 * @leave KErrNotReady Trying to reserve while on background.
209 * @leave KErrNoMemory There is a memory allocation failure.
211 virtual void ReserveVibraL()=0;
214 * Reserves vibration feature exclusively for this client.
215 * A higher priority (not process or thread priority, but the priority defined
216 * in the internal vibra policy of the HW Resource Manager) client may cause
217 * lower priority client reservation to be temporarily suspended. Commands
218 * can still be issued in suspended state, but they will not be acted upon
219 * unless suspension is lifted within specified duration.
220 * The suspended client will not get any notification about suspension and
221 * neither from resumption of reservation.
222 * If vibra is already reserved by a higher or equal priority application,
223 * reserving will still succeed, but reservation is immediately suspended.
226 * @param aRestoreState If ETrue, the state frozen on last release will be
227 * restored upon successful reservation.
228 * I.e. if vibra was on when it was released by this
229 * client the last time, it would continue the vibrating
230 * upon successful reservation.
231 * For the first reservation of each session this
232 * parameter is always considered EFalse regardless of
233 * what is supplied, as there is no previous frozen state
235 * @param aForceNoCCoeEnv If EFalse, then reservation requires that this client
236 * has the keyboard focus at the time of reservation and
237 * vibra will be automatically released and re-reserved
238 * based on the keyboard focus status of this client.
239 * This also implies that CCoeEnv::Static() != NULL is
241 * If ETrue, the client will not require CCoeEnv to be
242 * present nor does it automatically reserve/release vibra
243 * by depending on foreground/background status of the
245 * Only trusted clients are allowed to set this flag to
246 * ETrue. A client is considered trusted if it has nonstandard
247 * priority defined in the internal vibra policy of the
248 * HW Resource Manager. A client can be defined trusted
249 * only by S60 or a product.
251 * @leave KErrAccessDenied Parameter aForceNoCCoeEnv is ETrue and client is not
253 * @leave KErrBadHandle Parameter aForceNoCCoeEnv is EFalse and no CCoeEnv present.
254 * @leave KErrNotReady Trying to reserve while on background and parameter
255 * aForceNoCCoeEnv is EFalse.
256 * @leave KErrNoMemory There is a memory allocation failure.
258 virtual void ReserveVibraL(TBool aRestoreState, TBool aForceNoCCoeEnv)=0;
261 * Releases vibration feature if it was previously reserved for this client.
262 * If this client has not reserved vibration feature, does nothing.
263 * If vibra is on when it is released and no other client has a suspended
264 * reservation, vibra is stopped.
266 virtual void ReleaseVibra()=0;
270 * Starts the device vibration feature with the product specific default
272 * If StartVibraL is called again before the first vibration completes
273 * then the first vibration is interrupted and the second vibrations
274 * starts immediately -- i.e. The periods of vibration are not cumulative.
276 * The vibration can be interrupted with the method StopVibraL before
277 * the specified interval has elapsed.
279 * Vibra settings of the vibration feature in the user profile
282 * Note: The device may have implementation defined or hardware imposed
283 * limits to the duration of the vibration feature. In such
284 * circumstances any vibration will cut off at that limit even if
285 * the duration parameter is greater than the limit.
287 * @param aDuration Duration of the vibration measured in milliseconds.
288 * A value of KHWRMVibraInfiniteDuration specifies that
289 * the vibration should continue indefinetely and should
290 * be stopped with a call to StopVibraL. Duration
291 * usually has device specific maximum value.
293 * @leave KErrArgument Duration is invalid.
294 * @leave KErrAccessDenied Vibration setting in the user profile is not set.
295 * @leave KErrBadHandle Vibra session has been invalidated.
296 * @leave KErrLocked Vibra is locked down because too much continuous use
297 * or explicitly blocked by for example some vibration
298 * sensitive accessory.
299 * @leave KErrTimedOut Timeout occurred in controlling vibra.
300 * @leave KErrInUse Vibra is not reserved to this client but it is
301 * reserved to some other client.
302 * @leave KErrNoMemory There is a memory allocation failure.
303 * @leave KErrGeneral There is a hardware error.
305 * @see MHWRMVibraObserver
307 virtual void StartVibraL(TInt aDuration)=0;
310 * Starts the device vibration feature. If StartVibraL is called again before
311 * the first vibration completes then the first vibration is interrupted
312 * and the second vibrations starts immediately -- i.e. The periods of
313 * vibration are not cumulative.
315 * The vibration can be interrupted with the method StopVibraL before
316 * the specified interval has elapsed.
318 * Vibra settings of the vibration feature in the user profile
321 * Note: The device may have implementation defined or hardware imposed
322 * limits to the duration of the vibration feature. In such
323 * circumstances any vibration will cut off at that limit even if
324 * the duration parameter is greater than the limit.
326 * @param aDuration Duration of the vibration measured in milliseconds.
327 * A value of KHWRMVibraInfiniteDuration specifies that
328 * the vibration should continue indefinetely and should
329 * be stopped with a call to StopVibraL. Duration
330 * usually has device specific maximum value.
331 * @param aIntensity Intensity of the vibra in decimal is KHWRMVibraMinIntensity
332 * to KHWRMVibraMaxIntensity,
333 * which shows the percentage of the vibra motor full
334 * rotation speed. When intensity is negative,
335 * the vibra motor rotates in the negative direction.
336 * When intensity is positive, the vibra motor rotates
337 * in the positive direction. Value 0 stops the vibra.
338 * NOTE: The device might have hardware-imposed limits
339 * on supported vibra intensity values, so actual
340 * effect might vary between different hardware.
342 * @leave KErrNotSupported The device doesn't support user-defined
344 * @leave KErrArgument One of the parameters is out of range.
345 * @leave KErrAccessDenied Vibration setting in the user profile
347 * @leave KErrBadHandle Vibra session has been invalidated.
348 * @leave KErrLocked Vibra is locked down because too much continuous use
349 * or explicitly blocked by for example some vibration
350 * sensitive accessory.
351 * @leave KErrTimedOut Timeout occurred in controlling vibra.
352 * @leave KErrInUse Vibra is not reserved to this client but it is
353 * reserved to some other client.
354 * @leave KErrNoMemory There is a memory allocation failure.
355 * @leave KErrGeneral There is a hardware error.
357 * @see MHWRMVibraObserver
359 virtual void StartVibraL(TInt aDuration, TInt aIntensity)=0;
362 * Interrupts the device vibration that is started with the StartVibraL
363 * method immediately.
365 * @leave KErrBadHandle Vibra session has been invalidated.
366 * @leave KErrTimedOut Timeout occurred in controlling vibra.
367 * @leave KErrInUse Vibra is not reserved to this client but it is
368 * reserved to some other client.
369 * @leave KErrNoMemory There is a memory allocation failure.
370 * @leave KErrGeneral There is a hardware error.
372 * @see MHWRMVibraObserver
374 virtual void StopVibraL()=0;
377 * This method retrieves the current settings of the vibration feature
378 * in the user profile. The developer can check the Vibra settings
379 * in the profile and if there is no Vibra active but it is needed by
380 * the client application then the user can be informed.
382 * @return TVibraModeState indicating the current vibra mode setting.
384 * @see TVibraModeState
385 * @see MHWRMVibraObserver
387 virtual TVibraModeState VibraSettings() const=0;
390 * This method retrieves the current vibra status.
392 * @return TVibraStatus indicating the current vibra status
395 * @see MHWRMVibraObserver
397 virtual TVibraStatus VibraStatus() const=0;
400 * This method is intended only for firmware build time configured
401 * privileged clients.
403 * Executes a tactile feedback vibration pulse with product
404 * specific default intensity and duration.
405 * If PulseVibraL is called before ongoing vibration completes and
406 * PulseVibraL calling client has higher priority than executing client,
407 * pulse request is accepted. Also possible vibra-reservations are bypassed.
408 * If client calling PulseVibraL has lower or equal priority
409 * than executing client, ongoing vibration is not affected.
411 * Tactile feedback vibration settings of the vibration feature in the
412 * user profile must be active.
414 * Note: The device may have implementation defined or hardware imposed
415 * limits to the duration of the vibration feature. In such
416 * circumstances any vibration will cut off at that limit even if
417 * the duration parameter is greater than the limit.
419 * @param aDuration Duration of the vibration measured in milliseconds.
420 * Duration can have maximum value
421 * of KHWRMVibraMaxDuration.
423 * @leave KErrAccessDenied Vibration setting in the user profile is not set
424 * or client is not privileged to use pulse feature.
425 * @leave KErrBadHandle Vibra session has been invalidated.
426 * @leave KErrLocked Vibra is locked down because too much continuous use
427 * or explicitly blocked by for example some vibration
428 * sensitive accessory.
429 * @leave KErrTimedOut Timeout occurred in controlling vibra.
430 * @leave KErrInUse Vibra is not reserved to this client but it is
431 * reserved to some other client or ongoing vibration
432 * has been requested by higher priority client.
433 * @leave KErrNoMemory There is a memory allocation failure.
434 * @leave KErrGeneral There is a hardware error.
436 * @see MHWRMVibraFeedbackObserver
438 virtual void PulseVibraL()=0;
441 * This method is intended only for firmware build time configured
442 * privileged clients.
444 * Executes a tactile feedback vibration pulse with product
445 * specific default intensity and specified duration.
446 * If PulseVibraL is called before ongoing vibration completes and
447 * PulseVibraL calling client has higher priority than executing client,
448 * pulse request is accepted. Also possible vibra-reservations are bypassed.
449 * If client calling PulseVibraL has lower or equal priority
450 * than executing client, ongoing vibration is not affected.
452 * Tactile feedback vibration settings of the vibration feature in the
453 * user profile must be active.
455 * Note: The device may have implementation defined or hardware imposed
456 * limits to the duration of the vibration feature. In such
457 * circumstances any vibration will cut off at that limit even if
458 * the duration parameter is greater than the limit.
460 * @param aDuration Duration of the vibration measured in milliseconds.
461 * Duration can have maximum value
462 * of KHWRMVibraMaxDuration.
464 * @leave KErrArgument One of the parameters is out of range.
465 * @leave KErrAccessDenied Vibration setting in the user profile is not set
466 * or client is not privileged to use pulse feature.
467 * @leave KErrBadHandle Vibra session has been invalidated.
468 * @leave KErrLocked Vibra is locked down because too much continuous use
469 * or explicitly blocked by for example some vibration
470 * sensitive accessory.
471 * @leave KErrTimedOut Timeout occurred in controlling vibra.
472 * @leave KErrInUse Vibra is not reserved to this client but it is
473 * reserved to some other client or ongoing vibration
474 * has been requested by higher priority client.
475 * @leave KErrNoMemory There is a memory allocation failure.
476 * @leave KErrGeneral There is a hardware error.
478 * @see MHWRMVibraFeedbackObserver
480 virtual void PulseVibraL(TInt aDuration)=0;
483 * This method is intended only for firmware build time configured
484 * privileged clients.
486 * Executes a tactile feedback vibration pulse.
487 * If PulseVibraL is called before ongoing vibration completes and
488 * PulseVibraL calling client has higher priority than executing client,
489 * pulse request is accepted. Also possible vibra-reservations are bypassed.
490 * If client calling PulseVibraL has lower or equal priority
491 * than executing client, ongoing vibration is not affected.
493 * Tactile feedback vibration settings of the vibration feature in the
494 * user profile must be active.
496 * Note: The device may have implementation defined or hardware imposed
497 * limits to the duration of the vibration feature. In such
498 * circumstances any vibration will cut off at that limit even if
499 * the duration parameter is greater than the limit.
501 * @param aDuration Duration of the vibration measured in milliseconds.
502 * Duration can have maximum value
503 * of KHWRMVibraMaxDuration.
504 * @param aIntensity Intensity of the pulse in decimal is KHWRMVibraMinPulseIntensity
505 * to KHWRMVibraMaxIntensity, which shows the percentage
506 * of the vibra motor full rotation speed.
507 * NOTE: The device might have hardware-imposed limits
508 * on supported vibra intensity values, so actual
509 * effect might vary between different hardware.
511 * @leave KErrNotSupported The device doesn't support user-defined
513 * @leave KErrArgument One of the parameters is out of range.
514 * @leave KErrAccessDenied Vibration setting in the user profile is not set
515 * or client is not privileged to use pulse feature.
516 * @leave KErrBadHandle Vibra session has been invalidated.
517 * @leave KErrLocked Vibra is locked down because too much continuous use
518 * or explicitly blocked by for example some vibration
519 * sensitive accessory.
520 * @leave KErrTimedOut Timeout occurred in controlling vibra.
521 * @leave KErrInUse Vibra is not reserved to this client but it is
522 * reserved to some other client or ongoing vibration
523 * has been requested by higher priority client.
524 * @leave KErrNoMemory There is a memory allocation failure.
525 * @leave KErrGeneral There is a hardware error.
527 * @see MHWRMVibraFeedbackObserver
529 virtual void PulseVibraL(TInt aDuration, TInt aIntensity)=0;
532 * Use this method for setting feedback observer.
534 * @param aCallback Pointer to callback instance
536 virtual void SetFeedbackObserver(MHWRMVibraFeedbackObserver* aCallback)=0;
539 * This method retrieves the current settings of the feedback vibration feature
540 * in the user profile. The developer can check the feedback vibration settings
541 * in the profile and if there is no feedback vibration active but it is needed by
542 * the client application then the user can be informed. However, client needs to
543 * explicitly register to listen these changes via SetFeedbackObserver-method.
545 * @return TVibraFeedbackModeState indicating the current vibra feedback mode setting.
547 * @see TVibraFeedbackModeState
548 * @see MHWRMVibraFeedbackObserver
550 virtual TVibraFeedbackModeState VibraFeedbackSettings() const=0;
554 * A callback interface for vibra status reporting.
556 * If the client requires up-to-date status information, the client needs
557 * to derive a class from the MHWRMVibraObserver interface and implement
558 * the VibraModeChanged() and VibraStatusChanged() methods.
560 * A callback object header example:
564 * #include <HWRMVibra.h> // Link against HWRMVibraClient.lib.
566 * class CTest : public CBase,
567 * public MHWRMVibraObserver
574 * static CTest* NewL();
576 * // from MHWRMVibraObserver
577 * virtual void VibraModeChanged(CHWRMVibra::TVibraModeState aStatus);
578 * virtual void VibraStatusChanged(CHWRMVibra::TVibraStatus aStatus);
581 * CHWRMVibra* iVibra;
585 * A callback method implementation example:
588 * void CTest::VibraStatusChanged(CHWRMVibra::TVibraStatus aStatus)
592 * case CHWRMVibra::EVibraStatusUnknown:
593 * RDebug::Print(_L("### Vibra state changed: EVibraStatusUnknown"));
595 * case CHWRMVibra::EVibraStatusNotAllowed:
596 * RDebug::Print(_L("### Vibra state changed: EVibraStatusNotAllowed"));
598 * case CHWRMVibra::EVibraStatusStopped:
599 * RDebug::Print(_L("### Vibra state changed: EVibraStatusStopped"));
601 * case CHWRMVibra::EVibraStatusOn:
602 * RDebug::Print(_L("### Vibra state changed: EVibraStatusOn"));
605 * RDebug::Print(_L("### Vibra state changed: UNDEFINED !"));
613 class MHWRMVibraObserver
618 * Called when the vibration setting in the user profile is changed.
620 * @param aStatus Indicates the new setting.
622 * @see CHWRMVibra::TVibraModeState
624 virtual void VibraModeChanged(CHWRMVibra::TVibraModeState aStatus) = 0;
627 * Called when the device vibration feature state changes
629 * @param aStatus Indicates vibra status.
631 * @see CHWRMVibra::TVibraStatus
633 virtual void VibraStatusChanged(CHWRMVibra::TVibraStatus aStatus) = 0;
637 * A callback interface for tactile feedback vibra mode reporting.
639 * If the client requires up-to-date status information, the client needs
640 * to derive a class from the MHWRMVibraFeedbackObserver interface and implement
641 * the VibraFeedbackModeChanged() method. In order to register for callback, client
642 * needs to call SetFeedbackObserver-method.
644 * A callback object header example:
648 * #include <HWRMVibra.h> // Link against HWRMVibraClient.lib.
650 * class CTest : public CBase,
651 * public MHWRMVibraFeedbackObserver
658 * static CTest* NewL();
660 * // from MHWRMVibraFeedbackObserver
661 * virtual void VibraFeedbackModeChanged(CHWRMVibra::TVibraFeedbackModeState aMode);
664 * CHWRMVibra* iVibra;
668 * A callback method implementation example:
672 * #include <HWRMVibra.h> // link against HWRMVibraClient.lib
674 * // A CHWRMVibra instance can be created by using NewL() or NewLC() methods.
675 * CHWRMVibra* vibra = CHWRMVibra::NewL();
677 * // Request notification of feedback setting change
678 * vibra->SetFeedbackObserver(this);
680 * // To clean up, delete the created object:
683 * void CTest::VibraFeedbackModeChanged(CHWRMVibra::TVibraFeedbackModeState aMode)
687 * case CHWRMVibra::EVibraFeedbackModeUnknown:
688 * RDebug::Print(_L("### Feedback vibration mode : EVibraFeedbackModeUnknown"));
690 * case CHWRMVibra::EVibraFeedbackModeON:
691 * RDebug::Print(_L("### Feedback vibration mode : EVibraFeedbackModeON"));
693 * case CHWRMVibra::EVibraFeedbackModeOFF:
694 * RDebug::Print(_L("### Feedback vibration mode : EVibraFeedbackModeOFF"));
704 class MHWRMVibraFeedbackObserver
709 * Called when the tactile feedback vibration setting in the user profile is changed.
711 * @param aMode Indicates the new setting.
713 * @see CHWRMVibra::TVibraFeedbackModeState
715 virtual void VibraFeedbackModeChanged(CHWRMVibra::TVibraFeedbackModeState aMode) = 0;
719 #endif // HWRMVIBRA_H