Blackbe;rry JAVA DEVELOPMENT ENVIRONMENT - - GPS AND MAPS

GPS and BlackBerry Maps

Version: 4.7.0

Development Guide

SWD-596846-1209055709-001

Contents

1 GPS location information........................................................................................................................................................... 3

Specifying the source of GPS location information.................................................................................................................... 3

Get location information from cell site towers................................................................................................................... 3

Get location information from GPS satellites using PDE.................................................................................................. 4

Get location information from GPS satellites and the GPS receiver on a BlackBerry device....................................... 4

Get location information from the GPS receiver on a BlackBerry device........................................................................ 5

Getting GPS location information................................................................................................................................................. 6

Specify a response time for getting the location of the BlackBerry device..................................................................... 6

Get the location information for a BlackBerry device........................................................................................................ 6

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

Get the course of the BlackBerry device, in degrees.......................................................................................................... 7

Get the number of GPS satellites that a BlackBerry device tracks.................................................................................. 7

Get the time that a BlackBerry device application retrieved GPS information.............................................................. 7

Maintain a connection with GPS satellites......................................................................................................................... 7

Get continuous GPS readings using the cell site mode..................................................................................................... 7

Get GPS information during a call....................................................................................................................................... 7

Get location information updates........................................................................................................................................ 8

Change the criteria for obtaining location information..................................................................................................... 8

2BlackBerry Maps location information..................................................................................................................................... 9

Displaying location information on a BlackBerry device............................................................................................................ 9

Displaying location information in BlackBerry Maps......................................................................................................... 9

Open BlackBerry Maps to display the default map view................................................................................................... 12

Open BlackBerry Maps to display a location on a map..................................................................................................... 13

Open BlackBerry Maps to display multiple locations on a map....................................................................................... 14

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

Open BlackBerry Maps to display a custom map view...................................................................................................... 17

Open BlackBerry Maps to display the location for an address in the contact list.......................................................... 17

Start a BlackBerry device application from BlackBerry Maps........................................................................................... 19

Displaying location information in your application................................................................................................................... 23

Work with a map that displays in a UI field......................................................................................................................... 23

Converting latitudinal and longitudinal coordinates to pixel values............................................................................... 24

Requesting location information for an address......................................................................................................................... 25

Retrieve location information for an address stored in address fields............................................................................. 25

Retrieve location information for an address stored in a String....................................................................................... 26

Cancel a request for location information for an address................................................................................................. 26

Determine why a request for location information was unsuccessful............................................................................. 26

Open BlackBerry Maps from the browser.................................................................................................................................... 26

Clearing data from the map........................................................................................................................................................... 27

Clear data from a location document with an id attribute................................................................................................ 27

Clear data from all location documents with an id attribute............................................................................................ 27

Clear data from specific location documents with an id attribute................................................................................... 28

Clear all location data from a map....................................................................................................................................... 28

3 Glossary......................................................................................................................................................................................... 29

4 Provide feedback......................................................................................................................................................................... 30

5 Legal notice.................................................................................................................................................................................. 31

GPS location information 1

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.

Specifying the source of GPS location information

GPS location information might be unavailable if the BlackBerry® device cannot receive signals from GPS satellites. This situation

can occur when something is obstructing 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 then pass the instance

to LocationProvider.getInstance().

• cell site: Use this mode to get location information from cell site towers. This mode allows a BlackBerry device application

to retrieve location information faster than the assisted and autonomous modes. However, the accuracy of the location

information is low-level and does not provide tracking information such as speed or route information. 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 allows a BlackBerry device

application to retrieve location information faster than the autonomous mode and more accurately than the cell site mode.

To use this mode requires wireless network coverage, and the BlackBerry device and the wireless service provider must

support this 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 allows a BlackBerry device application to retrieve location information that has high-

accuracy, and does not require assistance from the wireless network. However, the speed at which this mode retrieves

location information is slower than the other modes.

Get location information from cell site towers

1. Create an instance of a Criteria object.

