Blackberry Java Application Development Guide 863631 1109120059 001 5.0 Beta US

8/8/2019 Blackberry Java Application Development Guide 863631 1109120059 001 5.0 Beta US

1/81

BlackBerry Java Application

Location-Based Services Version: 5.0

Development Guide


2/81

Published: 2010-04-06SWD-863631-0401094559-001


3/81

Contents 1 GPS overview................................................................................................................................................................................ 4

2 Specifying the GPS mode........................................................................................................................................................... 6Specifying the GPS mode by using JSR 179................................................................................................................................. 6

Specify the GPS mode (JSR 179)........................................................................................................................................... 6Criteria mapping properties.................................................................................................................................................. 7

Specifying the GPS mode by using BlackBerry extensions to JSR 179..................................................................................... 8GPS Modes.............................................................................................................................................................................. 8Specify the GPS mode by using BlackBerry extensions to JSR 179.................................................................................. 9

Retrieving location information by using the assisted GPS mode............................................................................................ 11Assisted mode using a PDE server....................................................................................................................................... 11 Verify that PDE server information is required................................................................................................................... 11Specify the PDE server information..................................................................................................................................... 11

Code sample: Specifying the PDE server information....................................................................................................... 13

3 Retrieving a location provider.................................................................................................................................. ................. 15Retrieve a location provider by using the LocationProvider class............................................................................................. 15Controlling location tracking by using the BlackBerryLocationProvider class........................................................................ 17Control location tracking by using the BlackBerryLocationProvider class............................................................................... 18

Code sample: Using the BlackBerryLocationProvider class to control location tracking.............................................. 19

Retrieve a location provider by using the BlackBerryLocationProvider class.......................................................................... 21

4 Retrieving the location of a BlackBerry device....................................................................................................................... 22Retrieve the location of a BlackBerry device............................................................................................................................... 22

Code sample: Retrieving the GPS location of a BlackBerry device.................................................................................. 23Retrieve the location of a BlackBerry device by specifying continuous fix requests.............................................................. 24

Code sample: Retrieving the GPS location of a BlackBerry device by using continuous fix requests......................... 26

Retrieving location information by using the Location class..................................................................................................... 27Retrieve location information by using the Location class................................................................................................ 27

Retrieving location information by using the BlackBerryLocation class.................................................................................. 30Retrieve satellite information by using the BlackBerryLocation class............................................................................. 30

Change the criteria to receive location information................................................................................................................... 34Code sample: Changing the criteria to retrieve location information............................................................................. 35

Error handling.................................................................................................................................................................................. 37


4/81

Handle errors (JSR 179).................................................................................................................................................................. 37

Handle errors (BlackBerry extensions to JSR 179)...................................................................................................................... 38

5 Geocoding and reverse geocoding........................................................................................................................................... 41Retrieve geospatial coordindates for an address by using geocoding..................................................................................... 41Retrieve an address by using reverse geocoding........................................................................................................................ 43

6 BlackBerry Maps.......................................................................................................................................................................... 46

Opening BlackBerry Maps from your application....................................................................................................................... 46Open BlackBerry Maps by using the default settings................................................................................................................ 46Open BlackBerry Maps by using information from a contact................................................................................................... 47Open BlackBerry Maps by using specific coordinates................................................................................................................ 49Open BlackBerry Maps by using a landmark............................................................................................................................... 50Opening BlackBerry Maps by using a location document......................................................................................................... 52

XML element: ................................................................................................................................................................ 52

XML element: ....................................................................................................................................................... 53XML element: ..................................................................................................................................................... 55Display and clear locations on a map by using a location document.............................................................................. 55Display and clear a route on a map by using a location document................................................................................. 57

Open BlackBerry Maps by using a local search.......................................................................................................................... 59Using KML documents with BlackBerry Maps............................................................................................................................ 60

Supported KML elements...................................................................................................................................................... 60

Create a basic KML document.............................................................................................................................................. 61Displaying KML overlays on BlackBerry Maps.................................................................................................................... 61Invoke BlackBerry Maps by using a KML document.......................................................................................................... 62

Opening BlackBerry Maps from the BlackBerry Browser........................................................................................................... 63Retrieving a GPS location by using a web page.......................................................................................................................... 63Retrieve a GPS location by using a web page............................................................................................................................. 65Embedding a map in an application............................................................................................................................................. 66

Embed a map in an application............................................................................................................................................ 67

7 Glossary......................................................................................................................................................................................... 73

8 Provide feedback........................................................................................................................................................ ................. 74

9 Document revision history......................................................................................................................................................... 75


5/81

10 Legal notice.................................................................................................................................................................................. 77


6/81

GPS overview 1 You can allow a BlackBerry device application to retrieve the GPS location of a BlackBerry device. The values for the locationinformation are returned as the coordinates for latitude, longitude, and altitude.

The GPS mode that you specify to retrieve the location information depends on the type of application that you want to develop. The GPS modes include the autonomous mode, assisted mode, and cell site mode. The GPS mode can affect the initial speed of a GPS fix and the level of location accuracy. For example, a weather application might specify a cell site mode, which can quicklyprovide an approximate location. For more information about the BlackBerry device models and their available correspondingGPS modes, visit http://www.blackberry.com/knowledgecenterpublic/ to read article DB-00615.

To retrieve location information, you can use the JSR 179 Location API for Java ME in thejavax.microedition.location package, or the BlackBerry extension to JSR 179 in thenet.rim.device.api.gps package.

The JSR 179 Location API for Java MEis supported on BlackBerry devices that run BlackBerry Device Software 4.0.2 or later.

The BlackBerry extensions to JSR 179 is supported on BlackBerry devices that run BlackBerry Device Software 5.0.0 or later.

Retrieving the GPS location of a BlackBerry device involves the following actions:

Specifying the GPS mode Retrieving a location provider Making a GPS request that is based on the frequency of the GPS fix Retrieving the GPS location of a BlackBerry device

Code sample: Specifying the GPS mode/* JSR 179 */Criteria myCriteria = new Criteria();

/* JSR 179 extension */BlackBerryCriteria myBlackBerryCriteria = new BlackBerryCriteria();

Code sample: Retrieving a location provider/* JSR 179 */LocationProvider myProvider = LocationProvider.getInstance(myCriteria);

/* JSR 179 extension */BlackBerryLocationProvider myBlackBerryProvider =

(BlackBerryLocationProvider) LocationProvider.getInstance(myBlackBerryCriteria);

Code sample: Makin g a GPS request that is based on the frequ ency of the GPS fix /*

* Single GPS fix*/

/* JSR 179 */

Development Guide GPS overview

4
http://www.blackberry.com/knowledgecenterpublic/http://www.blackberry.com/knowledgecenterpublic/


7/81

Location myLoc = myProvider.getLocation();

/* JSR 179 extension */BlackBerryLocation myBlackBerryLoc = myBlackBerryProvider.getLocation();

/** Continuous GPS fixes*/

/* JSR 179 */myProvider.setLocationListener();

/* JSR 179 extension */myBlackBerryProvider.setLocationListener();

Code sample: Retrieving the GPS location of a BlackBerry device/* JSR 179 */double lat = myLoc.getQualifiedCoordinates().getLatitude();

/* JSR 179 extension */double lat = myBlackBerryLoc.getQualifiedCoordinates().getLatitude();

Development Guide GPS overview

5


8/81

Specifying the GPS mode 2 You must specify the GPS mode to retrieve the location of a BlackBerry device. GPS modes include autonomous, assisted andcell site.

Autonomous mode relies on GPS satellites only. Assisted mode relies on GPS satellites and servers on the wireless network. Cell site mode relies on the geolocation service, or the wireless network to provide the location information of the current

base station.

Specifying the GPS mode by using JSR 179If you use the JSR 179 package, you must specify the properties for the GPS mode in thejavax.microedition.location.Criteria class. The application cannot set the GPS mode directly. If a BlackBerrydevice is paired with a Bluetooth enabled GPS device to determine location, then the Bluetooth enabled device will be usedregardless of how the Criteria object has been configured.

