Creating apps that are data lock aware

An app that is data lock aware can continue to run when the work space enters a data lock state. Continuing to run can be important if, for example, an app needs to alert the user of important events as they happen.

Not all apps need to be data lock aware. If any of the following situations apply, you probably don't need to create an app that is data lock aware:

  • The app will be used only on personal devices. Personal devices can't enter a data lock state.
  • The app will be used only in the personal space of a device with BlackBerry Balance. The personal space on a device never enters a data lock state.
  • The app needs to run only while the work space is unlocked. The app can be idle while the work space is locked.

Design considerations

  • During data lock, your app needs to remove any sensitive information from the screen. For example, instead of displaying the subject line of a message, it might indicate only how many unread messages are waiting.
  • Data that your app needs to access when the work space is startup locked must be stored in the dataLockStartupHome folder. Files in this folder can also be accessed when the work space is data locked.
  • Data that your app needs to access when the work space is data locked (but not when it is startup locked) must be stored in the dataLockOperationalHome folder.
  • When a work space is transitioning from not being data locked to being data locked, it goes into a pending locked state for 10 seconds. During this transitional state, your app can perform any necessary tasks to prepare itself for running during data lock, such as closing files outside the startup and operational folders.
  • When data lock ends, your app may need to take restorative actions such as reopening files and displaying information that was removed from the screen while the work space was data locked.

Permissions

Apps that are data lock aware must request permission to use features related to advanced data at rest protection. Asking for permission ensures that the administrator who approves the app knows that it can store data in parts of the work space file system that have less stringent security.

When you develop apps using the BlackBerry 10 Native SDK, you set permissions in the bar-descriptor.xml file. When you develop apps using the BlackBerry 10 WebWorks SDK, you set permissions in the config.xml file.

The following permissions are specifically related to advanced data at rest protection:

Permission Description
_sys_allow_extend_data_lock This permission must be granted for your app to be able to extend the time before the work space switches into a data lock state. This permission applies only to apps developed using the BlackBerry 10 Native SDK.
access_operational_data_domain This permission must be granted for your app to be able to access files in the dataLockOperationalHome folder on the device.
access_startup_data_domain This permission must be granted for your app to be able to access files in the dataLockStartupHome folder on the device.
allow_request_lock This permission must be granted for your app to be able to request that the work space be put in a data lock state. This permission applies only to apps developed using the BlackBerry 10 Native SDK.
run_when_data_locked This permission must be granted for your app to be able to continue to run while the work space is in a data lock state.

The work space can enter a data lock state only when the work space is locked, so your app also needs one or more of the following permissions:

  • run_when_backgrounded
  • _sys_run_headless
  • _sys_headless_nostop

Data lock APIs

APIs for the BlackBerry 10 WebWorks SDK

There are two BlackBerry WebWorks APIs that help you write apps that use advanced data at rest protection.

IO

  • To access files in your app's startup folder, use the dataLockStartupHome property to help build the path.
  • To access files in your app's operational folder, use the dataLockOperationalHome property to help build the path.

System

  • To determine whether the work space is in a notLocked, pendingLocked, dataLocked, or startupLocked state, use the dataLockState property.
  • To determine when the work space will change from being in a pendingLocked state to being in a dataLocked state, use the dataLockTime property.
  • To be notified when the value of the dataLockState changes, use the datalockstatechanged event.

APIs for the BlackBerry 10 Native SDK

There are two BlackBerry 10 Native SDK APIs that help you write apps that use advanced data at rest protection.

AdarpDomain

  • To determine the current state of the work space, use the dataLockState() function.
  • To determine when the work space will move from the pendingDataLock state to the dataLocked state, use the nextDataLockTime() function.
  • To request extra time before the work space goes into a data lock state, use the extendDataLockTime() slot.
  • To trigger the data lock state in the work space, use the requestDataLock() slot.
  • To detect when the data lock state changes, listen for the dataLockStateChanged() signal.
  • To detect a change in what time the work space will go into a data lock state, listen for the nextDataLockTimeChanged() signal.
  • To determine the response to your request to extend the data lock time or trigger the data lock state, listen for the responseReceived() signal.

DataLockState

  • This API provides the set of possible datalock states.