BlackBerry Java Development Environment GPS & BlackBerry Maps

Version: 4.7.0

Development Guide

Published: 2009-05-15 SWD-596846-0515013402-001

Contents
1 GPS location information........................................................................................................................................................... Specifying the source of GPS location information.................................................................................................................... Get location information from cell site towers................................................................................................................... Get location information from GPS satellites using PDE.................................................................................................. Get location information from GPS satellites and the GPS receiver on a BlackBerry device....................................... Get location information from the GPS receiver on a BlackBerry device........................................................................ Getting GPS location information................................................................................................................................................. Specify a response time for getting the location of the BlackBerry device..................................................................... Get the location information for a BlackBerry device........................................................................................................ Get the speed of the BlackBerry device, in meters per second........................................................................................ Get the course of the BlackBerry device, in degrees.......................................................................................................... Get the number of GPS satellites that a BlackBerry device tracks.................................................................................. Get the time that a BlackBerry device application retrieved GPS information.............................................................. Maintain a connection with GPS satellites......................................................................................................................... Get continuous GPS readings using the cell site mode..................................................................................................... Get GPS information during a call....................................................................................................................................... Get location information updates........................................................................................................................................ Change the criteria for obtaining location information..................................................................................................... Specifying a GPS receiver as the source for location information................................................................................... 3 3 4 4 5 5 6 6 6 7 7 8 8 9 9 10 10 11 11 13 13 14 14 14 17 17 18 19 20 21 23 27 27

2 BlackBerry Maps location information..................................................................................................................................... Opening BlackBerry Maps............................................................................................................................................................. Opening BlackBerry Maps from an application.......................................................................................................................... Displaying location information on a BlackBerry device............................................................................................................ Displaying location information in BlackBerry Maps......................................................................................................... Open BlackBerry Maps to display the default map view................................................................................................... Open BlackBerry Maps to display a location on a map..................................................................................................... Open BlackBerry Maps to display multiple locations on a map....................................................................................... Open BlackBerry Maps to display a route between locations on a map......................................................................... Open BlackBerry Maps to display a custom map view...................................................................................................... Open BlackBerry Maps to display the location for an address in the contact list.......................................................... Start a BlackBerry device application from BlackBerry Maps........................................................................................... Displaying location information in a UI field............................................................................................................................... Work with a map that displays in a UI field.........................................................................................................................

Converting latitudinal and longitudinal coordinates to pixel values............................................................................... Configure the display size of a map that displays in a UI field......................................................................................... Requesting location information for an address......................................................................................................................... Retrieve location information for an address stored in address fields............................................................................. Retrieve location information for an address stored in a String....................................................................................... Cancel a request for location information for an address................................................................................................. Open BlackBerry Maps from the browser.................................................................................................................................... Clearing data from the map........................................................................................................................................................... Clear data from a map........................................................................................................................................................... 3 Resources...................................................................................................................................................................................... 4 Glossary......................................................................................................................................................................................... 5 Provide feedback......................................................................................................................................................................... 6 Legal notice..................................................................................................................................................................................

28 29 29 29 30 31 31 31 32 34 35 36 37

Development Guide

GPS location information

GPS location information

You can create a BlackBerry device application to display the current latitudinal and longitudinal position of a BlackBerry device. Depending on the mode for getting location information that you specify, the BlackBerry device application can also display information such as the speed and route information. To create a BlackBerry device application to get location information, you can use the Location API for Java ME in the javax.microedition.location package (JSR 179). The time it takes to retrieve the location of the BlackBerry device for the first time depends on several factors, such as the mode for getting location information and the GPS signal strength. In autonomous mode, typical times are less than 2 minutes. In assisted mode, typical times are less than 30 seconds. To retrieve and display GPS location information, the BlackBerry device must support GPS technology and a valid SIM card must be inserted in the BlackBerry device.
Related topics Specifying the source of GPS location information, 3 BlackBerry Maps location information, 13

Specifying the source of GPS location information

GPS location information might be unavailable if the BlackBerry device cannot receive signals from GPS satellites. This can occur when something obstructs the signals such as buildings or dense clouds. To specify the source of GPS location information, you specify the mode by creating an instance of the javax.microedition.location.Criteria class, invoke the appropriate set methods, and pass the instance to LocationProvider.getInstance(). cell site: Use this mode to obtain location information from cell site towers. This mode permits a BlackBerry device application to retrieve location information faster than the assisted and autonomous modes permit. However, the accuracy of the location information is low-level and does not provide tracking information such as the speed or route. Using this mode requires wireless network coverage and that both the BlackBerry device and the wireless service provider support this mode. assisted: Use this mode to get location information from satellites using a PDE. This mode permits a BlackBerry device application to retrieve location information faster than the autonomous mode permits and more accurately than the cell site mode permits. To use this mode requires wireless network coverage and the BlackBerry device and the wireless service provider must support this mode. It is possible that a BlackBerry device user might incur some costs if it uses the assisted mode. autonomous: Use this mode to get location information from the GPS receiver on the BlackBerry device without assistance from the wireless network. This mode permits a BlackBerry device application to retrieve location information that is highly accurate and does not require assistance from the wireless network. However, the speed that this mode retrieves location information at is slower than the other modes.

Related topics GPS location information, 3 BlackBerry Maps location information, 13

Development Guide

Specifying the source of GPS location information

Getting GPS location information, 6

Get location information from cell site towers

1. Import the following classes: javax.microedition.location.LocationProvider javax.microedition.location.Criteria Create an instance of a Criteria object.
Criteria criteria = new Criteria();

2. 3. 4. 5. 6. 7.

Invoke criteria.setHorizontalAccuracy(NO_REQUIREMENT) to specify that longitudinal accuracy is not required. Invoke criteria.setVerticalAccuracy(NO_REQUIREMENT) to specify that latitudinal accuracy is not required. Invoke criteria.setCostAllowed(true) to specify that this mode can incur cost. Invoke setPreferredPowerConsumption(POWER_USAGE_LOW) to specify that power consumption is low. Invoke LocationProvider.getInstance(), storing the returned object in a LocationProvider object.
LocationProvider provider = LocationProvider.getInstance(criteria);

Related topics Get location information from GPS satellites using PDE, 4 Get location information from GPS satellites and the GPS receiver on a BlackBerry device, 5

Get location information from GPS satellites using PDE

1. Import the following classes: javax.microedition.location.LocationProvider javax.microedition.location.Criteria Create an instance of a Criteria object.
Criteria criteria = new Criteria();

2. 3. 4. 5. 6. 7.

Invoke criteria.setHorizontalAccuracy(NO_REQUIREMENT) to specify that longitudinal accuracy is not required. Invoke criteria.setVerticalAccuracy(NO_REQUIREMENT) to specify that latitudinal accuracy is not required. Invoke criteria.setCostAllowed(true) to specify that this mode can incur cost. Invoke criteria.setPreferredPowerConsumption(int level) using either POWER_USAGE_MEDIUM, or NO_REQUIREMENT as the parameter to specify power consumption is medium or not required. Invoke LocationProvider.getInstance(), storing the returned object in a LocationProvider object.
LocationProvider provider = LocationProvider.getInstance(criteria);

Related topics Get location information from cell site towers, 4 Get location information from GPS satellites and the GPS receiver on a BlackBerry device, 5

Development Guide

Specifying the source of GPS location information

Get location information from GPS satellites and the GPS receiver on a BlackBerry device
1. Import the following classes: javax.microedition.location.LocationProvider javax.microedition.location.Criteria Create an instance of a Criteria object.
Criteria criteria = new Criteria();