Specify the GPS mode (JSR 179) The JSR 179 Location API is supported on BlackBerry devices that run BlackBerry Device Software 4.0.2 or later.

1. Import the required class.

import javax.microedition.location.Criteria;

2. Create a class and constructor.public class handleGPS{

public handleGPS(){}

}

3. In the constructor, create an instance of the Criteria class. Create a variable to specify a GPS mode.

Criteria myCriteria = new Criteria();int myMode = 2; // AUTONOMOUS

4. In the constructor, map the properties for each GPS mode by invoking the corresponding set method for each property.

switch ( myMode ){

case 0: // CELLSITEmyCriteria.setPreferredPowerConsumption(Criteria.POWER_USAGE_LOW);myCriteria.setHorizontalAccuracy(Criteria.NO_REQUIREMENT);

Development Guide Specifying the GPS mode

6


9/81

myCriteria.setVerticalAccuracy(Criteria.NO_REQUIREMENT);myCriteria.setCostAllowed(true);break;

case 1: // ASSISTmyCriteria.setPreferredPowerConsumption(Criteria.POWER_USAGE_MEDIUM);myCriteria.setHorizontalAccuracy(100);myCriteria.setVerticalAccuracy(100);myCriteria.setCostAllowed(true);break;

case 2: // AUTONOMOUSmyCriteria.setCostAllowed(false);break;

}

Criteria mapping propertiesIf you use the JSR 179 Location API for to specify a GPS mode, you must map the following properties for theCriteria class.

GPS modeHorizontalaccuracy

Verticalaccuracy

Cost allowedPower usagelevel

Response time Fix frequency

Autonomous required required no any any single ormultiple

Autonomous not required not required no medium, high,or not required

any single ormultiple

Assisted ordata optimal

not required not required yes medium, high,or not required

any single ormultiple

Assisted orspeed optimal

required required yes high quality of service

multiple

Assisted or MS-Based

required required yes medium or not required

quality of service

multiple

Assisted oraccuracyoptimal

required required yes high quality of service

single

Assisted or MS-Assisted

required required yes medium or not required

quality of service

single

Cell site not required not required yes low any any

Development Guide Specifying the GPS mode by using JSR 179

7


10/81


11/81

GPS mode Description

autonomous This mode uses the GPS receiver on the BlackBerry device to retrieve location information. This modecannot be used indoors or in close proximity to many physical obstructions, and it can take severalminutes to fully synchronize with four or more satellites for the first GPS fix.

assisted This mode uses the wireless network to retrieve satellite information. This mode can achieve a fast retrieval of the first GPS fix.

MS-based This mode uses the wireless network to retrieve satellite information. After the first GPS fix, theBlackBerry device relies on the autonomous mode to more accurately retrieve subsequent GPS fixes. The MS-based GPS mode applies to BlackBerry devices that use the Qualcomm gpsOne andoperate on the CDMA network.

MS-assisted This mode uses the wireless network to retrieve satellite information. This mode applies to BlackBerrydevices that use the Qualcomm gpsOne and operate on the CDMA network.

speed optimal This mode focuses on providing the fastest possible GPS fix that meets the criteria that is set by theapplication. This mode applies to BlackBerry devices that use the Qualcomm gpsOne and operate

on the CDMA network.accuracy optimal This mode is determined based on the accuracy of a GPS fix. This mode either relies on network

information, or performs local calculations, depending on what is the most accurate and available. This mode applies to BlackBerry devices that use the Qualcomm gpsOne and operate on the CDMAnetwork.

data optimal This mode is determined based on the least amount of network traffic that is required for a GPS fix. This mode either relies on network information, or performs local calculations, depending on what

is available that uses the least amount of data traffic. This mode applies to BlackBerry devices that use the Qualcomm gpsOne and operate on the CDMA network.

Bluetooth enabledGPS

This mode is determined by the configuration of the Bluetooth enabled GPS device. The configurationof a Bluetooth enabled GPS device that is paired with a BlackBerry device cannot be specified in aCriteria object.

Specify the GPS mode by using BlackBerry extensions to JSR 179 The BlackBerry extensions to JSR 179 are supported on BlackBerry devices that run BlackBerry Device Software 5.0.0 or later.


import net.rim.device.api.gps.*;

2. Create a class and constructor.

Development Guide Specifying the GPS mode by using BlackBerry extensions to JSR 179

9


12/81

public class handleGPS

{ BlackBerryCriteria myCriteria;


}

3. In the constructor, create a try/catch block. In this block, create an instance of the BlackBerryCriteria class bypassing the GPS mode as a parameter to the constructor.

try{

myCriteria = new BlackBerryCriteria(GPSInfo.GPS_MODE_ASSIST);}catch ( UnsupportedOperationException ex ){

return;}

4. In the constructor, invoke setFailloverMode() to specify the GPS failover mode to use if the first GPS mode that youspecify cannot retrieve a GPS fix. InvokesetSubsequentMode() to specify a subsequent GPS mode to use after asuccessful first fix is retrieved.

myCriteria.setFailoverMode(GPSInfo.GPS_MODE_AUTONOMOUS, 3, 100);myCriteria.setSubsequentMode(GPSInfo.GPS_MODE_AUTONOMOUS);

5. To verify if a GPS mode is supported, invokeGPSInfo.isGPSModeAvailable() and pass the GPS mode as aparameter. Invoke setMode() to specify the GPS mode, if the mode is supported.

public class handleGPS{

public handleGPS(){

BlackBerryCriteria myCriteria = new BlackBerryCriteria();

if (GPSInfo.isGPSModeAvailable(GPSInfo.GPS_MODE_ASSIST))myCriteria.setMode(GPSInfo.GPS_MODE_ASSIST);

else if (GPSInfo.isGPSModeAvailable(GPSInfo.GPS_MODE_AUTONOMOUS))myCriteria.setMode(GPSInfo.GPS_MODE_AUTONOMOUS);

}}

Development Guide

10


13/81

Retrieving location information by using the assisted GPS mode

Assisted mode using a PDE server The assisted mode can be used with BlackBerry devices that are associated with a CDMA network that utilizes PDE servertechnology. The assisted mode is designed to provide fast retrieval of a GPS fix.

Assisted GPS capabilities are currently defined by wireless service providers. In many instances, you must enter into a formalrelationship with wireless service providers before you can connect to their PDE server.

Verify that PDE server information is requiredBefore using assisted mode with a PDE server, you must verify whether PDE server information is required.


import net.rim.device.api.gps.GPSSettings;2. Create a class and constructor. In the constructor, invoke isPDEInfoRequired() to verify if you need to specify the

PDE server information to use assisted mode.

public class checkPDE{

public checkPDE(){

if ( isPDEInfoRequired(GPSInfo.GPS_MODE_ASSIST))

{ // set up PDE server access}

}}

Specify the PDE server informationBefore you begin:

You must have the user ID, password, IP address and port number that the wireless service provider uses for their PDE server.

1. Import the required classes.

import net.rim.device.api.gps.*;import javax.microedition.location.*;

2. Create a class and a constructor.

Development Guide Retrieving location information by using the assisted GPS mode

11


14/81


static GPSThread gpsThread;


}

3. In the constructor, create and start an instance of the Thread class.

gpsThread = new GPSThread();gpsThread.start();

4. In the class, create a private static class that extends Thread , and create a run() method.

private static class GPSThread extends Thread{

public void run(){}

}

5. In the run() method of the private class, invoke isGPSModeAvailable() passing GPS_MODE_ASSIST as aparameter to determine if the assisted mode is available on the BlackBerry device. Invoke isPDEInfoRequired() todetermine if you need to specify PDE server information. If PDE server information is required, create an instance of theBlackBerryCriteria class by passing GPS_MODE_ASSIST as a parameter to the constructor.

if ( !GPSInfo.isGPSModeAvailable(GPSInfo.GPS_MODE_ASSIST) ||!GPSSettings.isPDEInfoRequired(GPSInfo.GPS_MODE_ASSIST))return;

