|
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 HWRMLIGHT_H |
|
22 #define HWRMLIGHT_H |
|
23 |
|
24 // INCLUDES |
|
25 #include <e32base.h> |
|
26 |
|
27 // CONSTANTS |
|
28 |
|
29 /** |
|
30 * Minimum allowed intensity setting for Light. |
|
31 * |
|
32 * @publishedAll |
|
33 * @released |
|
34 */ |
|
35 const TInt KHWRMLightMinIntensity = 1; |
|
36 |
|
37 /** |
|
38 * Maximum allowed intensity setting for Light. |
|
39 * |
|
40 * @publishedAll |
|
41 * @released |
|
42 */ |
|
43 const TInt KHWRMLightMaxIntensity = 100; |
|
44 |
|
45 /** |
|
46 * Indicates default intensity in various methods. |
|
47 * |
|
48 * @publishedAll |
|
49 * @released |
|
50 */ |
|
51 const TInt KHWRMDefaultIntensity = 0; |
|
52 |
|
53 /** |
|
54 * Maximum allowed duration value. |
|
55 * |
|
56 * @publishedAll |
|
57 * @released |
|
58 */ |
|
59 const TInt KHWRMLightMaxDuration = (KMaxTInt / 1000) - 1; |
|
60 |
|
61 /** |
|
62 * Infinite duration value. |
|
63 * |
|
64 * @publishedAll |
|
65 * @released |
|
66 */ |
|
67 const TInt KHWRMInfiniteDuration = 0; |
|
68 |
|
69 /** |
|
70 * Indicates device default Blink cycle time. |
|
71 * |
|
72 * @publishedAll |
|
73 * @released |
|
74 */ |
|
75 const TInt KHWRMDefaultCycleTime = 0; |
|
76 |
|
77 |
|
78 class MHWRMLightObserver; |
|
79 class CHWRMEnhancedLight; |
|
80 |
|
81 /** |
|
82 * RGB values. |
|
83 * |
|
84 * @publishedAll |
|
85 */ |
|
86 |
|
87 struct THWRMLightColor |
|
88 { |
|
89 TUint8 iRed; |
|
90 TUint8 iGreen; |
|
91 TUint8 iBlue; |
|
92 }; |
|
93 |
|
94 |
|
95 /** |
|
96 * The class used to control the device lights. |
|
97 * |
|
98 * The HW Resource Manager Light API is a library API providing the ability |
|
99 * to control the various light targets of the device. The API provides also |
|
100 * methods to retrieve the current light status and the supported light targets |
|
101 * of the device. The API is meant for all applications which need to control |
|
102 * lights of the device. |
|
103 * |
|
104 * Type of the HW Resource Manager Light API is a synchronous method call meaning |
|
105 * the method call will block the client application. Every new call of the light |
|
106 * API method stops all ongoing light control orders. Light state after duration |
|
107 * based orders expire is the state specified by the last non-duration based order. |
|
108 * |
|
109 * The API consist of the classes CHWRMLight and MHWRMLightObserver. If the client |
|
110 * requires up-to-date status information, it should also provide callback pointer |
|
111 * of the MHWRMLightObserver implementing class for the NewL-method. |
|
112 * |
|
113 * Usage: |
|
114 * |
|
115 * @code |
|
116 * #include <hwrmlight.h> |
|
117 * |
|
118 * // A CHWRMLight instance can be created by using NewL() or NewLC() methods. |
|
119 * // Up-to-date status information not required, no callbacks. |
|
120 * CHWRMLight* light = CHWRMLight::NewL(); |
|
121 * |
|
122 * // After this, lights can be directly controlled via the provided class methods. |
|
123 * light-> LightOnL (EPrimaryDisplay, 5000); // Turn display lights on for five seconds. |
|
124 * light->LightOffL(EPrimaryDisplay); // Turn display lights off indefinitely. |
|
125 * |
|
126 * // To clean up, delete the created object: |
|
127 * delete light; |
|
128 * @endcode |
|
129 * |
|
130 * @publishedAll |
|
131 * @released |
|
132 */ |
|
133 class CHWRMLight : public CBase |
|
134 { |
|
135 public: |
|
136 |
|
137 /** |
|
138 * Possible light states that can be get for the different light targets |
|
139 */ |
|
140 enum TLightStatus |
|
141 { |
|
142 /** |
|
143 For debugging/development and signaling an error conditions. |
|
144 */ |
|
145 ELightStatusUnknown = 0, |
|
146 /** |
|
147 Light state switch to light on. |
|
148 */ |
|
149 ELightOn, |
|
150 /** |
|
151 Light state switch to light off. |
|
152 */ |
|
153 ELightOff, |
|
154 /** |
|
155 Light state switch to light blinking. |
|
156 */ |
|
157 ELightBlink |
|
158 }; |
|
159 |
|
160 /** |
|
161 * Possible light targets. |
|
162 * Targets can be used as bitmask. Some common masks are provided as enum. |
|
163 * |
|
164 * Note that all targets are not supported by all devices. |
|
165 * Attempting to use unsupported target will result in |
|
166 * KErrNotSupported. |
|
167 * |
|
168 * At least one target must be defined. |
|
169 */ |
|
170 enum TLightTarget |
|
171 { |
|
172 /** |
|
173 No target. Not a valid target value, used only for error checking. |
|
174 */ |
|
175 ENoTarget = 0x0, |
|
176 /** |
|
177 Primary display of the device. |
|
178 */ |
|
179 EPrimaryDisplay = 0x1, |
|
180 /** |
|
181 Primary keyboard of the device. |
|
182 */ |
|
183 EPrimaryKeyboard = 0x2, |
|
184 /** |
|
185 Both primary display and the primary keyboard of the device. |
|
186 */ |
|
187 EPrimaryDisplayAndKeyboard = 0x3, |
|
188 /** |
|
189 Secondary display of the device. |
|
190 */ |
|
191 ESecondaryDisplay = 0x4, |
|
192 /** |
|
193 Secondary keyboard of the device. |
|
194 */ |
|
195 ESecondaryKeyboard = 0x8, |
|
196 /** |
|
197 Both secondary display and the secondary keyboard of the device. |
|
198 */ |
|
199 ESecondaryDisplayAndKeyboard = 0xC, |
|
200 /** |
|
201 Device specific custom target 1. |
|
202 */ |
|
203 ECustomTarget1 = 0x10, |
|
204 /** |
|
205 Device specific custom target 2. |
|
206 */ |
|
207 ECustomTarget2 = 0x20, |
|
208 /** |
|
209 Device specific custom target 3. |
|
210 */ |
|
211 ECustomTarget3 = 0x40, |
|
212 /** |
|
213 Device specific custom target 4. |
|
214 */ |
|
215 ECustomTarget4 = 0x80, |
|
216 /** |
|
217 * Special target used to control all currently available system lights. |
|
218 * |
|
219 * System lights normally include all displays and keyboards, |
|
220 * but not custom lights. This is however device dependent. |
|
221 * |
|
222 * A target mask including this target is |
|
223 * always changed to a device state specific target mask. |
|
224 * Note that the system target with any other target is not supported. |
|
225 * |
|
226 * This target is always supported but it is never |
|
227 * included in supported targets mask. |
|
228 * |
|
229 * @see CHWRMLight::SupportedTargets() |
|
230 */ |
|
231 ESystemTarget = 0x80000000 |
|
232 }; |
|
233 |
|
234 public: // Constructors |
|
235 |
|
236 /** |
|
237 * Two-phased constructor. |
|
238 * |
|
239 * @return A pointer to a new instance of the CHWRMLight class. |
|
240 * |
|
241 * @leave KErrNotSupported Device doesn't support Light feature. |
|
242 * @leave KErrNoMemory There is a memory allocation failure. |
|
243 */ |
|
244 IMPORT_C static CHWRMLight* NewL(); |
|
245 |
|
246 /** |
|
247 * Two-phased constructor. |
|
248 * Leaves instance to cleanup stack. |
|
249 * |
|
250 * @return A pointer to a new instance of the CHWRMLight class. |
|
251 * |
|
252 * @leave KErrNotSupported Device doesn't support Light feature. |
|
253 * @leave KErrNoMemory There is a memory allocation failure. |
|
254 */ |
|
255 IMPORT_C static CHWRMLight* NewLC(); |
|
256 |
|
257 /** |
|
258 * Two-phased constructor. |
|
259 * Use this method for creating a Light client with callbacks. |
|
260 * |
|
261 * @param aCallback Pointer to the callback instance. |
|
262 * @return A pointer to a new instance of the CHWRMLight class. |
|
263 * |
|
264 * @leave KErrNotSupported Device doesn't support Light feature. |
|
265 * @leave KErrNoMemory There is a memory allocation failure. |
|
266 */ |
|
267 IMPORT_C static CHWRMLight* NewL(MHWRMLightObserver* aCallback); |
|
268 |
|
269 /** |
|
270 * Two-phased constructor. |
|
271 * Use this method for creating a Light client with callbacks. |
|
272 * Leaves instance to cleanup stack. |
|
273 * |
|
274 * @param aCallback Pointer to the callback instance |
|
275 * @return A pointer to a new instance of the CHWRMLight class. |
|
276 * |
|
277 * @leave KErrNotSupported Device doesn't support Light feature. |
|
278 * @leave KErrNoMemory There is a memory allocation failure. |
|
279 */ |
|
280 IMPORT_C static CHWRMLight* NewLC(MHWRMLightObserver* aCallback); |
|
281 |
|
282 |
|
283 /** |
|
284 * Destructor |
|
285 */ |
|
286 IMPORT_C ~CHWRMLight(); |
|
287 |
|
288 public: // New functions |
|
289 |
|
290 |
|
291 /** |
|
292 * Reserves light target exclusively for this client. |
|
293 * A higher priority client may cause lower priority client reservation |
|
294 * to be temporarily suspended. Commands can still be issued in suspended |
|
295 * state, but they will not be acted upon unless suspension is lifted |
|
296 * within specified duration. |
|
297 * The suspended client will not get any notification about suspension. |
|
298 * If light target is already reserved by a higher or equal priority application, |
|
299 * reserving will still succeeds, but reservation is immediately suspended. |
|
300 * |
|
301 * Calling this method is equal to calling ReserveLightL( aTarget, EFalse, EFalse), |
|
302 * i.e. any previously frozen state will not be restored and CCoeEnv |
|
303 * background/foreground status is always used to control further reservations. |
|
304 * |
|
305 * @param aTarget Defines which light should be reserved. Multiple lights can |
|
306 * be specified with using bitwise-or. |
|
307 * |
|
308 * @leave KErrNotSupported One or more of specified targets are not supported. |
|
309 * @leave KErrAccessDenied No CCoeEnv present. |
|
310 * @leave KErrNotReady Trying to reserve while on background. |
|
311 * @leave KErrNoMemory There is a memory allocation failure. |
|
312 * |
|
313 * @see TLightTarget |
|
314 */ |
|
315 virtual void ReserveLightL(TInt aTarget); |
|
316 |
|
317 /** |
|
318 * Reserves light target exclusively for this client. |
|
319 * A higher priority client may cause lower priority client reservation |
|
320 * to be temporarily suspended. Commands can still be issued in suspended |
|
321 * state, but they will not be acted upon unless suspension is lifted |
|
322 * within specified duration. |
|
323 * The suspended client will not get any notification about suspension. |
|
324 * If light target is already reserved by a higher or equal priority application, |
|
325 * reserving will still succeeds, but reservation is immediately suspended. |
|
326 * |
|
327 * |
|
328 * @param aTarget Defines which light should be reserved. Multiple lights can |
|
329 * be specified with using bitwise-or. |
|
330 * @param aRestoreState If ETrue, the state frozen on last release will be |
|
331 * restored upon successful reservation. |
|
332 * I.e. if light was blinking when it was released by this |
|
333 * client the last time, it would start blinking again upon |
|
334 * successful reservation. |
|
335 * For the first reservation of each session this parameter |
|
336 * is always considered EFalse regardless of what is supplied, |
|
337 * as there is no previous frozen state to restore. |
|
338 * @param aForceNoCCoeEnv If EFalse, then reservation requires that this client is |
|
339 * on the foreground at the time of reservation and light |
|
340 * target will be automatically released and re-reserved based |
|
341 * on background/foreground status of the this client. This |
|
342 * also implies that CCoeEnv::Static() != NULL is required. |
|
343 * If ETrue, the client will not require CCoeEnv to be present |
|
344 * nor does it automatically reserve/release light by depending |
|
345 * on foreground/background status of the client. |
|
346 * Only trusted clients are allowed to set this flag to ETrue. |
|
347 * A client is considered trusted if it has nonstandard |
|
348 * priority defined in the internal lights policy of the |
|
349 * HW Resource Manager. A client can be defined trusted |
|
350 * only by a product. |
|
351 * |
|
352 * @leave KErrNotSupported One or more of specified targets are not supported. |
|
353 * @leave KErrAccessDenied Paramenter aForceNoCCoeEnv is ETrue and client is not trusted. |
|
354 * @leave KErrBadHandle Parameter ForceNoCCoeEnv is EFalse and no CCoeEnv present. |
|
355 * @leave KErrNotReady Trying to reserve while on background and parameter |
|
356 * aForceNoCCoeEnv is EFalse. |
|
357 * @leave KErrNoMemory There is a memory allocation failure. |
|
358 * |
|
359 * @see TLightTarget |
|
360 */ |
|
361 virtual void ReserveLightL(TInt aTarget, TBool aRestoreState, TBool aForceNoCCoeEnv); |
|
362 |
|
363 /** |
|
364 * Releases light target if it was previously reserved for this client. |
|
365 * If this client has not reserved any of the specified lights, |
|
366 * this method does nothing. |
|
367 * Any reserved light targets that are released and have no other suspended |
|
368 * clients will be reset to default state, which is either lights on or lights off, |
|
369 * depending on system inactivity time. |
|
370 * |
|
371 * @param aTarget Defines which light should be released. Multiple lights can |
|
372 * be specified with using bitwise-or. |
|
373 * |
|
374 * @see TLightTarget |
|
375 */ |
|
376 virtual void ReleaseLight(TInt aTarget); |
|
377 |
|
378 |
|
379 /** |
|
380 * The LightOnL method switches the specified target light on |
|
381 * for infinite duration using default intensity. Lights will use fade-in. |
|
382 * |
|
383 * Calling this method is equal to calling |
|
384 * LightOnL(aTarget, KHWRMInfiniteDuration, KHWRMDefaultIntensity, ETrue). |
|
385 * |
|
386 * @param aTarget Defines which light should be controlled. Multiple lights can |
|
387 * be specified with using bitwise-or. |
|
388 * |
|
389 * @leave KErrNotSupported One or more of specified targets are not supported. |
|
390 * @leave KErrBadHandle Light session has been invalidated. |
|
391 * @leave KErrTimedOut Timeout occurred in controlling light. |
|
392 * @leave KErrInUse One or more of specified targets are not reserved for |
|
393 * this client but are reserved for others. |
|
394 * @leave KErrNoMemory There is a memory allocation failure. |
|
395 * @leave KErrGeneral There is a hardware error. |
|
396 * |
|
397 * @see TLightTarget |
|
398 */ |
|
399 virtual void LightOnL(TInt aTarget); |
|
400 |
|
401 /** |
|
402 * The LightOnL method switches the specified target light on |
|
403 * for the specified duration using default intensity. Lights will use fade-in. |
|
404 * |
|
405 * Calling this method is equal to call |
|
406 * LightOnL(aTarget, aDuration, KHWRMDefaultIntensity, ETrue). |
|
407 * |
|
408 * @param aTarget Defines which light should be controlled. Multiple lights can |
|
409 * be specified with using bitwise-or. |
|
410 * @param aDuration Duration of the time the light is switched on measured in milliseconds. |
|
411 * After the duration expires, the light state for target will be changed |
|
412 * to whatever state was caused by the last infinite time duration call, or |
|
413 * default state determined by inactivity timer, in case there has not |
|
414 * been a previous infinite time duration call in this session. |
|
415 * If the aDuration time is KHWRMInfiniteDuration then it means an |
|
416 * infinite value that has to be stopped by calling of any of the other |
|
417 ' light control methods. |
|
418 * Duration can have maximum value of KHWRMLightMaxDuration. |
|
419 * |
|
420 * @leave KErrArgument Parameter aDuration is out of range. |
|
421 * @leave KErrNotSupported One or more of specified targets are not supported. |
|
422 * @leave KErrBadHandle Light session has been invalidated. |
|
423 * @leave KErrTimedOut Timeout occurred in controlling light. |
|
424 * @leave KErrInUse One or more of specified targets are not reserved for |
|
425 * this client but are reserved for others. |
|
426 * @leave KErrNoMemory There is a memory allocation failure. |
|
427 * @leave KErrGeneral There is a hardware error. |
|
428 * |
|
429 * @see TLightTarget |
|
430 */ |
|
431 virtual void LightOnL(TInt aTarget, |
|
432 TInt aDuration); |
|
433 |
|
434 /** |
|
435 * The LightOnL method switches the specified target light on |
|
436 * for the specified duration using specified intensity. Fade-in can also be controlled. |
|
437 * |
|
438 * @param aTarget Defines which light should be controlled. Multiple lights can |
|
439 * be specified with using bitwise-or. |
|
440 * @param aDuration Duration of the time the light is switched on measured in milliseconds. |
|
441 * After the duration expires, the light state for target will be changed |
|
442 * to whatever state was caused by the last infinite time duration call, or |
|
443 * default state determined by inactivity timer, in case there has not |
|
444 * been a previous infinite time duration call in this session. |
|
445 * If the aDuration time is KHWRMInfiniteDuration then it means |
|
446 * an infinite value that has to be stopped by calling of any of |
|
447 * the other light control methods. |
|
448 * Duration can have maximum value of KHWRMLightMaxDuration. |
|
449 * @param aIntensity Intensity of the light. If aIntensity is KHWRMDefaultIntensity, device default |
|
450 * intensity will be used. |
|
451 * Note: All devices might not support user defined intensity, in which case |
|
452 * device will behave in its default fashion. |
|
453 * @param aFadeIn If ETrue, lights will not turn on instantly but instead smoothly fade-in. |
|
454 * Note: All devices will not support fade-in, in which case device will |
|
455 * behave in its default fashion. |
|
456 * |
|
457 * @leave KErrArgument One of the parameters is out of range. |
|
458 * @leave KErrNotSupported One or more of specified targets are not supported. |
|
459 * @leave KErrBadHandle Light session has been invalidated. |
|
460 * @leave KErrTimedOut Timeout occurred in controlling light. |
|
461 * @leave KErrInUse One or more of specified targets are not reserved for |
|
462 * this client but are reserved for others. |
|
463 * @leave KErrNoMemory There is a memory allocation failure. |
|
464 * @leave KErrGeneral There is a hardware error. |
|
465 * |
|
466 * @see TLightTarget |
|
467 */ |
|
468 virtual void LightOnL(TInt aTarget, |
|
469 TInt aDuration, |
|
470 TInt aIntensity, |
|
471 TBool aFadeIn); |
|
472 |
|
473 /** |
|
474 * The LightBlinkL method blinks the target light(s) of the device for infinite duration |
|
475 * using default intensity. |
|
476 * |
|
477 * Calling this method is equal to call |
|
478 * @code |
|
479 * LightBlinkL(aTarget, KHWRMInfiniteDuration, KHWRMDefaultCycleTime, |
|
480 * KHWRMDefaultCycleTime, KHWRMDefaultIntensity). |
|
481 * @endcode |
|
482 * |
|
483 * @param aTarget Defines which light should be controlled. Multiple lights can |
|
484 * be specified with using bitwise-or. |
|
485 * |
|
486 * @leave KErrNotSupported One or more of specified targets are not supported. |
|
487 * @leave KErrBadHandle Light session has been invalidated. |
|
488 * @leave KErrTimedOut Timeout occurred in controlling light. |
|
489 * @leave KErrInUse One or more of specified targets are not reserved for |
|
490 * this client but are reserved for others. |
|
491 * @leave KErrNoMemory There is a memory allocation failure. |
|
492 * @leave KErrGeneral There is a hardware error. |
|
493 * |
|
494 * @see TLightTarget |
|
495 */ |
|
496 virtual void LightBlinkL(TInt aTarget); |
|
497 |
|
498 /** |
|
499 * The LightBlinkL method blinks the target light(s) of the device for specified duration |
|
500 * using default intensity. |
|
501 * |
|
502 * Calling this method is equal to calling |
|
503 * LightBlinkL(aTarget, aDuration, KHWRMDefaultCycleTime, |
|
504 * KHWRMDefaultCycleTime, KHWRMDefaultIntensity). |
|
505 * |
|
506 * @param aTarget Defines which light should be controlled. Multiple lights can |
|
507 * be specified with using bitwise-or. |
|
508 * @param aDuration Duration of the time the light is set to blink measured in milliseconds. |
|
509 * After the duration expires, the light state for target will be changed |
|
510 * to whatever state was caused by the last infinite time duration call, or |
|
511 * default state determined by inactivity timer, in case there has not |
|
512 * been a previous infinite time duration call in this session. |
|
513 * If the aTotalDuration time is KHWRMInfiniteDuration then it |
|
514 * means an infinite value that has to be |
|
515 * stopped by calling of any of the other light control methods. |
|
516 * Duration can have maximum value of KHWRMLightMaxDuration. |
|
517 * |
|
518 * @leave KErrArgument Parameter aDuration is out of range. |
|
519 * @leave KErrNotSupported One or more of specified targets are not supported. |
|
520 * @leave KErrBadHandle Light session has been invalidated. |
|
521 * @leave KErrTimedOut Timeout occurred in controlling light. |
|
522 * @leave KErrInUse One or more of specified targets are not reserved for |
|
523 * this client but are reserved for others. |
|
524 * @leave KErrNoMemory There is a memory allocation failure. |
|
525 * @leave KErrGeneral There is a hardware error. |
|
526 * |
|
527 * @see TLightTarget |
|
528 */ |
|
529 virtual void LightBlinkL(TInt aTarget, |
|
530 TInt aDuration); |
|
531 |
|
532 /** |
|
533 * The LightBlinkL method blinks the target light(s) of the device for specified duration |
|
534 * using specified intensity. On- and Off-cycle times of the blinking can also be controlled. |
|
535 * |
|
536 * @param aTarget Defines which light should be controlled. Multiple lights can |
|
537 * be specified with using bitwise-or. |
|
538 * @param aDuration Duration of the time the light is set to blink measured in milliseconds. |
|
539 * After the duration expires, the light state for target will be changed |
|
540 * to whatever state was caused by the last infinite time duration call, or |
|
541 * default state determined by inactivity timer, in case there has not |
|
542 * been a previous infinite time duration call in this session. |
|
543 * If the aTotalDuration time is KHWRMInfiniteDuration then it |
|
544 * means an infinite value that has to be |
|
545 * stopped by calling of any of the other light control methods. |
|
546 * Duration can have maximum value of KHWRMLightMaxDuration. |
|
547 * @param aOnDuration Duration time, measured in milliseconds, of how long the Light is |
|
548 * switched on 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 aOffDuration Duration time, measured in milliseconds, of how long the Light |
|
556 * is switched off in every Blink cycle. |
|
557 * Duration can have maximum value of KHWRMLightMaxDuration. |
|
558 * For device default cycle duration, use value KHWRMDefaultCycleTime. |
|
559 * If either of aOnDuration or aOffDuration is KHWRMDefaultCycleTime, |
|
560 * both must be KHWRMDefaultCycleTime. |
|
561 * Some devices might not support variable blink cycle times, in which |
|
562 * case default value will be substituted. |
|
563 * @param aIntensity Intensity of the light. If aIntensity is KHWRMDefaultIntensity, device default |
|
564 * intensity will be used. |
|
565 * Note: All devices might not support user defined intensity, in which case |
|
566 * device will behave in its default fashion. |
|
567 * |
|
568 * @leave KErrArgument One of the parameters is out of range or otherwise invalid. |
|
569 * @leave KErrNotSupported One or more of specified targets are not supported. |
|
570 * @leave KErrBadHandle Light session has been invalidated. |
|
571 * @leave KErrTimedOut Timeout occurred in controlling light. |
|
572 * @leave KErrInUse One or more of specified targets are not reserved for |
|
573 * this client but are reserved for others. |
|
574 * @leave KErrNoMemory There is a memory allocation failure. |
|
575 * @leave KErrGeneral There is a hardware error. |
|
576 * |
|
577 * @see TLightTarget |
|
578 */ |
|
579 virtual void LightBlinkL(TInt aTarget, |
|
580 TInt aDuration, |
|
581 TInt aOnDuration, |
|
582 TInt aOffDuration, |
|
583 TInt aIntensity); |
|
584 |
|
585 /** |
|
586 * The LightOffL method switches the device light off for the specified target for |
|
587 * infinite duration. Lights will be switched off with fade-out. |
|
588 * |
|
589 * Calling this method is equal to call |
|
590 * LightOffL(aTarget, KHWRMInfiniteDuration, ETrue). |
|
591 * |
|
592 * @param aTarget Defines which light should be controlled. Multiple lights can |
|
593 * be specified with using bitwise-or. |
|
594 * |
|
595 * @leave KErrNotSupported One or more of specified targets are not supported. |
|
596 * @leave KErrBadHandle Light session has been invalidated. |
|
597 * @leave KErrTimedOut Timeout occurred in controlling light. |
|
598 * @leave KErrInUse One or more of specified targets are not reserved for |
|
599 * this client but are reserved for others. |
|
600 * @leave KErrNoMemory There is a memory allocation failure. |
|
601 * @leave KErrGeneral There is a hardware error. |
|
602 * |
|
603 * @see TLightTarget |
|
604 */ |
|
605 virtual void LightOffL(TInt aTarget); |
|
606 |
|
607 /** |
|
608 * The LightOffL method switches the device light off for the specified target for |
|
609 * the specified duration time. Lights will be switched off with fade-out. |
|
610 * |
|
611 * Calling this method is equal to call LightOffL(aTarget, aDuration, ETrue). |
|
612 * |
|
613 * @param aTarget Defines which light should be controlled. Multiple lights can |
|
614 * be specified with using bitwise-or. |
|
615 * @param aDuration Duration of the time the light is switched off measured in milliseconds. |
|
616 * After the duration expires, the light state for target will be changed |
|
617 * to whatever state was caused by the last infinite time duration call, or |
|
618 * default state determined by inactivity timer, in case there has not |
|
619 * been a previous infinite time duration call in this session. |
|
620 * If the aDuration time is KHWRMInfiniteDuration then it |
|
621 * means an infinite value that has to be |
|
622 * stopped by calling of any of the other light control methods. |
|
623 * Duration can have maximum value of KHWRMLightMaxDuration. |
|
624 * |
|
625 * @leave KErrArgument Parameter aDuration is out of range. |
|
626 * @leave KErrNotSupported One or more of specified targets are not supported. |
|
627 * @leave KErrBadHandle Light session has been invalidated. |
|
628 * @leave KErrTimedOut Timeout occurred in controlling light. |
|
629 * @leave KErrInUse One or more of specified targets are not reserved for |
|
630 * this client but are reserved for others. |
|
631 * @leave KErrNoMemory There is a memory allocation failure. |
|
632 * @leave KErrGeneral There is a hardware error. |
|
633 * |
|
634 * @see TLightTarget |
|
635 */ |
|
636 virtual void LightOffL(TInt aTarget, |
|
637 TInt aDuration); |
|
638 |
|
639 /** |
|
640 * The LightOffL method switches the device light off for the specified target for |
|
641 * the specified duration time. Lights fade-out can also be controlled. |
|
642 * |
|
643 * @param aTarget Defines which light should be controlled. Multiple lights can |
|
644 * be specified with using bitwise-or. |
|
645 * @param aDuration Duration of the time the light is switched off measured in milliseconds. |
|
646 * After the duration expires, the light state for target will be changed |
|
647 * to whatever state was caused by the last infinite time duration call, or |
|
648 * default state determined by inactivity timer, in case there has not |
|
649 * been a previous infinite time duration call in this session. |
|
650 * If the aDuration time is KHWRMInfiniteDuration then it |
|
651 * means an infinite value that has to be |
|
652 * stopped by calling of any of the other light control methods. |
|
653 * Duration can have maximum value of KHWRMLightMaxDuration. |
|
654 * @param aFadeOut If ETrue, lights will not turn off instantly but instead smoothly fade-out |
|
655 * Note: All devices will not support fade-out, in which case device will |
|
656 * behave in its default fashion. |
|
657 * |
|
658 * @leave KErrArgument aDuration is out of range. |
|
659 * @leave KErrNotSupported One or more of specified targets are not supported. |
|
660 * @leave KErrBadHandle Light session has been invalidated. |
|
661 * @leave KErrTimedOut Timeout occurred in controlling light. |
|
662 * @leave KErrInUse One or more of specified targets are not reserved for |
|
663 * this client but are reserved for others. |
|
664 * @leave KErrNoMemory There is a memory allocation failure. |
|
665 * @leave KErrGeneral There is a hardware error. |
|
666 * |
|
667 * @see TLightTarget |
|
668 */ |
|
669 virtual void LightOffL(TInt aTarget, |
|
670 TInt aDuration, |
|
671 TBool aFadeOut); |
|
672 |
|
673 /** |
|
674 * This method retrieves the current light status. |
|
675 * |
|
676 * @param aTarget Defines which light status is returned. |
|
677 * This method only supports single target, as different |
|
678 * targets might have different statuses. |
|
679 * @return TLightStatus indicating the current light status. If there is a problem or |
|
680 * multiple targets were specified, CHWRMLight::ELightStatusUnknown is returned. |
|
681 * |
|
682 * @see MHWRMLightObserver |
|
683 * @see TLightTarget |
|
684 */ |
|
685 virtual TLightStatus LightStatus(TInt aTarget) const; |
|
686 |
|
687 /** |
|
688 * This method retrieves the supported light targets of the device. |
|
689 * Any attempt to use or reserve unsupported targets will fail with |
|
690 * KErrNotSupported. |
|
691 * |
|
692 * @return Bitmask containing supported light targets. |
|
693 * |
|
694 * @see TLightTarget |
|
695 */ |
|
696 virtual TInt SupportedTargets() const; |
|
697 |
|
698 |
|
699 /* |
|
700 * Used for setting color of Light Target(s). |
|
701 * |
|
702 * @param aTarget Defines which light should be controlled. Multiple lights can |
|
703 * be specified with using bitwise-or. |
|
704 * |
|
705 * @param aRGB RGB Values to be set for the target(s). |
|
706 * |
|
707 * @leave KErrNotSupported One or more of specified targets are not supported. |
|
708 * @leave KErrBadHandle Light session has been invalidated. |
|
709 * @leave KErrTimedOut Timeout occurred in controlling light. |
|
710 * @leave KErrInUse One or more of specified targets are not reserved for |
|
711 * this client but are reserved for others. |
|
712 * @leave KErrNoMemory There is a memory allocation failure. |
|
713 |
|
714 * @see THWRMLightColor |
|
715 */ |
|
716 IMPORT_C void SetLightColorL(TInt aTarget, THWRMLightColor& aRGB); |
|
717 |
|
718 /* |
|
719 * Used for setting default color of Light Target(s). |
|
720 * |
|
721 * @param aTarget Defines which light should be controlled. Multiple lights can |
|
722 * be specified with using bitwise-or. |
|
723 * @leave KErrNotSupported One or more of specified targets are not supported. |
|
724 * @leave KErrBadHandle Light session has been invalidated. |
|
725 * @leave KErrTimedOut Timeout occurred in controlling light. |
|
726 * @leave KErrInUse One or more of specified targets are not reserved for |
|
727 * this client but are reserved for others. |
|
728 * @leave KErrNoMemory There is a memory allocation failure. |
|
729 |
|
730 */ |
|
731 |
|
732 IMPORT_C void SetLightDefaultColorL(TInt aTarget); |
|
733 |
|
734 /** |
|
735 * The LightOnL method switches the specified target light on |
|
736 * for the specified duration and specified color. |
|
737 * |
|
738 * @param aTarget Defines which light should be controlled. Multiple lights can |
|
739 * be specified with using bitwise-or. |
|
740 * @param aDuration Duration of the time the light is switched on measured in milliseconds. |
|
741 * After the duration expires, the light state for target will be changed |
|
742 * to whatever state was caused by the last infinite time duration call, or |
|
743 * default state determined by inactivity timer, in case there has not |
|
744 * been a previous infinite time duration call in this session. |
|
745 * If the aDuration time is KHWRMInfiniteDuration then it means |
|
746 * an infinite value that has to be stopped by calling of any of |
|
747 * the other light control methods. |
|
748 * Duration can have maximum value of KHWRMLightMaxDuration. |
|
749 * @param aRGBParam RGB Values to be set for the target(s). |
|
750 * |
|
751 * @leave KErrArgument One of the parameters is out of range. |
|
752 * @leave KErrNotSupported One or more of specified targets are not supported. |
|
753 * @leave KErrBadHandle Light session has been invalidated. |
|
754 * @leave KErrTimedOut Timeout occurred in controlling light. |
|
755 * @leave KErrInUse One or more of specified targets are not reserved for |
|
756 * this client but are reserved for others. |
|
757 * @leave KErrNoMemory There is a memory allocation failure. |
|
758 * @leave KErrGeneral There is a hardware error. |
|
759 * |
|
760 * @see TLightTarget |
|
761 * @see THWRMLightColor |
|
762 */ |
|
763 IMPORT_C void LightOnL(TInt aTarget, TInt aDuration, const THWRMLightColor& aRGBParam); |
|
764 |
|
765 /** |
|
766 * The LightOnL method switches the specified target light on |
|
767 * for the specified duration using specified intensity and color. Fade-in can also be controlled. |
|
768 * |
|
769 * @param aTarget Defines which light should be controlled. Multiple lights can |
|
770 * be specified with using bitwise-or. |
|
771 * @param aDuration Duration of the time the light is switched on measured in milliseconds. |
|
772 * After the duration expires, the light state for target will be changed |
|
773 * to whatever state was caused by the last infinite time duration call, or |
|
774 * default state determined by inactivity timer, in case there has not |
|
775 * been a previous infinite time duration call in this session. |
|
776 * If the aDuration time is KHWRMInfiniteDuration then it means |
|
777 * an infinite value that has to be stopped by calling of any of |
|
778 * the other light control methods. |
|
779 * Duration can have maximum value of KHWRMLightMaxDuration. |
|
780 * @param aIntensity Intensity of the light. If aIntensity is KHWRMDefaultIntensity, device default |
|
781 * intensity will be used. |
|
782 * Note: All devices might not support user defined intensity, in which case |
|
783 * device will behave in its default fashion. |
|
784 * @param aFadeIn If ETrue, lights will not turn on instantly but instead smoothly fade-in. |
|
785 * Note: All devices will not support fade-in, in which case device will |
|
786 * behave in its default fashion. |
|
787 * @param aRGBParam RGB Values to be set for the target(s). |
|
788 * |
|
789 * @leave KErrArgument One of the parameters is out of range. |
|
790 * @leave KErrNotSupported One or more of specified targets are not supported. |
|
791 * @leave KErrBadHandle Light session has been invalidated. |
|
792 * @leave KErrTimedOut Timeout occurred in controlling light. |
|
793 * @leave KErrInUse One or more of specified targets are not reserved for |
|
794 * this client but are reserved for others. |
|
795 * @leave KErrNoMemory There is a memory allocation failure. |
|
796 * @leave KErrGeneral There is a hardware error. |
|
797 * |
|
798 * @see TLightTarget |
|
799 * @see THWRMLightColor |
|
800 */ |
|
801 |
|
802 IMPORT_C void LightOnL(TInt aTarget, TInt aDuration, TInt aIntensity, TBool aFadeIn, |
|
803 const THWRMLightColor& aRGBParam); |
|
804 |
|
805 /** |
|
806 * The LightBlinkL method blinks the target light(s) of the device for specified duration and color |
|
807 * using default intensity. |
|
808 * |
|
809 * |
|
810 * @param aTarget Defines which light should be controlled. Multiple lights can |
|
811 * be specified with using bitwise-or. |
|
812 * @param aDuration Duration of the time the light is set to blink measured in milliseconds. |
|
813 * After the duration expires, the light state for target will be changed |
|
814 * to whatever state was caused by the last infinite time duration call, or |
|
815 * default state determined by inactivity timer, in case there has not |
|
816 * been a previous infinite time duration call in this session. |
|
817 * If the aTotalDuration time is KHWRMInfiniteDuration then it |
|
818 * means an infinite value that has to be |
|
819 * stopped by calling of any of the other light control methods. |
|
820 * Duration can have maximum value of KHWRMLightMaxDuration. |
|
821 * |
|
822 * @param aRGBParam RGB Values to be set for the target(s). |
|
823 * |
|
824 * @leave KErrArgument Parameter aDuration is out of range. |
|
825 * @leave KErrNotSupported One or more of specified targets are not supported. |
|
826 * @leave KErrBadHandle Light session has been invalidated. |
|
827 * @leave KErrTimedOut Timeout occurred in controlling light. |
|
828 * @leave KErrInUse One or more of specified targets are not reserved for |
|
829 * this client but are reserved for others. |
|
830 * @leave KErrNoMemory There is a memory allocation failure. |
|
831 * @leave KErrGeneral There is a hardware error. |
|
832 * |
|
833 * @see TLightTarget |
|
834 * @see THWRMLightColor |
|
835 */ |
|
836 |
|
837 IMPORT_C void LightBlinkL(TInt aTarget, TInt aDuration, const THWRMLightColor& aRGBParam); |
|
838 |
|
839 /** |
|
840 * The LightBlinkL method blinks the target light(s) of the device for specified duration |
|
841 * using specified intensity and color. On- and Off-cycle times of the blinking can also be controlled. |
|
842 * |
|
843 * @param aTarget Defines which light should be controlled. Multiple lights can |
|
844 * be specified with using bitwise-or. |
|
845 * @param aDuration Duration of the time the light is set to blink measured in milliseconds. |
|
846 * After the duration expires, the light state for target will be changed |
|
847 * to whatever state was caused by the last infinite time duration call, or |
|
848 * default state determined by inactivity timer, in case there has not |
|
849 * been a previous infinite time duration call in this session. |
|
850 * If the aTotalDuration time is KHWRMInfiniteDuration then it |
|
851 * means an infinite value that has to be |
|
852 * stopped by calling of any of the other light control methods. |
|
853 * Duration can have maximum value of KHWRMLightMaxDuration. |
|
854 * @param aOnDuration Duration time, measured in milliseconds, of how long the Light is |
|
855 * switched on in every Blink cycle. |
|
856 * Duration can have maximum value of KHWRMLightMaxDuration. |
|
857 * For device default cycle duration, use value KHWRMDefaultCycleTime. |
|
858 * If either of aOnDuration or aOffDuration is KHWRMDefaultCycleTime, |
|
859 * both must be KHWRMDefaultCycleTime. |
|
860 * Some devices might not support variable blink cycle times, in which |
|
861 * case default value will be substituted. |
|
862 * @param aOffDuration Duration time, measured in milliseconds, of how long the Light |
|
863 * is switched off in every Blink cycle. |
|
864 * Duration can have maximum value of KHWRMLightMaxDuration. |
|
865 * For device default cycle duration, use value KHWRMDefaultCycleTime. |
|
866 * If either of aOnDuration or aOffDuration is KHWRMDefaultCycleTime, |
|
867 * both must be KHWRMDefaultCycleTime. |
|
868 * Some devices might not support variable blink cycle times, in which |
|
869 * case default value will be substituted. |
|
870 * @param aIntensity Intensity of the light. If aIntensity is KHWRMDefaultIntensity, device default |
|
871 * intensity will be used. |
|
872 * Note: All devices might not support user defined intensity, in which case |
|
873 * device will behave in its default fashion. |
|
874 * |
|
875 * @param aRGBParam RGB Values to be set for the target(s). |
|
876 * |
|
877 * @leave KErrArgument One of the parameters is out of range or otherwise invalid. |
|
878 * @leave KErrNotSupported One or more of specified targets are not supported. |
|
879 * @leave KErrBadHandle Light session has been invalidated. |
|
880 * @leave KErrTimedOut Timeout occurred in controlling light. |
|
881 * @leave KErrInUse One or more of specified targets are not reserved for |
|
882 * this client but are reserved for others. |
|
883 * @leave KErrNoMemory There is a memory allocation failure. |
|
884 * @leave KErrGeneral There is a hardware error. |
|
885 * |
|
886 * @see TLightTarget |
|
887 * @see THWRMLightColor |
|
888 */ |
|
889 |
|
890 IMPORT_C void LightBlinkL(TInt aTarget, TInt aDuration, TInt aOnDuration, TInt aOffDuration, |
|
891 TInt aIntensity, const THWRMLightColor& aRGBParam); |
|
892 |
|
893 |
|
894 |
|
895 |
|
896 private: |
|
897 CHWRMLight(); |
|
898 void ConstructL(MHWRMLightObserver* aCallback); |
|
899 |
|
900 private: |
|
901 CHWRMEnhancedLight* iEnhanced; |
|
902 |
|
903 }; |
|
904 |
|
905 /** |
|
906 * A callback interface for light status reporting. |
|
907 * |
|
908 * If the client requires up-to-date status information, the client needs |
|
909 * to derive a class from the MHWRMlightObserver interface and implement |
|
910 * the LightStatusChanged() method. |
|
911 * |
|
912 * A callback object header example: |
|
913 * |
|
914 * @code |
|
915 * // INCLUDES |
|
916 * #include <hwrmlight.h> // Link against HWRMLightClient.lib. |
|
917 * |
|
918 * class CTests : public CBase, |
|
919 * public MHWRMLightObserver |
|
920 * { |
|
921 * public: |
|
922 * CTests(); |
|
923 * ~CTests(); |
|
924 * |
|
925 * void ConstructL(); |
|
926 * static CTests* NewL(); |
|
927 * |
|
928 * // from MHWRMLightObserver |
|
929 * virtual void LightStatusChanged(TInt aTarget, |
|
930 * CHWRMLight::TLightStatus aStatus); |
|
931 * |
|
932 * private: |
|
933 * CHWRMLight* iLight; |
|
934 * }; |
|
935 * |
|
936 * @endcode |
|
937 * |
|
938 * A callback method implementation example: |
|
939 * |
|
940 * @code |
|
941 * void CTests::LightStatusChanged(TInt aTarget, |
|
942 * CHWRMLight::TLightStatus aStatus) |
|
943 * { |
|
944 * RDebug::Print(_L("### Light state changed for target: 0x%x"), aTarget); |
|
945 * switch ( aStatus ) |
|
946 * { |
|
947 * case CHWRMLight::ELightOn: |
|
948 * RDebug::Print(_L("### Light state changed: ELightOn")); |
|
949 * break; |
|
950 * case CHWRMLight::ELightOff: |
|
951 * RDebug::Print(_L("### Light state changed: ELightOff")); |
|
952 * break; |
|
953 * case CHWRMLight::ELightBlink: |
|
954 * RDebug::Print(_L("### Light state changed: ELightBlink")); |
|
955 * break; |
|
956 * case CHWRMLight::ELightStatusUnknown: |
|
957 * RDebug::Print(_L("### Light state changed: ELightStatusUnknown")); |
|
958 * break; |
|
959 * default: |
|
960 * RDebug::Print(_L("### Light state changed: UNDEFINED !")); |
|
961 * break; |
|
962 * } |
|
963 * } |
|
964 * |
|
965 * @endcode |
|
966 * |
|
967 * @publishedAll |
|
968 * @released |
|
969 */ |
|
970 class MHWRMLightObserver |
|
971 { |
|
972 public: |
|
973 |
|
974 /** |
|
975 * Called when the device light status changes. |
|
976 * Note that if the light status for certain target changes |
|
977 * very rapidly, some state transitions might be missed. |
|
978 * It is however guaranteed that latest state is always obtained. |
|
979 * |
|
980 * @param aTarget Indicates target(s) the new status applies to. |
|
981 * @param aStatus Indicates light request status. |
|
982 * |
|
983 * @see CHWRMLight::TLightTarget |
|
984 * @see CHWRMLight::TLightStatus |
|
985 */ |
|
986 virtual void LightStatusChanged(TInt aTarget, |
|
987 CHWRMLight::TLightStatus aStatus) = 0; |
|
988 }; |
|
989 |
|
990 |
|
991 #endif // HWRMLIGHT_H |
|
992 |
|
993 // End of File |