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