background image

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

3

Summary of Contents for GPS and BlackBerry Maps

Page 1: ...GPS and BlackBerry Maps Version 4 7 0 Development Guide...

Page 2: ...SWD 596846 1209055709 001...

Page 3: ...adings 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 2 BlackBerry Maps location information...

Page 4: ...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 i...

Page 5: ...ocation Criteriaclass invoketheappropriatesetmethods andthenpasstheinstance to LocationProvider getInstance cell site Use this mode to get location information from cell site towers This mode allows a...

Page 6: ...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_ME...

Page 7: ...ormation 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...

Page 8: ...n 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 Bl...

Page 9: ...ed 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 connect...

Page 10: ...teria 2 Invoke the setHorizontalAccuracy setVerticalAccuracy setCostAllowed and setPreferredPowerConsumption methods of the new Criteria object to specify the new criteria 3 Invoke LocationProvider re...

Page 11: ...erry Maps is included on BlackBerry devices that run BlackBerry Device Software version 4 2 or later Displaying location information on a BlackBerry device Displaying location information in BlackBerr...

Page 12: ...nt represents the starting point of a route while the second location element represents the ending point of a route You can only use the x and y attributes in a location element that is nested within...

Page 13: ...g email address no 4 2 1 or later categories String category no 4 2 1 or later rating String rating information between 0 and 5 no 4 2 1 or later Create a location document to display location informa...

Page 14: ...s object that does not contain any arguments View a sample application that displays the default map 1 From the BlackBerry Integrated Development Environment launch the BlackBerryMapsDemo project 2 In...

Page 15: ...n document location lon 7938675 lat 4367022 label Toronto ON description Toronto zoom 10 location document 3 Invoke invokeApplication using the APP_TYPE_MAPS constant parameter a new MapsArguments obj...

Page 16: ...e Invoke net rim blackberry api invoke MapsArguments 2 Create a String that contains location information for multiple locations String document location document location lon 8030000 lat 4326000 labe...

Page 17: ...enu and click View Multiple Locations Open BlackBerry Maps to display a route between locations on a map 1 Import the following classes net rim blackberry api invoke Invoke net rim blackberry api invo...

Page 18: ...ents ARG_LOCATION_DOCUMENT document View a sample application that displays a route between locations on a map 1 From the BlackBerry Integrated Development Environment launch the BlackBerryMapsDemo pr...

Page 19: ...APS new MapsArguments mapView View a sample application that displays a custom map view 1 From the BlackBerry Integrated Development Environment launch the BlackBerryMapsDemo project 2 In the BlackBer...

Page 20: ...APP_TYPE_MAPS new MapsArguments c 0 notFinished 0 catch PIMException e 7 If a contact address is not found display the default map in the BlackBerry Maps if null Invoke invokeApplication Invoke APP_T...

Page 21: ...rgument in the main method of the BlackBerry Application 6 Select Auto run on startup 7 Select System module 8 Click OK 9 Import the following classes import net rim device api ui import net rim devic...

Page 22: ...e main method register a menu item with BlackBerry Maps public static void main String args if args null args length 0 if args 0 equals startup Register an ApplicationMenuItem when the BlackBerry smar...

Page 23: ...mv The int values that getLatitude and getLongitude return are 100 000 times the values specified by WGS84 _latitudeField new BasicEditField Latitude _mv getLatitude 100000 0 9 BasicEditField FILTER_R...

Page 24: ...iew setLatitude latitude _mapview setLongitude longitude Invoke BlackBerry Maps with a MapView object Invoke invokeApplication Invoke APP_TYPE_MAPS new MapsArguments _mapview close catch RuntimeExcept...

Page 25: ...ion based services A MapField gets data either from a map server for location based services or the BlackBerry device with BlackBerry Maps installed If location information is not present on the Black...

Page 26: ...MapField Invoke getRotation Converting latitudinal and longitudinal coordinates to pixel values You can create a BlackBerry device application to convert latitudinal and longitudinal coordinates to pi...

Page 27: ...al and longitudinal data for the address If the request is unsuccessful the server throws aLocatorException exception that contains the reason for the unsuccessful request A BlackBerry device applicat...

Page 28: ...rCode try catch LocationException e System err println LocationException e getErrorCode Open BlackBerry Maps from the browser A BlackBerry device user can use the browser on a BlackBerry device to acc...

Page 29: ...you send to BlackBerry Maps configure the clear attribute to the value of the id attribute of the location document that contains information for Kitchener String document lbs clear Kit location lon...

Page 30: ...d attribute set to a value Create a String that configures the clear attribute to a comma delimited list of ids String document lbs clear MONTREAL OTTAWA location lon 7938675 lat 4367022 label Toronto...

Page 31: ...tem JSR Java Specification Request MIME Multipurpose Internet Mail Extensions NMEA National Marine Electronics Association PDE Position Determination Entity SIM Subscriber Identity Module WGS World Ge...

Page 32: ...Provide feedback 4 To provide feedback on this deliverable visit www blackberry com docsfeedback Development Guide Provide feedback 30...

Page 33: ...u in a timely manner or at all This documentation might contain references to third party sources of information hardware or software products or services including components and content such as cont...

Page 34: ...UDING AIRTIME SERVICE PROVIDERS AND THEIR RESPECTIVE DIRECTORS EMPLOYEES AND INDEPENDENT CONTRACTORS IN ADDITION TO THE LIMITATIONS AND EXCLUSIONS SET OUT ABOVE IN NO EVENT SHALL ANY DIRECTOR EMPLOYEE...

Page 35: ...TOSUPERSEDEANYEXPRESSWRITTENAGREEMENTSORWARRANTIES PROVIDED BY RIM FOR PORTIONS OF ANY RIM PRODUCT OR SERVICE OTHER THAN THIS DOCUMENTATION Research In Motion Limited 295 Phillip Street Waterloo ON N2...

Reviews: