App permissions
A Cascades app can gather and use a lot of information about the device that it's running on. An app can retrieve device information such as PIN and serial number, as well as information about contacts, calendar entries, and email messages. An app can also access information about the device's surroundings, such as location and positioning information. By using this information, you can develop apps that integrate with other apps that users already have on their devices, which helps you provide an exceptional user experience.
Some of this information is considered sensitive and requires special permission to access. For example, users probably don't want just any app to be able to access their contact information, so they must grant your application access to the functionality that it needs.
The image to the right shows an example of a permission request to use the microphone on the device. This dialog box is handled and displayed automatically by the BlackBerry 10 OS when a permission request is required, so you don't need to create it yourself in your app.
To help protect against potentially malicious code, if your app uses APIs that access restricted functionality without first requesting permission to access the device, the API will return errors. For example, if your app tries to access a file in a shared folder and your app doesn't include the access_shared permission, you'll receive a "permission denied" error.
You specify app permissions in the bar-descriptor.xml file of your project. Each permission is included in a separate <permission> element in the file. There are two ways to specify permissions for your app:
Use the Permissions check boxes
When you open the bar-descriptor.xml file in the QNX Momentics IDE, you can click the Application tab to see the list of permissions that you can add to your app. In the Permissions section, you can select check boxes that are associated with each permission that you want your app to have.
When you select a permission, the appropriate <permission> element is added automatically to the bar-descriptor.xml file. You can verify that the element was added by clicking the Source tab.
Add the elements manually
Some permissions might not be available as a check box on the Application tab. If you need to add these types of permissions to your app, you can click the Source tab and add the <permission> elements yourself.
Be sure to check the API reference for the classes that you're working with to determine which permissions you need to add. The following table describes <permission> element values that are available:
| Feature | Permission element value | Description |
|---|---|---|
| Background processing | run_when_backgrounded |
Perform background processing. Without this permission, your app stops all processing when the user switches focus to another app. You should use this permission sparingly and only when your app must perform processing in the background. This permission is useful for apps that play music or manage downloads. Apps that use this permission are rigorously reviewed for acceptance to the BlackBerry World storefront for their use of device battery power. |
| BlackBerry Messenger | bbm_connect |
Connect to BlackBerry Messenger (BBM). You can use this permission to access contact lists and user profiles, invite BBM contacts to download your app, initiate BBM chats and share content from within your app, and stream data between apps. |
| Calendar | access_pimdomain_calendars |
Access the calendar on the device. This access includes viewing, adding, and deleting calendar appointments. |
| Camera | use_camera |
Access data that's received from the cameras on the device. With this permission, your app can take pictures, record videos, and use the flash. |
| Contacts | access_pimdomain_contacts |
Access the contacts that are stored on the device. This access includes viewing, creating, and deleting contacts. |
| Device identifying information | read_device_identifying_ information |
Access unique device identifiers, such as PIN and serial number. |
| Email and PIN messages | access_pimdomain_messages |
Access the email and PIN messages that are stored on the device. This access includes viewing, creating, sending, and deleting messages. |
| GPS location | read_geolocation |
Read the current GPS location of the device. This permission is deprecated. Instead, you should use the access_location_services permission. |
| Internet | access_internet |
Use the Internet connection from a Wi-Fi, wired, or other type of connection to access locations that are not local on the device. |
| Location | access_location_services |
Access the current location of the device, as well as locations that the user has saved. |
| Microphone | record_audio |
Access the audio stream from the microphone on the device. |
| Narrow swipe up | narrow_landscape_exit |
Reduce the width of the region along the bottom bezel of the device that accepts swipe-up gestures. When you use this permission, swipe-up gestures are recognized in a more narrow area along the bottom bezel. This behavior allows apps that run in landscape orientation, such as games, to use corner regions for menus and virtual gamepads and prevents the game from inadvertently being sent to the background. |
| Notebooks | access_pimdomain_notebooks |
Access the content that's stored in notebooks on the device. This access includes adding entries to, and deleting entries from, the notebooks. |
| Notifications | post_notification |
Post notifications to the notification area of the device screen. |
| Phone | access_phone |
Access phone features on the device. This access includes requesting the dial pad, initiating a call, and sending DTMF tones. |
| Push | _sys_use_consumer_push |
Access the Push Service with the BlackBerry Internet Service. This access allows an app to receive and request push messages. To use the Push Service with the BlackBerry Internet Service, you must register with Research In Motion. When you register, you receive a confirmation email message that contains information that your app needs to receive and request push messages. For more information about registering, visit the Push Service documentation. If you're using the Push Service with a BlackBerry Enterprise Server or the BlackBerry Device Software, you don't need to register with RIM. |
| Shared files | access_shared |
Read and write files that are shared between all applications on the device. With this permission, your app can access pictures, music, documents, and other files that are stored on the user's device, at a remote storage provider, or on a media card. |
| Text messages | access_sms_mms |
Access the text messages that are stored on the device. This access includes viewing, creating, sending, and deleting text messages. |
Last modified: 2013-04-03