Application integration

Magnetometer APIs

On some BlackBerry® devices that are running BlackBerry® Device Software 7.0, a magenetometer is integrated into the device (currently, only devices with touch screens have this functionality). The magnetometer sensor detects magnetic fields along the three axes: X, Y and Z of a BlackBerry device. You can use the Magnetometer APIs that are provided in the net.rim.device.api.system package to create applications (for example, a stud finder or compass) that detect the XYZ magnetic fields and the Earth's magnetic poles.

The MagnetometerSensor class is the main entry point for retrieving information from the magnetometer sensor, and the magnetometer data is encapsulated in the MagnetometerData class. You can use one of the following approaches to retrieve magnetometer data:

  • Periodically retrieve magnetometer data in a dedicated thread
  • Create a MagnetometerListener to notify your application when specific data changes (for example, when the orientation of the BlackBerry device changes)

You can use the DeviceOrientationUtil.getRotationMatrix method to calculate the rotation matrix for the BlackBerry device based on geomagnetic and gravitational vectors that are provided by the magnetometer and accelerometer sensors. You can use the DeviceOrientationUtil.getOrientation method with a specified rotation matrix to calculate the BlackBerry device's orientation (azimuth, pitch, and roll).

The magnetometer sensor can be calibrated when its accuracy no longer satisfies an application's requirements. When the magnetometer sensor is in calibration mode, it tries to filter out any distortions caused by magnetized materials, such as internal speaker phones or any adjacent computers that may affect directional and orientation readings of the BlackBerry device, and therefore improve the accuracy of the readings. As an example, if the magnetometer sensor on the BlackBerry device detects a source of magnetic interference, while running the Compass application, the Compass application is notified of the interference and the launches the calibration application with the instructions of gestures required for successful sensor calibration.

Inclination and declination for a magnetic field retrieval

You can retrieve the inclination, declination and several other estimates for a geomagnetic field by using the GeomagneticField class. The GeomagneticField is provided in the net.rim.device.api.location package and includes the following methods:

  • getDeclination(): Retrieves the declination (the difference between magnetic north and true north) of the geomagnetic field
  • getInclination(): Retrieves the inclination (the angle relative to the horizontal plane) of the geomagnetic field
  • getFieldStrength(): Retrieves the total intensity of the geomagnetic field
  • getHorizontalFieldStrength(): Retrieves the total horizontal intensity of the geomagnetic field
  • getX(), getY(), getZ(): Retrieves the north, east, and vertical components of the geomagnetic field

Compass application

The Compass application utilizes the Magnetometer APIs to provide the BlackBerry device user with the direction of the BlackBerry device relative to the Earth's magnetic poles.

The Compass application integrates with BlackBerry® Maps and provides the user with the ability to specify a destination. To specify a destination, perform the following steps:

  1. In the Compass application, press the Menu key.
  2. Select Set Destination to launch BlackBerry Maps.
  3. To set a destination, click a point on the map, then click or tap to select this point.

Unified Search additions

The Unified Search API includes new convenience classes and methods in the net.rim.device.api.unifiedsearch.searchables.adapters package.

The SearchableDataObject class provides an implementation of the SearchableEntity interface. You can extend this class to override the methods that are relevant to your data. The SearchableDataObject class provides defaults for methods that you do not override.

The EntityBasedSearchableProvider class provides an implementation of the EntityBasedSearchable interface. You can add, remove, and update your data in the search index without interacting with the AppContentManager class.

The ExtendedSearchProvider provides an implementation of the ExternalSearchProvider interface. You must override the search() method to connect to your search engine.

A new constructor for the SearchArguments class allows you to specify the search string only. The SearchArguments(String, String) constructor is deprecated.

Categorizing search results

The SearchableContentTypeConstantsInfo class provides two methods that help to determine the type of content returned by the Unified Search Service in a search result. The getAllContentTypes method returns a bitwise OR combination of all the content type constants defined in SearchableContentTypeConstants. The getMediaContentTypes method returns a bitwise OR combination of all the media content types in SearchableContentTypeConstants.

Two new constants in SearchableContentTypeConstants help identify media files. The CONTENT_TYPE_MEDIA_DOCUMENTS constant identifies document files. The CONTENT_TYPE_MEDIA_FILES_ALL identifies all media files (documents, music, ring tones, and so on).

You can compare the return values from these methods to the return value of the Searchable.getType() to determine whether a search result contains a particular data type.

Identifying media files

Two new constants in SearchableContentTypeConstants help identify media files. The CONTENT_TYPE_MEDIA_DOCUMENTS constant identifies document files. The CONTENT_TYPE_MEDIA_FILES_ALL identifies all media files (documents, music, ring tones, and so on).

Data volume monitoring on CDMA devices

You can now use the RadioInfo.getNumberOfPacketsSent() and RadioInfo.getNumberOfPacketsRecieved() methods to retrieve the number of packets (IP bytes) sent or receive on the radio for CDMA devices. Previously, you could only retrieve this information on GSM devices. You can use these methods to track how much data a device is sending and receiving over the network.

You can find the RadioInfo class in the net.rim.device.api.system package.

BlackBerry Balance support

The Multi Service Platform API has been added to support the BlackBerry® Balance™ feature that is new in BlackBerry® Enterprise Server 5.0.3.

BlackBerry Enterprise Server administrators can now set IT policy rules that distinguish between work data and personal data on a BlackBerry® device. These rules allow administrators to control access to work data, as well as facilitating the deletion of work data.

The net.rim.device.api.system.MultiServicePlatformManager class and net.rim.device.api.system.MultiServicePlatformListener interface allow you to implement controls on data access and create listeners that allow administrators to delete data remotely. Modes (such as corporate) are stored in the net.rim.device.api.system.ServiceMode class. The net.rim.device.api.system.Application class includes the following new methods: getServiceMode, setServiceMode, setServiceModeImpl, and suggestServiceMode.

A new field called PL_INVALID_OPERATION has been added to the FileIOException class. The PL_INVALID_OPERATION exception is generated when an unauthorized, personal or non-corporate application attempts to delete, create, read, or change a corporate file.

Previous topic: User interface

Was this information helpful? Send us your comments.