2. 3. 4.

Invoke criteria.setCostAllowed(false) to specify that this mode does not incur cost. Invoke LocationProvider.getInstance(), storing the returned object in a LocationProvider object.
LocationProvider provider = LocationProvider.getInstance(criteria);

Related topics Get location information from cell site towers, 4 Get location information from GPS satellites using PDE, 4 Get location information from the GPS receiver on a BlackBerry device, 5

Get location information from the GPS receiver on a BlackBerry device

1. Import the following classes: javax.microedition.location.LocationProvider javax.microedition.location.Criteria Create an instance of a Criteria object.
Criteria criteria = new Criteria();

2. 3.

Complete one of the following tasks to get location information using the GPS receiver on a BlackBerry device: Task Steps Invoke criteria.setHorizontalAccuracy(int accuracy) using an integer value that represents the accuracy, in meters. Invoke criteria.setVerticalAccuracy(int accuracy) using an integer value that represents the accuracy, in meters. Invoke criteria.setCostAllowed(false). Invoke criteria.setHorizontalAccuracy(int accuracy) using an integer value that represents the accuracy, in meters. Invoke criteria.setVerticalAccuracy(int accuracy) using an integer value that represents the accuracy, in meters. Invoke criteria.setCostAllowed(true).

Specify a level of accuracy, a. with no cost and no power consumption. b. c. Specify a level of accuracy, a. with cost and variable power consumption. b. c.

Development Guide

Getting GPS location information

Task

Steps d. Invoke criteria.setPreferredPowerConsumption(int level) using either POWER_USAGE_LOW, POWER_USAGE_MEDIUM, or NO_REQUIREMENT as the parameter. Invoke criteria.setHorizontalAccuracy(NO_REQUIREMENT). Invoke criteria.setVerticalAccuracy(NO_REQUIREMENT). Invoke criteria.setCostAllowed(false). Invoke criteria.setPreferredPowerConsumption(int level) using either POWER_USAGE_MEDIUM, POWER_USAGE_HIGH, or NO_REQUIREMENT as the parameter.

Specify a level of accuracy, a. with no cost and variable b. power consumption. c. d.

4.

Invoke LocationProvider.getInstance(), storing the returned object in a LocationProvider object.

LocationProvider provider = LocationProvider.getInstance(criteria);

Related topics Get location information from GPS satellites and the GPS receiver on a BlackBerry device, 5

Getting GPS location information

Related topics Specifying the source of GPS location information, 3

Specify a response time for getting the location of the BlackBerry device
1. 2. 3. Import the javax.microedition.location.Criteria class. Create an instance of a Criteria object.
Criteria criteria = new Criteria();

Invoke Criteria.setPreferredResponseTime(), and specify the response time, in milliseconds.

criteria.setPreferredResponseTime(500);

Related topics Get the time that a BlackBerry device application retrieved GPS information, 8 Get continuous GPS readings using the cell site mode, 9

Get the location information for a BlackBerry device

1. Import the following classes: javax.microedition.location.LocationProvider javax.microedition.location.Location Create an instance of a LocationProvider.

2.

Development Guide

Getting GPS location information

LocationProvider provider = new LocationProvider();

3.

In a non-event thread, invoke LocationProvider.getLocation(int), providing a timeout, in seconds.

try { Location location = provider.getLocation(-1); } catch (Exception e) { }

Related topics Get the speed of the BlackBerry device, in meters per second, 7 Get the course of the BlackBerry device, in degrees, 7

Get the speed of the BlackBerry device, in meters per second

1. Import the following classes: javax.microedition.location.LocationProvider javax.microedition.location.Location Create an instance of a LocationProvider.
LocationProvider provider = new LocationProvider();

2. 3. 4.

Invoke LocationProvider.getLocation() and assign the value that the method returns to a Location variable.
Location mylocation = provider.getLocation(-1);

Invoke Location.getSpeed() and save the value that the method returns to a float variable.
float speed = mylocation.getSpeed();

Related topics Get the location information for a BlackBerry device, 6 Get the course of the BlackBerry device, in degrees, 7

Get the course of the BlackBerry device, in degrees

1. Import the following classes: javax.microedition.location.LocationProvider javax.microedition.location.Location Create an instance of a LocationProvider.
LocationProvider provider = new LocationProvider();

2. 3. 4.

Invoke LocationProvider.getLocation() and assign the value that the method returns to a Location variable.
Location mylocation = provider.getLocation(-1);

Invoke location.getCourse() and save the value that the method returns to a float variable.
float course = mylocation.getCourse();

Development Guide

Getting GPS location information

Related topics Get the location information for a BlackBerry device, 6 Get the speed of the BlackBerry device, in meters per second, 7

Get the number of GPS satellites that a BlackBerry device tracks

1. Import the following classes: javax.microedition.location.LocationProvider javax.microedition.location.Location Create an instance of a LocationProvider.
LocationProvider provider = new LocationProvider();

2. 3. 4.

Invoke LocationProvider.getLocation() and assign the value that the method returns to a Location variable.
Location mylocation = provider.getLocation(-1);

Invoke the Location.getExtraInfo() method using the NMEA MIME type as a parameter. The method returns an encoded String that contains information about the number of GPS satellites.
String encodedStr = mylocation.getExtraInfo("application/X-jsr179-location-nmea");

5.

To retrieve the GPS satellite information, parse through the information in the returned String value.

Related topics Maintain a connection with GPS satellites, 9

Get the time that a BlackBerry device application retrieved GPS information
1. Import the following classes: javax.microedition.location.LocationProvider javax.microedition.location.Location Create an instance of a LocationProvider.
LocationProvider provider = new LocationProvider();

2. 3. 4.

Invoke LocationProvider.getLocation() and assign the value that the method returns to a Location variable.
Location mylocation = provider.getLocation(-1);

Invoke Location.getTimeStamp() and assign the value that the method returns to a long variable. The time is retrieved from the GPS receiver on the BlackBerry device.
long timestamp = myLocation.getTimeStamp();

Related topics Specify a response time for getting the location of the BlackBerry device, 6 Get continuous GPS readings using the cell site mode, 9

Development Guide

Getting GPS location information

Maintain a connection with GPS satellites

You can configure a BlackBerry device application to query the Location API for GPS location information in an interval that is less than 10 seconds. 1. Import the following classes: javax.microedition.location.Criteria javax.microedition.location.LocationProvider 2. 3. 4. 5. Import the LocationListener interface. Implement the LocationListener interface. Create an instance of the Criteria class.
Criteria criteria = new Criteria();

Invoke LocationProvider.getInstance() using the Criteria object as a parameter and assign the value that the method returns to a LocationProvider variable.
LocationProvider provider = LocationProvider.getInstance(criteria);

6.

Invoke LocationProvider.setLocationListener() to configure a LocationListener with an interval value that is less than 10 seconds.
provider.setLocationListener(loclistener, 9, -1, -1);

Related topics Get the number of GPS satellites that a BlackBerry device tracks, 8

Get continuous GPS readings using the cell site mode

1. Import the following classes: javax.microedition.location.LocationProvider javax.microedition.location.Location Create an instance of a LocationProvider.
LocationProvider provider = new LocationProvider();

2. 3.

Invoke the LocationProvider.getLocation() method within code that simulates the retrieval of GPS information at fixed intervals. Assign the value that the method returns to a Location variable.
Location loc = provider.getLocation(-1);