BlackBerryCriteria myCriteria = new BlackBerryCriteria(GPSInfo.GPS_MODE_ASSIST);

6. In the run() method of the private class, create a try/catch block. In the block, associate an instance of theBlackBerryCriteria class with a BlackBerryLocationProvider object. Create and specify the user ID,password, and IP address String objects, and the port ID. Combine the String objects into a single String . InvokesetPDEInfo() to specify the PDE server IP address and port number of the BlackBerry device.

try{

BlackBerryLocationProvider myProvider =(BlackBerryLocationProvider)LocationProvider.getInstance(myCriteria);

String user = "UserID";String pass = "Password";String ip = "127.0.0.1";int port = 0;String str = ip + ";" + user + ";" + pass;GPSSettings.setPDEInfo(str, port);


12

D l G id R i i l i i f i b i h i d GPS d


15/81

try{

BlackBerryLocation myLocation =(BlackBerryLocation)myProvider.getLocation(10);

}catch ( InterruptedException iex ){}catch ( LocationException lex ){}

}catch ( LocationException lex ){}

return;

Code sample: Specifying the PDE server information


public class handleGPS{static GPSThread gpsThread;

public handleGPS(){


}

private static class GPSThread extends Thread{public void run(){

if ( !GPSInfo.isGPSModeAvailable(GPSInfo.GPS_MODE_ASSIST) ||!GPSSettings.isPDEInfoRequired(GPSInfo.GPS_MODE_ASSIST))return;

BlackBerryCriteria myCriteria =new BlackBerryCriteria(GPSInfo.GPS_MODE_ASSIST);

try{


String user = "UserID";String pass = "Password";String ip = "127.0.0.1";int port = 0;


13



16/81

String str = ip + ";" + user + ";" + pass;GPSSettings.setPDEInfo(str, port);

try{


}catch ( InterruptedException iex ){

return;}catch ( LocationException lex ){

return;}

}catch ( LocationException lex ){

return;}return;

}}

}


14


17/81

Development Guide Retrieve a location provider by using the LocationProvider class


18/81

myCriteria.setPreferredPowerConsumption(Criteria.POWER_USAGE_LOW);myCriteria.setHorizontalAccuracy(Criteria.NO_REQUIREMENT);myCriteria.setVerticalAccuracy(Criteria.NO_REQUIREMENT);myCriteria.setCostAllowed(true);break;

case 1: // ASSISTmyCriteria.setPreferredPowerConsumption(Criteria.POWER_USAGE_MEDIUM);myCriteria.setHorizontalAccuracy(100);myCriteria.setVerticalAccuracy(100);myCriteria.setCostAllowed(true);break;

case 2: // AUTONOMOUSmyCriteria.setCostAllowed(false);break;

}

5. In the constructor, create a try/catch block. Within the block, create aLocationProvider object by invokinggetInstance() .

try

{ LocationProvider myProvider =LocationProvider.getInstance(myCriteria);


return;}

Code sample: Retrieving a location provider by using the LocationProvider classimport javax.microedition.location.*;


public handleGPS(){

Criteria myCriteria = new Criteria();

int myMode = 2; // AUTONOMOUS

switch ( myMode ){

case 0: // CELLSITEmyCriteria.setPreferredPowerConsumption(Criteria.POWER_USAGE_LOW);myCriteria.setHorizontalAccuracy(Criteria.NO_REQUIREMENT);myCriteria.setVerticalAccuracy(Criteria.NO_REQUIREMENT);myCriteria.setCostAllowed(true);break;

p p y g

16


19/81

Development Guide Control location tracking by using the BlackBerryLocationProvider class


20/81

Control location tracking by using the BlackBerryLocationProvider class You can pause, resume, and stop location tracking by using thenet.rim.device.api.gps.BlackBerryLocationProvider class.1. Import the required classes.


2. Create a new class and a constructor.


static BlackBerryLocationProvider myProvider;


}

3. In the constructor, create a try/catch block. In the block, create an instance of the BlackBerryCriteria class bypassing the GPS mode as a parameter to the constructor.

try{

BlackBerryCriteria myCriteria =new BlackBerryCriteria(GPSInfo.GPS_MODE_AUTONOMOUS);

}catch ( UnsupportedOperationException uoex ){

return;}

4. In the try part of the block, create a new try/catch block. In this block, create an instance of theBlackBerryLocationProvider class by retrieving an instance of the BlackBerryCriteria class. InvokesetLocationListener() by passing the interval value, timeout value, and maximum age as parameters to add aLocationListener .

try{

myProvider = (BlackBerryLocationProvider)LocationProvider.getInstance(myCriteria);

myProvider.setLocationListener(new handleGPSListener(), 10, -1, -1);}catch ( LocationException lex ){

return;}

18



21/81

myProvider.pauseLocationTracking(30);myProvider.resumeLocationTracking();

myProvider.stopLocationTracking();5. Outside of the try/catch block, invokepauseLocationTracking() , resumeLocationTracking() , or

stopLocationTracking() to pause, resume, or stop location tracking.

myProvider.pauseLocationTracking(30);myProvider.resumeLocationTracking();myProvider.stopLocationTracking();

6. In the class, implement the LocationListener interface. Implement the basic framework for the locationUpdated

() method, and the providerStateChanged() method.public static class handleGPSListener implements LocationListener{

public void locationUpdated(LocationProvider provider, Location location){

if (location.isValid()){}else{}

}public void providerStateChanged(LocationProvider provider, int newState){

if (newState == LocationProvider.AVAILABLE){}else if (newState == LocationProvider.OUT_OF_SERVICE){}else if (newState == LocationProvider.TEMPORARILY_UNAVAILABLE ){}

}}

Code sample: Using the BlackBerryLocationProvider class to control location tracking



static BlackBerryLocationProvider myProvider;

public handleGPS(){

try{


19



22/81

try{

myProvider = (BlackBerryLocationProvider)LocationProvider.getInstance(myCriteria);myProvider.setLocationListener(new handleGPSListener(), 10, -1, -1);


return;}

myProvider.pauseLocationTracking(30);myProvider.resumeLocationTracking();myProvider.stopLocationTracking();

}catch ( UnsupportedOperationException uoex ){

return;}

return;}

public static class handleGPSListener implements LocationListener{


if (location.isValid()){

// do something}else{

// invalid location}

}

public void providerStateChanged(LocationProvider provider, int newState){

if (newState == LocationProvider.AVAILABLE){

// available}else if (newState == LocationProvider.OUT_OF_SERVICE){

// GPS unavailable due to IT policy specification}else if (newState == LocationProvider.TEMPORARILY_UNAVAILABLE ){

// no GPS fix}

20

Development Guide Retrieve a location provider by using the BlackBerryLocationProvider class


23/81

}}

}

Retrieve a location provider by using the BlackBerryLocationProvider class1. Import the required classes.




static BlackBerryCriteria myCriteria;


}3. In the constructor, create a try/catch block. In the block, create an instance of the BlackBerryCriteria class and

pass the GPS mode to the constructor. Create a second try/catch block, then create an instance of theBlackBerryLocationProvider class by invokinggetInstance() to retrieve an instance of theBlackBerryCriteria object.

try{

myCriteria = new BlackBerryCriteria(GPSInfo.GPS_MODE_ASSIST);

try{

BlackBerryLocationProvider myProvider =(BlackBerryLocationProvider)

LocationProvider.getInstance(myCriteria);}catch ( LocationException lex ){

return;}

}catch ( UnsupportedOperationException ex ){

return;}

}}

21

Development Guide Retrieving the location of a BlackBerry device


24/81

Retrieving the location of a BlackBerry device 4 You can retrieve the location of a BlackBerry device by specifying a single GPS fix, or by specifying a location listener to retrievecontinuous GPS fixes.

Retrieve the location of a BlackBerry device1. Import the required classes.

import javax.microedition.location.*;




}3. Declare static fields in the class.

