net.rim.device.api.gps
Class LocationInfo

java.lang.Object
  net.rim.device.api.gps.LocationInfo

public class LocationInfo
extends Object

Provides access to location configuration information on the BlackBerry device.

This class provides the following:

• constants that define geolocation modes and location sources that can be used by applications that use the Location API. GPS-specific constants are defined in GPSInfo.
  • location sources - represents geolocation sources. These constants are used in LocationInfo methods to query the available and supported location sources. These constants are also used in the BlackBerryLocation and BlackBerryLocationProvider classes to indicate the type of location source.
  • modes - represents the location mode to use when requesting a location fix. You can set a specific location mode in a BlackBerryCriteria object. These modes are also used to indicate the mode that was used to obtain a BlackBerryLocation.
• methods to query location configuration information for modes and sources. A location source is considered available if all the settings to use the location source are enabled. A location source is considered supported if the device hardware supports the source and if the IT policy allows access to the location source. A location source might be supported but might not be available (for example, the user turned it off). A location source might be unsupported for the following reasons:
  • unsupported by the device hardware
  • disabled by an IT policy
  • disabled by a service book
  • radio is turned off
  • insufficient network connectivity

• methods to query or enable the Location Services (includes GPS and geolocation) option on the device.

  The following is a typical use for this feature:

  The Location Services option is disabled on the device, and the geolocation and GPS services are unavailable. When the application launches, the application calls LocationInfo.isLocationOn() to determine if the Location Services option is on. A dialog box prompts the user to turn on Location Services. When the user's permission is received, the application calls LocationInfo.setLocationOn() to turn on Location Services.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 6.0.0

Field Summary
	static int	GEOLOCATION_MODE The default geolocation mode used to retrieve the optimal location from geolocation positioning methods.
	static int	GEOLOCATION_MODE_CELL A geolocation mode used to obtain the location using cell tower positioning.
	static int	GEOLOCATION_MODE_WLAN A geolocation mode used to obtain the location using WLAN access point positioning.
	static int	LOCATION_SOURCE_GEOLOCATION Indicates geolocation as the location source.
	static int	LOCATION_SOURCE_GEOLOCATION_CELL Indicates geolocation cell tower positioning as the location source.
	static int	LOCATION_SOURCE_GEOLOCATION_WLAN Indicates geolocation WLAN access point positioning as the location source.

Method Summary
	static int	getAvailableLocationSources() Determines which location sources are available to provide location information.
	static double	getBearing(double lat1, double lon1, double lat2, double lon2) Retrieves the initial bearing between two specified locations (starting and ending locations).
	static int	getSupportedLocationSources() Determines which location sources are supported on the device.
	static boolean	isLocationOn() Determines whether the Location Services option is turned on.
	static boolean	isLocationSourceAvailable(int mode) Determines if a specific location source is available to provide location information.
	static boolean	isLocationSourceSupported(int mode) Determines if a specific location source is currently supported on the device.
	static boolean	isModeAvailable(int mode) Determines whether a location mode is available.
	static void	setLocationOn() Turns the Location Services option on.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

GEOLOCATION_MODE

public static final int GEOLOCATION_MODE

The default geolocation mode used to retrieve the optimal location from geolocation positioning methods.

See Also:

Constant Field Values

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 6.0.0

GEOLOCATION_MODE_CELL

public static final int GEOLOCATION_MODE_CELL

A geolocation mode used to obtain the location using cell tower positioning. If geolocation is not supported by the device, the location is obtained using the cellsite mode that is provided by the wireless service provider (if available).

See Also:

Constant Field Values

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 6.0.0

GEOLOCATION_MODE_WLAN

public static final int GEOLOCATION_MODE_WLAN

A geolocation mode used to obtain the location using WLAN access point positioning.

See Also:

Constant Field Values

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 6.0.0

LOCATION_SOURCE_GEOLOCATION_CELL

public static final int LOCATION_SOURCE_GEOLOCATION_CELL

Indicates geolocation cell tower positioning as the location source.

See Also:

Constant Field Values

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 6.0.0

LOCATION_SOURCE_GEOLOCATION_WLAN

public static final int LOCATION_SOURCE_GEOLOCATION_WLAN

Indicates geolocation WLAN access point positioning as the location source.

See Also:

Constant Field Values

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 6.0.0

LOCATION_SOURCE_GEOLOCATION

public static final int LOCATION_SOURCE_GEOLOCATION

Indicates geolocation as the location source.

See Also:

Constant Field Values

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 6.0.0

Method Detail

isModeAvailable

public static boolean isModeAvailable(int mode)

Determines whether a location mode is available. If a Bluetooth GPS receiver is used, the location mode is irrelevant because all location modes are available.

Parameters:

mode - The location mode can be one of the following:

GPSInfo.GPS_MODE_CELLSITE
GPSInfo.GPS_MODE_ASSIST
GPSInfo.GPS_MODE_AUTONOMOUS
GPSInfo.GPS_MODE_CDMA_MS_BASED
GPSInfo.GPS_MODE_CDMA_MS_ASSIST
GPSInfo.GPS_MODE_CDMA_SPEED_OPTIMAL
GPSInfo.GPS_MODE_CDMA_ACCURACY_OPTIMAL
GPSInfo.GPS_MODE_CDMA_DATA_OPTIMAL
GPSInfo.GPS_MODE_BT
LocationInfo.GEOLOCATION_MODE
LocationInfo.GEOLOCATION_MODE_CELL
LocationInfo.GEOLOCATION_MODE_WLAN