Related topics Specify a response time for getting the location of the BlackBerry device, 6 Get the time that a BlackBerry device application retrieved GPS information, 8

Development Guide

Getting GPS location information

Get GPS information during a call

You can permit a BlackBerry device application to obtain GPS information while a BlackBerry device user is on a phone call. 1. Import the following classes: javax.microedition.location.LocationProvider javax.microedition.location.Criteria Create an instance of the Criteria class.
Criteria criteria = new Criteria();

2. 3. 4.

Configure the Criteria object to obtain GPS information without using a wireless network. Invoke Criteria.setCostAllowed() using the boolean value of false as a parameter to configure that cost cannot be incurred.
criteria.setCostAllowed(false);

5.

Invoke the LocationProvider.getInstance() method using a Criteria object as a parameter that you configure to obtain GPS information without using a a wireless network. Assign the value that the method returns to a LocationProvider variable.
LocationProvider provider = LocationProvider.getInstance(criteria);

Get location information updates

You can associate only one LocationListener object with a specific provider for GPS location information. The BlackBerry device application typically listens for updates on a separate thread. 1. Import the following classes: javax.microedition.location.Criteria javax.microedition.location.LocationProvider 2. 3. 4. 5. Import the LocationListener interface. Implement the LocationListener interface. Create an instance of a Criteria object. Invoke LocationProvider.getInstance() using the Criteria object as a parameter and assign the value that the method returns to a LocationProvider variable.
LocationProvider provider = LocationProvider.getInstance(criteria);

6.

Invoke LocationProvider.setLocationListener() using an instance of the class that implements the LocationListener interface as a parameter to register your implementation.
provider.setLocationListener(loclistener, 9, -1, -1);

Related topics Change the criteria for obtaining location information, 11

10

Development Guide

Getting GPS location information

Change the criteria for obtaining location information

1. Import the following classes: javax.microedition.location.Criteria javax.microedition.location.LocationProvider Import the LocationListener interface. Implement the LocationListener interface. Create an instance of the Criteria class.
Criteria criteria = new Criteria();

2. 3. 4. 5. 6.

Invoke the setHorizontalAccuracy(), setVerticalAccuracy(), setCostAllowed(), and setPreferredPowerConsumption() methods of the new Criteria object to specify the new criteria. Invoke LocationProvider.reset() using the LocationProvider object with the criteria that you want to change.
provider.reset();

7.

Specify the LocationListener to null to unregister any LocationListeners that are currently associated with the LocationProvider.
provider.setLocationListener(null, -1, -1, -1);

8.

Invoke LocationProvider.getInstance() using the new Criteria object as a parameter to create a new instance of a LocationProvider. Assign the value that the method returns to the LocationProvider object with the criteria that you want to change.
provider = LocationProvider.getInstance(criteria);

9.

Invoke LocationProvider.setLocationListener() to associate a new LocationListener with the LocationProvider. provider.setLocationListener(locListener, -1, -1, -1);

Related topics Get location information updates, 10

Specifying a GPS receiver as the source for location information

You can configure a GPS receiver that uses Bluetooth technology as the data source for location information on a BlackBerry device that is running BlackBerry Device Software version 4.2 or later. You can also configure the frequency that a BlackBerry device uses to request location information from a Bluetooth enabled GPS receiver.

11

Development Guide

Getting GPS location information

Criteria A BlackBerry device that is running BlackBerry Device Software version 4.2 or later that does not have an internal GPS receiver and is paired with one or more Bluetooth enabled GPS receivers A BlackBerry device that is running BlackBerry Device Software version 4.2 or later that has an internal GPS receiver and is paired with one or more Bluetooth enabled GPS receivers A BlackBerry device that is running BlackBerry Device Software version 4.2 or later that has an internal GPS receiver and is paired with only one Bluetooth enabled GPS receiver A BlackBerry device that is running BlackBerry Device Software version 4.2 or later that has an internal GPS receiver and is not paired with a Bluetooth enabled GPS receiver

Source of location information for the Location API one of the Bluetooth enabled GPS receivers

internal GPS receiver or one of the Bluetooth enabled GPS receivers

internal GPS receiver or the Bluetooth enabled GPS receiver

internal GPS receiver

12

Development Guide

BlackBerry Maps location information

BlackBerry Maps location information

You can create a BlackBerry device application that interacts with BlackBerry Maps. The BlackBerry Maps is a map and location client application that can display a map for a location, the location of the BlackBerry device, a route from a starting location to a specific ending location, and points of interest on a map. The BlackBerry Maps uses latitudinal and longitudinal integer values that are 100,000 times the double values specified by JSR 179, which uses WGS 84 specifications for the longitudinal and latitudinal values. To create a BlackBerry device application that uses BlackBerry Maps, you can use the MapArguments class in the net.rim.blackberry.api.invoke package. A BlackBerry device application can interact with the BlackBerry Maps in the following ways: start the BlackBerry Maps from a BlackBerry device application add a menu item to the BlackBerry Maps that opens a BlackBerry device application

The BlackBerry Maps is included on BlackBerry devices that run BlackBerry Device Software version 4.2 or later.
Related topics GPS location information, 3 Specifying the source of GPS location information, 3

Opening BlackBerry Maps

You can display information in BlackBerry Maps in a variety of ways. Approach Start BlackBerry Maps. from a BlackBerry device application Description You can create a BlackBerry device application that can start BlackBerry Maps and display information. You place location information in to a String variable called a location document. You then invoke net.rim.blackberry. api.invoke.Invoke .invokeApplication()using as parameters the
net.rim.blackberry.api. invoke.Invoke.APP_TYPE_MAPs

constant, and a new instance of a

net.rim.blackberry.api .invoke.MapsArguments object created

using the net.rim.blackberry.api. invoke.MapsArguments

.ARG_LOCATION_DOCUMENT constant and the String variable with the

location information. BlackBerry Maps. starts and displays the information in the location document.

13

Development Guide

Opening BlackBerry Maps from an application

Approach Open BlackBerry Maps from the BlackBerry Browser

Description You can let aBlackBerry device user use the browser on a BlackBerry device to access location information on a web server and display that information in BlackBerry Maps. You create a file with the extension .xloc and place location information in the file. The location information is the same information that you assign to the location document to start BlackBerry Maps from a BlackBerry device application. You then place the .xloc file on a web server. When a BlackBerry device user accesses the link for the .xloc file, for example http://servername/Filename.xloc, the browser passes the .xloc file as a String to the location document parser. BlackBerry Maps starts and displays the information in the .xloc file.

Related topics Opening BlackBerry Maps from an application, 14 Open BlackBerry Maps from the browser, 31

Opening BlackBerry Maps from an application

Your BlackBerry device application must import the net.rim.blackberry.api.invoke.Invoke class and the net.rim.blackberry.api.invoke.MapsArguments class.
Related topics Opening BlackBerry Maps, 13 Open BlackBerry Maps from the browser, 31

Displaying location information on a BlackBerry device

Displaying location information in BlackBerry Maps
The BlackBerry Maps uses a location document to display location information on a map, such as locations and routes. A location document is a String that contains a set of XML elements with attributes that specify information about the location or route. You can include information for ten locations in one location document.
Related topics Create a location document to display location information, 17

14

Development Guide

Displaying location information on a BlackBerry device

XML element: <lbs>

The <lbs> and </lbs> elements encapsulate the information in a location document. The opening and closing <lbs> elements contain all other location document elements. BlackBerry Java Development Environment version 4.5.0 or later 4.5.0 or later

Attribute
id clear

Type
String String