static GPSThread gpsThread;static double latitude;static double longitude;

4. In the constructor, create and start a local thread.

gpsThread = new GPSThread();

gpsThread.start();5. In the class, create a private class that extends Thread , and create a run() method.

private class GPSThread extends Thread{

public void run(){}

}

6. In the run() method, create an instance of the Criteria class. Invoke setCostAllowed(false) to specify that the autonomous mode.

Criteria myCriteria = new Criteria();myCriteria.setCostAllowed(false);

22

Development Guide Retrieve the location of a BlackBerry device


25/81

7. In the run() method, create a try/catch block. In the block create a LocationProvider object by getting an

instance of the Criteria object. Create another try/catch block to create a Location object to request the current location of the BlackBerry device and specify the timeout period in seconds. When thegetLocation() method returns,request the latitude and longitude coordinates.

try{

LocationProvider myLocationProvider =LocationProvider.getInstance(myCriteria);

try

{ Location myLocation = myLocationProvider.getLocation(300);latitude = myLocation.getQualifiedCoordinates().getLatitude();longitude = myLocation.getQualifiedCoordinates().getLongitude();

}catch ( InterruptedException iex ){

return;}catch ( LocationException lex )

{ return;}


return;}return;

Code sample: Retrieving the GPS location of a BlackBerry device



static GPSThread gpsThread;static double latitude;

static double longitude;public handleGPS(){


}


23


26/81

Development Guide Retrieve the location of a BlackBerry device by specifying continuous fix requests


27/81

{}

}3. In the constructor, create an instance of the Criteria class. Create a try/catch block. In this block, create an instance of

the LocationProvider class by invokinggetInstance() and using the Criteria object. InvokesetLocationListener() to specify the location of the GPS event listener.

Criteria myCriteria = new Criteria();

try{

LocationProvider provider = LocationProvider.getInstance(myCriteria);provider.setLocationListener(new handleGPSListener(), 10, -1, -1);}catch ( LocationException lex ){

return;}

4. In the class, implement the LocationListener interface. You must add functionality as required to this implementation.




// do something}else{

// invalid locatuon}}


if (newState == LocationProvider.OUT_OF_SERVICE){}else if (newState == Location.TEMPORARILY_UNAVAILABLE ){}

}}

25

Development Guide Retrieve the location of a BlackBerry device by specifying continuous fix requests


28/81

Code sample: Retrieving the GPS location of a BlackBerry device by using continuous fixrequests



public handleGPS(){

Criteria myCriteria = new Criteria();try{

LocationProvider provider = LocationProvider.getInstance(myCriteria);provider.setLocationListener(new handleGPSListener(), 10, -1, -1);


return;

}}




// do something

}else{

// invalid location}

}


if (newState == LocationProvider.OUT_OF_SERVICE)

{// GPS unavailable due to IT policy specification

}else if (newState == LocationProvider.TEMPORARILY_UNAVAILABLE ){

// no GPS fix}

26

Development Guide Retrieving location information by using the Location class


29/81

}}

}

Retrieving location information by using the Location class You can use the JSR 179 Location API, which is provided in thejavax.microedition.location.Location package, toretrieve the following information:

latitude as a double longitude as a double ground speed of the BlackBerry device, in meters per second course of the BlackBerry device, in degrees relative to true north time stamp of the GPS fix NMEA sentence that contains the number of satellites that a BlackBerry device tracks

Retrieve location information by using the Location class You can request a GPS fix and then retrieve the latitude, longitude, velocity, course heading, time stamp, and the number of satellites that the BlackBerry device is tracking.




public class handleGPS{public handleGPS(){}

}

3. In the class, declare static fields for a thread and for each item of location information that you retrieve.

static GPSThread gpsThread;static double latitude;static double longitude;static float heading;static float velocity;static long timeStamp;static String nmeaString;

4. In the constructor, create and start a thread.

27

Development Guide Retrieving location information by using the Location class


30/81


5. In the class, create a private static class that extends Thread , and create a run() method.


public void run(){}

}

6. In run() , create an instance of the Criteria class. Invoke setCostAllowed(false) to specify the autonomousmode.

Criteria myCriteria = new Criteria();myCriteria.setCostAllowed(false);

7. In run() , create a try/catch block. In this block create an instance of the LocationProvider class by getting aninstance of the Criteria object. Create a try/catch block within this block, and create an instance of the Locationclass to retrieve the current GPS fix including a 300 second timeout expiry. Populate the fields, and specify the number of satellites by invoking getExtraInfo("application/X-jsr179-location-nmea") .

try{

LocationProvider myLocationProvider =LocationProvider.getInstance(myCriteria);

try{

Location myLocation = myLocationProvider.getLocation(300);

latitude = myLocation.getQualifiedCoordinates().getLatitude();longitude = myLocation.getQualifiedCoordinates().getLongitude();velocity = myLocation.getSpeed();heading = myLocation.getCourse();timeStamp = myLocation.getTimestamp();nmeaString = myLocation.getExtraInfo

("application/X-jsr179-location-nmea");}catch ( InterruptedException iex ){}catch ( LocationException lex ){}

}catch ( LocationException lex ){}

return;

28


31/81

Development Guide Retrieving location information by using the BlackBerryLocation class


32/81

return;}


return;}

return;}

}}

Retrieving location information by using the BlackBerryLocation class You can use the BlackBerry extensions to JSR 179 to retrieve location information about the BlackBerry device. You can use theBlackBerryLocation class to retrieve the following information:

number of satellites that a BlackBerry device is tracking

details about the satellites that a BlackBerry device is tracking average signal quality of a satellite data source that produces the GPS fix (an internal or an external GPS receiver) GPS mode that provides the location information

Retrieve satellite information by using the BlackBerryLocation class You can request a GPS fix and then retrieve the current number of satellites in view, tracked satellites, average satellite signal

quality, GPS data source (internal or external GPS), and the GPS mode.


import java.util.*;import java.lang.*;import net.rim.device.api.gps.*;




}

3. In the class, declare static fields for a thread and for each item of location information that you retrieve.

30



33/81

static GPSThread gpsThread;static int satCount;static int signalQuality;static int dataSource;static int gpsMode;

4. In the constructor, create and start a thread.


5. In the class, create a private static class that extends Thread and a run() method.


public void run(){}

}

6. In run() , create a try/catch block. In this block, create an instance of the BlackBerryCriteria class that specifiesthe GPS mode. Create a second try/catch block. In this block create an instance of the

