net.rim.device.api.gps
Class LocationInfo

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

public class LocationInfo
extends Object

Provides access to location configuration information on the device.

This class provides the following:

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
Category: Signed static int GEOLOCATION_MODE
          The default geolocation mode used to retrieve the optimal location from geolocation positioning methods.
Category: Signed static int GEOLOCATION_MODE_CELL
          A geolocation mode used to obtain the location using cell tower positioning.
Category: Signed static int GEOLOCATION_MODE_WLAN
          A geolocation mode used to obtain the location using WLAN access point positioning.
Category: Signed static int LOCATION_SOURCE_GEOLOCATION
          Indicates geolocation as the location source.
Category: Signed static int LOCATION_SOURCE_GEOLOCATION_CELL
          Indicates geolocation cell tower positioning as the location source.
Category: Signed static int LOCATION_SOURCE_GEOLOCATION_WLAN
          Indicates geolocation WLAN access point positioning as the location source.
 
Method Summary
Category: Signed static int getAvailableLocationSources()
          Determines which location sources are available to provide location information.
Category: Signed static int getSupportedLocationSources()
          Determines which location sources are supported on the device.
Category: Signed static boolean isLocationOn()
          Determines whether the Location Services option is turned on.
Category: Signed static boolean isLocationSourceAvailable(int mode)
          Determines if a specific location source is available to provide location information.
Category: Signed static boolean isLocationSourceSupported(int mode)
          Determines if a specific location source is currently supported on the device.
Category: Signed static boolean isModeAvailable(int mode)
          Determines whether a location mode is available.
Category: Signed 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 location services is turned on, GPS is enabled if the device supports GPS and if the IT Policy allows GPS access, and Geolocation services is enabled if the service book, IT policy, and 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, it is recommended that your application 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





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. All Rights Reserved.
Copyright 2002-2003 Nokia Corporation All Rights Reserved.
Java is a trademark of Sun Microsystems, Inc.