S60 Light API Specification: Using Light API

An instance with notify handling is created if the client requires up-to-date status information. Otherwise an instance without callback pointer is created. After an instance is created, lights can be directly controlled via the provided class methods.

There are three light control methods, each with several overloads: LightOnL() to turn on the lights, LightBlinkL() to make lights blink and LightOffL() to turn lights off.

All control methods need at least a target mask as a parameter. Devices can have multiple independent lights, called targets, such as device primary display light or keyboard light. All devices do not support all possible light targets. Supported targets may be queried with the SupportedTargets() method. Note that some devices may interpret targets to mean different lights depending on hardware configuration of the device, e.g. folding phone with two displays might interpret primary display target differently depending on whether it is folded or not.

All control methods also accept optional duration parameter. If duration is KHWRMInfiniteDuration, the light in question is turned on forever. Any infinite duration call also sets session base light state for targets it affects. This base state is what the target is set to when any duration timer affecting it expires. If there has not been any infinite duration calls for a target session, any timer expiration for that target sets the target to the so called default state, which is either on or off, depending on device inactivity time and the inactivity time limit defined by general settings.

Each target can only have one duration timer, so if a target with ongoing timer is issued new orders, the ongoing timer is cancelled and a new one set.

Example: The primary display light is turned off indefinitely, thus defining its base state. After some time, the primary display light is set to blink for ten seconds. Two seconds after that the primary display light is turned on for five seconds. This overwrites the original ten seconds timer that made the primary display light blink. After the specified five seconds pass, the primary display light is returned to its base state, which is off.

Light intensity can be optionally controlled by the LightOnL() and LightBlinkL() methods. Intensity is controlled as a percentage. KHWRMDefaultIntensity can use default intensity or ambient light sensor controlled intensity, depending on general settings.

Light fade can be optionally controlled by the LightOnL() and LightOffL() methods. Fade simply means that lights are turned on or off over a short period of time with multiple gradual intensity changes instead of single instant change. Note, however, that all devices do not support this functionality.

Current status of any light target can be obtained with the LightStatus() method.

One or more light targets can be reserved to a single instance of CHWRMLight by calling the ReserveLightL() method. When light targets are no longer required exclusively, they must be released with a call to ReleaseLight(). If there is already a reservation active when a reservation from a higher priority client comes, the previously active reservation is suspended, and the new reservation is set as the active one. On the other hand, if there is already a reservation active when a reservation from a same or lower priority client comes, the new reservation is immediately put in suspended mode. Some trusted clients have higher than default priorities.

Light can be controlled without a reservation, if there is no other client with a reservation.

If the client is not trusted, Light API automatically releases the reservation when the client goes to the background, and reserves it again when the client comes back to the foreground. This also implies that untrusted clients can only use Light API where CCoeEnv is available. Trusted clients have an option to disable this autoreservation feature.

The client gets no notifications about whether or not its reservation is suspended, but the control methods can be called normally when the client’s reservation is suspended. In that case only the virtual state of the lights is remembered by the session; actual lights are not controlled. When suspended reservation is activated, the actual lights state is restored to the same as the virtual state.

Use cases

Create an instance used for controlling the lights of the device

A CHWRMLight instance can be created by using NewL() or NewLC() methods. After this, lights can be directly controlled via the provided class methods.

Without notify handling

The user has to create an instance of the CHWRMLight implementation class using the NewL or NewLC constructor without a parameter. The following code snippet demonstrates how to create an instance without notify handling for controlling the lights of the device.

CHWRMLight* light = CHWRMLight::NewLC(); // No callbacks

With notify handling

The client needs to derive a class from the MHWRMLightObserver interface and implement the LightStatusChanged() method. The following code snippet gives an example of the header of the class implemented by the client.

// INCLUDES
#include <HWRMLight.h> // Link against HWRMLightClient.lib.
class CTest : public CBase, 
              public MHWRMLightObserver    
    {
    public:
        CTest();
        ~CTest();
                         
        void ConstructL();
        static CTest* NewL();
                
        // from MHWRMLightObserver
        virtual void LightStatusChanged(TInt aTarget, 
                                        CHWRMLight::TLightStatus aStatus);

    private:
        CHWRMLight* iLight;
    };

The user has to create an instance of the CHWRMLight implementation class using the NewL or NewLC constructor with a parameter. This parameter is a pointer to an object that is derived from MHWRMLightObserver. After this, lights can be directly controlled via the provided class methods. Every light status change causes the notification MHWRMLightObserver::LightStatusChanged(). The following code snippet demonstrates how to create an instance with notify handling for controlling the lights of the device.

void CTest::ConstructL()
    {
    iLight = CHWRMLight::NewL(this)
    }

Retrieve the supported light targets of the device

SupportedTargets() call retrieves the supported light targets of the device. Note that any attempt to use or reserve unsupported targets fails with KErrNotSupported. The following code snippet demonstrates how to retrieve the supported light targets of the device.

// The method returns a bitmask containing supported light targets.
TInt supportedTargets = iLight->SupportedTargets();

Retrieve the current light status

The LightStatus() method retrieves the current light status. This method only supports single target, as different targets might have different statuses. If multiple targets were specified, CHWRMLight::ELightStatusUnknown is returned. The following code snippet demonstrates how to retrieve the current light status.

CHWRMLight::TLightStatus lightStatus = iLight->LightStatus(CHWRMLight::EPrimaryDisplay);

Reserve light target(s)

