Device Characteristics and the BlackBerry Infrastructure

Overview

This document describes how to find information about a BlackBerry device and how to interact with the BlackBerry infrastructure.

Device characteristics [back to top]

The BlackBerry® Java® SDK lets you interact with hardware on a BlackBerry device. The packages in this category include classes that let you query for details about the hardware and other characteristics of a particular device.

There are some general mechanisms you can use to query information about your device. You can use System.getProperty() to get information about a diverse set of device characteristics, including whether the device supports audio mixing and what time zone is currently set on the device. For more information, see the API reference.

Beginning with BlackBerry Java SDK 6.0, you can use the DeviceCapability class to query for information about a device. The class indicates whether covered capabilites are supported, allowed, or available. To find out which device capabilities are covered and how to use the class, see the API reference.

In addition to the two general mechanisms mentioned above, there are a number of methods, mostly in classes in the net.rim.device.api.system package, that provide information about a device. The following is a list of some common device information you can get using those methods. Most of the methods are static. Some of the methods return integral types that represent a set of bit flags. When that is the case, the class includes bit masks you can use to extract the information.

Device characteristicMethod
Identity
simulator?DeviceInfo.isSimulator()
manufacturerDeviceInfo.getManufacturerName()
device nameDeviceInfo.getDeviceName()
PINDeviceInfo.getDeviceId()
IMSISIMCardInfo.getIMSI()
ESNCDMAInfo.getESN()
MEIDCDMAInfo.getHexMEID()
IMEIGPRSInfo.getIMEI()
owner informationOwnerInfo.getOwnerInformation()
owner nameOwnerInfo.getOwnerName()
vendor IDBranding.getVendorId()
branding data versionBranding.getVersion()
is branding data signedBranding.isDataSigned()
Battery
battery level (%)DeviceInfo.getBatteryLevel()
detailed battery informationDeviceInfo.getBatteryStatus()
battery temperature (°C)DeviceInfo.getBatteryTemperature()
battery voltage (mV)DeviceInfo.getBatteryVoltage()
battery removable?DeviceInfo.isBatteryRemovable()
Speaker/Headset
audio?Audio.isSupported()
codecs supported?Audio.isCodecSupported()
volume level (%)Audio.getVolume()
built-in headset?Audio.hasBuiltInHeadset()
headset connected?Audio.isHeadsetConnected()
Accelerometer
accelerometer?AccelerometerSensor.isSupported()
Flip Sensor
flip open or closed?Sensor.getState()
flip?Sensor.isSupported()
Holster Sensor
in holster?Sensor.getState()
holster sensor?Sensor.isSupported()
Slide Sensor
sliding keyboard?Sensor.isSupported()
slide open?Sensor.isSlideOpened()
slide closed?Sensor.isSlideClosed()
slide moving?Sensor.isSlideInTransition()
Display
horizontal resolution (pixels per meter)Display.getHorizontalResolution()
vertical resolution (pixels per meter)Display.getVerticalResolution()
drawable area height (pixels)Display.getHeight()
drawable area width (pixels)Display.getWidth()
number of display colorsDisplay.getNumColors()
subpixels? backlight required?Display.getProperties()
Backlight
backlight on?Backlight.isEnabled()
backlight brightness (%)Backlight.getBrightness()
backlight brightness configurable?Backlight.isBrightnessConfigurable()
backlight brightness default (%)Backlight.getBrightnessDefault()
default backlight timeout (s)Backlight.getTimeoutDefault()
L.E.D.
LED?LED.isSupported()
multi-color LEDLED.isPolychromatic()
Radios
supported wireless access familiesRadioInfo.getSupportedWAFs()
GPS
GPS?GPSInfo.isGPSModeAvailable()
default GPS modeGPSInfo.getDefaultGPSMode()
Bluetooth
Bluetooth®BluetoothSerialPort.isSupported()
Bluetooth informationBluetoothSerialPort.getSerialPortInfo()
Phone
phone numberPhone.getDevicePhoneNumber()
voice mail?Phone.isVoiceMailIndicatorOn()
Memory
flash memory size (bytes)DeviceInfo.getTotalFlashSizeEx()
free flash memory (bytes)Memory.getFlashFree()
get RAM statistics objectMemory.getRAMStats()
OS and software
platform versionDeviceInfo.getPlatformVersion()
software versionDeviceInfo.getSoftwareVersion()
Camera
camera?DeviceInfo.hasCamera()
USB port
USB port?USBPort.isSupported()
USB connection stateUSBPort.getConnectionState()