Description the id of a location document the action to perform on the information in a map NONE: clears no information DOCS: clears location or route information from all location documents with a id attribute set to a value LOCATIONS: clears location information from the map ALL: clears location and route information from the map

Required no no

Related topics XML element: <getRoute>, 15 XML element: <location>, 16

XML element: <getRoute>

The <getRoute> and </getRoute> elements contain route information. To display route information in a map, you must place two <location> elements within the opening and closing <getRoute> elements. The first <location> element represents the starting point of a route while the second <location> element represents the ending point of a route. You can only use the x and y attributes in a <location> element that is nested within a <getRoute> element.
Related topics XML element: <lbs>, 15 XML element: <location>, 16

15

Development Guide

Displaying location information on a BlackBerry device

XML element: <location>

The <location> element contains information for a specific location and has the following required and optional attributes BlackBerry Java Development Environment version 4.2.0 or later 4.2.0 or later 4.2.0 or later 4.2.0 or later

Attribute y x zoom label

Type
integer integer integer String

Description latitude in decimal degrees x 100,000 longitude in decimal degrees x 100,000 zoom level from 0 to MAX_ZOOM a label that is displayed beside a location on a map description information for a location address city province or state country postal code phone number fax number URL email address category rating information, between 0 and 5

Required yes yes yes yes

description address city region country postalCode phone fax url email categories rating

String String String String String String String String String String String String

yes no no no no no no no no no no no

4.2.0 or later 4.2.1 or later 4.2.1 or later 4.2.1 or later 4.2.1 or later 4.2.1 or later 4.2.1 or later 4.2.1 or later 4.2.1 or later 4.2.1 or later 4.2.1 or later 4.2.1 or later

Related topics XML element: <lbs>, 15 XML element: <getRoute>, 15

16

Development Guide

Displaying location information on a BlackBerry device

Create a location document to display location information

1. 2. Import the net.rim.blackberry.api.invoke.Invoke class. Create a String using required elements, or required and optional elements.
String document = <lbs> <location y='latitude' x='longitude' label='Location_Label' description='Description'/> <location y='latitude' x='longitude' label='Location_Label' description='Description'/> <location y='latitude' x='longitude' label='Location_Label' description='Description'/> ....</lbs>;

3.

Invoke Invoke.invokeApplication() using the String as one of the parameters.

Invoke.invokeApplication(Invoke.APP_TYPE_MAPS, new MapsArguments ( MapsArguments.ARG_LOCATION_DOCUMENT, document));

Related topics Displaying location information in BlackBerry Maps, 14

Open BlackBerry Maps to display the default map view

1. Import the following classes: net.rim.blackberry.api.invoke.Invoke net.rim.blackberry.api.invoke.MapsArguments Invoke invokeApplication()using a new MapsArguments object that does not contain any arguments.

2.

Related topics View a sample application that displays the default map, 17

View a sample application that displays the default map

1. 2. 3. 4. From the BlackBerry Integrated Development Environment, launch the BlackBerryMapsDemo project. In the BlackBerry Smartphone Simulator, click BlackBerry Maps Demo. Open the menu and click Invoke Default. Open the menu and click View Map.

Related topics Open BlackBerry Maps to display the default map view, 17

Open BlackBerry Maps to display a location on a map

1. Import the following classes:

17

Development Guide

Displaying location information on a BlackBerry device

net.rim.blackberry.api.invoke.Invoke net.rim.blackberry.api.invoke.MapsArguments 2. Create a String that contains location information for one location.
String document = "<location-document><location lon='-8052237' lat='4346518' label='Waterloo, ON' description='Waterloo' zoom='10'/></location-document>";

3.

Invoke invokeApplication() using the APP_TYPE_MAPS constant parameter, a new MapsArguments object that uses the ARG_LOCATION_DOCUMENT property, and the location String.
Invoke.invokeApplication(Invoke.APP_TYPE_MAPS, new MapsArguments ( MapsArguments.ARG_LOCATION_DOCUMENT, document));

Related topics View a sample application that displays a location on a map, 18

View a sample application that displays a location on a map

1. 2. 3. 4. 5. From the BlackBerry Integrated Development Environment, launch the BlackBerryMapsDemo project. In the BlackBerry Smartphone Simulator, click BlackBerry Maps Demo. Open the menu and click Invoke Location Document. Open the menu and click View Single Location. To view more details, from the application menu, select Details.

Related topics Open BlackBerry Maps to display a location on a map, 17

Open BlackBerry Maps to display multiple locations on a map

1. Import the following classes: net.rim.blackberry.api.invoke.Invoke net.rim.blackberry.api.invoke.MapsArguments

18

Development Guide

Displaying location information on a BlackBerry device

2.

Create a String that contains location information for multiple locations.

String document = "<location-document>" + "<location lon='-8052237' lat='4346518' label='Waterloo, ON' description='Waterloo, Ontario, Canada' />" + "<location lon='-7569792' lat='4542349' label='Ottawa, ON' description='Ottawa, Ontario, Canada' />" + "</location-document>";

3.

Invoke invokeApplication() using the APP_TYPE_MAPS constant parameter, a new MapsArguments object that uses the ARG_LOCATION_DOCUMENT property, and the location String.
Invoke.invokeApplication(Invoke.APP_TYPE_MAPS, new MapsArguments ( MapsArguments.ARG_LOCATION_DOCUMENT, document));

Related topics View a sample application that displays multiple locations on a map, 19

View a sample application that displays multiple locations on a map

1. 2. 3. 4. From the BlackBerry Integrated Development Environment, launch the BlackBerryMapsDemo project. In the BlackBerry Smartphone Simulator, click BlackBerry Maps Demo. Open the menu and click Invoke Location Document. Open the menu and click View Multiple Locations.

Related topics Open BlackBerry Maps to display multiple locations on a map, 18

Open BlackBerry Maps to display a route between locations on a map

1. Import the following classes: net.rim.blackberry.api.invoke.Invoke net.rim.blackberry.api.invoke.MapsArguments Create a String with route information within the <getRoute> elements.

2.

19

Development Guide

Displaying location information on a BlackBerry device

String document = "<location-document><GetRoute>" + "<location lon='-8052237' lat='4346518' label='Waterloo, ON' description='Waterloo, Ontario, Canada' />" + "<location lon='-7569792' lat='4542349' label='Ottawa, ON' description='Ottawa, Ontario, Canada' />" + "</GetRoute></location-document>";

3.

Invoke invokeApplication() using the APP_TYPE_MAPS constant parameter, a new MapsArguments object that uses the ARG_LOCATION_DOCUMENT property, and the String.
Invoke.invokeApplication(Invoke.APP_TYPE_MAPS, new MapsArguments ( MapsArguments.ARG_LOCATION_DOCUMENT,document));

Related topics View a sample application that displays a route between locations on a map, 20

View a sample application that displays a route between locations on a map

1. 2. 3. 4. 5. From the BlackBerry Integrated Development Environment, launch the BlackBerryMapsDemo project. In the BlackBerry Smartphone Simulator, click BlackBerry Maps Demo. Open the menu and click Invoke Location Document. Open the menu and click View Route. To view tracking information from one location to another, from the application menu, select Directions.

Related topics Open BlackBerry Maps to display a route between locations on a map, 19

Open BlackBerry Maps to display a custom map view

A MapView object represents the view that the BlackBerry Maps displays. The MapView object contains the latitude and longitude that the BlackBerry Maps uses as the center of the map and the zoom and rotation values for the map that it displays. 1. Import the following classes: net.rim.blackberry.api.invoke.Invoke net.rim.blackberry.api.maps.MapView