BlackBerryLocationProvider class by getting an instance of the BlackBerryCriteria object.try{

BlackBerryCriteria myCriteria = newBlackBerryCriteria(GPSInfo.GPS_MODE_AUTONOMOUS);

try{


7. Create a third try/catch block that is in the first try/catch block. Create a BlackBerryLocation object to retrievethe GPS fix including a 300 second timeout expiry. Populate the fields and extract the satellite information into aStringBuffer object.

try{


satCount= myLocation.getSatelliteCount();signalQuality = myLocation.getAverageSatelliteSignalQuality();dataSource = myLocation.getDataSource();gpsMode = myLocation.getGPSMode();

SatelliteInfo si;StringBuffer sb = new StringBuffer("[Id:SQ:E:A]\n");String separator = ":";

31



34/81

for (Enumeration e = myLocation.getSatelliteInfo();e!=null && e.hasMoreElements(); )

{ si = (SatelliteInfo)e.nextElement();sb.append(si.getId() + separator);sb.append(si.getSignalQuality() + separator);sb.append(si.getElevation() + separator);sb.append(si.getAzimuth());sb.append('\n');

}}catch ( InterruptedException iex )

{}catch ( LocationException lex ){}

Code sample: Using the BlackBerryLocation class to retrieve satellite information

import net.rim.device.api.gps.*;import java.util.*;import javax.microedition.location.*;


static GPSThread gpsThread;static int satCount;static int signalQuality;static int dataSource;static int gpsMode;

public handleGPS(){


}


public void run(){

try{


try{


LocationProvider.getInstance(myCriteria);

32


35/81

Development Guide Change the criteria to receive location information


36/81

Change the criteria to receive location information You can use an instance of the LocationProvider class to automatically change the criteria that is used to track the locationof a BlackBerry device.

1. Import the required classes and interface.

import net.rim.device.api.gps.GPSInfo;import javax.microedition.location.*;

2. Create a class and constructor.public class handleGPS{

public handleGPS(int gpsMode){}

}

3. In the class, define static fields for the location provider, latitude, longitude, altitude, speed and course.

static LocationProvider locationProvider;static double lat, lon;static float alt, spd, crs;

4. In the constructor, add a code block to set up a LocationProvider instance to switch to a different method of locationtracking. Invoke reset() on the LocationProvider object, and then set the location listener to null to disable thelistener.

if (locationProvider != null){

locationProvider.reset();locationProvider.setLocationListener(null, -1, -1, -1);

}

5. In the constructor, create and configure a Criteria object based on the GPS mode that is passed as a parameter to theconstructor.

Criteria myCriteria = new Criteria();myCriteria.setPreferredResponseTime(Criteria.NO_REQUIREMENT);myCriteria.setCostAllowed(true);

if ( gpsMode == GPSInfo.GPS_MODE_AUTONOMOUS ){

myCriteria.setCostAllowed(false);}else if ( gpsMode == GPSInfo.GPS_MODE_ASSIST ){

myCriteria.setPreferredPowerConsumption(Criteria.POWER_USAGE_MEDIUM);}else

34



37/81

{myCriteria.setPreferredPowerConsumption(Criteria.POWER_USAGE_LOW);

}6. In the constructor, create a try/catch block. In this block, create an instance of the LocationListener class by

invokinggetInstance() and passing the Criteria object as a parameter. Specify a location listener to handle theGPS location updates.

try{

locationProvider = LocationProvider.getInstance(myCriteria);

if (locationProvider != null){locationProvider.setLocationListener

(new myLocationListener(), -1, -1, -1);}

}catch (Exception err){}

7. In the class, create a private static class that implements the LocationListener interface. Retrieve the current location

information in the locationUpdated() method. Create a basic implementation of the providerStateChanged() method to monitor the LocationProvider state.

private static class myLocationListener implements LocationListener{


lat = location.getQualifiedCoordinates().getLatitude();lon = location.getQualifiedCoordinates().getLongitude();alt = location.getQualifiedCoordinates().getAltitude();

spd = location.getSpeed();crs = location.getCourse();}

public void providerStateChanged(LocationProvider provider, int newState){}

}

Code sample: Changing the criteria to retrieve location information

import net.rim.device.api.gps.GPSInfo;import javax.microedition.location.*;


static LocationProvider locationProvider;static double lat, lon;static float alt, spd, crs;

35



38/81

public static void main(String[] args)

{}

public handleGPS(int gpsMode){

if (locationProvider != null){

locationProvider.reset();locationProvider.setLocationListener(null, -1, -1, -1);

}

Criteria myCriteria = new Criteria();myCriteria.setPreferredResponseTime(Criteria.NO_REQUIREMENT);myCriteria.setCostAllowed(true);

if ( gpsMode == GPSInfo.GPS_MODE_AUTONOMOUS ){

myCriteria.setCostAllowed(false);}else if ( gpsMode == GPSInfo.GPS_MODE_ASSIST )

{ myCriteria.setPreferredPowerConsumption(Criteria.POWER_USAGE_MEDIUM);}else{

myCriteria.setPreferredPowerConsumption(Criteria.POWER_USAGE_LOW);}

try{

locationProvider = LocationProvider.getInstance(myCriteria);if (locationProvider != null){

locationProvider.setLocationListener(new myLocationListener(), -1, -1, -1);

}}catch (Exception err){

}}



lat = location.getQualifiedCoordinates().getLatitude();lon = location.getQualifiedCoordinates().getLongitude();alt = location.getQualifiedCoordinates().getAltitude();

36

Development Guide Error handling


39/81

spd = location.getSpeed();crs = location.getCourse();

}


}}

Error handling You can retrieve the last error that was received when a GPS fix is unsuccessful by invokingGPSInfo.getLastGPSError() , available in the JSR 179 Location API, orBlackBerryLocation.getError() , available in the BlackBerry extensionsto JSR 179.

Handle errors (JSR 179)If a request for a GPS fix is unsuccessful, you can retrieve the last returned error.1. Import the required class.

import net.rim.device.api.gps.GPSInfo;




}

3. In the constructor, invoke GPSInfo.getLastGPSError() to retrieve the error.

switch (GPSInfo.getLastGPSError()){

case GPSInfo.GPS_ERROR_NONE: break;case GPSInfo.GPS_ERROR_ALMANAC_OUTDATED: break;

case GPSInfo.GPS_ERROR_AUTHENTICATION_FAILURE: break;case GPSInfo.GPS_ERROR_CHIPSET_DEAD: break;case GPSInfo.GPS_ERROR_DEGRADED_FIX_IN_ALLOTTED_TIME: break;case GPSInfo.GPS_ERROR_GPS_LOCKED: break;case GPSInfo.GPS_ERROR_INVALID_NETWORK_CREDENTIAL: break;case GPSInfo.GPS_ERROR_INVALID_REQUEST: break;case GPSInfo.GPS_ERROR_LOW_BATTERY: break;case GPSInfo.GPS_ERROR_NETWORK_CONNECTION_FAILURE: break;case GPSInfo.GPS_ERROR_NO_FIX_IN_ALLOTTED_TIME: break;case GPSInfo.GPS_ERROR_NO_SATELLITE_IN_VIEW: break;

37

Development Guide Handle errors (BlackBerry extensions to JSR 179)


40/81

case GPSInfo.GPS_ERROR_PRIVACY_ACCESS_DENIED: break;case GPSInfo.GPS_ERROR_SERVICE_UNAVAILABLE: break;case GPSInfo.GPS_ERROR_TIMEOUT_DEGRADED_FIX_NO_ASSIST_DATA: break;case GPSInfo.GPS_ERROR_TIMEOUT_NO_FIX_NO_ASSIST_DATA: break;

}

Handle errors (BlackBerry extensions to JSR 179) You can check the status of a GPS fix request by invoking the getStatus() method that is provided in the BlackBerryextensions to JSR 179. If the return isBlackBerryLocation.GPS_ERROR , you can retrieve the error value by invokingBlackBerryLocation.getError() .1. Import the required classes and interfaces.





}

3. In the constructor, create a try/catch block. In this block, create an instance of the BlackBerryCriteria class bypassing the GPS mode to the constructor.

try{

BlackBerryCriteria myCriteria =new BlackBerryCriteria(GPSInfo.GPS_MODE_ASSIST);


return;}

4. In the try/catch block, create another try/catch block. In this block, create an instance of theBlackBerryLocationProvider class by retrieving the BlackBerryCriteria object. Invoke

setLocationListener() to specify the location listener.try{


myProvider.setLocationListener(new myLocationListener(), -1, -1, -1);}catch ( LocationException lex )

38



41/81

{return;

}

5. In the class, create a static class that implements LocationListener . Implement locationUpdated() andproviderStateChanged() .


public void locationUpdated(LocationProvider provider, Location location){}


}

6. In locationUpdated() , verify if thelocation parameter is an instance of BlackBerryLocation . If so, thencreate a local BlackBerryLocation object by passing the location parameter. Invoke getStatus() to retrievethe status of GPS location request, and then process the returned status.

if (location instanceof BlackBerryLocation){

BlackBerryLocation bLoc = (BlackBerryLocation)location;

switch(bLoc.getStatus()){

case BlackBerryLocation.GPS_ERROR:int gpsStatus = bLoc.getError();break;

case BlackBerryLocation.FAILOVER_MODE_ON:case BlackBerryLocation.SUBSEQUENT_MODE_ON:case BlackBerryLocation.GPS_FIX_PARTIAL:case BlackBerryLocation.GPS_FIX_COMPLETE:

break;}

}