BlackBerry infrastructure [back to top]

BlackBerry Enterprise Server

The BlackBerry® Enterprise Server is designed to be a secure, centralized link between an organization's wireless network, communications software, applications, and BlackBerry devices. The BlackBerry Enterprise Server integrates with an organization's existing infrastructure, which can include messaging and collaboration software, calendar and contact information, wireless Internet and intranet access, and custom applications, to provide BlackBerry device users with mobile access to the organization's resources.

The BlackBerry Enterprise Server supports Advanced Encryption Standard (AES) and Triple Data Encryption Standard (Triple DES) encryption to help protect and maintain the integrity of wireless data that is transmitted between the BlackBerry Enterprise Server components and BlackBerry devices. Administrators can choose from more than 450 IT policy rules that they can configure to control the features of the BlackBerry devices that are used in the organization's environment.

The BlackBerry Enterprise Server supports several optional components and configurations to meet the organization's requirements. The BlackBerry Collaboration Service integrates with supported third-party instant messaging servers to permit users to access the organization's instant messaging system from their BlackBerry devices using a BlackBerry instant messaging client. The BlackBerry MDS Integration Service supports custom application development and distribution. Administrators can configure the BlackBerry Enterprise Server and the BlackBerry Enterprise Server components to support high availability to enhance the consistency and reliability of the organization's environment.

For more information, visit www.blackberry.com/go/serverdocs to read the BlackBerry Enterprise Server Feature and Technical Overview.

BlackBerry Internet Service

The BlackBerry® Internet Service is designed to provide users with real-time delivery of email messages, mobile access to attachments, and convenient access to Internet content.

The BlackBerry Internet Service uses the security of the wireless network that it connects to. Email messages that are sent between the BlackBerry Internet Service and a BlackBerry device are not encrypted. When email messages are sent over the wireless network, they are subject to the existing or available network security model(s). However, email messages that are sent between the BlackBerry Internet Service and a messaging server can be encrypted using Secure Sockets Layer (SSL) encryption. SSL encryption can also be used by the BlackBerry® Browser and other applications on a BlackBerry device to help protect data when a user connects to the Internet (for example, while shopping and banking online).

BlackBerry Push Service SDK

Package: net.rim.blackberry.api.push

The BlackBerry® Push Service is an essential component of the real-time, always-on experience of BlackBerry smartphones. It offers an efficient and reliable way of sending information to your users. It also lets your application process information in the background and notify users when their attention is required.

To learn about developing applications that use the BlackBerry push package visit the Push Service documentation repository.

Service book

Package: net.rim.device.api.servicebook

A service book contains information that specifies how a BlackBerry device interacts with the BlackBerry® Infrastructure. It also turns on specific services for a BlackBerry device.

A service book consists of service records that define a service that can be enabled on a BlackBerry device. For example, service book records can define the communication protocol available on a BlackBerry device (for example, Wireless Application Protocol (WAP) or Internet Protocol Proxy Protocol (IPPP)), the available network gateway, and configuration information such as browser settings. When the wireless service provider provisions the BlackBerry device, service book records are sent to the BlackBerry device Personal Identification Number (PIN). When a BlackBerry device is activated on a BlackBerry Enterprise Server, additional service book records are sent from the BlackBerry Enterprise Server to the BlackBerry device. The service book records on a BlackBerry device depend on the features provided by the wireless service provider and the IT policies set up by the BlackBerry Enterprise Server administrator.

Users can view the service book on a BlackBerry device by opening the options application and clicking Service Book. For a list of common service book records, visit www.blackberry.com/support to read KB03151.