20

Development Guide

Displaying location information on a BlackBerry device

2. 3.

Create an instance of a MapView object.

MapView mapView = new MapView();

Modify the latitude, longitude, and zoom values for the MapView object.
mapView.setLatitude(4331168); mapView.setLongitude(-8055339); mapView.setZoom(10);

4.

Invoke invokeApplication() using the APP_TYPE_MAPS constant parameter, and a new MapsArguments object that uses the MapView object you created.
Invoke.invokeApplication(Invoke.APP_TYPE_MAPS, new MapsArguments(mapView));

Related topics View a sample application that displays a custom map view, 21

View a sample application that displays a custom map view

1. 2. 3. 4. From the BlackBerry Integrated Development Environment, launch the BlackBerryMapsDemo project. In the BlackBerry Smartphone Simulator, click BlackBerry Maps Demo. Open the menu and click Invoke Map View. Open the menu and click View Map.

Related topics Open BlackBerry Maps to display a custom map view, 20

Open BlackBerry Maps to display the location for an address in the contact list
You can create a BlackBerry Application that displays a map for the address of a contact in the contact list. The address for the contact must be a valid address. 1. Import the following classes: javax.microedition.pim.PIM net.rim.blackberry.api.invoke.Invoke net.rim.blackberry.api.invoke.MapsArguments javax.microedition.pim.PIMException 2. Import the following interfaces: javax.microedition.pim.Contact javax.microedition.pim.ContactList java.util.Enumeration Implement the following interfaces: javax.microedition.pim.Contact javax.microedition.pim.ContactList java.util.Enumeration

3.

21

Development Guide

Displaying location information on a BlackBerry device

4. 5.

Create a Contact object.

Contact c = null;

In a try block, get the contact list.

try { ContactList contactList = (ContactList)PIM.getInstance().openPIMList (PIM.CONTACT_LIST, PIM.READ_WRITE);

6.

Place the items from the contact list into an enumeration.

Enumeration enumContact = contactList.items(); int notFinished = 1;

7.

Create a While loop to iterate through all the items in the enumeration.
while ((enumContact.hasMoreElements()) && ( notFinished == 1)) { c = (Contact)enumContact.nextElement(); int[] fieldIds = c.getFields(); int id;

8.

Search for the first contact with a valid city and region and display the address information for this contact in the BlackBerry Maps.
if (c.countValues(Contact.ADDR) > 0) { String address[] = c.getStringArray(Contact.ADDR,0); if ((address[Contact.ADDR_LOCALITY] != null) && (address[Contact.ADDR_REGION] != null)) { Invoke.invokeApplication(Invoke.APP_TYPE_MAPS, new MapsArguments(c,0)); notFinished = 0; } } } } catch (PIMException e) { }

9.

If a contact address is not found, display the default map in the BlackBerry Maps.
if == null) { Invoke.invokeApplication(Invoke.APP_TYPE_MAPS, new MapsArguments()); } } };

Related topics View a sample application that displays the location for an address in the contact list, 22

View a sample application that displays the location for an address in the contact list
Before you begin: On a BlackBerry device, open the contact list. If there are no addresses in the contact list, the sample will display the default view in the BlackBerry Maps.

22

Development Guide

Displaying location information on a BlackBerry device

1. 2. 3. 4. 5.

Open the BlackBerry Integrated Development Environment. Launch the BlackBerryMapsDemo project. In the BlackBerry Smartphone Simulator, click BlackBerry Maps Demo. Open the menu and click Invoke Contact. Open the menu and click View Map.

Related topics Open BlackBerry Maps to display the location for an address in the contact list, 21

Start a BlackBerry device application from BlackBerry Maps

You can add a menu item to BlackBerry Maps that lets a BlackBerry device user start a BlackBerry device application using location information. The BlackBerry device user can also change location information and send the information to the BlackBerry device application. 1. Open the BlackBerry Integrated Development Environment. 2. Create a project. 3. Right-click the project, and click Properties. 4. Click the Application tab. 5. In the Arguments passed to field, type startup. Make sure the value you type matches the value in the startsWith argument in the main method of the BlackBerry device application. 6. Select Auto-run on startup. 7. Select System module. 8. Click OK. 9. Import the following classes:
import import import import import import import net.rim.device.api.ui.*; net.rim.device.api.ui.component.*; net.rim.device.api.ui.container.*; net.rim.blackberry.api.invoke.*; net.rim.device.api.system.*; net.rim.blackberry.api.maps.*; net.rim.blackberry.api.menuitem.*;

10. Create a class that extends the ApplicationMenuItem class and implements the run() and toString() methods.
private static class MapsMenuItem extends ApplicationMenuItem { MapsMenuItem() { super(20); } public String toString()

23

Development Guide

Displaying location information on a BlackBerry device

{ return "Menu Item Demo"; } public Object run(Object context) { if (context instanceof MapView ) { _mv = (MapView)context; UiApplication app = UiApplication.getUiApplication(); app.pushScreen( new MapsMenuItemScreen(_mv) ); app.requestForeground(); } return null; } } }

11.

In the main() method, register a menu item with BlackBerry Maps.

public static void main(String[] args) { if (args != null && args.length > 0) { if (args[0].equals("startup")) { ApplicationMenuItemRepository amir = ApplicationMenuItem Repository.getInstance(); ApplicationDescriptor artup = ApplicationDescriptor .currentApplicationDescriptor(); ApplicationDescriptor ad_gui = new ApplicationDescriptor (ad_startup , "gui", new String[]{"gui"}); amir.addMenuItem(ApplicationMenuItemRepository. MENUITEM_MAPS , new MapsMenuItem() , ad_gui); } else if (args[0].equals("gui")) { MapsMenuItemDemo app = new MapsMenuItemDemo(); app.enterEventDispatcher(); } } }

12. Create a screen for the application.

24

Development Guide

Displaying location information on a BlackBerry device

