#include <HWRMLight.h>
Link against:
hwrmlightclient.lib
class CHWRMLight : public CBase;
Description
The class used to control the device lights.
The HW Resource Manager Light API is a library API providing the ability to control the various light targets of the device.
The API provides also methods to retrieve the current light status and the supported light targets of the device. The API
is meant for all applications which need to control lights of the device.
Type of the HW Resource Manager Light API is a synchronous method call meaning the method call will block the client application.
Every new call of the light API method stops all ongoing light control orders. Light state after duration based orders expire
is the state specified by the last non-duration based order.
The API consist of the classes CHWRMLight and MHWRMLightObserver
. If the client requires up-to-date status information, it should also provide callback pointer of the MHWRMLightObserver
implementing class for the NewL-method.
Usage:
#include <HWRMLight.h>
// A CHWRMLight instance can be created by using NewL() or NewLC() methods.
// Up-to-date status information not required, no callbacks.
CHWRMLight* light = CHWRMLight::NewL();
// After this, lights can be directly controlled via the provided class methods.
light-> LightOnL (EPrimaryDisplay, 5000); // Turn display lights on for five seconds.
light->LightOffL(EPrimaryDisplay); // Turn display lights off indefinitely.
// To clean up, delete the created object:
delete light;
Derivation
CBase
-
Base class for all classes to be instantiated on the heap.
CHWRMLight
- The class used to control the device lights.
Members
Defined in CHWRMLight
:
ECustomTarget1
Device specific custom target 1.
ECustomTarget2
Device specific custom target 2.
ECustomTarget3
Device specific custom target 3.
ECustomTarget4
Device specific custom target 4.
ELightBlink
Light state switch to light blinking.
ELightOff
Light state switch to light off.
ELightOn
Light state switch to light on.
ELightStatusUnknown
For debugging/development and signaling an error conditions.
ENoTarget
No target. Not a valid target value, used only for error checking.
EPrimaryDisplay
Primary display of the device.
EPrimaryDisplayAndKeyboard
Both primary display and the primary keyboard of the device.
EPrimaryKeyboard
Primary keyboard of the device.
ESecondaryDisplay
Secondary display of the device.
ESecondaryDisplayAndKeyboard
Both secondary display and the secondary keyboard of the device.
ESecondaryKeyboard
Secondary keyboard of the device.
ESystemTarget
Special target used to control all currently available system lights.
LightBlinkL(TInt)
The LightBlinkL method blinks the target light(s) of the device for infinite dur...
LightBlinkL(TInt,TInt)
The LightBlinkL method blinks the target light(s) of the device for specified du...
LightBlinkL(TInt,TInt,TInt,TInt,TInt)
The LightBlinkL method blinks the target light(s) of the device for specified du...
LightOffL(TInt)
The LightOffL method switches the device light off for the specified target for ...
LightOffL(TInt,TInt)
The LightOffL method switches the device light off for the specified target for ...
LightOffL(TInt,TInt,TBool)
The LightOffL method switches the device light off for the specified target for ...
LightOnL(TInt)
The LightOnL method switches the specified target light on for infinite duration...
LightOnL(TInt,TInt)
The LightOnL method switches the specified target light on for the specified dur...
LightOnL(TInt,TInt,TInt,TBool)
The LightOnL method switches the specified target light on for the specified dur...
LightStatus(TInt)const
This method retrieves the current light status.
NewL()
Two-phased constructor.
NewL(MHWRMLightObserver *)
Two-phased constructor. Use this method for creating a Light client with callbac...
NewLC()
Two-phased constructor. Leaves instance to cleanup stack.
NewLC(MHWRMLightObserver *)
Two-phased constructor. Use this method for creating a Light client with callbac...
ReleaseLight(TInt)
Releases light target if it was previously reserved for this client. If this cli...
ReserveLightL(TInt)
Reserves light target exclusively for this client. A higher priority client may ...
ReserveLightL(TInt,TBool,TBool)
Reserves light target exclusively for this client. A higher priority client may ...
SupportedTargets()const
This method retrieves the supported light targets of the device. Any attempt to ...
TLightStatus
Possible light states that can be get for the different light targets
TLightTarget
Possible light targets. Targets can be used as bitmask. Some common masks are pr...
~CHWRMLight()
Destructor
Inherited from CBase
:
Construction and destruction
IMPORT_C static CHWRMLight* NewL();
Description
Two-phased constructor.
Return value
CHWRMLight *
|
A pointer to a new instance of the CHWRMLight class.
|
|
Leave codes
KErrNotSupported |
Device doesn't support Light feature.
|
KErrNoMemory |
There is a memory allocation failure.
|
|
IMPORT_C static CHWRMLight* NewLC();
Description
Two-phased constructor. Leaves instance to cleanup stack.
Return value
CHWRMLight *
|
A pointer to a new instance of the CHWRMLight class.
|
|
Leave codes
KErrNotSupported |
Device doesn't support Light feature.
|
KErrNoMemory |
There is a memory allocation failure.
|
|
NewL(MHWRMLightObserver *)
IMPORT_C static CHWRMLight* NewL(MHWRMLightObserver *aCallback);
Description
Two-phased constructor. Use this method for creating a Light client with callbacks.
Parameters
MHWRMLightObserver *aCallback |
Pointer to the callback instance.
|
|
Return value
CHWRMLight *
|
A pointer to a new instance of the CHWRMLight class.
|
|
Leave codes
KErrNotSupported |
Device doesn't support Light feature.
|
KErrNoMemory |
There is a memory allocation failure.
|
|
NewLC(MHWRMLightObserver *)
IMPORT_C static CHWRMLight* NewLC(MHWRMLightObserver *aCallback);
Description
Two-phased constructor. Use this method for creating a Light client with callbacks. Leaves instance to cleanup stack.
Parameters
MHWRMLightObserver *aCallback |
Pointer to the callback instance
|
|
Return value
CHWRMLight *
|
A pointer to a new instance of the CHWRMLight class.
|
|
Leave codes
KErrNotSupported |
Device doesn't support Light feature.
|
KErrNoMemory |
There is a memory allocation failure.
|
|
IMPORT_C ~CHWRMLight();
Description
Destructor
virtual void ReserveLightL(TInt aTarget);
Description
Reserves light target exclusively for this client. A higher priority client may cause lower priority client reservation to
be temporarily suspended. Commands can still be issued in suspended state, but they will not be acted upon unless suspension
is lifted within specified duration. The suspended client will not get any notification about suspension. If light target
is already reserved by a higher or equal priority application, reserving will still succeeds, but reservation is immediately
suspended.
Calling this method is equal to calling ReserveLightL( aTarget, EFalse, EFalse), i.e. any previously frozen state will not
be restored and CCoeEnv
background/foreground status is always used to control further reservations.
Parameters
TInt aTarget |
Defines which light should be reserved. Multiple lights can be specified with using bitwise-or.
|
|
Leave codes
KErrNotSupported |
One or more of specified targets are not supported.
|
KErrAccessDenied |
No CCoeEnv present.
|
KErrNotReady |
Trying to reserve while on background.
|
KErrNoMemory |
There is a memory allocation failure.
|
|
See also:
ReserveLightL(TInt,TBool,TBool)
virtual void ReserveLightL(TInt aTarget, TBool aRestoreState, TBool aForceNoCCoeEnv);
Description
Reserves light target exclusively for this client. A higher priority client may cause lower priority client reservation to
be temporarily suspended. Commands can still be issued in suspended state, but they will not be acted upon unless suspension
is lifted within specified duration. The suspended client will not get any notification about suspension. If light target
is already reserved by a higher or equal priority application, reserving will still succeeds, but reservation is immediately
suspended.
Parameters
TInt aTarget |
Defines which light should be reserved. Multiple lights can be specified with using bitwise-or.
|
TBool aRestoreState |
If ETrue, the state frozen on last release will be restored upon successful reservation. I.e. if light was blinking when it
was released by this client the last time, it would start blinking again upon successful reservation. For the first reservation
of each session this parameter is always considered EFalse regardless of what is supplied, as there is no previous frozen
state to restore.
|
TBool aForceNoCCoeEnv |
If EFalse, then reservation requires that this client is on the foreground at the time of reservation and light target will
be automatically released and re-reserved based on background/foreground status of the this client. This also implies that
CCoeEnv::Static() != NULL is required. If ETrue, the client will not require CCoeEnv to be present nor does it automatically reserve/release light by depending on foreground/background status of the client.
Only trusted clients are allowed to set this flag to ETrue. A client is considered trusted if it has nonstandard priority
defined in the internal lights policy of the HW Resource Manager. A client can be defined trusted only by a product.
|
|
Leave codes
KErrNotSupported |
One or more of specified targets are not supported.
|
KErrAccessDenied |
Paramenter aForceNoCCoeEnv is ETrue and client is not trusted.
|
KErrBadHandle |
Parameter ForceNoCCoeEnv is EFalse and no CCoeEnv present.
|
KErrNotReady |
Trying to reserve while on background and parameter aForceNoCCoeEnv is EFalse.
|
KErrNoMemory |
There is a memory allocation failure.
|
|
See also:
virtual void ReleaseLight(TInt aTarget);
Description
Releases light target if it was previously reserved for this client. If this client has not reserved any of the specified
lights, this method does nothing. Any reserved light targets that are released and have no other suspended clients will be
reset to default state, which is either lights on or lights off, depending on system inactivity time.
Parameters
TInt aTarget |
Defines which light should be released. Multiple lights can be specified with using bitwise-or.
|
|
See also:
virtual void LightOnL(TInt aTarget);
Description
The LightOnL method switches the specified target light on for infinite duration using default intensity. Lights will use
fade-in.
Calling this method is equal to calling LightOnL(aTarget, KHWRMInfiniteDuration, KHWRMDefaultIntensity, ETrue).
Parameters
TInt aTarget |
Defines which light should be controlled. Multiple lights can be specified with using bitwise-or.
|
|
Leave codes
KErrNotSupported |
One or more of specified targets are not supported.
|
KErrBadHandle |
Light session has been invalidated.
|
KErrTimedOut |
Timeout occurred in controlling light.
|
KErrInUse |
One or more of specified targets are not reserved for this client but are reserved for others.
|
KErrNoMemory |
There is a memory allocation failure.
|
KErrGeneral |
There is a hardware error.
|
|
See also:
virtual void LightOnL(TInt aTarget, TInt aDuration);
Description
The LightOnL method switches the specified target light on for the specified duration using default intensity. Lights will
use fade-in.
Calling this method is equal to call LightOnL(aTarget, aDuration, KHWRMDefaultIntensity, ETrue).
Parameters
TInt aTarget |
Defines which light should be controlled. Multiple lights can be specified with using bitwise-or.
|
TInt aDuration |
Duration of the time the light is switched on measured in milliseconds. After the duration expires, the light state for target
will be changed to whatever state was caused by the last infinite time duration call, or default state determined by inactivity
timer, in case there has not been a previous infinite time duration call in this session. If the aDuration time is KHWRMInfiniteDuration
then it means an infinite value that has to be stopped by calling of any of the other ' light control methods. Duration can
have maximum value of KHWRMLightMaxDuration.
|
|
Leave codes
KErrArgument |
Parameter aDuration is out of range.
|
KErrNotSupported |
One or more of specified targets are not supported.
|
KErrBadHandle |
Light session has been invalidated.
|
KErrTimedOut |
Timeout occurred in controlling light.
|
KErrInUse |
One or more of specified targets are not reserved for this client but are reserved for others.
|
KErrNoMemory |
There is a memory allocation failure.
|
KErrGeneral |
There is a hardware error.
|
|
See also:
LightOnL(TInt,TInt,TInt,TBool)
virtual void LightOnL(TInt aTarget, TInt aDuration, TInt aIntensity, TBool aFadeIn);
Description
The LightOnL method switches the specified target light on for the specified duration using specified intensity. Fade-in can
also be controlled.
Parameters
TInt aTarget |
Defines which light should be controlled. Multiple lights can be specified with using bitwise-or.
|
TInt aDuration |
Duration of the time the light is switched on measured in milliseconds. After the duration expires, the light state for target
will be changed to whatever state was caused by the last infinite time duration call, or default state determined by inactivity
timer, in case there has not been a previous infinite time duration call in this session. If the aDuration time is KHWRMInfiniteDuration
then it means an infinite value that has to be stopped by calling of any of the other light control methods. Duration can
have maximum value of KHWRMLightMaxDuration.
|
TInt aIntensity |
Intensity of the light. If aIntensity is KHWRMDefaultIntensity, device default intensity will be used. Note: All devices might
not support user defined intensity, in which case device will behave in its default fashion.
|
TBool aFadeIn |
If ETrue, lights will not turn on instantly but instead smoothly fade-in. Note: All devices will not support fade-in, in which
case device will behave in its default fashion.
|
|
Leave codes
KErrArgument |
One of the parameters is out of range.
|
KErrNotSupported |
One or more of specified targets are not supported.
|
KErrBadHandle |
Light session has been invalidated.
|
KErrTimedOut |
Timeout occurred in controlling light.
|
KErrInUse |
One or more of specified targets are not reserved for this client but are reserved for others.
|
KErrNoMemory |
There is a memory allocation failure.
|
KErrGeneral |
There is a hardware error.
|
|
See also:
virtual void LightBlinkL(TInt aTarget);
Description
The LightBlinkL method blinks the target light(s) of the device for infinite duration using default intensity.
Calling this method is equal to call
LightBlinkL(aTarget, KHWRMInfiniteDuration, KHWRMDefaultCycleTime,
KHWRMDefaultCycleTime, KHWRMDefaultIntensity).
Parameters
TInt aTarget |
Defines which light should be controlled. Multiple lights can be specified with using bitwise-or.
|
|
Leave codes
KErrNotSupported |
One or more of specified targets are not supported.
|
KErrBadHandle |
Light session has been invalidated.
|
KErrTimedOut |
Timeout occurred in controlling light.
|
KErrInUse |
One or more of specified targets are not reserved for this client but are reserved for others.
|
KErrNoMemory |
There is a memory allocation failure.
|
KErrGeneral |
There is a hardware error.
|
|
See also:
virtual void LightBlinkL(TInt aTarget, TInt aDuration);
Description
The LightBlinkL method blinks the target light(s) of the device for specified duration using default intensity.
Calling this method is equal to calling LightBlinkL(aTarget, aDuration, KHWRMDefaultCycleTime, KHWRMDefaultCycleTime, KHWRMDefaultIntensity).
Parameters
TInt aTarget |
Defines which light should be controlled. Multiple lights can be specified with using bitwise-or.
|
TInt aDuration |
Duration of the time the light is set to blink measured in milliseconds. After the duration expires, the light state for target
will be changed to whatever state was caused by the last infinite time duration call, or default state determined by inactivity
timer, in case there has not been a previous infinite time duration call in this session. If the aTotalDuration time is KHWRMInfiniteDuration
then it means an infinite value that has to be stopped by calling of any of the other light control methods. Duration can
have maximum value of KHWRMLightMaxDuration.
|
|
Leave codes
KErrArgument |
Parameter aDuration is out of range.
|
KErrNotSupported |
One or more of specified targets are not supported.
|
KErrBadHandle |
Light session has been invalidated.
|
KErrTimedOut |
Timeout occurred in controlling light.
|
KErrInUse |
One or more of specified targets are not reserved for this client but are reserved for others.
|
KErrNoMemory |
There is a memory allocation failure.
|
KErrGeneral |
There is a hardware error.
|
|
See also:
LightBlinkL(TInt,TInt,TInt,TInt,TInt)
virtual void LightBlinkL(TInt aTarget, TInt aDuration, TInt aOnDuration, TInt aOffDuration, TInt aIntensity);
Description
The LightBlinkL method blinks the target light(s) of the device for specified duration using specified intensity. On- and
Off-cycle times of the blinking can also be controlled.
Parameters
TInt aTarget |
Defines which light should be controlled. Multiple lights can be specified with using bitwise-or.
|
TInt aDuration |
Duration of the time the light is set to blink measured in milliseconds. After the duration expires, the light state for target
will be changed to whatever state was caused by the last infinite time duration call, or default state determined by inactivity
timer, in case there has not been a previous infinite time duration call in this session. If the aTotalDuration time is KHWRMInfiniteDuration
then it means an infinite value that has to be stopped by calling of any of the other light control methods. Duration can
have maximum value of KHWRMLightMaxDuration.
|
TInt aOnDuration |
Duration time, measured in milliseconds, of how long the Light is switched on in every Blink cycle. Duration can have maximum
value of KHWRMLightMaxDuration. For device default cycle duration, use value KHWRMDefaultCycleTime. If either of aOnDuration
or aOffDuration is KHWRMDefaultCycleTime, both must be KHWRMDefaultCycleTime. Some devices might not support variable blink
cycle times, in which case default value will be substituted.
|
TInt aOffDuration |
Duration time, measured in milliseconds, of how long the Light is switched off in every Blink cycle. Duration can have maximum
value of KHWRMLightMaxDuration. For device default cycle duration, use value KHWRMDefaultCycleTime. If either of aOnDuration
or aOffDuration is KHWRMDefaultCycleTime, both must be KHWRMDefaultCycleTime. Some devices might not support variable blink
cycle times, in which case default value will be substituted.
|
TInt aIntensity |
Intensity of the light. If aIntensity is KHWRMDefaultIntensity, device default intensity will be used. Note: All devices might
not support user defined intensity, in which case device will behave in its default fashion.
|
|
Leave codes
KErrArgument |
One of the parameters is out of range or otherwise invalid.
|
KErrNotSupported |
One or more of specified targets are not supported.
|
KErrBadHandle |
Light session has been invalidated.
|
KErrTimedOut |
Timeout occurred in controlling light.
|
KErrInUse |
One or more of specified targets are not reserved for this client but are reserved for others.
|
KErrNoMemory |
There is a memory allocation failure.
|
KErrGeneral |
There is a hardware error.
|
|
See also:
virtual void LightOffL(TInt aTarget);
Description
The LightOffL method switches the device light off for the specified target for infinite duration. Lights will be switched
off with fade-out.
Calling this method is equal to call LightOffL(aTarget, KHWRMInfiniteDuration, ETrue).
Parameters
TInt aTarget |
Defines which light should be controlled. Multiple lights can be specified with using bitwise-or.
|
|
Leave codes
KErrNotSupported |
One or more of specified targets are not supported.
|
KErrBadHandle |
Light session has been invalidated.
|
KErrTimedOut |
Timeout occurred in controlling light.
|
KErrInUse |
One or more of specified targets are not reserved for this client but are reserved for others.
|
KErrNoMemory |
There is a memory allocation failure.
|
KErrGeneral |
There is a hardware error.
|
|
See also:
virtual void LightOffL(TInt aTarget, TInt aDuration);
Description
The LightOffL method switches the device light off for the specified target for the specified duration time. Lights will be
switched off with fade-out.
Calling this method is equal to call LightOffL(aTarget, aDuration, ETrue).
Parameters
TInt aTarget |
Defines which light should be controlled. Multiple lights can be specified with using bitwise-or.
|
TInt aDuration |
Duration of the time the light is switched off measured in milliseconds. After the duration expires, the light state for target
will be changed to whatever state was caused by the last infinite time duration call, or default state determined by inactivity
timer, in case there has not been a previous infinite time duration call in this session. If the aDuration time is KHWRMInfiniteDuration
then it means an infinite value that has to be stopped by calling of any of the other light control methods. Duration can
have maximum value of KHWRMLightMaxDuration.
|
|
Leave codes
KErrArgument |
Parameter aDuration is out of range.
|
KErrNotSupported |
One or more of specified targets are not supported.
|
KErrBadHandle |
Light session has been invalidated.
|
KErrTimedOut |
Timeout occurred in controlling light.
|
KErrInUse |
One or more of specified targets are not reserved for this client but are reserved for others.
|
KErrNoMemory |
There is a memory allocation failure.
|
KErrGeneral |
There is a hardware error.
|
|
See also:
LightOffL(TInt,TInt,TBool)
virtual void LightOffL(TInt aTarget, TInt aDuration, TBool aFadeOut);
Description
The LightOffL method switches the device light off for the specified target for the specified duration time. Lights fade-out
can also be controlled.
Parameters
TInt aTarget |
Defines which light should be controlled. Multiple lights can be specified with using bitwise-or.
|
TInt aDuration |
Duration of the time the light is switched off measured in milliseconds. After the duration expires, the light state for target
will be changed to whatever state was caused by the last infinite time duration call, or default state determined by inactivity
timer, in case there has not been a previous infinite time duration call in this session. If the aDuration time is KHWRMInfiniteDuration
then it means an infinite value that has to be stopped by calling of any of the other light control methods. Duration can
have maximum value of KHWRMLightMaxDuration.
|
TBool aFadeOut |
If ETrue, lights will not turn off instantly but instead smoothly fade-out Note: All devices will not support fade-out, in
which case device will behave in its default fashion.
|
|
Leave codes
KErrArgument |
aDuration is out of range.
|
KErrNotSupported |
One or more of specified targets are not supported.
|
KErrBadHandle |
Light session has been invalidated.
|
KErrTimedOut |
Timeout occurred in controlling light.
|
KErrInUse |
One or more of specified targets are not reserved for this client but are reserved for others.
|
KErrNoMemory |
There is a memory allocation failure.
|
KErrGeneral |
There is a hardware error.
|
|
See also:
virtual TLightStatus LightStatus(TInt aTarget) const;
Description
This method retrieves the current light status.
Parameters
TInt aTarget |
Defines which light status is returned. This method only supports single target, as different targets might have different
statuses.
|
|
Return value
See also:
virtual TInt SupportedTargets() const;
Description
This method retrieves the supported light targets of the device. Any attempt to use or reserve unsupported targets will fail
with KErrNotSupported.
Return value
TInt
|
Bitmask containing supported light targets.
|
|
See also:
TLightStatus
Description
Possible light states that can be get for the different light targets
TLightTarget
Description
Possible light targets. Targets can be used as bitmask. Some common masks are provided as enum.
Note that all targets are not supported by all devices. Attempting to use unsupported target will result in KErrNotSupported.
At least one target must be defined.
ENoTarget |
No target. Not a valid target value, used only for error checking.
|
EPrimaryDisplay |
Primary display of the device.
|
EPrimaryKeyboard |
Primary keyboard of the device.
|
EPrimaryDisplayAndKeyboard |
Both primary display and the primary keyboard of the device.
|
ESecondaryDisplay |
Secondary display of the device.
|
ESecondaryKeyboard |
Secondary keyboard of the device.
|
ESecondaryDisplayAndKeyboard |
Both secondary display and the secondary keyboard of the device.
|
ECustomTarget1 |
Device specific custom target 1.
|
ECustomTarget2 |
Device specific custom target 2.
|
ECustomTarget3 |
Device specific custom target 3.
|
ECustomTarget4 |
Device specific custom target 4.
|
ESystemTarget |
Special target used to control all currently available system lights.
System lights normally include all displays and keyboards, but not custom lights. This is however device dependent.
A target mask including this target is always changed to a device state specific target mask. Note that the system target
with any other target is not supported.
This target is always supported but it is never included in supported targets mask.
|
|