The Service Book API (net.rim.device.api.servicebook) enables applications to interact with the service book on a BlackBerry device. For example, you can use a service record to keep track of multiple email connections or to search for individual email messages within an email hierarchy based on the email item's content ID (CID). Service records can also be used to keep track of network Unique Identifiers (UIDs), allowing you to easily manage MDS connections. The ServiceBook class maintains a collection of ServiceRecord objects. Each ServiceRecord object is identified by a unique identifier (UID) and connection ID (CID).

To view a code sample that demonstrates how to access the service book on a BlackBerry device, visit www.blackberry.com/knowledgecenterpublic to read DB-00418. To view a code sample that demonstrates how to determine when the BlackBerry device is able to route data optimally, visit www.blackberry.com/knowledgecenterpublic to read DB-00485.

IT policies [back to top]

Package: net.rim.device.api.itpolicy

BlackBerry Enterprise Server administrators can use IT policies to control a BlackBerry device, a BlackBerry enabled device, the BlackBerry® Desktop Software, and the BlackBerry® Web Desktop Manager in an organization's environment. An IT policy consists of multiple IT policy rules that manage the security and behavior of the BlackBerry® Enterprise Solution. For example, administrators can use IT policy rules to manage the following security features and behaviors of the BlackBerry device:

After a BlackBerry device user activates a BlackBerry device, the BlackBerry Enterprise Server automatically sends the IT policies that the administrator assigned to the user to the BlackBerry device. For a full list of IT policies, visit www.blackberry.com/go/serverdocs to read the BlackBerry Enterprise Server Policy Reference Guide.

You can use the IT Policy API (net.rim.device.api.itpolicy) to access the IT policy settings on a BlackBerry device. For example, you can use the IT Policy API to determine whether or not WAP is enabled on the BlackBerry device.

ITPolicy.getBoolean(ITPolicy.ENABLE_WAP_CONFIG, 0,  false);

An IT policy rule consists of a descriptive key and a value. The value can be a String, integer, or Boolean value.

Another common IT policy to query is SecurityPolicy.ALLOW_RESET_IDLE_TIMER, which allows you to prevent locked BlackBerry screens from interrupting your application. To view a code sample that demonstrates how to prevent the lock screen on a BlackBerry device from interrupting your application, visit www.blackberry.com/knowledgecenterpublic to read DB-00563.

Application control policies [back to top]

Package: net.rim.device.api.applicationcontrol

BlackBerry Enterprise Server administrators can control the data and APIs that BlackBerry Java Applications can access on BlackBerry devices, and the external data sources and network connections that BlackBerry Java Applications can access by using application control policies. For example, administrators can use application control policies to prevent users from installing an application on a BlackBerry device.

Application control policies enable administrators to perform the following actions:

Application control policies apply to BlackBerry devices connected to BlackBerry Enterprise Server 4.0 or later. Application control policies are not available for devices that use the BlackBerry Internet Service. For a full list of application control policies, visit www.blackberry.com/go/serverdocs to read the BlackBerry Enterprise Server Policy Reference Guide.

You can determine whether an API is available for use on a BlackBerry device and request that the user change permissions, if necessary. In the following code sample, the application checks whether the application control settings permit access to location-based services. If the API is unavailable, the application prompts the user for permission to use this API.

Click for code sample: Requesting permission to use an API

ApplicationPermissionsManager appPermMgr = ApplicationPermissionsManager.getInstance();

// Query the Location permission
int locationPermission = appPermMgr.getPermission( ApplicationPermissions.PERMISSION_LOCATION_DATA );
        
if( locationPermission != ApplicationPermissions.VALUE_ALLOW ) {

    // Build the permission request
    ApplicationPermissions requestedPermissions = 
        new ApplicationPermissions();

    requestedPermissions.addPermission( 
        ApplicationPermissions.PERMISSION_LOCATION_DATA );

    // Invoke the request, the system takes over            
    appPermMgr.invokePermissionsRequest( requestedPermissions ); 
}

Copyright 1999-2010 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.