Code sample: Handling errors (BlackBerry extensions to JSR 179)



public handleGPS(){

try{

BlackBerryCriteria myCriteria =

39



42/81

new BlackBerryCriteria(GPSInfo.GPS_MODE_ASSIST);

try{


LocationProvider.getInstance(myCriteria);myProvider.setLocationListener

(new myLocationListener(), -1, -1, -1);}catch ( LocationException lex ){

return;}


return;}

}

private static class myLocationListener implements LocationListener

{ public void locationUpdated(LocationProvider provider, Location location)

{if (location instanceof BlackBerryLocation){

BlackBerryLocation bLoc = (BlackBerryLocation)location;

switch(bLoc.getStatus()){

case BlackBerryLocation.GPS_ERROR:int gpsStatus = bLoc.getError();break;

case BlackBerryLocation.FAILOVER_MODE_ON:case BlackBerryLocation.SUBSEQUENT_MODE_ON:case BlackBerryLocation.GPS_FIX_PARTIAL:case BlackBerryLocation.GPS_FIX_COMPLETE:

break;}

}}

public void providerStateChanged(LocationProvider provider, int newState)

{}

}}

40

Development Guide Geocoding and reverse geocoding


43/81

Geocoding and reverse geocoding 5 The net.rim.device.api.lbs.Locator API provides the geocoding methods that can allow you to request geospatialcoordinates for a street address. It also provides the reverse geocoding methods that can allow you to request a street addressfor a geospatial coordinate.

You can use the geocode() methods to request geospatial coordinates. A successful request returns an array of Landmarkobjects.

You can use the reverseGeocode() methods to request an approximate street address, city, province/state, or country. Asuccessful request returns an array of Landmark objects. ALandmark object can contain a display label name, a description,the geospatial coordinates, and a street address.

Requests for geocoding and reverse geocoding information are synchronous and can be interrupted. A BlackBerry deviceapplication can use the Locator class to make only one request at a time.

Your application must invoke the geocode() and reverseGeocode() methods outside of the event dispatch thread.Requests to these methods that are made on the event dispatch thread are denied and result in anIllegalThreadStateException . Each request is sent to theBlackBerry Infrastructure. If a request is unsuccessful, aLocatorException is thrown with an error code that indicates why the request is unsuccessful. If a request is unsuccessfulor stalls at the transport level, it is cancelled as specified by the value for REQUEST_TIMEOUT .

If the LBS Map API module (net_rim_bb_lbs_api ) is not installed on a BlackBerry device, then invoking thegeocode()and reverseGeocode() methods throws a MapServiceException .

The BlackBerry device does not cache requests.

Retrieve geospatial coordindates for an address by using geocoding You can retrieve geospatial coordinates by invoking Locator.geocode() . When you invokeLocator.geocode() , youmust specify a street address by using an AddressInfo object or a String object of address information. Your applicationmust request geocoding information outside of the event dispatch thread. A successful request for geocoding information willreturn an array of Landmark objects.1. Import the required classes.

import net.rim.device.api.lbs.*;import javax.microedition.location.*;


public class myGeocode{

public myGeocode()

41

Development Guide Retrieve geospatial coordindates for an address by using geocoding


44/81

{}

}

3. In the class, create a private variable of type Thread .

private Thread geocoder;

4. In the constructor, create an instance of the Thread class. You cannot retrieve geocoding information on the application'sprimary thread.

geocoder = new Thread(thread);geocoder.setPriority(Thread.MIN_PRIORITY);

geocoder.start();5. In the class, create a Thread that invokes a public run() method. In run() , create an instance of the AddressInfo

class. Populate the object with address information. Create an instance of the Coordinates class by passing the latitude,longitude, and altitude values to the constructor to start the geocode search. In the following code sample, the positivenorthern latitude and negative western longitude of the Waterloo, Ontario region are used by the LBS Locate Server toperform the geocode search. Create a try/catch block. In this block, invokegeocode() to find the address and returnthe results in a Landmark array.

Runnable thread = new Runnable(){public void run(){

AddressInfo addrInfo = new AddressInfo();

addrInfo.setField(AddressInfo.STREET, "455 Phillip Street");addrInfo.setField(AddressInfo.CITY, "Waterloo");addrInfo.setField(AddressInfo.STATE, "Ontario");addrInfo.setField(AddressInfo.POSTAL_CODE, "N2L 3X2");

addrInfo.setField(AddressInfo.COUNTRY, "Canada");Coordinates coord = new Coordinates(43.28, -80.31, Float.NaN);

try{

Landmark[] results = Locator.geocode(addrInfo, coord);}catch ( LocatorException lex ){

}}};

Code sample: Retrieving geospatial coordinates for an address by using geocodingimport net.rim.device.api.lbs.*;import javax.microedition.location.*;

42

Development Guide Retrieve an address by using reverse geocoding


45/81

public class myGeocode{

private Thread geocoder;

public myGeocode(){

geocoder = new Thread(thread);geocoder.setPriority(Thread.MIN_PRIORITY);geocoder.start();

}

Runnable thread = new Runnable(){

public void run(){

AddressInfo addrInfo = new AddressInfo();

addrInfo.setField(AddressInfo.STREET, "455 Phillip Street");addrInfo.setField(AddressInfo.CITY, "Waterloo");addrInfo.setField(AddressInfo.STATE, "Ontario");addrInfo.setField(AddressInfo.POSTAL_CODE, "N2L 3X2");addrInfo.setField(AddressInfo.COUNTRY, "Canada");

Coordinates coord = new Coordinates(43.28, -80.31, Float.NaN);

try{

Landmark[] results = Locator.geocode(addrInfo, coord);}catch ( LocatorException lex ){}

}};}

Retrieve an address by using reverse geocoding You can retrieve an address by invoking Locator.reverseGeocode() . When you invokeLocator.reverseGeocode() , you must specify the latitude and longitude coordinates by using two int fields, or by using aCoordinates object. Thevalues for the coordinates are passed as decimal degrees, to five decimal places, with the values multiplied by 100,000. Yourapplication must request reverse geocoding information outside of the event dispatch thread. The process uses the LBS LocateServer over the wireless radio or Wi-Fi. A successful request for reverse geocoding information will return an array of Landmark objects.1. Import the required classes.

import net.rim.device.api.lbs.*;import javax.microedition.location.*;

43


46/81

Development Guide Retrieve an address by using reverse geocoding


47/81

Locator.COUNTRY : returns a value that is focused on the country level Locator.PROVINCE_STATE : returns a value that is focused on the province or state level

Code sample: Retrieving an address by using reverse geocodingimport net.rim.device.api.lbs.*;import javax.microedition.location.*;

public class myReverseGeocode{

private Thread reverseGeocode;

public myReverseGeocode(){

reverseGeocode = new Thread(thread);reverseGeocode.setPriority(Thread.MIN_PRIORITY);reverseGeocode.start();

}

Runnable thread = new Runnable(){

public void run(){

AddressInfo addrInfo = null;

int latitude = (int)(45.423488 * 100000);int longitude = (int)(-80.32480 * 100000);

try{

Landmark[] results = Locator.reverseGeocode(latitude, longitude, Locator.ADDRESS );

if ( results != null && results.length > 0 )addrInfo = results[0].getAddressInfo();

}catch ( LocatorException lex ){}

}};

}

45

Development Guide BlackBerry Maps


48/81

BlackBerry Maps 6 You can create a BlackBerry device application that interacts with BlackBerry Maps. BlackBerry Maps is a map and locationapplication that can display a map, the location of the BlackBerry device, a route from a starting location to a specific endinglocation, and points of interest on a map.

Your application can interact with BlackBerry Maps in the following ways:

Open BlackBerry Maps from your BlackBerry device application. Display KML overlays on BlackBerry Maps. Open BlackBerry Maps from the BlackBerry Browser. Embed a map in your BlackBerry device application.

BlackBerry Maps can be installed on BlackBerry devices that are running BlackBerry Device Software 4.2 or later.

