1.1 --- a/epoc32/include/hwrmlight.h Tue Nov 24 13:55:44 2009 +0000
1.2 +++ b/epoc32/include/hwrmlight.h Tue Mar 16 16:12:26 2010 +0000
1.3 @@ -1,1 +1,709 @@
1.4 -hwrmlight.h
1.5 +/*
1.6 +* Copyright (c) 2002-2006 Nokia Corporation and/or its subsidiary(-ies).
1.7 +* All rights reserved.
1.8 +* This component and the accompanying materials are made available
1.9 +* 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
1.10 +* which accompanies this distribution, and is available
1.11 +* at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".
1.12 +*
1.13 +* Initial Contributors:
1.14 +* Nokia Corporation - initial contribution.
1.15 +*
1.16 +* Contributors:
1.17 +*
1.18 +* Description: This file contains the header of the
1.19 +* CHWRMLight class.
1.20 +*
1.21 +*/
1.22 +
1.23 +
1.24 +#ifndef HWRMLIGHT_H
1.25 +#define HWRMLIGHT_H
1.26 +
1.27 +// INCLUDES
1.28 +#include <e32base.h>
1.29 +
1.30 +// CONSTANTS
1.31 +
1.32 +/**
1.33 +* Minimum allowed intensity setting for Light.
1.34 +*/
1.35 +const TInt KHWRMLightMinIntensity = 1;
1.36 +
1.37 +/**
1.38 +* Maximum allowed intensity setting for Light.
1.39 +*/
1.40 +const TInt KHWRMLightMaxIntensity = 100;
1.41 +
1.42 +/**
1.43 +* Indicates default intensity in various methods.
1.44 +*/
1.45 +const TInt KHWRMDefaultIntensity = 0;
1.46 +
1.47 +/**
1.48 +* Maximum allowed duration value.
1.49 +*/
1.50 +const TInt KHWRMLightMaxDuration = (KMaxTInt / 1000) - 1;
1.51 +
1.52 +/**
1.53 +* Infinite duration value.
1.54 +*/
1.55 +const TInt KHWRMInfiniteDuration = 0;
1.56 +
1.57 +/**
1.58 +* Indicates device default Blink cycle time.
1.59 +*/
1.60 +const TInt KHWRMDefaultCycleTime = 0;
1.61 +
1.62 +
1.63 +// FORWARD DECLARATIONS
1.64 +class MHWRMLightObserver;
1.65 +
1.66 +// CLASS DECLARATIONS
1.67 +
1.68 +/**
1.69 +* The class used to control the device lights.
1.70 +*
1.71 +* The HW Resource Manager Light API is a library API providing the ability
1.72 +* to control the various light targets of the device. The API provides also
1.73 +* methods to retrieve the current light status and the supported light targets
1.74 +* of the device. The API is meant for all applications which need to control
1.75 +* lights of the device.
1.76 +*
1.77 +* Type of the HW Resource Manager Light API is a synchronous method call meaning
1.78 +* the method call will block the client application. Every new call of the light
1.79 +* API method stops all ongoing light control orders. Light state after duration
1.80 +* based orders expire is the state specified by the last non-duration based order.
1.81 +*
1.82 +* The API consist of the classes CHWRMLight and MHWRMLightObserver. If the client
1.83 +* requires up-to-date status information, it should also provide callback pointer
1.84 +* of the MHWRMLightObserver implementing class for the NewL-method.
1.85 +*
1.86 +* Usage:
1.87 +*
1.88 +* @code
1.89 +* #include <HWRMLight.h> // link against HWRMLightClient.lib
1.90 +*
1.91 +* // A CHWRMLight instance can be created by using NewL() or NewLC() methods.
1.92 +* // Up-to-date status information not required, no callbacks.
1.93 +* CHWRMLight* light = CHWRMLight::NewL();
1.94 +*
1.95 +* // After this, lights can be directly controlled via the provided class methods.
1.96 +* light-> LightOnL (EPrimaryDisplay, 5000); // Turn display lights on for five seconds.
1.97 +* light->LightOffL(EPrimaryDisplay); // Turn display lights off indefinitely.
1.98 +*
1.99 +* // To clean up, delete the created object:
1.100 +* delete light;
1.101 +* @endcode
1.102 +*
1.103 +* @lib HWRMLIGHTCLIENT.DLL
1.104 +* @since S60 3.0
1.105 +*/
1.106 +class CHWRMLight : public CBase
1.107 + {
1.108 + public:
1.109 +
1.110 + /**
1.111 + * Possible light states that can be get for the different light targets
1.112 + */
1.113 + enum TLightStatus
1.114 + {
1.115 + ELightStatusUnknown = 0, ///< For debugging/development and signaling an error conditions.
1.116 + ELightOn, ///< Light state switch to light on.
1.117 + ELightOff, ///< Light state switch to light off.
1.118 + ELightBlink ///< Light state switch to light blinking.
1.119 + };
1.120 +
1.121 + /**
1.122 + * Possible light targets.
1.123 + * Targets can be used as bitmask. Some common masks are provided as enum.
1.124 + *
1.125 + * Note that all targets are not supported by all devices.
1.126 + * Attempting to use unsupported target will result in
1.127 + * KErrNotSupported.
1.128 + *
1.129 + * At least one target must be defined.
1.130 + */
1.131 + enum TLightTarget
1.132 + {
1.133 + ENoTarget = 0x0, ///< No target. Not a valid target value, used only
1.134 + ///< for error checking.
1.135 +
1.136 + EPrimaryDisplay = 0x1, ///< Primary display of the device.
1.137 + EPrimaryKeyboard = 0x2, ///< Primary keyboard of the device.
1.138 + EPrimaryDisplayAndKeyboard = 0x3, ///< Both primary display and the
1.139 + ///< primary keyboard of the device.
1.140 +
1.141 + ESecondaryDisplay = 0x4, ///< Secondary display of the device.
1.142 + ESecondaryKeyboard = 0x8, ///< Secondary keyboard of the device.
1.143 + ESecondaryDisplayAndKeyboard = 0xC, ///< Both secondary display and the
1.144 + ///< secondary keyboard of the device.
1.145 +
1.146 + ECustomTarget1 = 0x10, ///< Device specific custom target 1.
1.147 + ECustomTarget2 = 0x20, ///< Device specific custom target 2.
1.148 + ECustomTarget3 = 0x40, ///< Device specific custom target 3.
1.149 + ECustomTarget4 = 0x80, ///< Device specific custom target 4.
1.150 +
1.151 + /**
1.152 + * Special target used to control all currently available system lights.
1.153 + *
1.154 + * System lights normally include all displays and keyboards,
1.155 + * but not custom lights. This is however device dependent.
1.156 + *
1.157 + * A target mask including this target is
1.158 + * always changed to a device state specific target mask.
1.159 + * Note that the system target with any other target is not supported.
1.160 + *
1.161 + * This target is always supported but it is never
1.162 + * included in supported targets mask.
1.163 + *
1.164 + * @see CHWRMLight::SupportedTargets()
1.165 + */
1.166 + ESystemTarget = 0x80000000
1.167 + };
1.168 +
1.169 + public: // Constructors
1.170 +
1.171 + /**
1.172 + * Two-phased constructor.
1.173 + *
1.174 + * @return A pointer to a new instance of the CHWRMLight class.
1.175 + *
1.176 + * @leave KErrNotSupported Device doesn't support Light feature.
1.177 + * @leave KErrNoMemory There is a memory allocation failure.
1.178 + */
1.179 + IMPORT_C static CHWRMLight* NewL();
1.180 +
1.181 + /**
1.182 + * Two-phased constructor.
1.183 + * Leaves instance to cleanup stack.
1.184 + *
1.185 + * @return A pointer to a new instance of the CHWRMLight class.
1.186 + *
1.187 + * @leave KErrNotSupported Device doesn't support Light feature.
1.188 + * @leave KErrNoMemory There is a memory allocation failure.
1.189 + */
1.190 + IMPORT_C static CHWRMLight* NewLC();
1.191 +
1.192 + /**
1.193 + * Two-phased constructor.
1.194 + * Use this method for creating a Light client with callbacks.
1.195 + *
1.196 + * @param aCallback Pointer to the callback instance.
1.197 + * @return A pointer to a new instance of the CHWRMLight class.
1.198 + *
1.199 + * @leave KErrNotSupported Device doesn't support Light feature.
1.200 + * @leave KErrNoMemory There is a memory allocation failure.
1.201 + */
1.202 + IMPORT_C static CHWRMLight* NewL(MHWRMLightObserver* aCallback);
1.203 +
1.204 + /**
1.205 + * Two-phased constructor.
1.206 + * Use this method for creating a Light client with callbacks.
1.207 + * Leaves instance to cleanup stack.
1.208 + *
1.209 + * @param aCallback Pointer to the callback instance
1.210 + * @return A pointer to a new instance of the CHWRMLight class.
1.211 + *
1.212 + * @leave KErrNotSupported Device doesn't support Light feature.
1.213 + * @leave KErrNoMemory There is a memory allocation failure.
1.214 + */
1.215 + IMPORT_C static CHWRMLight* NewLC(MHWRMLightObserver* aCallback);
1.216 +
1.217 + public: // New functions
1.218 +
1.219 +
1.220 + /**
1.221 + * Reserves light target exclusively for this client.
1.222 + * A higher priority client may cause lower priority client reservation
1.223 + * to be temporarily suspended. Commands can still be issued in suspended
1.224 + * state, but they will not be acted upon unless suspension is lifted
1.225 + * within specified duration.
1.226 + * The suspended client will not get any notification about suspension.
1.227 + * If light target is already reserved by a higher or equal priority application,
1.228 + * reserving will still succeeds, but reservation is immediately suspended.
1.229 + *
1.230 + * Calling this method is equal to calling ReserveLightL( aTarget, EFalse, EFalse),
1.231 + * i.e. any previously frozen state will not be restored and CCoeEnv
1.232 + * background/foreground status is always used to control further reservations.
1.233 + *
1.234 + * @param aTarget Defines which light should be reserved. Multiple lights can
1.235 + * be specified with using bitwise-or.
1.236 + *
1.237 + * @leave KErrNotSupported One or more of specified targets are not supported.
1.238 + * @leave KErrAccessDenied No CCoeEnv present.
1.239 + * @leave KErrNotReady Trying to reserve while on background.
1.240 + * @leave KErrNoMemory There is a memory allocation failure.
1.241 + *
1.242 + * @see TLightTarget
1.243 + */
1.244 + virtual void ReserveLightL(TInt aTarget)=0;
1.245 +
1.246 + /**
1.247 + * Reserves light target exclusively for this client.
1.248 + * A higher priority client may cause lower priority client reservation
1.249 + * to be temporarily suspended. Commands can still be issued in suspended
1.250 + * state, but they will not be acted upon unless suspension is lifted
1.251 + * within specified duration.
1.252 + * The suspended client will not get any notification about suspension.
1.253 + * If light target is already reserved by a higher or equal priority application,
1.254 + * reserving will still succeeds, but reservation is immediately suspended.
1.255 + *
1.256 + *
1.257 + * @param aTarget Defines which light should be reserved. Multiple lights can
1.258 + * be specified with using bitwise-or.
1.259 + * @param aRestoreState If ETrue, the state frozen on last release will be
1.260 + * restored upon successful reservation.
1.261 + * I.e. if light was blinking when it was released by this
1.262 + * client the last time, it would start blinking again upon
1.263 + * successful reservation.
1.264 + * For the first reservation of each session this parameter
1.265 + * is always considered EFalse regardless of what is supplied,
1.266 + * as there is no previous frozen state to restore.
1.267 + * @param aForceNoCCoeEnv If EFalse, then reservation requires that this client is
1.268 + * on the foreground at the time of reservation and light
1.269 + * target will be automatically released and re-reserved based
1.270 + * on background/foreground status of the this client. This
1.271 + * also implies that CCoeEnv::Static() != NULL is required.
1.272 + * If ETrue, the client will not require CCoeEnv to be present
1.273 + * nor does it automatically reserve/release light by depending
1.274 + * on foreground/background status of the client.
1.275 + * Only trusted clients are allowed to set this flag to ETrue.
1.276 + * A client is considered trusted if it has nonstandard
1.277 + * priority defined in the internal lights policy of the
1.278 + * HW Resource Manager. A client can be defined trusted
1.279 + * only by S60 or a product.
1.280 + *
1.281 + * @leave KErrNotSupported One or more of specified targets are not supported.
1.282 + * @leave KErrAccessDenied Paramenter aForceNoCCoeEnv is ETrue and client is not trusted.
1.283 + * @leave KErrBadHandle Parameter ForceNoCCoeEnv is EFalse and no CCoeEnv present.
1.284 + * @leave KErrNotReady Trying to reserve while on background and parameter
1.285 + * aForceNoCCoeEnv is EFalse.
1.286 + * @leave KErrNoMemory There is a memory allocation failure.
1.287 + *
1.288 + * @see TLightTarget
1.289 + */
1.290 + virtual void ReserveLightL(TInt aTarget, TBool aRestoreState, TBool aForceNoCCoeEnv)=0;
1.291 +
1.292 + /**
1.293 + * Releases light target if it was previously reserved for this client.
1.294 + * If this client has not reserved any of the specified lights,
1.295 + * this method does nothing.
1.296 + * Any reserved light targets that are released and have no other suspended
1.297 + * clients will be reset to default state, which is either lights on or lights off,
1.298 + * depending on system inactivity time.
1.299 + *
1.300 + * @param aTarget Defines which light should be released. Multiple lights can
1.301 + * be specified with using bitwise-or.
1.302 + *
1.303 + * @see TLightTarget
1.304 + */
1.305 + virtual void ReleaseLight(TInt aTarget)=0;
1.306 +
1.307 +
1.308 + /**
1.309 + * The LightOnL method switches the specified target light on
1.310 + * for infinite duration using default intensity. Lights will use fade-in.
1.311 + *
1.312 + * Calling this method is equal to calling
1.313 + * LightOnL(aTarget, KHWRMInfiniteDuration, KHWRMDefaultIntensity, ETrue).
1.314 + *
1.315 + * @param aTarget Defines which light should be controlled. Multiple lights can
1.316 + * be specified with using bitwise-or.
1.317 + *
1.318 + * @leave KErrNotSupported One or more of specified targets are not supported.
1.319 + * @leave KErrBadHandle Light session has been invalidated.
1.320 + * @leave KErrTimedOut Timeout occurred in controlling light.
1.321 + * @leave KErrInUse One or more of specified targets are not reserved for
1.322 + * this client but are reserved for others.
1.323 + * @leave KErrNoMemory There is a memory allocation failure.
1.324 + * @leave KErrGeneral There is a hardware error.
1.325 + *
1.326 + * @see TLightTarget
1.327 + */
1.328 + virtual void LightOnL(TInt aTarget) = 0;
1.329 +
1.330 + /**
1.331 + * The LightOnL method switches the specified target light on
1.332 + * for the specified duration using default intensity. Lights will use fade-in.
1.333 + *
1.334 + * Calling this method is equal to call
1.335 + * LightOnL(aTarget, aDuration, KHWRMDefaultIntensity, ETrue).
1.336 + *
1.337 + * @param aTarget Defines which light should be controlled. Multiple lights can
1.338 + * be specified with using bitwise-or.
1.339 + * @param aDuration Duration of the time the light is switched on measured in milliseconds.
1.340 + * After the duration expires, the light state for target will be changed
1.341 + * to whatever state was caused by the last infinite time duration call, or
1.342 + * default state determined by inactivity timer, in case there has not
1.343 + * been a previous infinite time duration call in this session.
1.344 + * If the aDuration time is KHWRMInfiniteDuration then it means an
1.345 + * infinite value that has to be stopped by calling of any of the other
1.346 + ' light control methods.
1.347 + * Duration can have maximum value of KHWRMLightMaxDuration.
1.348 + *
1.349 + * @leave KErrArgument Parameter aDuration is out of range.
1.350 + * @leave KErrNotSupported One or more of specified targets are not supported.
1.351 + * @leave KErrBadHandle Light session has been invalidated.
1.352 + * @leave KErrTimedOut Timeout occurred in controlling light.
1.353 + * @leave KErrInUse One or more of specified targets are not reserved for
1.354 + * this client but are reserved for others.
1.355 + * @leave KErrNoMemory There is a memory allocation failure.
1.356 + * @leave KErrGeneral There is a hardware error.
1.357 + *
1.358 + * @see TLightTarget
1.359 + */
1.360 + virtual void LightOnL(TInt aTarget,
1.361 + TInt aDuration) = 0;
1.362 +
1.363 + /**
1.364 + * The LightOnL method switches the specified target light on
1.365 + * for the specified duration using specified intensity. Fade-in can also be controlled.
1.366 + *
1.367 + * @param aTarget Defines which light should be controlled. Multiple lights can
1.368 + * be specified with using bitwise-or.
1.369 + * @param aDuration Duration of the time the light is switched on measured in milliseconds.
1.370 + * After the duration expires, the light state for target will be changed
1.371 + * to whatever state was caused by the last infinite time duration call, or
1.372 + * default state determined by inactivity timer, in case there has not
1.373 + * been a previous infinite time duration call in this session.
1.374 + * If the aDuration time is KHWRMInfiniteDuration then it means
1.375 + * an infinite value that has to be stopped by calling of any of
1.376 + * the other light control methods.
1.377 + * Duration can have maximum value of KHWRMLightMaxDuration.
1.378 + * @param aIntensity Intensity of the light. If aIntensity is KHWRMDefaultIntensity, device default
1.379 + * intensity will be used.
1.380 + * Note: All devices might not support user defined intensity, in which case
1.381 + * device will behave in its default fashion.
1.382 + * @param aFadeIn If ETrue, lights will not turn on instantly but instead smoothly fade-in.
1.383 + * Note: All devices will not support fade-in, in which case device will
1.384 + * behave in its default fashion.
1.385 + *
1.386 + * @leave KErrArgument One of the parameters is out of range.
1.387 + * @leave KErrNotSupported One or more of specified targets are not supported.
1.388 + * @leave KErrBadHandle Light session has been invalidated.
1.389 + * @leave KErrTimedOut Timeout occurred in controlling light.
1.390 + * @leave KErrInUse One or more of specified targets are not reserved for
1.391 + * this client but are reserved for others.
1.392 + * @leave KErrNoMemory There is a memory allocation failure.
1.393 + * @leave KErrGeneral There is a hardware error.
1.394 + *
1.395 + * @see TLightTarget
1.396 + */
1.397 + virtual void LightOnL(TInt aTarget,
1.398 + TInt aDuration,
1.399 + TInt aIntensity,
1.400 + TBool aFadeIn) = 0;
1.401 +
1.402 + /**
1.403 + * The LightBlinkL method blinks the target light(s) of the device for infinite duration
1.404 + * using default intensity.
1.405 + *
1.406 + * Calling this method is equal to call
1.407 + * LightBlinkL(aTarget, KHWRMInfiniteDuration, KHWRMDefaultCycleTime,
1.408 + * KHWRMDefaultCycleTime, KHWRMDefaultIntensity).
1.409 + *
1.410 + * @param aTarget Defines which light should be controlled. Multiple lights can
1.411 + * be specified with using bitwise-or.
1.412 + *
1.413 + * @leave KErrNotSupported One or more of specified targets are not supported.
1.414 + * @leave KErrBadHandle Light session has been invalidated.
1.415 + * @leave KErrTimedOut Timeout occurred in controlling light.
1.416 + * @leave KErrInUse One or more of specified targets are not reserved for
1.417 + * this client but are reserved for others.
1.418 + * @leave KErrNoMemory There is a memory allocation failure.
1.419 + * @leave KErrGeneral There is a hardware error.
1.420 + *
1.421 + * @see TLightTarget
1.422 + */
1.423 + virtual void LightBlinkL(TInt aTarget) = 0;
1.424 +
1.425 + /**
1.426 + * The LightBlinkL method blinks the target light(s) of the device for specified duration
1.427 + * using default intensity.
1.428 + *
1.429 + * Calling this method is equal to calling
1.430 + * LightBlinkL(aTarget, aDuration, KHWRMDefaultCycleTime,
1.431 + * KHWRMDefaultCycleTime, KHWRMDefaultIntensity).
1.432 + *
1.433 + * @param aTarget Defines which light should be controlled. Multiple lights can
1.434 + * be specified with using bitwise-or.
1.435 + * @param aDuration Duration of the time the light is set to blink measured in milliseconds.
1.436 + * After the duration expires, the light state for target will be changed
1.437 + * to whatever state was caused by the last infinite time duration call, or
1.438 + * default state determined by inactivity timer, in case there has not
1.439 + * been a previous infinite time duration call in this session.
1.440 + * If the aTotalDuration time is KHWRMInfiniteDuration then it
1.441 + * means an infinite value that has to be
1.442 + * stopped by calling of any of the other light control methods.
1.443 + * Duration can have maximum value of KHWRMLightMaxDuration.
1.444 + *
1.445 + * @leave KErrArgument Parameter aDuration is out of range.
1.446 + * @leave KErrNotSupported One or more of specified targets are not supported.
1.447 + * @leave KErrBadHandle Light session has been invalidated.
1.448 + * @leave KErrTimedOut Timeout occurred in controlling light.
1.449 + * @leave KErrInUse One or more of specified targets are not reserved for
1.450 + * this client but are reserved for others.
1.451 + * @leave KErrNoMemory There is a memory allocation failure.
1.452 + * @leave KErrGeneral There is a hardware error.
1.453 + *
1.454 + * @see TLightTarget
1.455 + */
1.456 + virtual void LightBlinkL(TInt aTarget,
1.457 + TInt aDuration) = 0;
1.458 +
1.459 + /**
1.460 + * The LightBlinkL method blinks the target light(s) of the device for specified duration
1.461 + * using specified intensity. On- and Off-cycle times of the blinking can also be controlled.
1.462 + *
1.463 + * @param aTarget Defines which light should be controlled. Multiple lights can
1.464 + * be specified with using bitwise-or.
1.465 + * @param aDuration Duration of the time the light is set to blink measured in milliseconds.
1.466 + * After the duration expires, the light state for target will be changed
1.467 + * to whatever state was caused by the last infinite time duration call, or
1.468 + * default state determined by inactivity timer, in case there has not
1.469 + * been a previous infinite time duration call in this session.
1.470 + * If the aTotalDuration time is KHWRMInfiniteDuration then it
1.471 + * means an infinite value that has to be
1.472 + * stopped by calling of any of the other light control methods.
1.473 + * Duration can have maximum value of KHWRMLightMaxDuration.
1.474 + * @param aOnDuration Duration time, measured in milliseconds, of how long the Light is
1.475 + * switched on in every Blink cycle.
1.476 + * Duration can have maximum value of KHWRMLightMaxDuration.
1.477 + * For device default cycle duration, use value KHWRMDefaultCycleTime.
1.478 + * If either of aOnDuration or aOffDuration is KHWRMDefaultCycleTime,
1.479 + * both must be KHWRMDefaultCycleTime.
1.480 + * Some devices might not support variable blink cycle times, in which
1.481 + * case default value will be substituted.
1.482 + * @param aOffDuration Duration time, measured in milliseconds, of how long the Light
1.483 + * is switched off in every Blink cycle.
1.484 + * Duration can have maximum value of KHWRMLightMaxDuration.
1.485 + * For device default cycle duration, use value KHWRMDefaultCycleTime.
1.486 + * If either of aOnDuration or aOffDuration is KHWRMDefaultCycleTime,
1.487 + * both must be KHWRMDefaultCycleTime.
1.488 + * Some devices might not support variable blink cycle times, in which
1.489 + * case default value will be substituted.
1.490 + * @param aIntensity Intensity of the light. If aIntensity is KHWRMDefaultIntensity, device default
1.491 + * intensity will be used.
1.492 + * Note: All devices might not support user defined intensity, in which case
1.493 + * device will behave in its default fashion.
1.494 + *
1.495 + * @leave KErrArgument One of the parameters is out of range or otherwise invalid.
1.496 + * @leave KErrNotSupported One or more of specified targets are not supported.
1.497 + * @leave KErrBadHandle Light session has been invalidated.
1.498 + * @leave KErrTimedOut Timeout occurred in controlling light.
1.499 + * @leave KErrInUse One or more of specified targets are not reserved for
1.500 + * this client but are reserved for others.
1.501 + * @leave KErrNoMemory There is a memory allocation failure.
1.502 + * @leave KErrGeneral There is a hardware error.
1.503 + *
1.504 + * @see TLightTarget
1.505 + */
1.506 + virtual void LightBlinkL(TInt aTarget,
1.507 + TInt aDuration,
1.508 + TInt aOnDuration,
1.509 + TInt aOffDuration,
1.510 + TInt aIntensity) = 0;
1.511 +
1.512 + /**
1.513 + * The LightOffL method switches the device light off for the specified target for
1.514 + * infinite duration. Lights will be switched off with fade-out.
1.515 + *
1.516 + * Calling this method is equal to call
1.517 + * LightOffL(aTarget, KHWRMInfiniteDuration, ETrue).
1.518 + *
1.519 + * @param aTarget Defines which light should be controlled. Multiple lights can
1.520 + * be specified with using bitwise-or.
1.521 + *
1.522 + * @leave KErrNotSupported One or more of specified targets are not supported.
1.523 + * @leave KErrBadHandle Light session has been invalidated.
1.524 + * @leave KErrTimedOut Timeout occurred in controlling light.
1.525 + * @leave KErrInUse One or more of specified targets are not reserved for
1.526 + * this client but are reserved for others.
1.527 + * @leave KErrNoMemory There is a memory allocation failure.
1.528 + * @leave KErrGeneral There is a hardware error.
1.529 + *
1.530 + * @see TLightTarget
1.531 + */
1.532 + virtual void LightOffL(TInt aTarget) = 0;
1.533 +
1.534 + /**
1.535 + * The LightOffL method switches the device light off for the specified target for
1.536 + * the specified duration time. Lights will be switched off with fade-out.
1.537 + *
1.538 + * Calling this method is equal to call LightOffL(aTarget, aDuration, ETrue).
1.539 + *
1.540 + * @param aTarget Defines which light should be controlled. Multiple lights can
1.541 + * be specified with using bitwise-or.
1.542 + * @param aDuration Duration of the time the light is switched off measured in milliseconds.
1.543 + * After the duration expires, the light state for target will be changed
1.544 + * to whatever state was caused by the last infinite time duration call, or
1.545 + * default state determined by inactivity timer, in case there has not
1.546 + * been a previous infinite time duration call in this session.
1.547 + * If the aDuration time is KHWRMInfiniteDuration then it
1.548 + * means an infinite value that has to be
1.549 + * stopped by calling of any of the other light control methods.
1.550 + * Duration can have maximum value of KHWRMLightMaxDuration.
1.551 + *
1.552 + * @leave KErrArgument Parameter aDuration is out of range.
1.553 + * @leave KErrNotSupported One or more of specified targets are not supported.
1.554 + * @leave KErrBadHandle Light session has been invalidated.
1.555 + * @leave KErrTimedOut Timeout occurred in controlling light.
1.556 + * @leave KErrInUse One or more of specified targets are not reserved for
1.557 + * this client but are reserved for others.
1.558 + * @leave KErrNoMemory There is a memory allocation failure.
1.559 + * @leave KErrGeneral There is a hardware error.
1.560 + *
1.561 + * @see TLightTarget
1.562 + */
1.563 + virtual void LightOffL(TInt aTarget,
1.564 + TInt aDuration) = 0;
1.565 +
1.566 + /**
1.567 + * The LightOffL method switches the device light off for the specified target for
1.568 + * the specified duration time. Lights fade-out can also be controlled.
1.569 + *
1.570 + * @param aTarget Defines which light should be controlled. Multiple lights can
1.571 + * be specified with using bitwise-or.
1.572 + * @param aDuration Duration of the time the light is switched off measured in milliseconds.
1.573 + * After the duration expires, the light state for target will be changed
1.574 + * to whatever state was caused by the last infinite time duration call, or
1.575 + * default state determined by inactivity timer, in case there has not
1.576 + * been a previous infinite time duration call in this session.
1.577 + * If the aDuration time is KHWRMInfiniteDuration then it
1.578 + * means an infinite value that has to be
1.579 + * stopped by calling of any of the other light control methods.
1.580 + * Duration can have maximum value of KHWRMLightMaxDuration.
1.581 + * @param aFadeOut If ETrue, lights will not turn off instantly but instead smoothly fade-out
1.582 + * Note: All devices will not support fade-out, in which case device will
1.583 + * behave in its default fashion.
1.584 + *
1.585 + * @leave KErrArgument aDuration is out of range.
1.586 + * @leave KErrNotSupported One or more of specified targets are not supported.
1.587 + * @leave KErrBadHandle Light session has been invalidated.
1.588 + * @leave KErrTimedOut Timeout occurred in controlling light.
1.589 + * @leave KErrInUse One or more of specified targets are not reserved for
1.590 + * this client but are reserved for others.
1.591 + * @leave KErrNoMemory There is a memory allocation failure.
1.592 + * @leave KErrGeneral There is a hardware error.
1.593 + *
1.594 + * @see TLightTarget
1.595 + */
1.596 + virtual void LightOffL(TInt aTarget,
1.597 + TInt aDuration,
1.598 + TBool aFadeOut) = 0;
1.599 +
1.600 + /**
1.601 + * This method retrieves the current light status.
1.602 + *
1.603 + * @param aTarget Defines which light status is returned.
1.604 + * This method only supports single target, as different
1.605 + * targets might have different statuses.
1.606 + * @return TLightStatus indicating the current light status. If there is a problem or
1.607 + * multiple targets were specified, CHWRMLight::ELightStatusUnknown is returned.
1.608 + *
1.609 + * @see MHWRMLightObserver
1.610 + * @see TLightTarget
1.611 + */
1.612 + virtual TLightStatus LightStatus(TInt aTarget) const = 0;
1.613 +
1.614 + /**
1.615 + * This method retrieves the supported light targets of the device.
1.616 + * Any attempt to use or reserve unsupported targets will fail with
1.617 + * KErrNotSupported.
1.618 + *
1.619 + * @return Bitmask containing supported light targets.
1.620 + *
1.621 + * @see TLightTarget
1.622 + */
1.623 + virtual TInt SupportedTargets() const = 0;
1.624 + };
1.625 +
1.626 +/**
1.627 +* A callback interface for light status reporting.
1.628 +*
1.629 +* If the client requires up-to-date status information, the client needs
1.630 +* to derive a class from the MHWRMlightObserver interface and implement
1.631 +* the LightStatusChanged() method.
1.632 +*
1.633 +* A callback object header example:
1.634 +*
1.635 +* @code
1.636 +* // INCLUDES
1.637 +* #include <HWRMLight.h> // Link against HWRMLightClient.lib.
1.638 +*
1.639 +* class CTests : public CBase,
1.640 +* public MHWRMLightObserver
1.641 +* {
1.642 +* public:
1.643 +* CTests();
1.644 +* ~CTests();
1.645 +*
1.646 +* void ConstructL();
1.647 +* static CTests* NewL();
1.648 +*
1.649 +* // from MHWRMLightObserver
1.650 +* virtual void LightStatusChanged(TInt aTarget,
1.651 +* CHWRMLight::TLightStatus aStatus);
1.652 +*
1.653 +* private:
1.654 +* CHWRMLight* iLight;
1.655 +* };
1.656 +*
1.657 +* @endcode
1.658 +*
1.659 +* A callback method implementation example:
1.660 +*
1.661 +* @code
1.662 +* void CTests::LightStatusChanged(TInt aTarget,
1.663 +* CHWRMLight::TLightStatus aStatus)
1.664 +* {
1.665 +* RDebug::Print(_L("### Light state changed for target: 0x%x"), aTarget);
1.666 +* switch ( aStatus )
1.667 +* {
1.668 +* case CHWRMLight::ELightOn:
1.669 +* RDebug::Print(_L("### Light state changed: ELightOn"));
1.670 +* break;
1.671 +* case CHWRMLight::ELightOff:
1.672 +* RDebug::Print(_L("### Light state changed: ELightOff"));
1.673 +* break;
1.674 +* case CHWRMLight::ELightBlink:
1.675 +* RDebug::Print(_L("### Light state changed: ELightBlink"));
1.676 +* break;
1.677 +* case CHWRMLight::ELightStatusUnknown:
1.678 +* RDebug::Print(_L("### Light state changed: ELightStatusUnknown"));
1.679 +* break;
1.680 +* default:
1.681 +* RDebug::Print(_L("### Light state changed: UNDEFINED !"));
1.682 +* break;
1.683 +* }
1.684 +* }
1.685 +*
1.686 +* @endcode
1.687 +*
1.688 +* @since S60 3.0
1.689 +*/
1.690 +class MHWRMLightObserver
1.691 + {
1.692 + public:
1.693 +
1.694 + /**
1.695 + * Called when the device light status changes.
1.696 + * Note that if the light status for certain target changes
1.697 + * very rapidly, some state transitions might be missed.
1.698 + * It is however guaranteed that latest state is always obtained.
1.699 + *
1.700 + * @param aTarget Indicates target(s) the new status applies to.
1.701 + * @param aStatus Indicates light request status.
1.702 + *
1.703 + * @see CHWRMLight::TLightTarget
1.704 + * @see CHWRMLight::TLightStatus
1.705 + */
1.706 + virtual void LightStatusChanged(TInt aTarget,
1.707 + CHWRMLight::TLightStatus aStatus) = 0;
1.708 + };
1.709 +
1.710 +
1.711 +#endif // HWRMLIGHT_H
1.712 +
1.713 +// End of File