Program Applications to Turn the Smartphone Backlight Off and On

Article
08/28/2006

You can programmatically turn the Windows Mobile–based device's backlight on and off by calling a pair of Power Management Functions to direct the Power Manager to accommodate your application's specific and immediate device power requirement. You use SetPowerRequirement to control the power state of the backlight (to turn it on and off), and you use ReleasePowerRequirement to release this power state control.

Note In the context of Power Management, the term "device" refers to a Windows Mobile–based device subsystem, and not a Windows Mobile–based device per se. Examples of devices are Back Light (BKL1), Notification LED (NLD1), Infrared Communications Port (COM3), Camera (CAM1), Subscriber Identity Module (SIM1), BlueTooth (BTL1), and Storage Card (DSK1). For information on the available devices, see the system registry under the key \HKEY_LOCAL_MACHINE\Drivers\.

Code Example

The following code example demonstrates how to programmatically set and release the device power requirement to keep the backlight at full power (a CEDEVICE_POWER_STATE of D0).

Note To make the following code example easier to read, security checking and error handling are not included. This code example should not be used in a release configuration unless it has been modified to include them.

//  IN BOOL fBacklightOn - TRUE to keep the backlight on.
void SetBacklightRequirement(BOOL fBacklightOn)
{
    // The name of the backlight device.
    TCHAR tszBacklightName[] = TEXT("BKL1:"); 

    static HANDLE s_hBacklightReq = NULL;
    
    if (fBacklightOn) 
    {
        if (NULL == s_hBacklightReq) 
        {
            // Turn the backlight on by setting the requirement that the backlight device 
            // must remain in device state D0 (full power). Replace D0 with D4 (zero power) to 
            // turn the backlight off.
            s_hBacklightReq = SetPowerRequirement(tszBacklightName, D0, POWER_NAME, NULL, 0);

            if (!s_hBacklightReq)
                RETAILMSG(1, (L"SetPowerRequirement failed: %X\n", GetLastError()));
        }
    } 
    else 
    {
        if (s_hBacklightReq) 
        {
            if (ERROR_SUCCESS != ReleasePowerRequirement(s_hBacklightReq))
                RETAILMSG(1, (L"ReleasePowerRequirement failed: %X\n", GetLastError()));

            s_hBacklightReq = NULL;
        }
    }
}

Remarks

Your application should turn the backlight off as soon as it no longer needs it on.

The Windows Mobile Version 5.0 Pocket PC and Smartphone SDKs ship with a sample application called Power Manager that demonstrates how to programmatically change the state of the backlight. For more information, see Code Samples.

Requirements

OS Versions: Windows CE .NET 4.0 and later
Header: Pm.h
Library: Coredll.lib

Program Applications to Turn the Smartphone Backlight Off and On

Code Example

Remarks

Requirements

See Also

Additional resources