final class MapsMenuItemScreen extends MainScreen { private MapView _mapview; private BasicEditField _latitudeField; private BasicEditField _logitudeField; private NumericChoiceField _zoomField; MapsMenuItemScreen(MapView _mv) { _mapview = _mv; _latitudeField = new BasicEditField ("Latitude: " , _mv.getLatitude() /100000.0 + "" , 9 , BasicEditField.FILTER_REAL_NUMERIC ); _logitudeField = new BasicEditField ("Longitude: ",_mv.getLongitude() /100000.0 + "" , 10 , BasicEditField.FILTER_REAL_NUMERIC); _zoomField = new NumericChoiceField ("Zoom: " , 0 , MapView.MAX_ZOOM , 1 , _mv.getZoom()); add(_latitudeField); add(_logitudeField); add(_zoomField); add(new SeparatorField()); add(new RichTextField("Edit latitude, longitude and zoom level settings and select View Map from the menu." , Field.NON_FOCUSABLE)); addMenuItem(viewMapItem); setTitle("Location Details Screen"); }

13. Create a menu item that displays the latitude, longitude, and zoom values from the MapView context object.
private MenuItem viewMapItem = new MenuItem("View Map", 1000, 10) { public void run() { _mapview.setZoom( _zoomField.getSelectedValue() ); try { int latitude = (int) (100000 * Double.parseDouble (_latitudeField.getText())); int longitude = (int) (100000 * Double.parseDouble (_logitudeField.getText())); if (latitude > 9000000 || latitude < -9000000 ||

25

Development Guide

longitude >= 18000000 || longitude < -18000000) { throw new IllegalArgumentException (); } _mapview.setLatitude(latitude); _mapview.setLongitude(longitude); Invoke.invokeApplication(Invoke.APP_TYPE_MAPS, new MapsArguments(_mapview)); close(); } catch(RuntimeException re) { Dialog.alert("Invalid Longitude and/or Latitude"); _latitudeField.setFocus(); } } };

14. Populate the menu.

protected void makeMenu( Menu menu, int instance ) { super.makeMenu( menu, instance ); if(getFieldWithFocus() == _zoomField) { menu.setDefault(1); } }
Related topics View a sample application that starts a BlackBerry Application from BlackBerry Maps, 26

View a sample application that starts a BlackBerry Application from BlackBerry Maps
1. 2. 3. 4. From the BlackBerry Integrated Development Environment, launch the BlackBerry Smartphone Simulator. In the BlackBerry Smartphone Simulator, launchBlackBerry Maps. In BlackBerry Maps, click Menu Item Demo. Complete the instructions on the screen and click View Map.

Related topics Start a BlackBerry device application from BlackBerry Maps, 23

26

Development Guide

Displaying location information in a UI field

Displaying location information in a UI field

A BlackBerry device application can use the net.rim.device.api.lbs.MapField class to display a map in a UI field. For a BlackBerry device application to use the net.rim.device.api.lbs.MapField class, BlackBerry Maps must be installed on the BlackBerry device and the BlackBerry device must be able to download data from the map server for locationbased services. A BlackBerry device application can use a net.rim.device.api.lbs.MapField object to get data either from a map server for location-based services or the BlackBerry device with BlackBerry Maps installed. If location information is not present on the BlackBerry device, the BlackBerry device application can use anet.rim.device.api.lbs.MapField object to request data from the map server. See the API reference for the BlackBerry Java Development Environment for more information about the net.rim.device.api.lbs.MapField API.
Related topics Work with a map that displays in a UI field, 27 Configure the display size of a map that displays in a UI field, 29

Work with a map that displays in a UI field

A BlackBerry device application can use the net.rim.device.api.lbs.MapField class to display a map in the UI. The net.rim.device.api.lbs.MapField class lets a BlackBerry device application change and retrieve the properties of the map including the zoom level, the center of the map, and current rotation of the map. Method
MapField.moveTo(int la titude, int longitude) MapField.moveTo(javax.mic roedition.location. Coordinates coords) MapField.move(int dx, int dy)

Description Modify the center of a map in a UI field using latitudinal and longitudinal values, in degrees. The latitude and longitude values are calculated as degrees multiplied by 100,000. Modify the center of a map in a UI field using specific coordinates.

MapField.setZoom(int z)

Modify the center of a map in a UI field using pixel values. The move(dx,dy) method moves the center of the map in terms of relative pixels. A positive dx moves the center of the map east if the rotation is 0, and a positive dy moves the center of the map north if the rotation is 0. Modify the zoom value for a map in a UI field. Zoom values can be from 0 to 15. The zoom operation is performed to the center of the map in the MapField.

27

Development Guide

Displaying location information in a UI field

Method
MapField.setRotation(int r)

Description Modify the rotation for a map in a UI field, in degrees. Rotation can range from 0 to 360, clockwise. A rotation setting of 0 specifies north at the top of the map view. Retrieve the latitude of the center of a map in a UI field. Retrieve the longitude of the center of a map in a UI field. Retrieve the zoom value of a map in a UI field. Retrieve the rotation setting for a map in a UI field.

MapField.getLatitude() MapField.getLongitude() MapField.getZoom() MapField.getRotation()

Related topics Displaying location information in a UI field, 27 Configure the display size of a map that displays in a UI field, 29

Converting latitudinal and longitudinal coordinates to pixel values

You can create a BlackBerry device application to convert latitudinal and longitudinal coordinates to pixel values. You can then move a map by invoking MapField.move() using the pixel values as parameters. For latitude, north is a positive value, and south is a negative value. For longitude, east is a positive value and west is a negative value. The Coordinates class represents coordinates as latitudinal, longitudinal, and altitudinal values. The latitudinal and longitudinal values are expressed in degrees using floating point values. Altitudinal values represent the height of a location above the WGS84 ellipsoid, in meters. The Coordinates class provides coordinates using World Geodetic System 1984 (WGS 84) data.
Related topics Convert latitudinal and longitudinal coordinates, 28

Convert latitudinal and longitudinal coordinates

The XYPoint object stores the initial coordinates and changes to the converted coordinates. 1. Import the following classes: net.rim.device.api.lbs.MapField javax.microedition.location.Coordinates net.rim.device.api.ui.XYPoint 2. To convert latitudinal and longitudinal coordinates to pixels, invoke
MapField.convertWorldToField(Coordinates worldIn, XYPoint fieldOut) or MapField.convertWorldToField(XYPoint worldIn, XYPoint fieldOut). MapField myMapField = new MapField(); myMapField.convertWorldToField(coordinatesToConvert, xyptCartPlain);

28

Development Guide

Requesting location information for an address

3.

To convert pixels to latitudinal and longitudinal coordinates, invoke

MapField.convertFieldToWorld(XYPoint fieldIn, Coordinates worldOut) or MapField.convertFieldToWorld(XYPoint fieldIn, XYPoint worldOut). MapField myMapField = new MapField(); myMapField.convertFieldToWorld(xyptCartPlainToConvert, coordinates);

Related topics Converting latitudinal and longitudinal coordinates to pixel values, 28

Configure the display size of a map that displays in a UI field

A BlackBerry device application can control the display size of a map that displays in a UI field to make other UI components visible on the screen of a BlackBerry device. If you configure the preferred size of a net.rim.device.api.lbs.MapField, you override the dimension values passed in layout(). The height and width values are in pixels. 1. 2. Import the net.rim.device.api.lbs.MapField class. Invoke MapField.setPreferredSize(int preferredWidth, int preferredHeight).
MapField myMapField = new MapField(); myMapField.setPreferredSize(-1, -1);
Related topics Displaying location information in a UI field, 27 Work with a map that displays in a UI field, 27

Requesting location information for an address

You can use the Locator class in a BlackBerry device application to request location information for an address. Requests are sent to a locator server for location-based services. If the request is successful, the server returns an enumeration that contains latitudinal and longitudinal data for the address. If the request is unsuccessful, the server throws aLocatorException exception that contains the reason for the unsuccessful request. A BlackBerry device application can request location information for only one address at a time.
Related topics Cancel a request for location information for an address, 31

Retrieve location information for an address stored in address fields

Requesting information by invoking Locator.geocode() can result in a LocationException if the request fails. 1. Import the following classes: javax.microedition.location.AddressInfo javax.microedition.location.Coordinates net.rim.device.api.lbs.Locator

29

Development Guide

Requesting location information for an address

javax.microedition.location.Landmark javax.microedition.location.LocationException 2. 3. Create an AddressInfo object.

AddressInfo ai = new AddressInfo();

Set the fields of the AddressInfo object.

ai.setField(AddressInfo.STREET, main street); ai.setField(AddressInfo.CITY, Waterloo); ai.setField(AddressInfo.STATE, Ontario); ai.setField(AddressInfo.POSTAL_CODE, XXX XXX); ai.setField(AddressInfo.COUNTRY, Canada);

4.

Create a Coordinates object that the location-based services locator server uses as a starting location to search for location information for an address.
Coordinates co = new Coordinates(43.46518, -80.52237, 0);

5.

Invoke Locator.geocode(AddressInfo address, Coordinates startCoords) and assign the value that the method returns to a Landmark array.
Landmark[] lm = Locator.geocode(ai,co);

Related topics Retrieve location information for an address stored in a String, 30

Retrieve location information for an address stored in a String

Requesting information by invoking Locator.geocode() can result in a LocationException if the request fails. 1. Import the following classes: javax.microedition.location.Coordinates net.rim.device.api.lbs.Locator javax.microedition.location.Landmark javax.microedition.location.LocationException Create a String object that contains address information. String Address = Waterloo, Canada; Create a Coordinates object that the locator server for location-based services uses as a starting location to search for location information for an address.
Coordinates co = new Coordinates(43.46518, -80.52237, 0);

2. 3.

4.

Invoke Locator.geocode(String freeformString, Coordinates startCoords) and assign the value that the method returns to a Landmark array.
Landmark[] = Locator.geocode(sAddress, co);

Related topics Retrieve location information for an address stored in address fields, 29

30

Development Guide

Open BlackBerry Maps from the browser

Cancel a request for location information for an address

1. 2. Import the net.rim.device.api.lbs.Locator class. Invoke Locator.cancel().
lo.cancel();
Related topics Requesting location information for an address, 29

Open BlackBerry Maps from the browser

1. 2. Create a file with the extension .xloc. Place the information that you would normally place in a location document in the .xloc file. The location document information is the same information you assign to the String variable location document.
"<lbs><location lon='-8052237' lat='4346518' label='Waterloo, ON' description='Waterloo' zoom='10'/></lbs>";

3. 4.

On a web server, place the .xloc file in the folder where you store .html files. Register the following MIME type with the web server: text/vnd.rim.location xloc.

Related topics Opening BlackBerry Maps, 13 Opening BlackBerry Maps from an application, 14

Clearing data from the map

You can use the id and clear attributes of the <lbs> element to remove data from a map. When you want BlackBerry Maps to no longer display certain location data, in the next location document you send to BlackBerry Maps, configure the clear attribute to the value of the id attribute of the location document with the location data to remove. For example, to display data for Kitchener, Ontario in BlackBerry Maps that you can later remove, give the id attribute of the location document a value.
String document = "<lbs id='Wat' ><location lon='-8052237' lat='4346518' label='Waterloo, ON' description='Waterloo' zoom='10'/></lbs>";

When you send the location document for Kitchener, Ontario to BlackBerry Maps, BlackBerry Maps displays the information for Kitchener, Ontario. To remove the information for Kitchener, Ontario from BlackBerry Maps, in the next location document you send to BlackBerry Maps, configure the clear attribute to the value of the id attribute of the location document that contains information for Kitchener.

31

Development Guide

Clearing data from the map

String document = "<lbs clear='Wat' ><location lon='-8052237' lat='4346518' label='Waterloo, ON' description='Waterloo' zoom='10'/></lbs>";

When you send the new location document to BlackBerry Maps, BlackBerry Maps removes the Kitchener data from the map.
Related topics Clear data from a map, 32

Clear data from a map

You can create a BlackBerry device application that clears data from the map that BlackBerry Maps displays. A location document String with id and clear attributes uses the following format.
<lbs id='<string>' clear='{NONE | DOCS | LOCATIONS | ROUTES | ALL | comma_delimited_list_of_document_ids}>

1.

Import the following classes: java.lang.String net.rim.blackberry.api.invoke.Invoke Perform one of the following tasks: Task Clear data from a location document with an id attribute Step Create a String that configures the clear attribute to the id of the location document that contains the data to remove from a map.
String document = "<lbs clear='Montreal' ><location lon='-8052237' lat='4346518' label='Waterloo, ON' description='Waterloo' zoom='10'/></lbs>";

2.

Clear data from all location documents with an id attribute

Create a String that configures the clear attribute to Docs.

String document = "<lbs clear='Docs' ><location lon='-8052237' lat='4346518' label='Waterloo, ON' description='Waterloo' zoom='10'/></lbs>";

Clear data from specific location documents with an id attribute

Create a String that configures the clear attribute to a commadelimited list of ids.
String document = "<lbs clear='MONTREAL','OTTAWA' ><location lon='-8052237' lat='4346518' label='Waterloo, ON' description='Waterloo' zoom='10'/></lbs>";

Clear all location data from a map

Create a String that configures the clear attribute to Locations.

32

Development Guide

Clearing data from the map

Task

Step
String document = "<lbs clear='Locations' ><location lon='-8052237' lat='4346518' label='Waterloo, ON' description='Waterloo' zoom='10'/></lbs>";

3.

Invoke Invoke.invokeApplication() using as a parameter the String variable.

Invoke.invokeApplication(Invoke.APP_TYPE_MAPS, new MapsArguments ( MapsArguments.ARG_LOCATION_DOCUMENT, document));

Related topics Clearing data from the map, 31

33

Development Guide

Resources

Resources
For more information about APIs and GPS, visit www.blackberry.com/developers.

To view complete code samples for the BlackBerry Java Development Environment, visit www.blackberry.com/developers.

34

Development Guide

Glossary

Glossary
API application programming interface GPS Global Positioning System JSR Java Specification Request MIME Multipurpose Internet Mail Extensions NMEA National Marine Electronics Association PDE Position Determination Entity SIM Subscriber Identity Module WGS World Geodetic System XML Extensible Markup Language

35

Development Guide

Provide feedback

Provide feedback
To provide feedback on this deliverable, visit www.blackberry.com/docsfeedback.

36

Development Guide

Legal notice

Legal notice

2009 Research In Motion Limited. All rights reserved. BlackBerry, RIM, Research In Motion, SureType, SurePress and related trademarks, names, and logos are the property of Research In Motion Limited and are registered and/or used in the U.S. and countries around the world. Bluetooth is a trademark of Bluetooth SIG. Java is a trademark of Sun Microsystems, Inc. All other trademarks are the property of their respective owners. The BlackBerry smartphone and other devices and/or associated software are protected by copyright, international treaties, and various patents, including one or more of the following U.S. patents: 6,278,442; 6,271,605; 6,219,694; 6,075,470; 6,073,318; D445,428; D433,460; D416,256. Other patents are registered or pending in the U.S. and in various countries around the world. Visit www.rim.com/patents for a list of RIM (as hereinafter defined) patents. This documentation including all documentation incorporated by reference herein such as documentation provided or made available at www.blackberry.com/go/docs is provided or made accessible "AS IS" and "AS AVAILABLE" and without condition, endorsement, guarantee, representation, or warranty of any kind by Research In Motion Limited and its affiliated companies ("RIM") and RIM assumes no responsibility for any typographical, technical, or other inaccuracies, errors, or omissions in this documentation. In order to protect RIM proprietary and confidential information and/or trade secrets, this documentation may describe some aspects of RIM technology in generalized terms. RIM reserves the right to periodically change information that is contained in this documentation; however, RIM makes no commitment to provide any such changes, updates, enhancements, or other additions to this documentation to you in a timely manner or at all. This documentation might contain references to third-party sources of information, hardware or software, products or services including components and content such as content protected by copyright and/or third-party web sites (collectively the "Third Party Products and Services"). RIM does not control, and is not responsible for, any Third Party Products and Services including, without limitation the content, accuracy, copyright compliance, compatibility, performance, trustworthiness, legality, decency, links, or any other aspect of Third Party Products and Services. The inclusion of a reference to Third Party Products and Services in this documentation does not imply endorsement by RIM of the Third Party Products and Services or the third party in any way. EXCEPT TO THE EXTENT SPECIFICALLY PROHIBITED BY APPLICABLE LAW IN YOUR JURISDICTION, ALL CONDITIONS, ENDORSEMENTS, GUARANTEES, REPRESENTATIONS, OR WARRANTIES OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION, ANY CONDITIONS, ENDORSEMENTS, GUARANTEES, REPRESENTATIONS OR WARRANTIES OF DURABILITY, FITNESS FOR A PARTICULAR PURPOSE OR USE, MERCHANTABILITY, MERCHANTABLE QUALITY, NONINFRINGEMENT, SATISFACTORY QUALITY, OR TITLE, OR ARISING FROM A STATUTE OR CUSTOM OR A COURSE OF DEALING OR USAGE OF TRADE, OR RELATED TO THE DOCUMENTATION OR ITS USE, OR PERFORMANCE OR NON-PERFORMANCE OF ANY SOFTWARE, HARDWARE, SERVICE, OR ANY THIRD PARTY PRODUCTS AND SERVICES REFERENCED HEREIN, ARE HEREBY EXCLUDED. YOU MAY ALSO HAVE OTHER RIGHTS THAT VARY BY STATE OR PROVINCE. SOME JURISDICTIONS MAY NOT ALLOW THE EXCLUSION OR LIMITATION OF IMPLIED WARRANTIES AND CONDITIONS. TO THE EXTENT PERMITTED BY LAW, ANY IMPLIED WARRANTIES OR CONDITIONS RELATING TO THE DOCUMENTATION TO THE EXTENT THEY CANNOT BE EXCLUDED AS SET OUT ABOVE, BUT CAN BE LIMITED, ARE HEREBY LIMITED TO NINETY (90) DAYS FROM THE DATE YOU FIRST ACQUIRED THE DOCUMENTATION OR THE ITEM THAT IS THE SUBJECT OF THE CLAIM.

37

Development Guide

Legal notice

TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW IN YOUR JURISDICTION, IN NO EVENT SHALL RIM BE LIABLE FOR ANY TYPE OF DAMAGES RELATED TO THIS DOCUMENTATION OR ITS USE, OR PERFORMANCE OR NONPERFORMANCE OF ANY SOFTWARE, HARDWARE, SERVICE, OR ANY THIRD PARTY PRODUCTS AND SERVICES REFERENCED HEREIN INCLUDING WITHOUT LIMITATION ANY OF THE FOLLOWING DAMAGES: DIRECT, CONSEQUENTIAL, EXEMPLARY, INCIDENTAL, INDIRECT, SPECIAL, PUNITIVE, OR AGGRAVATED DAMAGES, DAMAGES FOR LOSS OF PROFITS OR REVENUES, FAILURE TO REALIZE ANY EXPECTED SAVINGS, BUSINESS INTERRUPTION, LOSS OF BUSINESS INFORMATION, LOSS OF BUSINESS OPPORTUNITY, OR CORRUPTION OR LOSS OF DATA, FAILURES TO TRANSMIT OR RECEIVE ANY DATA, PROBLEMS ASSOCIATED WITH ANY APPLICATIONS USED IN CONJUNCTION WITH RIM PRODUCTS OR SERVICES, DOWNTIME COSTS, LOSS OF THE USE OF RIM PRODUCTS OR SERVICES OR ANY PORTION THEREOF OR OF ANY AIRTIME SERVICES, COST OF SUBSTITUTE GOODS, COSTS OF COVER, FACILITIES OR SERVICES, COST OF CAPITAL, OR OTHER SIMILAR PECUNIARY LOSSES, WHETHER OR NOT SUCH DAMAGES WERE FORESEEN OR UNFORESEEN, AND EVEN IF RIM HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW IN YOUR JURISDICTION, RIM SHALL HAVE NO OTHER OBLIGATION, DUTY, OR LIABILITY WHATSOEVER IN CONTRACT, TORT, OR OTHERWISE TO YOU INCLUDING ANY LIABILITY FOR NEGLIGENCE OR STRICT LIABILITY. THE LIMITATIONS, EXCLUSIONS, AND DISCLAIMERS HEREIN SHALL APPLY: (A) IRRESPECTIVE OF THE NATURE OF THE CAUSE OF ACTION, DEMAND, OR ACTION BY YOU INCLUDING BUT NOT LIMITED TO BREACH OF CONTRACT, NEGLIGENCE, TORT, STRICT LIABILITY OR ANY OTHER LEGAL THEORY AND SHALL SURVIVE A FUNDAMENTAL BREACH OR BREACHES OR THE FAILURE OF THE ESSENTIAL PURPOSE OF THIS AGREEMENT OR OF ANY REMEDY CONTAINED HEREIN; AND (B) TO RIM AND ITS AFFILIATED COMPANIES, THEIR SUCCESSORS, ASSIGNS, AGENTS, SUPPLIERS (INCLUDING AIRTIME SERVICE PROVIDERS), AUTHORIZED RIM DISTRIBUTORS (ALSO INCLUDING AIRTIME SERVICE PROVIDERS) AND THEIR RESPECTIVE DIRECTORS, EMPLOYEES, AND INDEPENDENT CONTRACTORS. IN ADDITION TO THE LIMITATIONS AND EXCLUSIONS SET OUT ABOVE, IN NO EVENT SHALL ANY DIRECTOR, EMPLOYEE, AGENT, DISTRIBUTOR, SUPPLIER, INDEPENDENT CONTRACTOR OF RIM OR ANY AFFILIATES OF RIM HAVE ANY LIABILITY ARISING FROM OR RELATED TO THE DOCUMENTATION. Prior to subscribing for, installing, or using any Third Party Products and Services, it is your responsibility to ensure that your airtime service provider has agreed to support all of their features. Some airtime service providers might not offer Internet browsing functionality with a subscription to the BlackBerry Internet Service. Check with your service provider for availability, roaming arrangements, service plans and features. Installation or use of Third Party Products and Services with RIM's products and services may require one or more patent, trademark, copyright, or other licenses in order to avoid infringement or violation of third party rights. You are solely responsible for determining whether to use Third Party Products and Services and if any third party licenses are required to do so. If required you are responsible for acquiring them. You should not install or use Third Party Products and Services until all necessary licenses have been acquired. Any Third Party Products and Services that are provided with RIM's products and services are provided as a convenience to you and are provided "AS IS" with no express or implied conditions, endorsements, guarantees, representations, or warranties of any kind by RIM and RIM assumes no liability whatsoever, in relation thereto. Your use of Third Party Products and Services shall be governed by and subject to you agreeing to the terms of separate licenses and other agreements applicable thereto with third parties, except to the extent expressly covered by a license or other agreement with RIM. Certain features outlined in this documentation require a minimum version of BlackBerry Enterprise Server, BlackBerry Desktop Software, and/or BlackBerry Device Software.

38

Development Guide

Legal notice

The terms of use of any RIM product or service are set out in a separate license or other agreement with RIM applicable thereto. NOTHING IN THIS DOCUMENTATION IS INTENDED TO SUPERSEDE ANY EXPRESS WRITTEN AGREEMENTS OR WARRANTIES PROVIDED BY RIM FOR PORTIONS OF ANY RIM PRODUCT OR SERVICE OTHER THAN THIS DOCUMENTATION. Research In Motion Limited 295 Phillip Street Waterloo, ON N2L 3W8 Canada Research In Motion UK Limited Centrum House 36 Station Road Egham, Surrey TW20 9LF United Kingdom Published in Canada

39