Criteria criteria = new Criteria();

Development Guide GPS location information

2. Invoke criteria.setHorizontalAccuracy(NO_REQUIREMENT) to specify longitudinal accuracy is not

required.

3. Invoke criteria.setVerticalAccuracy(NO_REQUIREMENT) to specify latitudinal accuracy is not

required.

4. Invoke criteria.setCostAllowed(true) to specify that this mode can incur cost.

5. Invoke setPreferredPowerConsumption(POWER_USAGE_LOW) to specify power consumption is low.

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

LocationProvider provider = LocationProvider.getInstance(criteria);

Get location information from GPS satellites using PDE

1. Create an instance of a Criteria object.

Criteria criteria = new Criteria();

2. Invoke criteria.setHorizontalAccuracy(NO_REQUIREMENT) to specify longitudinal accuracy is not

required.

3. Invoke criteria.setVerticalAccuracy(NO_REQUIREMENT) to specify latitudinal accuracy is not

required.

4. Invoke criteria.setCostAllowed(true) to specify that this mode can incur cost.

5. Invoke criteria.setPreferredPowerConsumption(int level) using one of

POWER_USAGE_MEDIUM, or NO_REQUIREMENT as the parameter to specify power consumption is medium or not

required.

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

LocationProvider provider = LocationProvider.getInstance(criteria);

Get location information from GPS satellites and the GPS receiver on a BlackBerry device

1. Create an instance of a Criteria object.

Criteria criteria = new Criteria();

2. Complete one of the following tasks:

Task Steps

Specify a level of

accuracy for

longitudinal and

latitudinal data.

a. Invoke criteria.setHorizontalAccuracy(int accuracy) using an

integer value that represents the accuracy, in meters.

b. Invoke criteria.setVerticalAccuracy(int accuracy) using an

integer value that represents the accuracy, in meters.

Development Guide Specifying the source of GPS location information

Task Steps

Specify that no level

of accuracy for

longitudinal and

latitudinal data is

required,

a. Invoke criteria.setHorizontalAccuracy(NO_REQUIREMENT).

b. Invoke criteria.setVerticalAccuracy(NO_REQUIREMENT).

3. Invoke criteria.setCostAllowed(true) to specify that this mode can incur cost.

4. Invoke criteria.setPreferredPowerConsumption(POWER_USAGE_HIGH) to specify power

consumption is high.

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

LocationProvider provider = LocationProvider.getInstance(criteria);

Get location information from the GPS receiver on a BlackBerry device

1. Create an instance of a Criteria object.

Criteria criteria = new Criteria();

2. Complete one of the following tasks to get location information using the GPS receiver on a BlackBerry device :

Task Steps

Specify a level of accuracy,

with no cost and no power

consumption.

a. Invokecriteria.setHorizontalAccuracy(int accuracy) using

an integer value that represents the accuracy, in meters.

b. Invoke criteria.setVerticalAccuracy(int accuracy) using an

integer value that represents the accuracy, in meters.

c. Invoke criteria.setCostAllowed(false).

Specify a level of accuracy,

with cost and variable

power consumption.

a. Invokecriteria.setHorizontalAccuracy(int accuracy) using

an integer value that represents the accuracy, in meters.

b. Invoke criteria.setVerticalAccuracy(int accuracy) using an

integer value that represents the accuracy, in meters.

c. Invoke criteria.setCostAllowed(true).

d. Invoke

criteria.setPreferredPowerConsumption(int level) using

one of POWER_USAGE_LOW, POWER_USAGE_MEDIUM,or

NO_REQUIREMENT as the parameter.

Development Guide Specifying the source of GPS location information

Task Steps

Specify a level of accuracy,

with no cost and variable

power consumption.

a. Invoke criteria.setHorizontalAccuracy(NO_REQUIREMENT).

b. Invoke criteria.setVerticalAccuracy(NO_REQUIREMENT).

c. Invoke criteria.setCostAllowed(false).

