|
|||||||||
| PREV NEXT | FRAMES NO FRAMES | ||||||||
This category contains the packages that you can use to access the location, map, and landmark data on a BlackBerry® device.
For more information about LBS, visit www.blackberry.com/go/devguides to read the BlackBerry Java Application Location-Based Services Development Guide. For additional resources, visit www.blackberry.com/developers.
Packages: javax.microedition.location, net.rim.device.api.gps
You can create a BlackBerry® device application to retrieve the geographic location of a BlackBerry device. The values for the location information are returned as the latitude, longitude, and altitude.
You can interact with the GPS receiver on a BlackBerry device by using one the following GPS modes:
The GPS mode that you use to retrieve the location information can affect the initial speed of a location fix, the level of location accuracy, and the amount of resources that are consumed on the BlackBerry device.
You can retrieve location information by using the JSR 179 Location API in the javax.microedition.location package or the BlackBerry extensions to JSR 179 in the net.rim.device.api.gps package that are provided in BlackBerry® Java Development Environment 5.0. The BlackBerry extensions to JSR 179 is supported on BlackBerry devices that run BlackBerry Device Software 5.0.0 or later. The JSR 179 Location API is supported on BlackBerry devices that run BlackBerry® Device Software 4.0.2 or later. For more information about GPS support on BlackBerry devices, visit http://www.blackberry.com/knowledgecenterpublic to read DB-00615.
You can retrieve the location of a BlackBerry device by performing the following steps.
Step 1: Specify the GPS mode.
Click here for a code sample: Specifying the GPS mode
/* JSR 179 */
Criteria myCriteria = new Criteria();
/* JSR 179 extension */
BlackBerryCriteria myBlackBerryCriteria = new BlackBerryCriteria(…);
|
Step 2: Retrieve a location provider.
Click here for a code sample: Retrieving a location provider
/* JSR 179 */
LocationProvider myProvider = LocationProvider.getInstance(myCriteria);
/* JSR 179 extension */
BlackBerryLocationProvider myBlackBerryProvider =
(BlackBerryLocationProvider) LocationProvider.getInstance(myBlackBerryCriteria);
|
Step 3: Make a GPS request based on the frequency of the location fix.
Click here for a code sample: Making a GPS request based on the frequency of the location fix
/*
* Single location fix
*/
/* JSR 179 */
Location myLoc = myProvider.getLocation(…);
/* JSR 179 extension */
BlackBerryLocation myBlackBerryLoc = myBlackBerryProvider.getLocation(…);
/*
* Continuous location fixes
*/
/* JSR 179 */
myProvider.setLocationListener(…);
/* JSR 179 extension */
myBlackBerryProvider.setLocationListener(…);
|
Step 4: Retrieve the location of a BlackBerry device.
Click here for a code sample: Retrieving the location of a BlackBerry device
/* JSR 179 */
double lat = myLoc.getQualifiedCoordinates().getLatitude();
double lng = myLoc.getQualifiedCoordinates().getLongitude();
double alt = myLoc.getQualifiedCoordinates().getAltitude();
/* JSR 179 extension */
double lat = myBlackBerryLoc.getQualifiedCoordinates().getLatitude();
double lng = myBlackBerryLoc.getQualifiedCoordinates().getLongitude();
double alt = myBlackBerryLoc.getQualifiedCoordinates().getAltitude();
|
When you use the JSR 179 Location API to retrieve the location of a BlackBerry device, a single location request returns a Location that is provided by a LocationProvider. The GPS mode that the LocationProvider uses to retrieve the location is specified in a Criteria instance.
Similarly, when you use the BlackBerry extension to JSR 179 to retrieve the location of a BlackBerry device, a single location request returns a BlackBerryLocation that is provided by a BlackBerryLocationProvider. The GPS mode that the BlackBerryLocationProvider uses to retrieve the location is specified in a BlackBerryCriteria instance.
For more information about designing a GPS application for the BlackBerry device, visit http://www.blackberry.com/knowledgecenterpublic to read DB-00671.
Click here for a code sample: Determining satellite information
// The following code sample demonstrates how to request a location fix
// and then determine the current number of satellites in view, tracked
// satellites, average satellite signal quality, GPS data source
// (internal GPS or external Bluetooth® GPS puck), and the GPS mode.
import java.util.*;
import net.rim.device.api.gps.*;
import javax.microedition.location.*;
public class handleGPS
{
static GPSThread gpsThread;
static int satCount;
static int signalQuality;
static int dataSource;
static int gpsMode;
public handleGPS()
{
gpsThread = new GPSThread();
gpsThread.start();
}
private static class GPSThread extends Thread
{
public void run()
{
try
{
BlackBerryCriteria myCriteria =
new BlackBerryCriteria(GPSInfo.GPS_MODE_AUTONOMOUS);
try
{
BlackBerryLocationProvider myProvider =
(BlackBerryLocationProvider)
LocationProvider.getInstance(myCriteria);
try
{
BlackBerryLocation myLocation =
(BlackBerryLocation)myProvider.getLocation(300);
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 = ":";
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 )
{
return;
}
catch ( LocationException lex )
{
return;
}
}
catch ( LocationException lex )
{
return;
}
}
catch ( UnsupportedOperationException uoex )
{
return;
}
return;
}
}
}
|
| Item | Advantage |
|---|---|
| BlackBerryLocationProvider |
Keep the GPS receiver active by specifying an interval, in seconds, that is greater than 0 when you invoke BlackBerryLocationProvider.pauseLocationTracking(). For example, you can specify 60 so that the application tries to retrieve a location fix every 60 seconds. The location fix is not provided to your application during the paused state. |
| BlackBerryCriteria |
|
| BlackBerryLocation |
|
| GPSInfo |
Query the GPS capabilities on the BlackBerry device so that you can verify if a GPS mode is supported, by invoking GPSInfo.isGPSModeAvailable(). |
Packages: net.rim.device.api.lbs, javax.microedition.location
In BlackBerry® Java Development Environment 5.0, the net.rim.device.api.lbs.Locator API provides the geocoding methods that can allow you to request geospatial coordinates for a street address. It also provides the reverse geocoding methods that can allow you to request a street address for a geospatial coordinate.
You can use the geocode() method to request geospatial coordinates. A successful request returns an array of Landmark objects.
You can use the reverseGeocode() methods to request an approximate address, city, province/state or country information. A successful request returns an array of Landmark objects. A Landmark 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 device application can use the Locator class to make only one request at a time.
Your application must request geocoding or reverse geocoding information outside of the event dispatch thread. Requests made on the event dispatch thread are denied and result in a IllegalThreadStateException. Each request for geocoding or reverse geocoding information is sent to the LBS Locate Server. If a request is unsuccessful, a LocatorException is thrown with an error code that indicates the reason for the failure. If a request fails or 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 requests for geocoding or reverse geocoding information throw a MapServiceException.
Request results are not cached on the BlackBerry device.
Click here for a code sample: Retrieving a street address by using reverse geocoding
import 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 )
{
}
}
};
}
|
Packages: net.rim.blackberry.api.invoke, net.rim.blackberry.api.maps, net.rim.blackberry.api.menuitem, net.rim.device.api.lbs
You can create a BlackBerry® device application that interacts with BlackBerry® Maps. BlackBerry Maps is a map and location application that can display a map, the location of the BlackBerry device, a route from a starting location to a specific ending location, and points of interest on a map.
Your application can interact with BlackBerry Maps in the following ways:
BlackBerry Maps can be installed on BlackBerry devices that run 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 device application that interacts with BlackBerry Maps.
Click here for a code sample: Invoking BlackBerry Maps by using the default settings
import net.rim.blackberry.api.invoke.*;
public class invokeMaps
{
public invokeMaps()
{
Invoke.invokeApplication(Invoke.APP_TYPE_MAPS, new MapsArguments());
}
}
|
You can display a map in a UI field by using use the net.rim.device.api.lbs.MapField class. Your BlackBerry® device application can use a MapField object to get data either from a map server for location-based services or a BlackBerry device with BlackBerry® Maps installed. If location information is not present on the BlackBerry device, the BlackBerry device application can use a MapField object to request data from the map server.
The MapField class allows a BlackBerry device application to change and retrieve the properties of the map including the zoom level, the center of the map, and the current rotation of the map. To use the MapField class, BlackBerry Maps must be installed on the BlackBerry device and the BlackBerry device must be able to download data from the map server for location-based services.
For more information, see Application Integration. To download a sample application that demonstrates how to use the MapField class, visit www.blackberry.com/go/mapfieldsample.
You can add a menu item to the menu of BlackBerry® Maps by using the ApplicationMenuItem class and registering the ApplicationMenuItem with the ApplicationMenuItemRepository (type MENUITEM_MAPS). When you register the menu item, you must use an ApplicationDescriptor. When your ApplicationMenuItem is invoked, your application is passed a MapView context object.
For more information, see Application Integration or visit www.blackberry.com/knowledgecenterpublic to read article DB-00618.
Copyright 1999-2010 Research In Motion Limited. 295 Phillip Street, Waterloo, Ontario, Canada, N2L 3W8. All Rights Reserved.
Copyright 1993-2003 Sun Microsystems, Inc. 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark of Sun Microsystems,
Inc.