Enable the backlight and prevent the BlackBerry device screen from turning off or becoming locked

by BlackBerry Development Advisor ‎02-16-2010 09:11 AM - edited ‎09-16-2010 02:05 PM (9,376 Views)

Summary

 

This article applies to the following:

  • BlackBerry® devices based on Java® technology

Description

 

The backlight timer and security timer are distinct but their usage can be easily confused.  This article attempts to distinguish between the two types of timers, and to specify the conditions in which a third-party application can reset each of these timers.

 

Backlight Timer

 

The backlight timer determines the period of inactivity after which the LCD screen goes dark.  This timer is usually set to a small value (often 30 seconds).

 

Security Timer

 

The security timer determines the period of inactivity after which the keyboard or password lock are engaged.  In other words, after the security timer times out the BlackBerry device user must enter a password or screen lock to unlock the device.  This timer is usually set to a larger value (often 1 hour).

The security timer is sometimes also referred to as the “idle timer”.

 

Programmatically Resetting the Timers

 

Resetting the Backlight Timer


Third party applications can reset the backlight timer via the Backlight.enable() API. 

 

The following code specifies that the screen backlight, once activated, has a timeout period of 30 seconds.

 

 

if(( Display.getProperties()
& Display.DISPLAY_PROPERTY_REQUIRES_BACKLIGHT) != 0 )
{
Backlight.enable( true, 30 );
}

 

The backlight.enable method only turns the backlight on for the period of time specified, up to a maximum of 255 seconds. BlackBerry device user activity that occurs while the backlight is on resets the value specified in this method.

 

However, some applications might require the backlight to stay on for longer than 255 seconds. For example, in navigation software design, the backlight might be required for extended periods of time even though BlackBerry device user activity is not continuous (For example, while travelling). For this scenario, you can set a timer to turn the backlight on every 255 seconds.

 

Remember that BlackBerry device backlight usage consumes additional power. Excessive usage has a negative impact on the BlackBerry device battery.

 

Access to this functionality is controlled by the PERMISSION_DEVICE_SETTINGS permission.  Callers that have this permission will be able to successfully call this API and reset the backlight timer.  Callers that do not have this permission will receive a ControlledAccessException.

The PERMISSION_DEVICE_SETTINGS permission defaults to Allow, and applications rarely encounter problems resetting the backlight timer.

 

Users and testers can also check the current value of the application’s PERMISSION_DEVICE_SETTINGS permission via the Edit Permissions screen (Options -> Device -> Application Management -> <click on the application> -> Edit Permissions).  Applications can check the current value of their PERMISSION_DEVICE_SETTINGS permission via the ApplicationPermissionsManager.getPermissions() API. 

 

Resetting the Security Timer

 

The security timer cannot be directly reset programmatically.  Instead, this action is performed via the Backlight.enable() API.

 

Following a successful attempt to reset the backlight timer, Backlight.enable() check if the calling application is also permitted to reset the security timer.  If so permitted, Backlight.enable() will reset the security timer on the application’s behalf.  If the application is not permitted to modify the security timer, then Backlight.enable() will silently skip this step.  No indication is given to the calling application as to whether a security timer reset was performed.

 

Two conditions must be satisfied for an application to be able to reset the security timer:

 

  • If an IT Policy is present, the ALLOW_RESETTING_OF_IDLE_TIMER policy in the Security group must be set to True.  (This permits Blackberry Enterprise Server administrators to ban security timer resets entirely.)  This policy defaults to False.

 

  • The calling application must hold the PERMISSION_IDLE_TIMER permission (also called the “Security Timer Reset” permission).  This permission defaults to Deny.

 

BlackBerry device users and testers can check the current value of the ALLOW_RESETTING_OF_IDLE_TIMER policy by using RIM’s IT Policy Reader.  Users can also check the current value of this policy by inspecting the Security Timer Reset line in any application’s Edit Permissions screen. If an IT Policy exists that bans security timer resets entirely, the Security Timer Reset box will be grayed out, unmodifiable, and show “Deny”.

 

Users and testers can also check the current value of the application’s PERMISSION_IDLE_TIMER permission via the Edit Permissions screen (Options -> Device -> Application Management -> <click on the application> -> Edit Permissions).  However, as noted above, if an IT Policy prohibits the resetting of the idle timer via the ALLOW_RESETTING_OF_IDLE_TIMER policy, then this field on the Edit Permissions screen will not show the current value of the permission.  Instead, it will show an unmodifiable grayed out box that shows Deny.

 

Applications can check the current value of their PERMISSION_IDLE_TIMER permission via the ApplicationPermissionsManager.getPermissions() API.  The value returned by this API is always the current value of the PERMISSION_IDLE_TIMER, and does not reveal any information about the current value of the ALLOW_RESETTING_OF_IDLE_TIMER IT Policy (if one is present).

 

Impact of the Trust Dialog

 

When an application is run for the first time, a Trust Dialog is normally shown.  If the user elects to grant the application trusted status, the application’s PERMISSION_IDLE_TIMER permission is changed from the default value of Deny to the trusted value of Prompt.

 

If the application subsequently calls Backlight.enable(), the device will reset the backlight timer.  The device will then check if the calling application is permitted to reset the security timer.  If the IT Policy permits resetting of the idle timer (see above), the device proceeds to check the value of the PERMISSION_IDLE_TIMER permission.  If that permission is set to Prompt, then the device shows an Application Permissions prompt.  The user can elect to Allow or Deny the security timer reset action.

 

Note: The code sample above requires code signing. See the Controlled APIs and Code Signing page for more information.