d. Invoke

criteria.setPreferredPowerConsumption(int level) using

one of POWER_USAGE_MEDIUM, POWER_USAGE_HIGH, or

NO_REQUIREMENT as the parameter.

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

LocationProvider provider = LocationProvider.getInstance(criteria);

Getting GPS location information

Specify a response time for getting the location of the BlackBerry device

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

Get the location information for a BlackBerry device

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

try {

// Specify -1 to have the implementation use its default timeout value

// for this provider.

Location location = provider.getLocation(-1);

} catch (Exception e) {

// handle LocationException, InterruptedException, SecurityException

// and IllegalArgumentException

}

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

Invoke location.getSpeed().

Location location = provider.getLocation(-1);

float speed = mylocation.getSpeed();

Development Guide Getting GPS location information

Get the course of the BlackBerry device, in degrees

Invoke location.getCourse().

Location location = provider.getLocation(-1);

float course = mylocation.getCourse();

Get the number of GPS satellites that a BlackBerry device tracks

1. Invoke the Location.getExtraInfo() method using the NMEA MIME type as a parameter. The method returns

an encoded String that contains information on the number of GPS satellites.

Location location = provider.getLocation(-1);

String encodedStr = mylocation.getExtraInfo("application/X-jsr179-

location-nmea");

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

Get the time that a BlackBerry device application retrieved GPS information

Invoke Location.getTimeStamp(). The time is retrieved from the GPS receiver on the BlackBerry® device.

Location location = provider.getLocation(-1);

myLocation.getTimeStamp();

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 less

than 10 seconds.

Define a LocationListener with an interval value that is less than 10 seconds.

LocationProvider provider = LocationProvider.getInstance(criteria);

provider.setLocationListener(loclistener, 9, -1, -1);

Get continuous GPS readings using the cell site mode

Invoke the LocationProvider.getLocation() method within code that simulates the retrieval of GPS

information at fixed intervals.

Get GPS information during a call

Use the autonomous mode to retrieve GPS information.

Development Guide Getting GPS location information

Get location information updates

You can associate only one LocationListener object with a particular provider for GPS location information. The

BlackBerry® device application typically listens for updates on a separate thread.

1. Implement the LocationListener interface.

2. To register your implementation, invoke LocationProvider.setLocationListener().

Change the criteria for obtaining location information

1. Create a new Criteria object.

Criteria criteria2 = new Criteria();

2. Invoke the setHorizontalAccuracy(), setVerticalAccuracy(), setCostAllowed(), and

setPreferredPowerConsumption() methods of the new Criteria object to specify the new criteria.

3. Invoke LocationProvider.reset().

LocationProvider.reset();

4. Specify the LocationListener to null.

provider.setLocationListener(null, -1, -1, -1);

5. Invoke LocationProvider.getInstance() using the new Criteria object as a parameter to create a new

instance of a LocationProvider.

provider = LocationProvider.getInstance(criteria2);

6. Specify the LocationListener.

provider.setLocationListener(LocationListener listener, int interval, int

timeout, int maxAge);

Development Guide Getting GPS location information

Ce manuel convient aux modèles suivants

Table des matières

Autres manuels Blackbe;rry Logiciel

Blackbe;rry

Blackbe;rry PRD-10459-016 - Enterprise Server For MS... Mode d’emploi

Blackbe;rry

Blackbe;rry smartphone Manuel utilisateur

Blackbe;rry

Blackbe;rry INTERNET SERVICE Manuel utilisateur

Blackbe;rry

Blackbe;rry CLIENT FOR IBM LOTUS QUICKR - J2EE Manuel utilisateur

Blackbe;rry

Blackbe;rry JAVA DEVELOPMENT ENVIRONMENT - - MULTIMEDIA - DEVELOPMENT... Manuel utilisateur

Blackbe;rry

Blackbe;rry AIM service Mode d’emploi

Blackbe;rry

Blackbe;rry Smart Phone Manuel utilisateur

Blackbe;rry

Blackbe;rry MEDIA SYNC - VERWENDEN DES BROWSERS AUF IHREM... Manuel utilisateur

Blackbe;rry

Blackbe;rry YAHOO MESSENGER - LEARN MORE Manuel utilisateur

Blackbe;rry

Blackbe;rry TICKETMASTER - LEARN MORE Manuel utilisateur

Blackbe;rry

Blackbe;rry YAHOO! MESSENGER FOR SMARTPHONES Manuel utilisateur

Blackbe;rry

Blackbe;rry Amazon MP3 Mode d’emploi

Blackbe;rry

Blackbe;rry APP WORLD STOREFRONT 2.1 Mode d’emploi

Blackbe;rry

Blackbe;rry AOL INSTANT MESSENGER SERVICE FOR... Manuel utilisateur

Blackbe;rry

Blackbe;rry MESSENGER - VERWENDEN DES BROWSERS AUF IHREM... Manuel utilisateur

Blackbe;rry

Blackbe;rry CLIENT FOR IBM LOTUS SAMETIME - S V.2.5.20 Mode d’emploi

Blackbe;rry

Blackbe;rry Sales Client for SAP CRM Manuel utilisateur

Blackbe;rry

Blackbe;rry JAVA DEVELOPMENT ENVIRONMENT - - DEVICE APPLICATIONS INTEGRATION - DEVELOPMENT... Guide de configuration rapide

Blackbe;rry

Blackbe;rry TWITTER FOR BLACKBERRY SMARTPHONES 1.0 Mode d’emploi

Blackbe;rry

Blackbe;rry PROFESSIONAL SOFTWARE FOR IBM LOTUS DOMINO Manuel utilisateur

Blackbe;rry

Blackbe;rry JAVA DEVELOPMENT ENVIRONMENT - - CRYPTOGRAPHIC SMART CARD DRIVER - DEVELOPMENT... Manuel utilisateur

Blackbe;rry

Blackbe;rry ENTERPRISE SERVER FOR MICROSOFT EXCHANGE - CALENDAR SYNCHRONIZATION TOOL - TECHNICAL... Manuel utilisateur

Blackbe;rry

Blackbe;rry AMAZON MP3 - ANNEXE 472 V1.0 Manuel utilisateur

Blackbe;rry

Blackbe;rry GOOGLE TALK - LEARN MORE Manuel utilisateur

Manuels Logiciel populaires d'autres marques

COMPRO

COMPRO COMPROFM Manuel utilisateur

Muratec

Muratec OFFICEBRIDGE ONLINE Manuel utilisateur

Oracle

Oracle Contact Center Anywhere 8.1 Manuel utilisateur

Adobe

Adobe 65007312 - Photoshop Lightroom Manuel

Avaya

Avaya NULL One-X for RIM Blackberry Manuel utilisateur

HP ProLiant BL420c Manuel utilisateur

PS Audio

PS Audio PowerPlay Manuel du propriétaire

Brady

Brady LOCKOUT PRO 3.0 Manuel de service

Avaya

Avaya Interaction Center Manuel utilisateur

Texas Instruments

Texas Instruments TI-83 Plus Silver Edition Manuel

Novell

Novell GROUPWISE 8 - INTERNET AGENT Manuel utilisateur

Oracle

Oracle Application 9i Manuel utilisateur

Acer

Acer RDM Manuel utilisateur

Canon

Canon Vixia HF21 Manuel utilisateur

Canon

Canon ZR950 Manuel utilisateur

Samsung

Samsung Auto Backup Manuel utilisateur

Polycom

Polycom Vortex EF2201 Instructions d'installation et d'utilisation

Brocade Communications Systems

Brocade Communications Systems Brocade 8/12c Manuel utilisateur

Blackbe;rry JAVA DEVELOPMENT ENVIRONMENT - - GPS AND MAPS - DEVELOPMENT... Manuel utilisateur

Manuels Logiciel populaires d'autres marques