Returns:

true if the location mode is available, false otherwise.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 6.0.0

isLocationOn

public static boolean isLocationOn()

Determines whether the Location Services option is turned on. When the Location Services option is turned on, both GPS and Geolocation services are enabled. Users can change the Location Services option on the device in Location Settings under Options.

Returns:

true if Location Services is turned on, false otherwise.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 6.0.0

setLocationOn

public static void setLocationOn()
                          throws ControlledAccessException

Turns the Location Services option on. When the Location Services option is turned on, GPS is enabled if the device supports GPS and if the IT policy allows GPS access, and geolocation services are enabled if the service book, IT policy, and the user allow geolocation access.

Calling this method has the same effect as having the user turn on the Location Services option on the device in Location Settings under Options.

For privacy reasons, your application MUST prompt the user for permission to turn on the Location Services.

Throws:

ControlledAccessException - if the calling application does not have permission to modify the device settings.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 6.0.0

getSupportedLocationSources

public static int getSupportedLocationSources()

Determines which location sources are supported on the device. A location source might be supported by the device hardware and allowed access by the IT policy but might not be available for use (for example, the user turned it off).

To determine supported location sources, check the returned integer mask for a 1 in the corresponding position using:

GPSInfo.GPS_DEVICE_INTERNAL
GPSInfo.GPS_DEVICE_BLUETOOTH
LocationInfo.LOCATION_SOURCE_GEOLOCATION_CELL
LocationInfo.LOCATION_SOURCE_GEOLOCATION_WLAN

LOCATION_SOURCE_GEOLOCATION_CELL is considered as supported if either geolocation cell tower positioning or the cellsite mode provided by the wireless service provider is supported.

Returns:

An integer mask identifying which location sources are supported. To determine if the device supports any location sources, check for a returned value > 0.

The following example verifies if the location source for WLAN geolocation is supported:

if ((mask & LocationInfo.LOCATION_SOURCE_GEOLOCATION_WLAN) != 0)

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 6.0.0

isLocationSourceSupported

public static boolean isLocationSourceSupported(int mode)

Determines if a specific location source is currently supported on the device. A location source might be supported by the device hardware and allowed access by the IT policy but might not be available for use (for example, the user turned it off).

Parameters:

mode - The location source can be one of the following:

GPSInfo.GPS_DEVICE_INTERNAL
GPSInfo.GPS_DEVICE_BLUETOOTH
LocationInfo.LOCATION_SOURCE_GEOLOCATION
LocationInfo.LOCATION_SOURCE_GEOLOCATION_CELL
LocationInfo.LOCATION_SOURCE_GEOLOCATION_WLAN

Returns:

true if the location source is supported, false otherwise.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 6.0.0

getAvailableLocationSources

public static int getAvailableLocationSources()

Determines which location sources are available to provide location information. A location source is available when all the settings for that location source are turned on.

To determine available location sources, check the returned integer mask for a 1 in the corresponding position using:

GPSInfo.GPS_DEVICE_INTERNAL
GPSInfo.GPS_DEVICE_BLUETOOTH
LocationInfo.LOCATION_SOURCE_GEOLOCATION_CELL
LocationInfo.LOCATION_SOURCE_GEOLOCATION_WLAN

Returns:

An integer mask indicating which location source is available. To determine if any location sources are available, check for a returned value > 0.

The following example verifies if the location source for WLAN geolocation is available:

if ((mask & LocationInfo.LOCATION_SOURCE_GEOLOCATION_WLAN) != 0)

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 6.0.0

isLocationSourceAvailable

public static boolean isLocationSourceAvailable(int mode)

Determines if a specific location source is available to provide location information. A location source is available when all the settings for that location source are turned on.

Parameters:

mode - The location source can be one of the following:

GPSInfo.GPS_DEVICE_INTERNAL
GPSInfo.GPS_DEVICE_BLUETOOTH
LocationInfo.LOCATION_SOURCE_GEOLOCATION
LocationInfo.LOCATION_SOURCE_GEOLOCATION_CELL
LocationInfo.LOCATION_SOURCE_GEOLOCATION_WLAN

Returns:

true if the location source is available, false otherwise.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 6.0.0

getBearing

public static double getBearing(double lat1,
                                double lon1,
                                double lat2,
                                double lon2)

Retrieves the initial bearing between two specified locations (starting and ending locations). This is the (initial) bearing of a starting point to and ending point (in degrees) from north

Parameters:

lat1 - The latitudinal coordinate (in degrees) for the starting location.

lon1 - The longitudinal coordinate (in degrees) for the starting location.

lat2 - The latitudinal coordinate (in degrees) for the ending location.

lon2 - The longitudinal coordinate (in degrees) for the ending location.

Returns:

The initial bearing (in degrees) between the starting and ending locations.

Category:

Signed: This element is only accessible by signed applications. If you intend to use this element, please visit http://www.blackberry.com/go/codesigning to obtain a set of code signing keys. Code signing is only required for applications running on BlackBerry smartphones; development on BlackBerry Smartphone Simulators can occur without code signing.

Since:

BlackBerry API 7.0.0