net.rim.device.api.gps
Class GPSSettings

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

public class GPSSettings
extends Object

Provides access to the internal GPS receiver of the BlackBerry device.

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 4.2.0

Field Summary
Category: Signed static int AUTH_LIFETIME_ERROR
          Indicates an internal error has occurred when retrieving the authentication life time value.
Category: Signed static int AUTH_LIFETIME_UNSET
          Indicates that the authentication life time value was not set by the network.
 
Method Summary
Category: Signed static int getAuthLifeTime()
          Returns the authentication life time value that is received from the network.
Category: Signed static boolean isPDEInfoRequired(int mode)
          Determines whether Position Determination Entity (PDE) information must be specified to retrieve an assisted GPS position.
Category: Signed static boolean setPDEInfo(String ip, int port)
          Sets the given PDE IP address and port number for the BlackBerry device.
Category: Signed static boolean setPDEInfo(String ip, int port, int authLifeTime)
          Sets the given PDE IP address, port number, and authentication life time values for the BlackBerry device.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 



Field Detail

AUTH_LIFETIME_ERROR

public static final int AUTH_LIFETIME_ERROR
Indicates an internal error has occurred when retrieving the authentication life time value.

The authentication life time value indicates the time period for which PDE authentication is valid. The authentication life time value is sent by the network after authentication is performed by the PDE server.

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 4.7.0

AUTH_LIFETIME_UNSET

public static final int AUTH_LIFETIME_UNSET
Indicates that the authentication life time value was not set by the network.

The authentication life time value indicates the time period for which PDE authentication is valid. The authentication life time value is sent by the network after authentication is performed by the PDE server.

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 4.7.0


Method Detail

isPDEInfoRequired

public static boolean isPDEInfoRequired(int mode)
Determines whether Position Determination Entity (PDE) information must be specified to retrieve an assisted GPS position.

Parameters:
mode - The requested GPS mode.
Returns:
true if the application must set the PDE information, 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 5.0.0

setPDEInfo

public static boolean setPDEInfo(String ip,
                                 int port)
                          throws IllegalArgumentException
Sets the given PDE IP address and port number for the BlackBerry device.

Some wireless service providers require that your application call this method with the correct IP address and port number values of the PDE before your application can use the Location API. To obtain the required IP address and port number for the PDE server, contact the wireless service provider.

Parameters:
ip - The IP address for the PDE server.
port - The port number for the PDE server.
Returns:
true if the IP address and port number values are valid, false otherwise.
Throws:
UnsupportedOperationException - if a BlackBerry device with a non-Qualcomm chipset tries to invoke this method. This exception is also thrown if the application is not allowed to use the internal GPS receiver.
IllegalArgumentException - if the IP address string is not in the correct format.
NullPointerException - if the IP address is null.
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 4.2.0

setPDEInfo

public static boolean setPDEInfo(String ip,
                                 int port,
                                 int authLifeTime)
                          throws IllegalArgumentException
Sets the given PDE IP address, port number, and authentication life time values for the BlackBerry device.

Some wireless service providers require that your application call this method with the correct IP address, port number, and authentication life time values of the PDE before your application can use the Location API. To obtain the required IP address and port number for the PDE server, contact the wireless service provider.

Parameters:
ip - The IP address for the PDE server.
port - The port number for the PDE server.
authLifeTime - The authentication life time value (in seconds) for the PDE server.
Returns:
true if the IP address, port number, and authentication life time values are valid, false otherwise.
Throws:
UnsupportedOperationException - if a BlackBerry device with a non-Qualcomm chipset tries to invoke this method. This exception is also thrown if the application is not allowed to use the internal GPS receiver.
IllegalArgumentException - If the IP address string is not in the correct format.
NullPointerException - if the IP address is null.
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 4.7.0

getAuthLifeTime

public static int getAuthLifeTime()
                           throws UnsupportedOperationException
Returns the authentication life time value that is received from the network.

The authentication life time value indicates the time period for which PDE authentication is valid. The authentication life time value is sent by the network after authentication is performed by the PDE server.

Note: This method should be called only after invoking the GPSSettings.setPDEInfo(String ip, int port, int authLifeTime) method.

Returns:
  • AUTH_LIFETIME_ERROR - if this process did not invoke setPDEInfo(String ip, int port, int authLifeTime).
  • AUTH_LIFETIME_UNSET - if the authentication life time value was not yet set by the network.
  • An integer value representing the authentication life time value (in seconds) set by the network.
Throws:
UnsupportedOperationException - if a BlackBerry device with a non-Qualcomm chipset tries to invoke this method, or a BlackBerry device that operates on a CDMA network invokes this method for a wireless service provider that is not supported.
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 4.7.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.