|
1 /* |
|
2 * Copyright (c) 2006-2009 Nokia Corporation and/or its subsidiary(-ies). |
|
3 * All rights reserved. |
|
4 * This component and the accompanying materials are made available |
|
5 * under the terms of "Eclipse Public License v1.0" |
|
6 * which accompanies this distribution, and is available |
|
7 * at the URL "http://www.eclipse.org/legal/epl-v10.html". |
|
8 * |
|
9 * Initial Contributors: |
|
10 * Nokia Corporation - initial contribution. |
|
11 * |
|
12 * Contributors: |
|
13 * |
|
14 * Description: |
|
15 * |
|
16 */ |
|
17 |
|
18 |
|
19 |
|
20 |
|
21 #ifndef HWRMEXTENDEDLIGHT_H |
|
22 #define HWRMEXTENDEDLIGHT_H |
|
23 |
|
24 #include <hwrmlight.h> |
|
25 |
|
26 class MHWRMExtendedLightObserver; |
|
27 |
|
28 /** |
|
29 * Base class of Extended Light Client API of HWRM |
|
30 * |
|
31 * The HWRM Extended Light API provides the ability to control the device |
|
32 * display light as well as the keyboard illumination. |
|
33 * |
|
34 * Every new call of the extended light API method stops all ongoing light |
|
35 * control orders. Light state after duration based orders expire is the state |
|
36 * specified by the last non-duration based order. |
|
37 * |
|
38 * The interface contains synchronous methods that will block the client application. |
|
39 * |
|
40 * @publishedPartner |
|
41 * @released |
|
42 */ |
|
43 class CHWRMExtendedLight : public CBase |
|
44 { |
|
45 public: |
|
46 /** |
|
47 * Possible light states that can be get for the different light targets |
|
48 */ |
|
49 enum TLightStatus |
|
50 { |
|
51 /** |
|
52 For debugging/development and signaling an error conditions |
|
53 */ |
|
54 ELightStatusUnknown = 0, |
|
55 /** |
|
56 Light state switch to light on |
|
57 */ |
|
58 ELightOn, |
|
59 /** |
|
60 Light state switch to light off |
|
61 */ |
|
62 ELightOff, |
|
63 /** |
|
64 Light state switch to light blinking |
|
65 */ |
|
66 ELightBlink |
|
67 }; |
|
68 |
|
69 /** |
|
70 * Possible light targets. |
|
71 * Targets can be used as bitmask. Some common masks are provided as enum. |
|
72 * |
|
73 * Note that all targets are not supported by all devices. |
|
74 * Attempting to use unsupported target will result in |
|
75 * KErrNotSupported. |
|
76 * |
|
77 * At least one target must be defined. |
|
78 */ |
|
79 enum TLightTarget |
|
80 { |
|
81 /** |
|
82 No target. Not a valid target value, used only for error checking. |
|
83 */ |
|
84 ENoTarget = 0x0, |
|
85 /** |
|
86 Primary display of the device. |
|
87 */ |
|
88 EPrimaryDisplay = 0x1, |
|
89 /** |
|
90 Primary keyboard of the device. |
|
91 */ |
|
92 EPrimaryKeyboard = 0x2, |
|
93 /** |
|
94 Both primary display and the primary keyboard of the device. |
|
95 */ |
|
96 EPrimaryDisplayAndKeyboard = 0x3, |
|
97 /** |
|
98 Secondary display of the device. |
|
99 */ |
|
100 ESecondaryDisplay = 0x4, |
|
101 /** |
|
102 Secondary keyboard of the device. |
|
103 */ |
|
104 ESecondaryKeyboard = 0x8, |
|
105 /** |
|
106 Both secondary display and the secondary keyboard of the device. |
|
107 */ |
|
108 ESecondaryDisplayAndKeyboard = 0xC, |
|
109 /** |
|
110 Device specific custom target 1. |
|
111 */ |
|
112 ECustomTarget1 = 0x10, |
|
113 /** |
|
114 Device specific custom target 2. |
|
115 */ |
|
116 ECustomTarget2 = 0x20, |
|
117 /** |
|
118 Device specific custom target 3. |
|
119 */ |
|
120 ECustomTarget3 = 0x40, |
|
121 /** |
|
122 Device specific custom target 4. |
|
123 */ |
|
124 ECustomTarget4 = 0x80, |
|
125 /** |
|
126 Device specific custom target 5. |
|
127 */ |
|
128 ECustomTarget5 = 0x100, |
|
129 /** |
|
130 Device specific custom target 6. |
|
131 */ |
|
132 ECustomTarget6 = 0x200, |
|
133 /** |
|
134 Device specific custom target 7. |
|
135 */ |
|
136 ECustomTarget7 = 0x400, |
|
137 /** |
|
138 Device specific custom target 8. |
|
139 */ |
|
140 ECustomTarget8 = 0x800, |
|
141 /** |
|
142 Device specific custom target 9. |
|
143 */ |
|
144 ECustomTarget9 = 0x1000, |
|
145 /** |
|
146 Device specific custom target 10. |
|
147 */ |
|
148 ECustomTarget10 = 0x2000, |
|
149 /** |
|
150 Device specific custom target 11. |
|
151 */ |
|
152 ECustomTarget11 = 0x4000, |
|
153 /** |
|
154 Device specific custom target 12. |
|
155 */ |
|
156 ECustomTarget12 = 0x8000, |
|
157 /** |
|
158 Device specific custom target 13. |
|
159 */ |
|
160 ECustomTarget13 = 0x10000, |
|
161 /** |
|
162 Device specific custom target 14. |
|
163 */ |
|
164 ECustomTarget14 = 0x20000, |
|
165 /** |
|
166 Device specific custom target 15. |
|
167 */ |
|
168 ECustomTarget15 = 0x40000, |
|
169 /** |
|
170 Device specific custom target 16. |
|
171 */ |
|
172 ECustomTarget16 = 0x80000, |
|
173 /** |
|
174 Device specific custom target 17. |
|
175 */ |
|
176 ECustomTarget17 = 0x100000, |
|
177 /** |
|
178 Device specific custom target 18. |
|
179 */ |
|
180 ECustomTarget18 = 0x200000, |
|
181 /** |
|
182 Device specific custom target 19. |
|
183 */ |
|
184 ECustomTarget19 = 0x400000, |
|
185 /** |
|
186 Device specific custom target 20. |
|
187 */ |
|
188 ECustomTarget20 = 0x800000, |
|
189 /** |
|
190 Device specific custom target 21. |
|
191 */ |
|
192 ECustomTarget21 = 0x1000000, |
|
193 /** |
|
194 Device specific custom target 22. |
|
195 */ |
|
196 ECustomTarget22 = 0x2000000, |
|
197 /** |
|
198 Device specific custom target 23. |
|
199 */ |
|
200 ECustomTarget23 = 0x4000000, |
|
201 /** |
|
202 Device specific custom target 24. |
|
203 */ |
|
204 ECustomTarget24 = 0x8000000, |
|
205 /** |
|
206 Device specific custom target 25. |
|
207 */ |
|
208 ECustomTarget25 = 0x10000000, |
|
209 /** |
|
210 Device specific custom target 26. |
|
211 */ |
|
212 ECustomTarget26 = 0x20000000, |
|
213 /** |
|
214 Device specific custom target 27. |
|
215 */ |
|
216 ECustomTarget27 = 0x40000000, |
|
217 |
|
218 /** |
|
219 * Special target used to control all currently available system lights. |
|
220 * |
|
221 * System lights normally include all displays and keyboards, |
|
222 * but not custom lights. This is however device dependant. |
|
223 * |
|
224 * A target mask including this target is |
|
225 * always changed to a device state specific target mask. |
|
226 * Note that the system target with any other target is not supported. |
|
227 * |
|
228 * This target is always supported but it is never |
|
229 * included in supported targets mask. |
|
230 * |
|
231 * @see CHWRMExtendedLight::SupportedTargets() |
|
232 */ |
|
233 ESystemTarget = 0x80000000 |
|
234 }; |
|
235 |
|
236 public: // Constructors and destructor |
|
237 |
|
238 /** |
|
239 * Two-phased constructor for implementation class. |
|
240 * |
|
241 * @return Pointer to new CHWRMExtendedLight instance. |
|
242 * @leave KErrNotSupported Device doesn't support Light feature. |
|
243 * @leave KErrNoMemory if there is a memory allocation failure. |
|
244 */ |
|
245 IMPORT_C static CHWRMExtendedLight* NewL(); |
|
246 |
|
247 /** |
|
248 * Two-phased constructor for implementation class. |
|
249 * Leaves instance to cleanup stack. |
|
250 * |
|
251 * @return Pointer to new CHWRMExtendedLight instance. |
|
252 * @leave KErrNotSupported Device doesn't support Light feature. |
|
253 * @leave KErrNoMemory if there is a memory allocation failure. |
|
254 */ |
|
255 IMPORT_C static CHWRMExtendedLight* NewLC(); |
|
256 |
|
257 /** |
|
258 * Two-phased constructor for implementation class. |
|
259 * Use this method for creating a Light client with callbacks. |
|
260 * |
|
261 * @param aCallback Pointer to callback instance |
|
262 * @return Pointer to new CHWRMExtendedLight instance. |
|
263 * @leave KErrNotSupported Device doesn't support Light feature. |
|
264 * @leave KErrNoMemory if there is a memory allocation failure. |
|
265 */ |
|
266 IMPORT_C static CHWRMExtendedLight* NewL(MHWRMExtendedLightObserver* aCallback); |
|
267 |
|
268 /** |
|
269 * Two-phased constructor for implementation class. |
|
270 * Use this method for creating a Light client with callbacks. |
|
271 * Leaves instance to cleanup stack. |
|
272 * |
|
273 * @param aCallback Pointer to callback instance |
|
274 * @return Pointer to new CHWRMExtendedLight instance. |
|
275 * @leave KErrNotSupported Device doesn't support Light feature. |
|
276 * @leave KErrNoMemory if there is a memory allocation failure. |
|
277 */ |
|
278 IMPORT_C static CHWRMExtendedLight* NewLC(MHWRMExtendedLightObserver* aCallback); |
|
279 |
|
280 /** |
|
281 * Two-phased constructor for implementation class. |
|
282 * On opening passes permitted targets. |
|
283 * |
|
284 * @param aPermittedTargets permitted targets. |
|
285 * @return Pointer to new CHWRMExtendedLight instance. |
|
286 * @leave KErrNotSupported Device doesn't support Light feature. |
|
287 * @leave KErrNoMemory if there is a memory allocation failure. |
|
288 */ |
|
289 IMPORT_C static CHWRMExtendedLight* NewL(TInt aPermittedTargets); |
|
290 |
|
291 /** |
|
292 * Two-phased constructor for implementation class. |
|
293 * Use this method for creating a Light client with callbacks. |
|
294 * On opening passes permitted targets. |
|
295 * |
|
296 * @param aCallback Pointer to callback instance |
|
297 * @param aPermittedTargets permitted targets. |
|
298 * @return Pointer to new CHWRMExtendedLight instance. |
|
299 * @leave KErrNotSupported Device doesn't support Light feature. |
|
300 * @leave KErrNoMemory if there is a memory allocation failure. |
|
301 */ |
|
302 IMPORT_C static CHWRMExtendedLight* NewL(MHWRMExtendedLightObserver* aCallback, TInt aPermittedTargets); |
|
303 |
|
304 |
|
305 public: |
|
306 |
|
307 |
|
308 /** |
|
309 * Reserves light target exclusively for this client. |
|
310 * A higher priority client may cause lower priority client reservation |
|
311 * to be temporarily suspended. Commands can still be issued in suspended |
|
312 * state, but they will not be acted upon unless suspension is lifted |
|
313 * within specified duration. |
|
314 * The suspended client will not get any notification about suspension. |
|
315 * If light target is already reserved by a higher or equal priority application, |
|
316 * reserving will still succeeds, but reservation is immediately suspended. |
|
317 * |
|
318 * Calling this method is equal to call ReserveLightL( aTarget, EFalse, EFalse), |
|
319 * i.e. any previously frozen state will not be restored and CCoeEnv |
|
320 * background/foreground status is always used to control further reservations. |
|
321 * |
|
322 * @param aTarget Defines which light should be reserved. Multiple lights can |
|
323 * be specified with using bitwise-or. |
|
324 * |
|
325 * @leave KErrNotSupported One or more of specified targets are not supported. |
|
326 * @leave KErrAccessDenied if no CCoeEnv present. |
|
327 * @leave KErrNotReady if trying to reserve while on background. |
|
328 * @leave KErrNoMemory if there is a memory allocation failure. |
|
329 * |
|
330 * @see TLightTarget |
|
331 */ |
|
332 virtual void ReserveLightL(TInt aTarget)=0; |
|
333 |
|
334 /** |
|
335 * Reserves light target exclusively for this client. |
|
336 * A higher priority client may cause lower priority client reservation |
|
337 * to be temporarily suspended. Commands can still be issued in suspended |
|
338 * state, but they will not be acted upon unless suspension is lifted |
|
339 * within specified duration. |
|
340 * The suspended client will not get any notification about suspension. |
|
341 * If light target is already reserved by a higher or equal priority application, |
|
342 * reserving will still succeeds, but reservation is immediately suspended. |
|
343 * |
|
344 * |
|
345 * @param aTarget Defines which light should be reserved. Multiple lights can |
|
346 * be specified with using bitwise-or. |
|
347 * @param aRestoreState If ETrue, the state frozen on last release will be |
|
348 * restored upon successful reservation. |
|
349 * I.e. if light was blinking when it was released by this client the last |
|
350 * time, it would start blinking again upon successful reservation. |
|
351 * For the first reservation of each session this parameter is always |
|
352 * considered EFalse regardless of what is supplied, as there is no |
|
353 * previous frozen state to restore. |
|
354 * @param aForceNoCCoeEnv If EFalse, then reservation requires that |
|
355 * this client is on the foreground at the time of reservation |
|
356 * and light target will be automatically released and re-reserved based on |
|
357 * background/foreground status of the this client. This also implies |
|
358 * that CCoeEnv::Static() != NULL is required. |
|
359 * If ETrue, the client will not require CCoeEnv to |
|
360 * be present nor does it automatically reserve/release light |
|
361 * by depending on foreground/background status of the client. |
|
362 * Only trusted clients are allowed to set this flag to ETrue. |
|
363 * Client is considered trusted if it has nonstandard priority |
|
364 * defined in the lights policy. |
|
365 * |
|
366 * @leave KErrNotSupported One or more of specified targets are not supported. |
|
367 * @leave KErrAccessDenied if aForceNoCCoeEnv is ETrue and client is not trusted. |
|
368 * @leave KErrBadHandle if aForceNoCCoeEnv is EFalse and no CCoeEnv present. |
|
369 * @leave KErrNotReady if trying to reserve while on background and aForceNoCCoeEnv is EFalse. |
|
370 * @leave KErrNoMemory if there is a memory allocation failure. |
|
371 * |
|
372 * @see TLightTarget |
|
373 */ |
|
374 virtual void ReserveLightL(TInt aTarget, TBool aRestoreState, TBool aForceNoCCoeEnv)=0; |
|
375 |
|
376 /** |
|
377 * Releases light target if it was previously reserved for this client. |
|
378 * If this client has not reserved any of the specified lights, |
|
379 * this method does nothing. |
|
380 * Any reserved light targets that are released and have no other suspended |
|
381 * clients will be reset to default state, which is either lights on or lights off, |
|
382 * depending on system inactivity time. |
|
383 * |
|
384 * @param aTarget Defines which light should be released. Multiple lights can |
|
385 * be specified with using bitwise-or. |
|
386 * |
|
387 * @see TLightTarget |
|
388 */ |
|
389 virtual void ReleaseLight(TInt aTarget)=0; |
|
390 |
|
391 |
|
392 /** |
|
393 * The LightOnL method switches the specified target light on |
|
394 * for infinite duration using default intensity. Lights will use fade-in. |
|
395 * |
|
396 * @param aTarget Defines which light should be controlled. Multiple lights can |
|
397 * be specified with using bitwise-or. |
|
398 * |
|
399 * @leave KErrNotSupported One or more of specified targets are not supported. |
|
400 * @leave KErrBadHandle if light session has been invalidated. |
|
401 * @leave KErrTimedOut if timeout occurred in controlling light. |
|
402 * @leave KErrInUse if one or more of specified targets are not reserved for this client but are reserved for others. |
|
403 * @leave KErrNoMemory if there is a memory allocation failure. |
|
404 * @leave KErrGeneral if there is a hardware error. |
|
405 * |
|
406 * @see TLightTarget |
|
407 */ |
|
408 virtual void LightOnL(TInt aTarget) = 0; |
|
409 |
|
410 /** |
|
411 * The LightOnL method switches the specified target light on |
|
412 * for the specified duration using default intensity. Lights will use fade-in. |
|
413 * |
|
414 * @param aTarget Defines which light should be controlled. Multiple lights can |
|
415 * be specified with using bitwise-or. |
|
416 * @param aDuration Duration of the time the light is switched on measured in milliseconds. |
|
417 * After the duration expires, the light state for target will be changed |
|
418 * to whatever state was caused by the last infinite time duration call, or |
|
419 * default state determined by inactivity timer, in case there has not |
|
420 * been a previous infinite time duration call in this session. |
|
421 * If the aDuration time is KHWRMInfiniteDuration then it |
|
422 * means an infinite value that has to be |
|
423 * stopped by calling of any of the other light control methods. |
|
424 * Duration can have maximum value of KHWRMLightMaxDuration. |
|
425 * |
|
426 * @leave KErrArgument aDuration is out of range. |
|
427 * @leave KErrNotSupported One or more of specified targets are not supported. |
|
428 * @leave KErrBadHandle if light session has been invalidated. |
|
429 * @leave KErrTimedOut if timeout occurred in controlling light. |
|
430 * @leave KErrInUse if one or more of specified targets are not reserved for this client but are reserved for others. |
|
431 * @leave KErrNoMemory if there is a memory allocation failure. |
|
432 * @leave KErrGeneral if there is a hardware error. |
|
433 * |
|
434 * @see TLightTarget |
|
435 */ |
|
436 virtual void LightOnL(TInt aTarget, |
|
437 TInt aDuration) = 0; |
|
438 |
|
439 /** |
|
440 * The LightOnL method switches the specified target light on |
|
441 * for the specified duration using specified intensity. Fade-in can also be controlled. |
|
442 * |
|
443 * @param aTarget Defines which light should be controlled. Multiple lights can |
|
444 * be specified with using bitwise-or. |
|
445 * @param aDuration Duration of the time the light is switched on measured in milliseconds. |
|
446 * After the duration expires, the light state for target will be changed |
|
447 * to whatever state was caused by the last infinite time duration call, or |
|
448 * default state determined by inactivity timer, in case there has not |
|
449 * been a previous infinite time duration call in this session. |
|
450 * If the aDuration time is KHWRMInfiniteDuration then it |
|
451 * means an infinite value that has to be |
|
452 * stopped by calling of any of the other light control methods. |
|
453 * Duration can have maximum value of KHWRMLightMaxDuration. |
|
454 * @param aIntensity Intensity of the light. If aIntensity is KHWRMDefaultIntensity, device default |
|
455 * intensity will be used. |
|
456 * Note: All devices might not support user defined intensity, in which case |
|
457 * device will behave in its default fashion. |
|
458 * @param aFadeIn If ETrue, lights will not turn on instantly but instead smoothly fade-in. |
|
459 * Note: All devices will not support fade-in, in which case device will |
|
460 * behave in its default fashion. |
|
461 * |
|
462 * @leave KErrArgument One of the parameters is out of range. |
|
463 * @leave KErrNotSupported One or more of specified targets are not supported. |
|
464 * @leave KErrBadHandle if light session has been invalidated. |
|
465 * @leave KErrTimedOut if timeout occurred in controlling light. |
|
466 * @leave KErrInUse if one or more of specified targets are not reserved for this client but are reserved for others. |
|
467 * @leave KErrNoMemory if there is a memory allocation failure. |
|
468 * @leave KErrGeneral if there is a hardware error. |
|
469 * |
|
470 * @see TLightTarget |
|
471 */ |
|
472 virtual void LightOnL(TInt aTarget, |
|
473 TInt aDuration, |
|
474 TInt aIntensity, |
|
475 TBool aFadeIn) = 0; |
|
476 |
|
477 /** |
|
478 * The LightBlinkL method blinks the target light(s) of the device for infinite duration |
|
479 * using default intensity. |
|
480 * |
|
481 * @param aTarget Defines which light should be controlled. Multiple lights can |
|
482 * be specified with using bitwise-or. |
|
483 * |
|
484 * @leave KErrNotSupported One or more of specified targets are not supported. |
|
485 * @leave KErrBadHandle if light session has been invalidated. |
|
486 * @leave KErrTimedOut if timeout occurred in controlling light. |
|
487 * @leave KErrInUse if one or more of specified targets are not reserved for this client but are reserved for others. |
|
488 * @leave KErrNoMemory if there is a memory allocation failure. |
|
489 * @leave KErrGeneral if there is a hardware error. |
|
490 * |
|
491 * @see TLightTarget |
|
492 */ |
|
493 virtual void LightBlinkL(TInt aTarget) = 0; |
|
494 |
|
495 /** |
|
496 * The LightBlinkL method blinks the target light(s) of the device for specified duration |
|
497 * using default intensity. |
|
498 * |
|
499 * @param aTarget Defines which light should be controlled. Multiple lights can |
|
500 * be specified with using bitwise-or. |
|
501 * @param aDuration Duration of the time the light is set to blink measured in milliseconds. |
|
502 * After the duration expires, the light state for target will be changed |
|
503 * to whatever state was caused by the last infinite time duration call, or |
|
504 * default state determined by inactivity timer, in case there has not |
|
505 * been a previous infinite time duration call in this session. |
|
506 * If the aTotalDuration time is KHWRMInfiniteDuration then it |
|
507 * means an infinite value that has to be |
|
508 * stopped by calling of any of the other light control methods. |
|
509 * Duration can have maximum value of KHWRMLightMaxDuration. |
|
510 * |
|
511 * @leave KErrArgument aDuration is out of range. |
|
512 * @leave KErrNotSupported One or more of specified targets are not supported. |
|
513 * @leave KErrBadHandle if light session has been invalidated. |
|
514 * @leave KErrTimedOut if timeout occurred in controlling light. |
|
515 * @leave KErrInUse if one or more of specified targets are not reserved for this client but are reserved for others. |
|
516 * @leave KErrNoMemory if there is a memory allocation failure. |
|
517 * @leave KErrGeneral if there is a hardware error. |
|
518 * |
|
519 * @see TLightTarget |
|
520 */ |
|
521 virtual void LightBlinkL(TInt aTarget, |
|
522 TInt aDuration) = 0; |
|
523 |
|
524 /** |
|
525 * The LightBlinkL method blinks the target light(s) of the device for specified duration |
|
526 * using specified intensity. On- and Off-cycle times of the blinking can also be controlled. |
|
527 * |
|
528 * @param aTarget Defines which light should be controlled. Multiple lights can |
|
529 * be specified with using bitwise-or. |
|
530 * @param aDuration Duration of the time the light is set to blink measured in milliseconds. |
|
531 * After the duration expires, the light state for target will be changed |
|
532 * to whatever state was caused by the last infinite time duration call, or |
|
533 * default state determined by inactivity timer, in case there has not |
|
534 * been a previous infinite time duration call in this session. |
|
535 * If the aTotalDuration time is KHWRMInfiniteDuration then it |
|
536 * means an infinite value that has to be |
|
537 * stopped by calling of any of the other light control methods. |
|
538 * Duration can have maximum value of KHWRMLightMaxDuration. |
|
539 * @param aOnDuration Duration time, measured in milliseconds, of how long the Light is |
|
540 * switched on in every Blink cycle. |
|
541 * Duration can have maximum value of KHWRMLightMaxDuration. |
|
542 * For device default cycle duration, use value KHWRMDefaultCycleTime. |
|
543 * If either of aOnDuration or aOffDuration is KHWRMDefaultCycleTime, |
|
544 * both must be KHWRMDefaultCycleTime. |
|
545 * Some devices might not support variable blink cycle times, in which |
|
546 * case default value will be substituted. |
|
547 * @param aOffDuration Duration time, measured in milliseconds, of how long the Light |
|
548 * is switched off in every Blink cycle. |
|
549 * Duration can have maximum value of KHWRMLightMaxDuration. |
|
550 * For device default cycle duration, use value KHWRMDefaultCycleTime. |
|
551 * If either of aOnDuration or aOffDuration is KHWRMDefaultCycleTime, |
|
552 * both must be KHWRMDefaultCycleTime. |
|
553 * Some devices might not support variable blink cycle times, in which |
|
554 * case default value will be substituted. |
|
555 * @param aIntensity Intensity of the light. If aIntensity is KHWRMDefaultIntensity, device default |
|
556 * intensity will be used. |
|
557 * Note: All devices might not support user defined intensity, in which case |
|
558 * device will behave in its default fashion. |
|
559 * |
|
560 * @leave KErrArgument One of the parameters is out of range or otherwise invalid. |
|
561 * @leave KErrNotSupported One or more of specified targets are not supported. |
|
562 * @leave KErrBadHandle if light session has been invalidated. |
|
563 * @leave KErrTimedOut if timeout occurred in controlling light. |
|
564 * @leave KErrInUse if one or more of specified targets are not reserved for this client but are reserved for others. |
|
565 * @leave KErrNoMemory if there is a memory allocation failure. |
|
566 * @leave KErrGeneral if there is a hardware error. |
|
567 * |
|
568 * @see TLightTarget |
|
569 */ |
|
570 virtual void LightBlinkL(TInt aTarget, |
|
571 TInt aDuration, |
|
572 TInt aOnDuration, |
|
573 TInt aOffDuration, |
|
574 TInt aIntensity) = 0; |
|
575 |
|
576 /** |
|
577 * The LightOffL method switches the device light off for the specified target for |
|
578 * infinite duration. Lights will be switched off with fade-out. |
|
579 * |
|
580 * @param aTarget Defines which light should be controlled. Multiple lights can |
|
581 * be specified with using bitwise-or. |
|
582 * |
|
583 * @leave KErrNotSupported One or more of specified targets are not supported. |
|
584 * @leave KErrBadHandle if light session has been invalidated. |
|
585 * @leave KErrTimedOut if timeout occurred in controlling light. |
|
586 * @leave KErrInUse if one or more of specified targets are not reserved for this client but are reserved for others. |
|
587 * @leave KErrNoMemory if there is a memory allocation failure. |
|
588 * @leave KErrGeneral if there is a hardware error. |
|
589 * |
|
590 * @see TLightTarget |
|
591 */ |
|
592 virtual void LightOffL(TInt aTarget) = 0; |
|
593 |
|
594 /** |
|
595 * The LightOffL method switches the device light off for the specified target for |
|
596 * the specified duration time. Lights will be switched off with fade-out. |
|
597 * |
|
598 * @param aTarget Defines which light should be controlled. Multiple lights can |
|
599 * be specified with using bitwise-or. |
|
600 * @param aDuration Duration of the time the light is switched off measured in milliseconds. |
|
601 * After the duration expires, the light state for target will be changed |
|
602 * to whatever state was caused by the last infinite time duration call, or |
|
603 * default state determined by inactivity timer, in case there has not |
|
604 * been a previous infinite time duration call in this session. |
|
605 * If the aDuration time is KHWRMInfiniteDuration then it |
|
606 * means an infinite value that has to be |
|
607 * stopped by calling of any of the other light control methods. |
|
608 * Duration can have maximum value of KHWRMLightMaxDuration. |
|
609 * |
|
610 * @leave KErrArgument aDuration is out of range. |
|
611 * @leave KErrNotSupported One or more of specified targets are not supported. |
|
612 * @leave KErrBadHandle if light session has been invalidated. |
|
613 * @leave KErrTimedOut if timeout occurred in controlling light. |
|
614 * @leave KErrInUse if one or more of specified targets are not reserved for this client but are reserved for others. |
|
615 * @leave KErrNoMemory if there is a memory allocation failure. |
|
616 * @leave KErrGeneral if there is a hardware error. |
|
617 * |
|
618 * @see TLightTarget |
|
619 */ |
|
620 virtual void LightOffL(TInt aTarget, |
|
621 TInt aDuration) = 0; |
|
622 |
|
623 /** |
|
624 * The LightOffL method switches the device light off for the specified target for |
|
625 * the specified duration time. Lights fade-out can also be controlled. |
|
626 * |
|
627 * @param aTarget Defines which light should be controlled. Multiple lights can |
|
628 * be specified with using bitwise-or. |
|
629 * @param aDuration Duration of the time the light is switched off measured in milliseconds. |
|
630 * After the duration expires, the light state for target will be changed |
|
631 * to whatever state was caused by the last infinite time duration call, or |
|
632 * default state determined by inactivity timer, in case there has not |
|
633 * been a previous infinite time duration call in this session. |
|
634 * If the aDuration time is KHWRMInfiniteDuration then it |
|
635 * means an infinite value that has to be |
|
636 * stopped by calling of any of the other light control methods. |
|
637 * Duration can have maximum value of KHWRMLightMaxDuration. |
|
638 * @param aFadeOut If ETrue, lights will not turn off instantly but instead smoothly fade-out |
|
639 * Note: All devices will not support fade-out, in which case device will |
|
640 * behave in its default fashion. |
|
641 * |
|
642 * @leave KErrArgument aDuration is out of range. |
|
643 * @leave KErrNotSupported One or more of specified targets are not supported. |
|
644 * @leave KErrBadHandle if light session has been invalidated. |
|
645 * @leave KErrTimedOut if timeout occurred in controlling light. |
|
646 * @leave KErrInUse if one or more of specified targets are not reserved for this client but are reserved for others. |
|
647 * @leave KErrNoMemory if there is a memory allocation failure. |
|
648 * @leave KErrGeneral if there is a hardware error. |
|
649 * |
|
650 * @see TLightTarget |
|
651 */ |
|
652 virtual void LightOffL(TInt aTarget, |
|
653 TInt aDuration, |
|
654 TBool aFadeOut) = 0; |
|
655 |
|
656 /** |
|
657 * This method retrieves the current light status. |
|
658 * |
|
659 * @param aTarget Defines which light status is returned. |
|
660 * This method only supports single target, as different |
|
661 * targets might have different statuses. |
|
662 * @return TLightStatus indicating the current light status. If there is a problem or |
|
663 * multiple targets were specified, CHWRMExtendedLight::ELightStatusUnknown is returned. |
|
664 * |
|
665 * @see MHWRMExtendedLightObserver |
|
666 * @see TLightTarget |
|
667 */ |
|
668 virtual TLightStatus LightStatus(TInt aTarget) const = 0; |
|
669 |
|
670 /** |
|
671 * This method retrieves the supported light targets of the device. |
|
672 * Any attempt to use or reserve unsupported targets will fail with |
|
673 * KErrNotSupported. |
|
674 * |
|
675 * @return Bitmask containing supported light targets. |
|
676 * |
|
677 * @see TLightTarget |
|
678 */ |
|
679 virtual TInt SupportedTargets() const = 0; |
|
680 }; |
|
681 |
|
682 /** |
|
683 * An interface the developer implements for handling notification events from the HWRM server. |
|
684 * |
|
685 * @publishedPartner |
|
686 * @released |
|
687 */ |
|
688 class MHWRMExtendedLightObserver |
|
689 { |
|
690 public: |
|
691 |
|
692 /** |
|
693 * Called when the device light status changes. |
|
694 * Note that if the light status for certain target changes |
|
695 * very rapidly, some state transitions might be missed. |
|
696 * It is however guaranteed that latest state is always obtained. |
|
697 * |
|
698 * @param aTarget Indicates target(s) the new status applies to. |
|
699 * @param aStatus Indicates light request status. |
|
700 * |
|
701 * @see CHWRMExtendedLight::TLightTarget |
|
702 * @see CHWRMExtendedLight::TLightStatus |
|
703 */ |
|
704 virtual void LightStatusChanged(TInt aTarget, |
|
705 CHWRMExtendedLight::TLightStatus aStatus) = 0; |
|
706 }; |
|
707 |
|
708 |
|
709 #endif // HWRMEXTENDEDLIGHT_H |
|
710 |
|
711 // End of File |