You can use the MapsArguments class in the net.rim.blackberry.api.invoke package to create a BlackBerry deviceapplication that interacts with BlackBerry Maps.

Opening BlackBerry Maps from your application You can open BlackBerry Maps by using theInvoke.invokeApplication() method. When you use this method, youmust pass in a net.rim.blackberry.api.invoke.MapsArguments parameter to customize the map view that appears.

You can use the following methods to specify how you want to open BlackBerry Maps:

Use the default settings by invoking MapsArgument() . Use address information for a contact by invoking MapsArguments(Contact, int) . Display the location of a landmark by invokingMapsArguments(Landmark[]) . Display a location at specific coordinates by invokingMapsArguments(MapView) . Use a location document by invoking MapsArguments(String, String) . Use local search information by invoking MapsArguments(ARG_LOCAL_SEARCH, String, String) .

Open BlackBerry Maps by using the default settings You can open BlackBerry Maps to display the default map view by invokingInvoke.invokeApplication() and passingin a new MapsArguments object.1. Import the required classes.

import net.rim.blackberry.api.invoke.*;

2. Create a class and a constructor to use to invoke BlackBerry Maps.

46

Development Guide Open BlackBerry Maps by using information from a contact


49/81

public class invokeMaps{

public invokeMaps(){}

}

3. In the constructor, invoke Invoke.invokeApplication() to open BlackBerry Maps. Pass in a newMapsArguments object.

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

Code sample: Opening BlackBerry Maps by using the default settingsimport net.rim.blackberry.api.invoke.*;


public invokeMaps(){

Invoke.invokeApplication(Invoke.APP_TYPE_MAPS, new MapsArguments());}

}

Open BlackBerry Maps by using information from a contact You can open BlackBerry Maps to display a location on a map by using the address information from a contact in the contactsapplication on the BlackBerry device.1. Import the required classes and interfaces.

import net.rim.blackberry.api.invoke.*;import javax.microedition.pim.*;

2. Create a class and constructor to use to invoke BlackBerry Maps.


public invokeMaps (){}

}

3. In the constructor, retrieve an instance of a ContactList object from the BlackBerry device. Create a contact by usingthe Contact class. Populate the Contact with the name and address of the contact.

ContactList contacts = null;try{

contacts = (ContactList)PIM.getInstance().openPIMList(PIM.CONTACT_LIST, PIM.READ_ONLY);

47


50/81

Development Guide Open BlackBerry Maps by using specific coordinates


51/81

contact.addString(Contact.FORMATTED_NAME, PIMItem.ATTR_NONE,"Ms. Andrea Aime");

contact.addString(Contact.FORMATTED_ADDR, PIMItem.ATTR_NONE,"455 Phillip St. Waterloo ON N2L3X2 Canada");

String[] name = new String[ contacts.stringArraySize( Contact.NAME ) ];name[ Contact.NAME_GIVEN ] = "Andrea";name[ Contact.NAME_FAMILY ] = "Aime";name[ Contact.NAME_PREFIX ] = "Ms.";

String[] addr = new String[ contacts.stringArraySize( Contact.ADDR ) ];addr[ Contact.ADDR_STREET ] = "455 Phillip St";addr[ Contact.ADDR_LOCALITY ] = "Waterloo";addr[ Contact.ADDR_REGION ] = "ON";addr[ Contact.ADDR_POSTALCODE ] = "N2L3X2";addr[ Contact.ADDR_COUNTRY ] = "Canada";

MapsArguments mapsArgs = new MapsArguments(contact, 0);Invoke.invokeApplication(Invoke.APP_TYPE_MAPS, mapsArgs);

}}

Open BlackBerry Maps by using specific coordinates You can open BlackBerry Maps to display a location on a map by providing the coordinates for the latitude and longitude of alocation and by specifying the zoom and rotation values. The zoom values have a range of 0 to MapView.MAX_ZOOM . Therotation values are expressed in degrees to rotate the map from north facing up, and have a range of 0 to 359.1. Import the required classes.

import net.rim.blackberry.api.invoke.*;import net.rim.blackberry.api.maps.*;




}3. In the constructor, create an instance of the MapView class. InvokeMapView.setLatitude() ,

MapView.setLongitude() , and MapView.setZoom() to specify the coordinates and zoom that you want to use.

MapView mapView = new MapView();mapView.setLatitude(4328915);mapView.setLongitude(-8032480);mapView.setZoom(10);

49

4 I h i f h l i h bj I k

Development Guide Open BlackBerry Maps by using a landmark


52/81

4. In the constructor, create an instance of the MapsArguments class using the MapView object as an argument. InvokeInvoke.invokeApplication() to open BlackBerry Maps and pass in the MapsArguments object.

MapsArguments mapsArgs = new MapsArguments(mapView);Invoke.invokeApplication(Invoke.APP_TYPE_MAPS, mapsArgs);

Code sample: Invoking BlackBerry Maps by using specific coordinatesimport net.rim.blackberry.api.invoke.*;import net.rim.blackberry.api.maps.*;

public class invokeMaps

{ public invokeMaps(){

MapView mapView = new MapView();mapView.setLatitude(4328915);mapView.setLongitude(-8032480);mapView.setZoom(10);MapsArguments mapsArgs = new MapsArguments(mapView);Invoke.invokeApplication(Invoke.APP_TYPE_MAPS, mapsArgs);

}

}

Open BlackBerry Maps by using a landmark You can open BlackBerry Maps to display the location of a landmark on a map by specifying an array of Landmark objects. Alandmark object can contain a display label name, a description, the geospatial coordinates, and a street address.

If you do not specify the coordinates, BlackBerry Maps can use the address to find the coordinates. If the coordinates and addressare invalid, BlackBerry Maps does not display the location of the landmark.


import net.rim.blackberry.api.invoke.*;import javax.microedition.location.*;


public class invokeMaps

{ public invokeMaps (){}

}

3. In the constructor, create an array of Landmark objects that you can use to add the landmark information to.

Landmark[] landMarks = new Landmark[3];

50

4 In the constructor createan Add I f array and invoke Add I f tFi ld() to specify thestreet address

Development Guide Open BlackBerry Maps by using a landmark


53/81

4. In the constructor, create an AddressInfo array and invoke AddressInfo.setField() to specify the street address.Add the AddressInfo array to the Landmark array.

AddressInfo addressInfo = new AddressInfo();addressInfo.setField(AddressInfo.STREET, "455 Phillip St");addressInfo.setField(AddressInfo.CITY, "Waterloo");addressInfo.setField(AddressInfo.STATE, "Ontario");landMarks[0] = new Landmark("AAA", "Description 1", null, addressInfo);

5. In the constructor, create an instance of the QualifiedCoordinates class and specify the coordinates. Add theQualifiedCoordinates to the Landmark array.

QualifiedCoordinates coordinates =new QualifiedCoordinates(45.4, -75.1, 0, 0, 0);

landMarks[1] = new Landmark("BBB", "Description 2", coordinates, null);coordinates = new QualifiedCoordinates(45.3,-75.3,0,0,0);landMarks[2] = new Landmark("CCC", "Description 3", coordinates, null);

6. In the constructor, create an instance of the MapsArguments class using the Landmarks array as an argument. InvokeInvoke.invokeApplication() to open BlackBerry Maps. Pass in theMapsArguments object.

MapsArguments ma = new MapsArguments(landMarks);Invoke.invokeApplication(Invoke.APP_TYPE_MAPS, ma);

Code sample: Opening BlackBerry Maps by using a landmarkimport net.rim.blackberry.api.invoke.*;import javax.microedition.location.*;