The ReserveLightL() call reserves the light target(s) exclusively for this client. Multiple lights can be specified by using bitwise-or. A higher priority client may cause lower priority client reservation to be temporarily suspended. Commands can still be issued in suspended state, but they are not acted upon unless suspension is lifted within a specified duration. The suspended client does not get any notification about suspension. If the light target is already reserved by a higher or equal priority application, reserving still succeeds, but the reservation is immediately suspended. The following code snippet demonstrates how to reserve multiple light targets.

// aRestoreState = ETrue means that any previously frozen state will be restored.
// aForceNoCCoeEnv = EFalse means that the CCoeEnv background/foreground status
// is always used to control further reservations.

iLight->ReserveLightL((CHWRMLight::EPrimaryDisplay | CHWRMLight::EPrimaryKeyboard), ETrue, EFalse );

Calling the ReserveLightL() method without second and third parameters is equal to call ReserveLightL(aTarget, EFalse, EFalse), i.e. any previously frozen state is not restored and the CCoeEnv background/foreground status is always used to control further reservations.

Switch light(s) on

The LightOnL() method calls switch the specified target light on. Multiple light targets can be specified by using bitwise-or.

The following code snippet demonstrates how to switch on lights for infinite duration with default intensity for multiple targets. Lights are switched on with fade-in.

iLight->LightOnL(CHWRMLight::EPrimaryDisplay | CHWRMLight::EPrimaryKeyboard);

The following code snippet demonstrates how to switch lights on for the specified duration with default intensity for one target. Lights are switched on with fade-in.

// aDuration = 5000 milliseconds
light->LightOnL(CHWRMLight::ESecondaryDisplay, 5000);

After the duration expires, the light state for target is 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.

The following code snippet demonstrates how to switch on lights for the specified duration with specified intensity for one target. Also fade-in is controlled.

// aDuration = 5000 milliseconds
// aIntensity = 50, intensity can be between KHWRMLightMinIntensity and KHWRMLightMaxIntensity, inclusive.
// aFadeIn = EFalse means that lights will turn on instantly and fade-in is not used,
// ETrue would mean that lights would smoothly fade-in.

light->LightOnL(CHWRMLight::ESecondaryDisplay, 5000, 50, EFalse);

Note: All devices do not support user-defined intensity or fade-in, in which case the device behaves in its default fashion.

Switch light(s) off

The LightOffL() method calls switch the specified target light off. Multiple light targets can be specified by using bitwise-or.

The following code snippet demonstrates how to switch lights off for infinite duration for multiple targets. Lights are switched off with fade-out.

iLight->LightOffL(CHWRMLight::EPrimaryDisplay | CHWRMLight::EPrimaryKeyboard);

The following code snippet demonstrates how to switch off lights for the specified duration for one target. Lights are switched off with fade-out.

// aDuration = 5000 milliseconds
light->LightOffL(CHWRMLight::ESecondaryDisplay, 5000);

After the duration expires, the light state for the target is 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.

The following code snippet demonstrates how to switch lights off for the specified duration for one target. Also fade-out is controlled.

// aDuration = 5000 milliseconds
// aFadeOut = EFalse means that lights turn off instantly and fade-out is not used, 
// ETrue means that lights smoothly fade-out.

light->LightOnL(CHWRMLight::ESecondaryDisplay, 5000, EFalse);

Note: All devices do not support fade-out, in which case the device behaves in its default fashion.

Blink light(s)

The LightBlinkL() method calls make the specified target light to blink. Multiple light targets can be specified by using bitwise-or.

The following code snippet demonstrates how to make lights blink for infinite duration with default intensity for multiple targets.

iLight->LightBlinkL(CHWRMLight::EPrimaryDisplay | CHWRMLight::EPrimaryKeyboard);

The following code snippet demonstrates how to make lights blink for the specified duration with default intensity for one target.

// aDuration = 5000 milliseconds
light->LightOnL(CHWRMLight::ESecondaryDisplay, 5000);

The following code snippet demonstrates how to switch lights on for the specified duration with specified intensity for one target. On- and off-cycle times of the blinking can also be controlled.

// aDuration = 5000 milliseconds
// aOnDuration = 500 milliseconds
// aOffDuration = 500 milliseconds
// aIntensity = 30, intensity can be between KHWRMLightMinIntensity and KHWRMLightMaxIntensity, inclusive.

light->LightOnL(CHWRMLight::ESecondaryDisplay, 5000, 500, 500, 30);

For device default cycle duration, use the value KHWRMDefaultCycleTime. If either of aOnDuration or aOffDuration is KHWRMDefaultCycleTime, both must be KHWRMDefaultCycleTime.

Note: Some devices may not support variable blink cycle times, in which case default value is substituted. All devices may not support user-defined intensity, in which case the device behaves in its default fashion.

Release the reserved light target(s)

The ReleaseLight() call releases the light target if it was previously reserved for this client. Multiple lights can be specified by using bitwise-or. 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 are reset to default state, which is either lights on or lights off, depending on system inactivity time. The following code snippet demonstrates how to release the reserved light targets.

iLight->ReleaseLight(CHWRMLight::EPrimaryDisplay | CHWRMLight::EPrimaryKeyboard);

Release the instance

When the CHWRMLight instance is not needed anymore it must be released. If some target is still reserved to the client, the target is released when the instance is released. The following code snippet demonstrates how to release the instance created by using NewLC().

CleanupStack::PopAndDestroy(light);

The following code snippet demonstrates how to release the instance created by using NewL().

CTest::~CTest()
    {
    delete iLight;
    }

Error handling

The leave mechanism of the Symbian OS is used to handle error conditions on method calls.

Memory overhead

Light API does not consume significant amount of memory after the CHWRMLight implementation instance is created.