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

Questo manuale è adatto per i seguenti modelli

Indice

Altri manuali Blackbe;rry Software

Blackbe;rry

Blackbe;rry CLIENT FOR USE WITH MICROSOFT OFFICE COMMUNICATIONS SERVER... Manuale utente

Blackbe;rry

Blackbe;rry INTERNET SERVICE - FEATURE AND TECHNICAL OVERVIEW... Guida all'installazione

Blackbe;rry

Blackbe;rry JAVA DEVELOPMENT ENVIRONMENT - - COMPONENT PACKAGE - RELEASE... Manuale di istruzioni

Blackbe;rry

Blackbe;rry MYSPACE - VERWENDEN DES BROWSERS AUF IHREM... Manuale utente

Blackbe;rry

Blackbe;rry TIVO - LEARN MORE Manuale utente

Blackbe;rry

Blackbe;rry PRD-10459-003 - Enterprise Server For IBM Lotus... Manuale di istruzioni

Blackbe;rry

Blackbe;rry PROFESSIONAL SOFTWARE FOR IBM LOTUS DOMINO - - RELEASE... Manuale di istruzioni

Blackbe;rry

Blackbe;rry ICQ - RELEASE NOTES V2.5 Manuale di istruzioni

Blackbe;rry

Blackbe;rry CHALK PUSHCAST PLAYER Manuale utente

Blackbe;rry

Blackbe;rry FACEBOOK FOR BLACKBERRY SMARTPHONES 1.9 - RELEASE... Manuale di istruzioni

Blackbe;rry

Blackbe;rry PROFESSIONAL SOFTWARE FOR MICROSOFT EXCHANGE - - RELEASE... Manuale di istruzioni

Blackbe;rry

Blackbe;rry PRD-10459-016 - Enterprise Server For MS... Manuale di istruzioni

Blackbe;rry

Blackbe;rry ENTERPRISE SOLUTION SECURITY - SECURITY FOR DEVICES WITH BLUETOOTH WIRELESS TECHNOLOGY -... Guida all'installazione

Blackbe;rry

Blackbe;rry MEDIA SYNC - VERWENDEN DES BROWSERS AUF IHREM... Manuale utente

Blackbe;rry

Blackbe;rry BROWSER VERSION 4.7.0 - FUNDAMENTALS GUIDE Manuale utente

Blackbe;rry

Blackbe;rry ENTERPRISE INSTANT MESSAGING 2.5.46 - S Manuale di istruzioni

Blackbe;rry

Blackbe;rry PROFESSIONAL SOFTWARE FOR IBM LOTUS DOMINO - - MIGRATION... Manuale utente

Blackbe;rry

Blackbe;rry CHALK PUSHCAST PLAYER 5.6 Manuale utente

Blackbe;rry

Blackbe;rry PRESENTER - V1.2 Manuale utente

Blackbe;rry

Blackbe;rry Messenger Manuale utente

Blackbe;rry

Blackbe;rry Sales Client for SAP CRM Manuale utente

Blackbe;rry

Blackbe;rry CLIENT FOR IBM LOTUS SAMETIME 2.5.40 - S Manuale di istruzioni

Blackbe;rry

Blackbe;rry APP WORLD - SPORT CASE Manuale utente

Blackbe;rry

Blackbe;rry ENTERPRISE SERVER FOR MICROSOFT EXCHANGE - CALENDAR SYNCHRONIZATION TOOL - TECHNICAL... Manuale utente

Manuali Software popolari di altre marche

COMPRO

COMPRO COMPROFM Manuale utente

Muratec

Muratec OFFICEBRIDGE ONLINE Manuale utente

Oracle

Oracle Contact Center Anywhere 8.1 Manuale utente

Adobe

Adobe 65007312 - Photoshop Lightroom Manuale

Avaya

Avaya NULL One-X for RIM Blackberry Manuale utente

HP ProLiant BL420c Manuale utente

PS Audio

PS Audio PowerPlay Manuale del proprietario

Brady

Brady LOCKOUT PRO 3.0 Manuale di servizio

Avaya

Avaya Interaction Center Manuale utente

Texas Instruments

Texas Instruments TI-83 Plus Silver Edition Manuale

Novell

Novell GROUPWISE 8 - INTERNET AGENT Manuale utente

Oracle

Oracle Application 9i Manuale utente

Acer

Acer RDM Manuale utente

Canon

Canon Vixia HF21 Manuale utente

Canon

Canon ZR950 Manuale utente

Samsung

Samsung Auto Backup Manuale utente

Polycom

Polycom Vortex EF2201 Istruzioni per l'installazione e il funzionamento

Brocade Communications Systems

Brocade Communications Systems Brocade 8/12c Manuale utente

Blackbe;rry JAVA DEVELOPMENT ENVIRONMENT - - GPS AND MAPS - DEVELOPMENT... Manuale utente

Manuali Software popolari di altre marche