public invokeMaps (){

Landmark[] landMarks = new Landmark[3];

AddressInfo addressInfo = new AddressInfo();addressInfo.setField(AddressInfo.STREET, "455 Phillip St");addressInfo.setField(AddressInfo.CITY, "Waterloo");addressInfo.setField(AddressInfo.STATE, "Ontario");

landMarks[0] = new Landmark("AAA", "Description 1", null, addressInfo);

QualifiedCoordinates coordinates =new QualifiedCoordinates(45.4, -75.1, 0, 0, 0);

landMarks[1] = new Landmark("BBB", "Description 2", coordinates, null);

coordinates = new QualifiedCoordinates(45.3,-75.3,0,0,0);

landMarks[2] = new Landmark("CCC", "Description 3", coordinates, null);

MapsArguments ma = new MapsArguments(landMarks);

51

Invoke.invokeApplication(Invoke.APP_TYPE_MAPS, ma);

Development Guide Opening BlackBerry Maps by using a location document


54/81

}}

Opening BlackBerry Maps by using a location document You can open BlackBerry Maps to display map locations and routes by passing in a location document. A location document isa String object that contains XML elements with attributes that can specify the location and route information. The XMLelements that you can use include , and .

XML element: The opening and closing elements wrap the location document elements.

Valid parentsNone

Valid children ,

Attributes

Attribute Type Description Supported in

id String This value specifies the ID of a locationdocument.

BlackBerry JavaDevelopment Environment

4.5.0 or laterclear String This value specifies the clearing action to

perform on the information in a map. Thevalue is a list of location document IDsseparated by commas, or one of thefollowing values:

NONE: does not clear any information DOCS: clears location and route

information from all locationdocuments that have a specific idattribute

BlackBerry JDE 4.5.0 or later

52




55/81


LOCATIONS : clears all the locationinformation from the map

ROUTES: clears all route theinformation from the map

ALL: clears all the location and routeinformation from the map

Code sample

XML element: The element contains information for a specific location. The description , label , x and y are requiredattributes.

Valid parents ,

Valid childrenNone

Attributes


address String This attribute specifies the street address. BlackBerry Java Development Environment 4.2.1 or later

categories String This attribute specifies the category. BlackBerry JDE 4.2.1 or later

53




56/81

yp p pp

city String This attribute specifies the city. BlackBerry JDE 4.2.1 or latercountry String This attribute specifies the country. BlackBerry JDE 4.2.1 or laterdescription String This attribute specifies the description

information for a location.

This is a required attribute.


email String This attribute specifies the email address. BlackBerry JDE 4.2.1 or laterfax String This attribute specifies the fax number. BlackBerry JDE 4.2.1 or laterlabel String This attribute specifies the label that is

displayed beside a location on a map.



phone String This attribute specifies the phone number. BlackBerry JDE 4.2.1 or laterpostalCode String This attribute specifies the postal code or zip

code.BlackBerry JDE 4.2.1 or later

rating double This attribute specifies the ratinginformation in the range of 0 to 5.


region String This attribute specifies the province or state. BlackBerry JDE 4.2.1 or laterurl String This attribute specifies the URL. BlackBerry JDE 4.2.1 or laterx or the alias, lon integer This attribute specifies the longitude in

decimal degrees with five decimal accuracymultiplied by 100,000.



y or the alias, lat integer This attribute specifies the latitude indecimal degrees with five decimal accuracymultiplied by 100,000.



zoom integer This attribute specifies the zoom level from0 to 15 .


Code sample

54


57/81

{}



58/81

}}

3. In the constructor, create a String variable to use for the location document. Add an element. Configure a element with the location that you want to display.

String document = "";

4. In the constructor, invoke Invoke.invokeApplication() using the APP_TYPE_MAPS constant and a new

MapsArguments object as parameters to open BlackBerry Maps. Pass in the ARG_LOCATION_DOCUMENT property andthe String variable that represents the location document as parameters for the MapsArguments class to display thelocation provided in the location document.

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

5. Perform one of the following tasks to clear location information from a map after it has been displayed :

Task StepsClear a location from a map. Create a String that configures the clear attribute to be

the id of the location document that contains the locationinformation.


Clear all locations from a map. Create a String that configures the clear attribute to beLOCATIONS .


Clear all locations and routes from a map. Create a String that configures the clear attribute to beALL.


Clearing map content occurs before any new map content is displayed on the map. You can combine the actions of displayingand clearing map content into one location document.

56

String document = "


59/81

";

Code sample: Displaying locations on a map by using a location document import net.rim.blackberry.api.invoke.*;


public invokeMaps ()

{ String document ="

";Invoke.invokeApplication(Invoke.APP_TYPE_MAPS, new MapsArguments

(MapsArguments.ARG_LOCATION_DOCUMENT, document));}

}

Display and clear a route on a map by using a location document You can use a location document to display a route on a map in BlackBerry Maps. You can also clear a route from a map afterit is displayed.1. Import the required classes.


2. Create a class and constructor to use to invoke BlackBerry Maps.public class invokeMaps{


}

3. In the constructor, create a String variable to use for the location document. Add an and a element.

Add elements to specify the starting location and ending location of the route that you want to display.String document = "

";

57

4. In the constructor, invoke Invoke.invokeApplication() using the APP_TYPE_MAPS constant and a newM A t bj t t t Bl kB M P i th ARG LOCATION DOCUMENT t d



60/81

MapsArguments object as parameters to open BlackBerry Maps. Pass in the ARG_LOCATION_DOCUMENT property and

the String variable that represents the location document as parameters for the MapsArguments class to display theroute provided in the location document.

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

5. Perform one of the following tasks to clear route location information from a map after it has been displayed:

Task Steps

Clear a route from a map. Create a String that configures the clear attribute to bethe id of the location document that contains the routeinformation.


Clear all routes from a map. Create a String that configures the clear attribute to beROUTES.


Clear all routes and location information from a specificlocation documents with an id attribute.

Create a String that configures the clear attribute to beDOCS.


Clear all routes and location information from a map. Create a String that configures the clear attribute to beALL.


Clearing map content occurs before any new map content is displayed on the map. You can combine the actions of displayingand clearing map content into one location document.String document = "

";

Code sample: Displaying a route using a location document

58


Development Guide Open BlackBerry Maps by using a local search


61/81


public invokeMaps (){


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

}}

Open BlackBerry Maps by using a local search You can open BlackBerry Maps to display points of interest that are nearby the location that you specify in your search criteria. The search criteria is a String that must include a business category or a business name, and a location. For example, you candisplay all the hotels in the city of Waterloo.

A business category is a type of business, such as coffee, gas, hotels, pizza, and restaurants.

The location is a String that is the name of a village, town, or city, or the latitudinal and longitudinal coordinates, separatedby a comma (for example, 4328915,-8032480). The coordinates must be the measurement in decimal degrees with five decimalaccuracy multiplied by 100,000.



2. Create a class and a constructor to use to invoke BlackBerry Maps.


public invokeMaps(){}

}

3. In the constructor, create an instance of the MapsArguments class. Pass in theMapsArguments.ARG_LOCAL_SEARCH and String objects to represent the search criteria. The following codesample searches for hotels in Waterloo.

MapsArguments ma = new MapsArguments(MapsArguments.ARG_LOCAL_SEARCH, "hotels", "Waterloo");

59

4. In the constructor, invoke Invoke.invokeApplication() to open BlackBerry Maps. Pass in theMapsArguments object

Development Guide Using KML documents with BlackBerry Maps


62/81

MapsArguments object.

Invoke.invokeApplication(Invoke.APP_TYPE_MAPS, ma);

Code sample: Opening BlackBerry Maps by using a local searchimport net.rim.blackberry.api.invoke.*;


public invokeMaps()

{ MapsArguments ma = new MapsArguments(MapsArguments.ARG_LOCAL_SEARCH, "hotels", "Toronto");

Invoke.invokeApplication(Invoke.APP_TYPE_MAPS, ma);}

}

Using KML documents with BlackBerry Maps You can use a KML document to store location information about places, buildings, point of interests, travel paths, bus routes,cycle paths, pictures, and so on. You can create a KML document, publish it on a web site, and view it using BlackBerry Maps.

For more information about the KML standard, see the compl

Documents

Blackberry Java Application Development Guide 863631 1109120059 001 5.0 Beta US