BlackBerry
Skip Top Navigation
Developers Partners
North America [change region] Products Solutions Purchasing Support
Developers


API Spotlight: BlackBerry does GPS

Richard Evers,

My family took a trip to California last year. During our return journey from Napa Valley, we lost our way and ended up in a cemetery in a very lonely section of California.

I powered up my personal GPS, hung it out of the window for an eternity to sync with the satellites, got a street level map of the region, and used it to find the highway heading back to San Francisco.

Without question, my GPS is one of the best investments Iíve ever made. With GPS in hand, the fear of getting lost while traveling is largely a thing of the past.

The GPS-enabled BlackBerry 7520 Wireless Handheld™ implementation includes traditional Autonomous mode (direct sync with satellites), Assisted mode, and Cellsite mode. Each mode has strengths and weaknesses that will be discussed in this article.

Topics within this section include:

How it Works

Autonomous GPS works by syncing with four or more satellites to determine latitude, longitude and altitude.

Latitude is the angular distance north or south of the equator measured by lines circling the earth parallel to the equator measured from 0 degrees to 90 degrees.

Longitude is the angular distance east or west of the prime meridian (Greenwich Meridian) as measured by lines perpendicular to the parallels and converging at the poles 0 degrees to 180 degrees. Greenwich Meridian runs through "the primary transit" instrument (the main telescope) at the Royal Observatory in Greenwich, England.

Altitude is the current elevation above sea level.

GPS accuracy can be improved through use of the Wide Area Augmentation System (WAAS). WAAS is a Satellite-Based Augmentation System (SBAS) that calculates the errors in the GPS signal at several monitoring stations, and then transmits error correction messages from geostationary satellites to GPS receivers.

Statement from the FAA

WAAS is based on a network of approximately 25 ground reference stations that covers a very large service area. Signals from GPS satellites are received by wide area ground reference stations (WRSs). Each of these precisely surveyed reference stations receive GPS signals and determine if any errors exist. These WRSs are linked to form the U.S. WAAS network. Each WRS in the network relays the data to the wide area master station (WMS) where correction information is computed. The WMS calculates correction algorithms and assesses the integrity of the system. A correction message is prepared and uplinked to a geosynchronous satellite via a ground uplink system (GUS). The message is then broadcast from the satellite on the same frequency as GPS (L1, 1575.42MHz) to receivers on board aircraft (or hand-held receivers) which are within the broadcast coverage area of the WAAS. These communications satellites also act as additional navigation satellites for the aircraft, thus, providing additional navigation signals for position determination.

The WAAS will improve basic GPS accuracy to approximately 7 meters vertically and horizontally, improve system availability through the use of geostationary communication satellites (GEOs) carrying navigation payloads, and to provide important integrity information about the entire GPS constellation.

In practice, WAAS correction can improve accuracy to less than 7 meters in most commercial GPS units. GPS accuracy is better at night when the ionospheric errors have decreased. Accuracy of 1.8 meters has been documented in WAAS-capable devices at night.

The easiest way to understand how GPS works is to initially determine positioning from a two-dimensional perspective.

For example, four amazing birds (Raven, Robin, Jay and Martin) are gathered together in a park. Raven is lost and asks the other birds for help. Robin tells Raven that heís 15 km away from Lancaster, PA (as the bird flies). Jay tells Raven that heís 7 km away from Leola, PA, and Martin tells Raven that heís 8 km away from Strasburg, PA.

Raven whips out his trusty map and geometry compass, and (carefully using his wings as if they were hands) draws a circle around Lancaster with a scaled down radius of 15 km, draws a circle around Leola with a scaled down radius of 7 km, and draws a final circle around Strasburg with a scaled down radius of 8 km. The intersection of the three circles shows that Raven is perched in a park in Bird in Hand, PA.

To bring this into the realm of GPS, you would need three reference points represented by spheres where each point would be the distance from the caller to the satellite. Earth would act as the final sphere for this example. The final earthbound intersection point of the spheres would provide the latitude, longitude and altitude. Additionally, directional movement and speed could be mathematically determined after each refresh cycle.

Two things must be known before calculating GPS values:

  1. The location of each of the satellites
  2. The distance between the GPS unit and each of four or more satellites

The GPS clock, which is separate from the BlackBerry handheld clock, must also be regularly synced to the atomic clocks on the satellites before trying to determine distance. Constant syncing with atomic clocks is a standard feature of all GPS units.

There are 24 active GPS satellites in high orbit at all times in predictable locations with 3 backup satellites. Satellites are solar powered, 17 feet across when the solar panels are extended, weigh roughly 2,000 pounds, transmit up to about 50 watts, and are built to remain in use for 10 years. New satellites are constantly being built and launched by the U.S. Department of Defense to ensure that the network remains viable at all times.

Satellite location is initially determined by receiving the satellite identifier and then performing a lookup in a local GPS positioning almanac to determine where the satellite should be orbiting at that moment in time. The U.S. Department of Defense closely monitors the position of each satellite and reprograms the satellites to transmit location adjustments to all GPS units on a regular basis, and also repositions the satellites from time to time to return to normal orbit.

The distance between the GPS unit and a satellite is determined through use of a pseudo-random pattern. This pattern is generated and transmitted by the satellite at the same time as the GPS unit generates the same pattern. The satelliteís pattern will start to be received later than the initial time of generation, which means that the GPS unit can determine how far away the satellite is by multiplying the length of delay by the speed of light. This is why it is critical to sync to the atomic clock, and why some calculation errors still occur because the GPS clock will never be in perfect sync with the atomic clocks. Other factors come into play to further degrade the calculation such as signal obstructions on earth and in the atmosphere.

With location and distance known, a calculation can be made to determine where the four spheres intersect. Itís possible for three spheres to intersect even if the underlying values are wrong, but four spheres cannot intersect unless the calculations are accurate. Longitude and latitude can be determined with three satellites, but the fourth satellite is needed to determine altitude and reduce errors. Distance calculations are made in real time using the clock settings of the GPS unit, therefore all calculations will be proportionately incorrect and close enough to intersect the four spheres.

Once the GPS unit has fully synced with the satellites to determine position, itís easy to determine direction, actual and average speed, trip duration and length, estimated time of arrival, and traveled path by comparing and accumulating differences between sampling periods.

The greatest strengths of autonomous GPS is that it is accurate, free to use, and performs rapid updates after being fully synced with four satellites.

The greatest weaknesses are:

  • It can take several minutes to fully sync with four or more satellites the first time it is powered up in a new area
  • Power consumption can be fairly heavy for a wireless device depending on the sampling ratio. Itís often recommended to use a car charger when using a GPS unit for driving directions.
  • Connectivity is often hard to maintain because satellite signal strength of 50 watts from a distance of 12 miles is so weak that GPS units tend to lose connection when indoors, and when traveling through or around physical obstructions. The radio signal (1575.42 MHz in the UHF band for civilian use) travels by line of sight, which means that it will pass through clouds, glass and plastic but will not pass through most solid objects such as buildings, overpasses, earth, automobile bodies and mountains. It even has a hard time passing through water.
  • Accuracy is hard to maintain because signal delay errors can be introduced in the atmosphere through reflection off tall buildings and rocks and through use of the internal GPS clock. Additionally, orbital errors can be encountered where the reported satellite location is inaccurate.
  • Buildings, terrain, electronic interference and more can restrict satellite "visibility".
  • Poor placement of satellites (e.g. located in the line of sight or in a tight grouping) can degrade accuracy.


Supported Modes

The GPS implementation for BlackBerry includes Autonomous mode, Assisted mode, and Cellsite mode. If youíve managed to read this far, then you are pretty knowledgeable about Autonomous mode. Weíll cover the other modes here.

Cellsite Mode

Provides the GPS coordinate of the serving cellsite node. This mode provides the least accurate location information in the fastest possible time. It is useful when rapid emergency assistance is required and broad strokes positioning will suffice. It uses cell tower location to calculate approximate positioning. Accuracy is very poor in rural areas where cell tower density is sparse. Conversely, dense urban areas with dense concentrations of cell towers will improve accuracy, often times to within a few city blocks.

Assisted Mode

Uses the network in an assisted mode. It is more accurate than cellsite mode but takes more time to obtain location information due to wireless latency and server response times. It works by providing some information to a remote server for processing. The device makes a request for "assist data" from the server on the carrier network which has location information. The server will respond with "assist data" (which includes ephemeris, ionospheric modeling, etc). The greatest benefit of assisted GPS (aGPS) over autonomous GPS is the response time. Initial aGPS responses can return in under 10 seconds depending on network latency. Autonomous GPS takes longer to determine the initial position, but is fast for all subsequent positions.


GPS for BlackBerry

The Chip

The current implementation of the BlackBerry 7520TM uses a SiRFstarIIe/LP chipset to provide GPS services. Note that the chip used to provide GPS services may change over time.

This chip set supports Satellite Based Augmentation System (SBAS), which encompasses WAAS and the European Geostationary Navigation Overlay Service (EGNOS). It also provides support for Coast Guard Maritime Differential GPS (DGPS).

The chip cold starts in 45 seconds, uses less than 175 mW at full power, and will automatically support a mode to reduce power to under 60 mW and under 20 mA.

The manufacturer states that positional accuracy is less than 10 meters for autonomous GPS, less than 5 meters when WAAS is enabled, and less than 2.5 meters when enabled for Beacon DGPS. The chip is accurate beneath 60,000 feet, and under 1,000 knots (1,152 mph or 1,850 kph).

Source: http://www.sirf.com/products-ss2eLP.html


GPS coding in brief

try {
  // Create a Criteria object for
  // defining selection criteria
  Criteria cr = new Criteria();

  //
  // setAddressInfoRequired()
  // true: if location provider should be able
  // to determine textual address information
  // there is no guarantee that AddressInfo
  // is available in any mode
  // Default = false
  //
  // Note: in the current implementation,
  // setAddressInfoRequired() has no impact
  // on results
  //
// cr.setAddressInfoRequired(false);

  //
  // setAltitudeRequired()
  // true: if location provider should be able
  // to determine device altitude
  // AUTONOMOUS GPS is only mode that could
  // provide this information
  // Default = false
  //
  // Note: in the current implementation,
  // setAltitudeRequired() has no impact
  // on results
  //
//  cr.setAltitudeRequired(false);

  //
  // setPreferredResponseTime()
  // value: response time or timeout if the
  // response isn't provided in time
  // default: NO_REQUIREMENT
  //
  // Note: in the current implementation,
  // setPreferredResponseTime() has no impact
  // on results
  //
// cr.setPreferredResponseTime(NO_REQUIREMENT);

  //
  // setSpeedAndCourseRequired()
  // true: location provider should be able to
  // determine speed and course
  // Speed and course should be available in
  // all three modes
  // Default = false
  //
  // Note: in the current implementation,
  // setSpeedAndCourseRequired() has no
  // impact on results
  //
// cr.setSpeedAndCourseRequired(false);


  //
  // setCostAllowed()
  // Default = true
  // true: if there can be a cost associated
  // with determining location information
  // ASSISTED GPS is only mode that could
  // incur a direct cost
  //
  cr.setCostAllowed(true);

  //
  // setHorizontalAccuracy()
  // Default = NO_REQUIREMENT
  // value: the desired horizonal accuracy
  // in meters
  // Use NO_REQUIREMENT or a larger value (500
  // meters) for assisted and cellsite
  // set a lower value (such as 10 meters)
  // for autonomous
  //
  cr.setHorizontalAccuracy(NO_REQUIREMENT);

  //
  // setPreferredPowerConsumption()
  // Default = NO_REQUIREMENT
  // POWER_LEVEL_LOW autonomous, cellsite
  // POWER_LEVEL_MEDIUM autonomous, assisted
  // POWER_LEVEL_HIGH autonomous, assisted
  // NO_REQUIREMENT autonomous, assisted
  //
  cr.setPreferredPowerConsumption
    (NO_REQUIREMENT);

  //
  // setVerticalAccuracy()
  // Default = NO_REQUIREMENT
  // value: the desired vertical accuracy
  // in meters
  // Use NO_REQUIREMENT or a larger value
  // (500 meters) for assisted and cellsite
  // set a lower value (such as 10 meters)
  // for autonomous
  //
  cr.setVerticalAccuracy(NO_REQUIREMENT);

  //
  // set up a location provider instance
  //
  LocationProvider lp =
    LocationProvider.getInstance(cr);

  //
  // Get location, one minute timeout
  // leave up to 180 seconds for autonomous mode
  //
  Location l = lp.getLocation(60);

  Coordinates c = l.getQualifiedCoordinates();

  if ( c != null ) {
    // use coordinate information
    double latitude  = c.getLatitude();
    double longitude = c.getLongitude();
    float  altitude  = c.getAltitude();
  }

  } catch (LocationException e ) {
    // Not able to retrieve location information
    ...
  }
}


The API

BlackBerry supports JSR-179: Location API for Java ME, and uses the javax.microedition.location package which consists of the following functionality:


Interface: LocationListener

A listener that receives events associated with a particular LocationProvider. Applications implement this interface and register it with a LocationProvider to obtain regular position updates. If location updates cannot be provided at the defined interval, then an update can be sent to the listener that contains an 'invalid' Location instance. Applications are responsible for any possible synchronization needed in the listener methods. The listener methods must return quickly and should not perform any extensive processing. The method calls are intended as triggers to the application. An application should do any necessary extensive processing in a separate thread and only use these methods to initiate processing.

Method:
LocationListener.locationUpdated

Syntax:

void locationUpdated
(
  LocationProvider provider,
  Location location
)
  

Description:

Called by the LocationProvider to which this listener has been registered. This method will be called periodically according to the interval defined when registering the listener to provide updates of the current location. The parameters are the source of the event (provider), and the new position (location).

Method:
LocationListener.providerStateChanged

Syntax:

void providerStateChanged
(
  LocationProvider provider,
  int newState
)
  

Description:

Called by the LocationProvider to which this listener has been registered when the state of the LocationProvider changes.

Provided state changes are delivered to the application as soon as possible after the state of a provider changes. The timing of these events are not related to the period of the location updates.

If the application is subscribed to receive periodic location updates, it will continue to receive these regardless of the state of the LocationProvider. If the application wishes to stop receiving location updates for an unavailable provider, it should de-register itself from the provider.

The parameters are the source of the event (provider), and the new state of the LocationProvider (newState), which is a constant value defined in the LocationProvider class as shown below:

  • AVAILABLE
  • OUT_OF_SERVICE
  • TEMPORARILY_UNAVAILABLE


Interface: ProximityListener

A listener to events associated with detecting proximity to some registered coordinates. Applications implement this interface and register it with a static method in LocationProvider to obtain notfications when proximity to registered coordinates has been detected.

This listener is called when the device enters the proximity of the registered coordinates. The proximity is defined as the proximity radius around the coordinates combined with the horizontal accuracy of the current sampled location.

The listener is called only once when the device enters the proximity of the registered coordinates. The registration with these coordinates is cancelled when the listener is called. If the application wants to be notified again about these coordinates, it must re-register the coordinates and the listener.

Method:
ProximityListener.monitoringStateChanged

Syntax:

void monitoringStateChanged
  (boolean isMonitoringActive)
  

Description:

Called to notify that the state of the proximity monitoring has changed. These state changes are delivered to the application as soon as possible after the state of the monitoring changes. The ProximityListener always remains registered until the application explicitly removes it with LocationProvider.removeProximityListener or when the application exits.

The parameter is a boolean (isMonitoringActive ) indicating the new state of the proximity monitoring. A value of true indicates that the proximity monitoring is active.

Method:
ProximityListener.proximityEvent

Syntax:

void proximityEvent
(
  Coordinates coordinates,
  Location location
)
  

Description:

After registering this listener with the LocationProvider, this method will be called the current location of the deviceis within the defined proximity radius of the registered coordinates.

The parameters are the registered coordinates to which proximity has been detected (coordinates), and the current location of the device (location).


Class: AddressInfo

This class holds textual address information about a location. Typically the information is a street address where the information is divided into fields (e.g. street, postal code, city, etc.). Defined field constants can be used to retrieve field data. If the value of a field is not available, it is set to null.

The names of the fields use terms and definitions that are commonly used in the United States. Addresses for other countries should map these to the closest corresponding entities used in that country.

This class is only a container for the information. The getField method returns the value set for the defined field using the setField method.

Field Notes
STREET  
EXTENSION Unit, flat, apartment number
POSTAL_CODE Postal or zip code
CITY Village, town or city
COUNTY  
STATE State or province
COUNTRY  
COUNTRY_CODE Two-letter ISO 3166-1 code
DISTRICT Municipal district
BUILDING_NAME  
BUILDING_FLOOR  
BUILDING_ROOM  
BUILDING_ZONE  
CROSSING1 Street in a crossing
CROSSING2 Street in a crossing
URL  
PHONE_NUMBER  

Constructor

AddressInfo()

Method: AddressInfo.getField

Syntax:

java.lang.String getField(int field)
  

Description:

Returns the value of an address field or null if the field is not available.

The parameter is the ID of the field to be retrieved.

This method will throw java.lang.IllegalArgumentException if the parameter field ID is not one of the constant values defined in this class

Method: AddressInfo.setField

Syntax:

void setField(int field, java.lang.String value)
  

Description:

Sets the value of an address field.

The parameters are the ID of the field to be set and the new value for the field. null is used to indicate that the field has no content.

This method throws java.lang.IllegalArgumentException if the parameter field ID is not one of the constant values defined in this class


Class: Coordinates

Represents coordinates as latitude-longitude-altitude values. The latitude and longitude values are expressed in degrees using floating point values. The degrees are in decimal values (rather than minutes/seconds). The coordinates are given using the WGS84 datum., which is a set of conventions, constants and formulae. For more information:

http://www.gps.gov.uk/guide4.asp

This class also provides convenience methods for converting between a string coordinate representation and the double representation used in this class.

Field Description
DD_MM_SS Identifier for string coordinate representation Degrees, Minutes, Seconds and decimal fractions of a second
DD_MM Identifier for string coordinate representation Degrees, Minutes, decimal fractions of a minute

Constructor

public Coordinates
(
  double latitude,
  double longitude,
  float altitude
)

Constructs a new Coordinates object with the values specified. The latitude and longitude parameters are expressed in degrees using floating point values. The degrees are in decimal values (rather than minutes/seconds). The coordinate values always apply to the WGS84 datum. The Float.NaN value can be used for altitude to indicate that altitude is not known.

Parameters:

latitude

  • Latitude of the location. Valid range: [-90.0, 90.0].
  • Positive values indicate northern latitude and negative values southern latitude.

longitude

  • Longitude of the location. Valid range: [-180.0, 180.0).
  • Positive values indicate eastern longitude and negative values western longitude.

altitude

  • Altitude of the location in meters, defined as height above WGS84 ellipsoid.
  • Float.NaN can be used to indicate that altitude is not known.

The constructor throws java.lang.IllegalArgumentException if an input parameter is out of the valid range.

Method: Coordinates.getLatitude

Syntax:

public double getLatitude()
 

Description

Returns the latitude component in degrees of this coordinate. Positive values indicate northern latitude and negative values southern latitude. The latitude is given in WGS84 datum.

Method: Coordinates.getLongitude

Syntax:

public double getLongitude()
  

Description

Returns the longitude component in degrees of this coordinate. Positive values indicate eastern longitude and negative values western longitude. The longitude is given in WGS84 datum.

Method: Coordinates.getAltitude

Syntax:

public float getAltitude()
  

Description

Returns the altitude component in meters of this coordinate. Altitude is defined to mean height above the WGS84 reference ellipsoid. 0.0 means a location at the ellipsoid surface, negative values mean the location is below the ellipsoid surface, Float.NaN that no altitude is not available.

Method: Coordinates.setAltitude

Syntax:

public void setAltitude(float altitude)
  

Description:

Sets the geodetic altitude for this point. The parameter passed is the altitude of the location in meters, defined as height above the WGS84 ellipsoid. 0.0 means a location at the ellipsoid surface, negative values mean the location is below the ellipsoid surface, Float.NaN that no altitude is not available

Method: Coordinates.setLatitude

Syntax:

public void setLatitude(double latitude)
  

Description:

Sets the geodetic latitude for this point. Latitude is given as a double expressing the latitude in degrees in the WGS84 datum. The parameter passed is the latitude component of this location in degrees. Valid range: [-90.0, 90.0].

This method will throw java.lang.IllegalArgumentException if the latitude is out of the valid range.

Method: Coordinates.setLongitude

Syntax:

public void setLongitude(double longitude)
  

Description:

Sets the geodetic longitude for this point. Longitude is given as a double expressing the longitude in degrees in the WGS84 datum.

The parameter passed is the longitude of the location in degrees. Valid range: [-180.0, 180.0)

This method throws java.lang.IllegalArgumentException if longitude is out of the valid range.

Method: Coordinates.convert

Syntax:

public static double convert
  (java.lang.String coordinate)
  

Description:

Converts a String representation of a coordinate into float representation as used in this API. There are two string syntaxes supported:

  1. Degrees, minutes, seconds and decimal fractions of seconds. This is expressed as a string complying with the following Bibliotheque national de France (BNF) definition where the degrees are within the range [-179, 179] and the minutes and seconds are within the range [0, 59], or the degrees is -180 and the minutes, seconds and decimal fractions are 0:
    coordinate =
      degrees ":" minutes ":" seconds "." decimalfrac
      | degrees ":" minutes ":" seconds
      | degrees ":" minutes
    degrees = degreedigits | "-" degreedigits
    degreedigits =
      digit | nonzerodigit digit | "1" digit digit
    minutes = minsecfirstdigit digit
    seconds = minsecfirstdigit digit
    decimalfrac = 1*3digit
    digit = "0"|"1"|"2"|"3"|"4"|"5"|"6"|"7"|"8"|"9"
    nonzerodigit = "1"|"2"|"3"|"4|"5"|"6"|"7"|"8"|"9"
    minsecfirstdigit = "0"|"1"|"2"|"3"|"4"|"5"
          
  2. Degrees, minutes and decimal fractions of minutes. This is expressed as a string complying with the following BNF definition where the degrees are within the range [-179, 179] and the minutes are within the range [0, 59], or the degrees is -180 and the minutes and decimal fractions are 0:
    coordinate = degrees ":" minutes "." decimalfrac
      | degrees ":" minutes
    degrees = degreedigits | "-" degreedigits
    degreedigits =
      digit | nonzerodigit digit | "1" digit digit
    minutes = minsecfirstdigit digit
    decimalfrac = 1*5digit
    digit = "0"|"1"|"2"|"3"|"4"|"5"|"6"|"7"|"8"|"9"
    nonzerodigit = "1"|"2"|"3"|"4"|"5"|"6"|"7"|"8"|"9"
    minsecfirstdigit = "0"|"1"|"2"|"3"|"4"|"5"
          

For example, for the double value of the coordinate 61.51d, the corresponding syntax #1 string is "61:30:36" and the corresponding syntax #2 string is "61:30.6"

The single parameter passed is a String in either of the two representation specified above.

The method returns a double value with decimal degrees that matches the String representation given as the parameter.

This method will throw:

java.lang.IllegalArgumentException

  • The coordinate input parameter does not comply with the defined syntax for the indicated type or if the inputType is not one of the two constant values defined in this class

java.lang.NullPointerException

  • The coordinate string is null

Method: Coordinates.convert

Syntax:

public static java.lang.String convert
(
  double coordinate,
  int outputType
)
  

Description

Converts a double representation of a coordinate with decimal degrees into a string representation.

Parameters:

coordinate

  • A double representation of a coordinate

outputType

  • Type ID of the string representation wanted for output The constant DD_MM_SS identifies the syntax #1 and the constant DD_MM identifies the syntax #2.

This method returns a String representation of the coordinate in a format based on the parameter.

The method will throw java.lang.IllegalArgumentException if the outputType is not one of the two constant values defined in this class or if the coordinate value is not within the range [-180.0, 180.0) or is Double.Na.

Method: Coordinates.distance

Syntax:

public float distance(Coordinates to)
  

Description:

Calculates the geodetic distance in meters between the two points according to the ellipsoid model of WGS84. Altitude is left out of the calculations.

This method will throw java.lang.NullPointerException if the parameter is null.

Method: Coordinates.azimuthTo

Syntax:

public float azimuthTo(Coordinates to)
  

Description:

Calculates the azimuth between the two points according to the ellipsoid model of WGS84. The azimuth is relative to true north. The Coordinates object on which this method is called is considered the origin for the calculation and the Coordinates object passed as a parameter is the destination which the azimuth is calculated to. When the origin is the North pole and the destination is not the North pole, this method returns 180.0. When the origin is the South pole and the destination is not the South pole, this method returns 0.0. If the origin is equal to the destination, this method returns 0.0. The implementation shall calculate the result as exactly as it can. However, it is required that the result is within 1 degree of the correct result.

This method will throw java.lang.NullPointerException if the parameter is null.


Class: Criteria

The criteria used for the selection of the location provider is defined by the values in this class. Instances of Criteria are used by the application to indicate criteria for choosing the location provider in the LocationProvider.getInstance method call.

The default values for the criteria fields are specified below in the table. The default values are always the least restrictive option that will match all location providers. Default values:

Criteria field Default value
Horizontal accuracy NO_REQUIREMENT
Vertical accuracy NO_REQUIREMENT
Preferred response time NO_REQUIREMENT
Power consumption NO_REQUIREMENT
Cost allowed true (allowed to cost)
Speed and course required false (not required)
Altitude required false (not required)
Address info required false (not required)

The implementation of this class only retains the values that are passed in using the set* methods. It does not try to validate the values of the parameters in any way. Applications may set any values, even negative values, but the consequence may be that no matching LocationProvider can be created.

NO_REQUIREMENT

  • No requirements for the parameter

POWER_USAGE_HIGH

  • High power consumption allowed

POWER_USAGE_LOW

  • Only low power consumption allowed

POWER_USAGE_MEDIUM

  • Average power consumption allowed

Horizontal Accuracy Vertical Accuracy Cost Power Consumption Resulting Mode
Required - Set a value Required - Set a value false
Not allowed
N/A GPS_AID_MODE_ AUTONOMOUS
Required - Set a value Required - Set a value true
Allowed
POWER_USAGE_LOW, POWER_USAGE_MEDIUM or NO_REQUIREMENT GPS_AID_MODE_ AUTONOMOUS
Required - Set a value Required - Set a value true
Allowed
POWER_USAGE_HIGH 1st fix - GPS_AID_MODE_ ASSIST
Subsequent fixes - GPS_AID_MODE_ AUTONOMOUS
NO_REQUIREMENT NO_REQUIREMENT false
Not allowed
POWER_USAGE_MEDIUM or POWER_USAGE_HIGH or NO_REQUIREMENT GPS_AID_MODE_ AUTONOMOUS
NO_REQUIREMENT NO_REQUIREMENT true
Allowed
POWER_USAGE_MEDIUM or NO_REQUIREMENT GPS_AID_MODE_ASSIST
NO_REQUIREMENT NO_REQUIREMENT true
Allowed
POWER_USAGE_HIGH 1st fix - GPS_AID_MODE_ ASSIST
Subsequent fixes - GPS_AID_MODE_ AUTONOMOUS
NO_REQUIREMENT NO_REQUIREMENT true
Allowed
POWER_USAGE_LOW GPS_AID_MODE_ CELLSITE

Constructor

Criteria()

Method:
Criteria.getHorizontalAccuracy

Syntax:

int getHorizontalAccuracy()
  

Description:

Returns the horizontal accuracy in meters that has been set in this Criteria.

Method:
Criteria.getPreferredPowerConsumption

Syntax:

int getPreferredPowerConsumption()
  

Description:

Returns the preferred power consumption level.

  • NO_REQUIREMENT
  • POWER_LEVEL_LOW
  • POWER_LEVEL_MEDIUM
  • POWER_LEVEL_HIGH

Method:
Criteria.getPreferredResponseTime

Syntax:

int getPreferredResponseTime()
  

Description:

Returns the preferred maximum response time in milliseconds.

Method:
Criteria.getVerticalAccuracy

Syntax:

int getVerticalAccuracy()
  

Description:

Returns the vertical accuracy value in meters that has been set in this Criteria.

Method:
Criteria.isAddressInfoRequired

Syntax:

boolean isAddressInfoRequired()
  

Description:

Returns true if the location provider should be able to determine textual address information.

Method:
Criteria.isAllowedToCost

Syntax:

boolean isAllowedToCost()
  

Description:

Returns the preferred cost setting: true if allowed to cost, false if it must be free of charge

Method:
Criteria.isAltitudeRequired

Syntax:

boolean isAltitudeRequired()
  

Description:

Returns true if the location provider should be able to determine altitude.

Method:
Criteria.isSpeedAndCourseRequired

Syntax:

boolean isSpeedAndCourseRequired()
  

Description:

Returns true if the location provider should be able to determine speed and course.

Method:
Criteria.setAddressInfoRequired

Syntax:

void setAddressInfoRequired
  (boolean addressInfoRequired)
  

Description:

Sets whether the location provider should be able to determine textual address information. The default is false. Setting this criteria to true implies that a location provider should be selected that is capable of providing the textual address information. This does not mean that every returned location instance necessarily will have all the address information filled in, though.

Method:
Criteria.setAltitudeRequired

Syntax:

void setAltitudeRequired
  (boolean altitudeRequired)
  

Description:

Sets whether the location provider should be able to determine altitude. Default is false. If set to true, the LocationProvider is required to be able to normally determine the altitude.

Method:
Criteria.setCostAllowed

Syntax:

void setCostAllowed(boolean costAllowed)
  

Description:

Sets the preferred cost setting where requests for location determination is allowed to incur financial cost to the user of the terminal. The default condition is true.

Method:
Criteria.setHorizontalAccuracy

Syntax:

void setHorizontalAccuracy(int accuracy)
  

Description:

Sets the desired maximum horizontal accuracy preference in meters. The default is NO_REQUIREMENT, meaning no preference on horizontal accuracy.

Method:
Criteria.setPreferredPowerConsumption

Syntax:

void setPreferredPowerConsumption(int level)
  

Description:

Sets the preferred maximum level of power consumption.

  • NO_REQUIREMENT (default)
  • POWER_LEVEL_LOW
  • POWER_LEVEL_MEDIUM
  • POWER_LEVEL_HIGH

Method:
Criteria.setPreferredResponseTime

Syntax:

void setPreferredResponseTime(int time)
  

Description:

Sets the desired maximum response time preference in milliseconds. This value is typically used to determine a location method that is able to produce the location information within the defined time. The value is also used as a timeout value if the result cannot be produced within the defined time. The default is NO_REQUIREMENT, meaning no response time constraint.

Method:
Criteria.setSpeedAndCourseRequired

Syntax:

void setSpeedAndCourseRequired
  (boolean speedAndCourseRequired)
  

Description:

Sets whether the location provider should be able to determine speed and course. The default is false. If set to true, the LocationProvider is required to be able to normally determine the speed and course.

Method:
Criteria.setVerticalAccuracy

Syntax:

void setVerticalAccuracy(int accuracy)
  

Description:

Sets the desired vertical accuracy preference in meters. The default is NO_REQUIREMENT, meaning no preference on vertical accuracy.


Class: Landmark

Represents a landmark, which is a known location with a name. A landmark has a name by which it is known to the end user, a textual description, QualifiedCoordinates and optionally AddressInfo.

This class is only a container for the information. The constructor does not validate the parameters passed in but just stores the values, except that the name field is never allowed to be null. The get* methods return the values passed in the constructor.

Constructor

Landmark
(
  // Name of the landmark
  java.lang.String name,
  // Description of the landmark.
  // May be null if not available
  java.lang.String description,
  // The Coordinates of the landmark.
  // May be null if not known.
  QualifiedCoordinates coordinates,
  // The textual address information of the
  // landmark. May be null if not known.
  AddressInfo addressInfo
)

The constructor will throw java.lang.NullPointerException if the name is null.

Method:
Landmark.getAddressInfo

Syntax:

AddressInfo getAddressInfo()
  

Description:

Gets the AddressInfo of the landmark.

Method:
Landmark.getDescription

Syntax:

java.lang.String getDescription()
  

Description:

Gets the landmark description, null if not available.

Method:
Landmark.getDescription

Syntax:

java.lang.String getName()
  

Description:

Gets the landmark name.

Method:
Landmark.getQualifiedCoordinates

Syntax:

QualifiedCoordinates getQualifiedCoordinates()
  

Description:

Gets the QualifiedCoordinates of the landmark, null if not available.

Method:
Landmark.setAddressInfo

Syntax:

void setAddressInfo(AddressInfo addressInfo)
  

Description:

Sets the AddressInfo of the landmark.

Method:
Landmark.setDescription

Syntax:

void setDescription
  (java.lang.String description)
  

Description:

Sets the description of the landmark. Pass null to indicate that description is not available.

Method:
Landmark.setName

Syntax:

void setName(java.lang.String name)
  

Description:

Sets the name of the landmark.

Method:
Landmark.setQualifiedCoordinates

Syntax:

void setQualifiedCoordinates
  (QualifiedCoordinates cooordinates)
  

Description:

Sets the QualifiedCoordinates of the landmark.


Class: LandmarkStore

Provides methods to store, delete and retrieve landmarks from a persistent landmark store. There is one default landmark store and there may be multiple other landmark stores with different names. All landmark stores must be shared between all Java ME applications. Named landmark stores have unique names in this API.

The Landmarks have a name and may be placed in a category or several categories. The category is intended to group landmarks that are of similar type to the end user, for example, restaurants, museums, etc. The landmark names are strings that identify the landmark to the end user. The category names describe the category to the end user. The language used in the names may be any and depends on the preferences of the end user. The names of the categories are unique within a LandmarkStore. However, the names of the landmarks are not guaranteed to be unique. Landmarks with the same name can appear in multiple categories or even several Landmarks with the same name in the same category.

The Landmark objects returned from the getLandmarks methods in this class shall guarantee that the application can read a consistent set of the landmark data valid at the time of obtaining the object instance, even if the landmark information in the store is modified subsequently by this or some other application.

The Landmark object instances can be in two states:

  • Initially constructed by an application
  • Belongs to a LandmarkStore

A Landmark object belongs to a LandmarkStore if it has been obtained from the LandmarkStore using getLandmarks or if it has been added to the LandmarkStore using addLandmark. A Landmark object is initially constructed by an application when it has been constructed using the constructor but has not been added to a LandmarkStore using addLandmark.

The landmark stores created by an application and landmarks added in landmark stores persist even if the application itself is deleted from the device.

Accessing the landmark store may cause a SecurityException if the calling application does not have the required permissions. The permissions to read and write (including add and delete) landmarks are distinct. An application having permission to read landmarks wouldn't necessarily have the permission to delete them.

Method:
LandmarkStore.addCategory

Syntax:

void addCategory(java.lang.String categoryName)
  

Description:

Adds a category to this LandmarkStore.

This method will throw:

java.lang.IllegalArgumentException

  • A category with the specified name already exists

java.lang.NullPointerException

  • The parameter is null

javax.microedition.location.LandmarkException

  • This LandmarkStore does not support adding new categories

java.io.IOException

  • An I/O error occurs or there are no resources to add a new category

java.lang.SecurityException

  • The application does not have the permission to manage categories

Method:
LandmarkStore.addLandmark

Syntax:

void addLandmark
(
  Landmark landmark,
  java.lang.String category
)
  

Description

Adds a landmark to the specified category in the landmark store. Pass null as the category to indicate that the landmark does not belong to a category. Both parameters have a maximum length of 32 characters.

This method will throw:

java.lang.SecurityException

  • The application is not allowed to add landmarks.

java.lang.IllegalArgumentException

  • The landmark has a longer name field than the implementation can support or if the category defined in the landmark is not one of the categories supported by this LandmarkStore.

java.io.IOException

  • An I/O error happened when accessing the landmark database or if there are no resources available to store this landmark.

java.lang.NullPointerException

  • The landmark parameter is null.

Method:
LandmarkStore.createLandmarkStore

Syntax:

static void createLandmarkStore
  (java.lang.String storeName)
  

Description:

Creates a new landmark store with a specified name.All LandmarkStores are shared between all Java ME applications and may be shared with native applications.

This method will throw:

java.lang.IllegalArgumentException

  • The name is too long or if a landmark store with the specified name already exists

java.lang.NullPointerException

  • The parameter is null

javax.microedition.location.LandmarkException

  • The implementation does not support creating new landmark stores

java.io.IOException

  • The landmark store couldnít be created due to an I/O error

java.lang.SecurityException

  • The application does not have permissions to create a new landmark store

Method:
LandmarkStore.deleteCategory

Syntax:

void deleteCategory
  (java.lang.String categoryName)
  

Description:

Removes a category from this LandmarkStore. This method will not remove any of the landmarks, only the associated category information from the landmarks. If a category with the supplied name does not exist in this LandmarkStore, the method returns silently with no error.

This method will throw:

java.lang.NullPointerException

  • The parameter is null

javax.microedition.location.LandmarkException

  • This LandmarkStore does not support deleting categories

java.io.IOException

  • An I/O error occurs

java.lang.SecurityException

  • The application does not have the permission to manage categories

Method:
LandmarkStore.deleteLandmark

Syntax:

void deleteLandmark(Landmark lm)
  

Description:

Removes a landmark from all categories and deletes the information from this LandmarkStore. The Landmark instance passed in as the parameter must be an instance that belongs to this LandmarkStore. If the Landmark is not found in this LandmarkStore, then the request is silently ignored and the method call returns with no error.

This method will throw:

java.lang.SecurityException

  • The application is not allowed to delete the landmark

javax.microedition.location.LandmarkException

  • The landmark instance passed as the parameter does not belong to this LandmarkStore

java.io.IOException

  • An I/O error happened when accessing the landmark store

java.lang.NullPointerException

  • The parameter is null

Method:
LandmarkStore.deleteLandmarkStore

Syntax:

static void deleteLandmarkStore
  (java.lang.String storeName)
  

Description:

Delete a landmark store with a specified name. All the landmarks and categories defined in the named landmark store are irrevocably removed. If a landmark store with the specified name does not exist, this method returns silently without any error.

This method will throw:

java.lang.NullPointerException

  • The parameter is null (the default landmark store canít be deleted)

javax.microedition.location.LandmarkException

  • The implementation does not support deleting landmark stores

java.io.IOException

  • The landmark store couldnít be deleted due to an I/O error

java.lang.SecurityException

  • The application does not have permissions to delete a landmark store

Method:
LandmarkStore.getCategories

Syntax:

java.util.Enumeration getCategories()
  

Description:

Returns the category names that are defined in this LandmarkStore. The language and locale used for these names depends on the implementation and end user settings. The names shall be such that they can be displayed to the end user and have a meaning to the end user.

This method returns an java.util.Enumeration containing Strings representing the category names. If there are no categories defined in this LandmarkStore, an Enumeration with no entries is returned.

Method:
LandmarkStore.getInstance

Syntax:

static LandmarkStore getInstance
  (java.lang.String storeName)
  

Description:

Gets a LandmarkStore instance for storing, deleting and retrieving landmarks. There must be one default landmark store and there may be other landmark stores that can be accessed by name. If null is passed, the default landmark store will be returned. Throws java.lang.SecurityException if the application does not have a permission to read landmark stores.

Method:
LandmarkStore.getLandmarks

Syntax:

java.util.Enumeration getLandmarks()
  

Description:

Lists all landmarks stored in the database and returns an java.util.Enumeration object containing Landmark objects representing all the landmarks stored in this LandmarkStore. The method will throw a java.io.IOException if an I/O error happened when accessing the landmark database.

Method:
LandmarkStore.getLandmarks

Syntax:

java.util.Enumeration getLandmarks
(
  java.lang.String category,
  double minLatitude,
  double maxLatitude,
  double minLongitude,
  double maxLongitude
)
  

Description:

Lists all the landmarks that are within an area defined by bounding minimum and maximum latitude and longitude. The bounds are considered to belong to the area.

If minLongitude <= maxLongitude, then this area covers the longitude range [minLongitude, maxLongitude].

If minLongitude > maxLongitude, then this area covers the longitude range [-180.0, maxLongitude] and [minLongitude, 180.0).

For latitude, the area covers the latitude range [minLatitude, maxLatitude].

This method will throw java.io.IOException if an I/O error happened when accessing the landmark database, and will throw java.lang.IllegalArgumentException if the minLongitude or maxLongitude is out of the range [-180.0, 180.0), or minLatitude or minLongitude is out of the range [-90.0,90.0], or if minLatitude > maxLatitude

Method:
LandmarkStore.getLandmarks

Syntax:

java.util.Enumeration getLandmarks
(
  java.lang.String category,
  java.lang.String name
)
  

Description:

Gets the Landmarks from the storage where the category and/or name matches the given parameters. The category of the landmark is passed, or null which implies a wildcard that matches all categories. The name of the desired landmark is also passed where null implies a wildcard that matches all the names within the category indicated by the category parameter.

This method returns an Enumeration containing all the matching Landmarks or null if no Landmark matched the given parameters.

This method throws java.io.IOException if an I/O error happened when accessing the landmark database.

Method:
LandmarkStore.listLandmarkStores

Syntax:

static java.lang.String[] listLandmarkStores()
  

Description:

Lists the names of all the available landmark stores.The default landmark store is obtained from getInstance by passing null as the parameter. The null name for the default landmark store is not included in the list returned by this method. If there are no named landmark stores, other than the default landmark store, this method returns null.

This method returns an array of landmark store names, and will throw:

java.lang.SecurityException

  • The application does not have the permission to access landmark stores.

java.io.IOException

  • An I/O error occurred when trying to access the landmark stores.

Method:
LandmarkStore.removeLandmarkFromCategory

Syntax:

void removeLandmarkFromCategory
(
  Landmark lm,
  java.lang.String category
)
  

Description:

Removes the named landmark from the specified category.

The Landmark instance passed in as the parameter must be an instance that belongs to this LandmarkStore.

If the Landmark is not found in this LandmarkStore in the specified category or if the parameter is a Landmark instance that does not belong to this LandmarkStore, then the request is silently ignored and the method call returns with no error. The request is also silently ignored if the specified category does not exist in this LandmarkStore.

The landmark is only removed from the specified category but the landmark information is retained in the store. If the landmark no longer belongs to any category, it can still be obtained from the store by passing null as the category to getLandmarks.

This method will throw:

java.lang.NullPointerException

  • At least one parameter is null.

java.io.IOException

  • An I/O error happened when accessing the landmark store.

java.lang.SecurityException

  • The application is not allowed to the landmark.

Method:
LandmarkStore.updateLandmark

Syntax:

void updateLandmark(Landmark lm)
  

Description:

Updates the information about a landmark. This method only updates the information about a landmark and does not modify the categories the landmark belongs to. The Landmark instance passed in as the parameter must be an instance that belongs to this LandmarkStore. This method canít be used to add a new landmark to the store.

This method will throw:

java.lang.NullPointerException

  • The parameter is null.

javax.microedition.location.LandmarkException

  • The landmark instance passed as the parameter does not belong to this LandmarkStore or does not exist in the store any more.

java.io.IOException

  • An I/O error happened when accessing the landmark store.

java.lang.SecurityException

  • The application is not allowed to update the landmark.


Class: Location

Represents the standard set of basic location information. This includes the time stamped coordinates, accuracy, speed, heading, and information about the positioning method used for the location, plus an optional address.

The location method is indicated using a bit field. The individual bits are defined using constants in this class. This bit field is a bitwise combination of the location method technology bits (MTE_*), method type (MTY_*) and method assistance information (MTA_*). All other bits in the 32 bit integer than those that have defined constants in this class are reserved and MUST not be set by implementations (i.e. these bits must be 0).

A Location object may be either 'valid' or 'invalid'. The validity can be queried using the isValid method. A valid Location object represents a location with valid coordinates. An invalid Location object doesn't have valid coordinates, but the extra info that is obtained from the getExtraInfo method can provide information about the reason why it was not possible to provide a valid Location. The periodic location updates to the LocationListener may return invalid Location objects if it isn't possible to determine the location. This class is only a container for the information.

Field Description
MTA_ASSISTED Location method is assisted by the other party
MTA_UNASSISTED Location method is unassisted
MTE_ANGLEOFARRIVAL Location method Angle of Arrival for cellular / terrestrial RF system.
MTE_CELLID Location method Cell-ID for cellular (in GSM, this is the same as Cell Global Identity (CGI))
MTE_SATELLITE Location method using satellites (for example, Global Positioning System (GPS))
MTE_SHORTRANGE Location method Short-range positioning system (for example, Bluetooth LP)
MTE_TIMEDIFFERENCE Location method Time Difference for cellular / terrestrial RF system (for example, Enhanced Observed Time Difference (E-OTD) for GSM)
MTE_TIMEOFARRIVAL Location method Time of Arrival (TOA) for cellular / terrestrial RF system
MTY_NETWORKBASED Location method is of type network based
MTY_TERMINALBASED Location method is of type terminal based

Constructor

Location()

Method:
Location.getAddressInfo

Syntax:

AddressInfo getAddressInfo()
  

Description:

Returns null because the RIM implementation does not support textual address.

Method:
Location.getCourse

Syntax:

float getCourse()
  

Description:

Returns the deviceís course in degrees relative to true north. The value is always in the range [0.0,360.0) degrees. Returns Float.NaN if the course is not known.

Method:
Location.getExtraInfo

Syntax:

java.lang.String getExtraInfo
  (java.lang.String mimetype)
  

Description:

Returns extra information about the location. This method is intended to provide location method specific extra information that applications that are aware of the used location method and information format are able to use.

A MIME type is used to identify the type of the extra information when requesting it. It returns the extra information as a String encoded according to format identified by the MIME type.

When the MIME type is "application/X-java-location-nmea", the returned string shall be a valid sequence of NMEA sentences formatted according to the syntax specified in the NMEA 0183 v3.1 specification. These sentences should represent the set of NMEA sentences that are related to this location at the time this location was created.

A sample returned string of getExtraInfo("application/X-jsr179-location-nmea"):

$GPGGA,140234,26:08.76784,N,-80:15.22240,W,1,6,,7.0,M,,
$GPGLL,26:08.76784,N,-80:15.22240,W,140234,A

When the MIME type is "application/X-java-location-lif", the returned string shall contain an XML formatted document containing the "pd" element defined in the LIF Mobile Location Protocol TS 101 v3.0.0 as the root element of the document.

A sample returned string of getExtraInfo("application/X-jsr179-location-lif"). Note that the following string has been formatted for display purposes:

lif:
<pd>
  <time>1105044947940</time>
  <shape>
    <Point>
      <coord><X>-23.67</X><Y>34.45</Y></coord>
    </Point>
  </shape>
  <alt>456.0</alt>
  <alt_acc>23.0</alt_acc>
  <speed>20</speed>
  <direction>120</direction>
</pd>

When the MIME type is "text/plain", the returned string shall contain textual extra information that can be displayed to the end user.

Method:
Location.getLocationMethod

Syntax:

int getLocationMethod()
  

Description:

Returns information about the location method used. The returned value is a bitwise combination (OR) of the method technology, method type and assistance information. The method technology values are defined as constant values named MTE_* in this class, the method type values are named MTY_* and assistance information values are named MTA_*.

For example, if the location method used is device based, network assisted Enhanced Observed Time Difference (E-OTD), the following value would be returned:

0x00050002 ( = MTY_TERMINALBASED | MTA_ASSISTED
  | MTE_TIMEDIFFERENCE)

If the location is determined by combining several location technologies, the returned value may have several MTE_* bits set.

If the used location method is unknown, the returned value may have all the bits set to zero.

Only bits that have defined constants within this class are allowed to be used. Other bits are reserved and must be set to 0.

Method:
Location.getQualifiedCoordinates

Syntax:

QualifiedCoordinates getQualifiedCoordinates()
  

Description:

Returns the coordinates of this location and their accuracy, or null if not known.

Method:
Location.getSpeed

Syntax:

float getSpeed()
  

Description:

Returns the deviceís current ground speed in meters per second (m/s) at the time of measurement, or Float.NaN if the speed is not known. The speed is always a non-negative value. Note that unlike the coordinates, speed does not have an associated accuracy because the methods used to determine the speed typically are not able to indicate the accuracy.

Method:
Location.getTimestamp

Syntax:

long getTimestamp()
  

Description:

Returns the time stamp at which the data was collected. This timestamp should represent the point in time when the measurements were made. The time returned is the local device time in milliseconds using the same clock and same time representation as System.currentTimeMillis().

Method:
Location.isValid

Syntax:

boolean isValid()
  

Description:

Returns whether this Location instance represents a valid location with coordinates or an invalid one where all the data, especially the latitude and longitude coordinates, may not be present.

A valid Location object contains valid coordinates whereas an invalid Location object may not contain valid coordinates but may contain other information via the getExtraInfo() method to provide information on it was not possible to provide a valid Location object.

This method returns a boolean value with true indicating that this Location instance is valid and false indicating an invalid Location instance


Class: LocationProvider

This is the starting point for applications using this API and represents a source of the location information. A LocationProvider represents a location-providing module, generating Locations.

Applications obtain LocationProvider instances (classes implementing the actual functionality by extending this abstract class) by calling the factory method. It is the responsibility of the implementation to return the correct LocationProvider-derived object.

Applications that need to specify criteria for the location provider selection, must first create a Criteria object, and pass it to the factory method. The methods that access the location related information shall throw SecurityException if the application does not have the relevant permission to access the location information.

RIM Implementation Note

Textual address is not supported. If an application invokes LocationProvider.getInstance(criteria) with a Criteria instance that requires AddressInfo, it returns null.

AVAILABLE

  • Availability status code: the location provider is available

OUT_OF_SERVICE

  • Availability status code: the location provider is permanently unavailable. Permanent unavailability means that the method is unavailable and the implementation is not able to expect that this situation would change in the near future. An example is when using a location method implemented in an external device and the external device is detached.

TEMPORARILY_UNAVAILABLE

  • Availability status code: the location provider is temporarily unavailable. Temporary unavailability means that the method is unavailable due to reasons that can be expected to possibly change in the future and the provider to become available. An example is not being able to receive the signal because the signal used by the location method is currently being obstructed, e.g. when deep inside a building for satellite based methods. However, a very short transient obstruction of the signal should not cause the provider to toggle quickly between TEMPORARILY_UNAVAILABLE and AVAILABLE

Constructor

LocationProvider()

Empty constructor to help implementations and extensions. This is not intended to be used by applications. Applications should not make subclasses of this class and invoke this constructor from the subclass.

Method:
LocationProvider.addProximityListener

Syntax:

static void addProximityListener
(
  ProximityListener listener,
  Coordinates coordinates,
  float proximityRadius
)
  

Description:

Adds a ProximityListener for updates when proximity to the specified coordinates is detected.

If this method is called with a ProximityListener that is already registered, the registration to the specified coordinates is added in addition to the set of coordinates it has been previously registered for. A single listener can handle events for multiple sets of coordinates.

If the current location is known to be within the proximity radius of the specified coordinates in meters, the listener shall be called immediately.

Detecting the proximity to the defined coordinates is done on a best effort basis. Due to the limitations of the methods used to implement this, there are no guarantees that the proximity is always detected; especially in situations where the device briefly enters the proximity area and exits it shortly afterwards, it is possible that it will be missed. It is optional to provide this feature as it may not be reasonably implementable with all methods used to implement this API.

If the implementation is capable of supporting the proximity monitoring and has resources to add the new listener and coordinates to be monitored but the monitoring can't be currently done due to the current state of the method used to implement it, this method shall succeeed and the monitoringStateChanged method of the listener shall be immediately called to notify that the monitoring is not active currently.

This method throws:

javax.microedition.location.LocationException

  • The platform does not have resources to add a new listener and coordinates to be monitored or does not support proximity monitoring at all

java.lang.IllegalArgumentException

  • The proximity radius is 0 or negative* or Float.NaN

java.lang.NullPointerException

  • The listener or coordinates parameter is null

java.lang.SecurityException

  • The application does not have the permission to register a proximity listener

Method:
LocationProvider.getInstance

Syntax:

static LocationProvider getInstance
  (Criteria criteria)
  

Description:

This factory method is used to get an actual LocationProvider implementation based on the defined criteria. Pass null if the default provider is requested. If no concrete LocationProvider could be created that typically can match the defined criteria but there are other location providers not meeting the criteria that could be returned for a more relaxed criteria, null is returned to indicate this. The LocationException is thrown, if all supported location providers are out of service.

A LocationProvider instance is returned if there is a location provider meeting the criteria in either the available or temporarily unavailable state. If a LocationProvider meeting the criteria can be supported but is currently out of service, it shall not be returned.

When this method is called with a Criteria that has all fields set to the default values (i.e. the least restrictive criteria possible), it will return a LocationProvider if there is any provider that isn't in the out of service state. Passing null as the parameter is equal to passing a Criteria that has all fields set to the default values, i.e. the least restrictive set of criteria.

This method only makes the selection of the provider based on the criteria and is intended to return it quickly to the application. Any possible initialization of the provider is done at an implementation dependent time and must not block the call to this method.

This method may return the same LocationProvider instance as has been returned previously from this method to the calling application, if the same instance can be used to fulfil both defined criteria. Note that there can be only one LocationListener associated with a LocationProvider instance.

This method throws javax.microedition.location.LocationException if all LocationProviders are unavailable.

Method:
LocationProvider.getLastKnownLocation

Syntax:

static Location getLastKnownLocation()
  

Description:

Returns the latest known location. This is the best estimate for the previously known location. null is returned if there isnít any previous location information.

Applications can use this method to obtain the last known location and check the timestamp and other fields to determine if this is recent enough and good enough for the application to use without needing to make a new request for the current location.

This method throws java.lang.SecurityException if the calling application does not have a permission to query the location information.

Method:
LocationProvider.getLocation

Syntax:

abstract Location getLocation(int timeout)
  

Description:

Description:

Retrieves a Location with the constraints given by the Criteria associated with this class. If no result could be retrieved, a LocationException is thrown. If the location can't be determined within the timeout period specified in the parameter, the method shall throw a LocationException.

If the provider is temporarily unavailable, the device will wait and try to obtain the location until the timeout expires. If the provider is permanently unavailable, then the LocationException is thrown immediately.

Note that the individual Location returned might not fulfill exactly the criteria used for selecting this LocationProvider. The Criteria is used to select a location provider that typically is able to meet the defined criteria, but not necessarily for every individual location measurement.

The single parameter passed is a timeout value in seconds. -1 is used to indicate that a default timeout value for this provider should be used.

This method throws:

javax.microedition.location.LocationException

  • The location couldn't be retrieved or if the timeout period expired

java.lang.InterruptedException

  • The operation is interrupted by calling reset() from another thread

java.lang.SecurityException

  • The calling application does not have a permission to query the location information

java.lang.IllegalArgumentException

  • The timeout == 0 or timeout < -1

Method:
LocationProvider.getState

Syntax:

abstract int getState()
  

Description:

Returns the current state of this LocationProvider. The return value shall be one of the availability status code constants defined in this class.

Method:
LocationProvider.removeProximityListener

Syntax:

static void removeProximityListener
  (ProximityListener listener)
  

Description:

Removes a ProximityListener from the list of recipients for updates. If the specified listener is not registered or if the parameter is null, this method silently returns with no action.

Method:
LocationProvider.reset

Syntax:

abstract void reset()
  

Description:

Resets the LocationProvider.

All pending synchronous location requests will be aborted and any blocked getLocation method calls will terminate with InterruptedException.

Applications can use this method e.g. when exiting to have its threads freed from blocking synchronous operations.

Method:
LocationProvider.setLocationListener

Syntax:

abstract void setLocationListener
(
  LocationListener listener,
  int interval,
  int timeout,
  int maxAge
)
  

Description:

Adds a LocationListener for updates at the defined interval. The listener will be called with updated location at the defined interval. The listener also gets updates when the availablilty state of the LocationProvider changes.

Passing an interval of -1 selects the default interval which is dependent on the location method used. Passing an interval of 0 registers the listener to only receive provider status updates and not location updates at all.

Only one listener can be registered with each LocationProvider instance. Setting the listener replaces any possibly previously set listener. Setting the listener to null cancels the registration of any previously set listener.

The first location result will be obtained when the listener is registered and will provide the location to the listener as soon as it is available. Subsequent location updates will happen at the defined interval after the first one. If the specified update interval is smaller than the time it takes to obtain the first result, the listener shall receive location updates with invalid Locations at the defined interval until the first location result is available.

The timeout parameter determines a timeout that is used if it's not possible to obtain a new location result when the update is scheduled to be provided. This timeout value indicates how many seconds the update is allowed to be provided late compared to the defined interval. If it's not possible to get a new location result (interval + timeout) seconds after the previous update, the update will be made and an invalid Location instance is returned. This is also done if the reason for the inability to obtain a new location result is due to the provider being temporarily unavailable or out of service. For example, if the interval is 60 seconds and the timeout is 10 seconds, the update must be delivered at most 70 seconds after the previous update and if no new location result is available by that time the update will be made with an invalid Location instance.

The maxAge parameter defines how old the location result is allowed to be provided when the update is made. This allows the implementation to reuse location results if it has a recent location result when the update is due to be delivered. This parameter can only be used to indicate a larger value than the normal time of obtaining a location result by a location method. The normal time of obtaining the location result means the time it takes normally to obtain the result when a request is made. If the application specifies a time value that is less than what can be realized with the used location method, the implementation shall provide as recent location results as are possible with the used location method. For example, if the interval is 60 seconds, the maxAge is 20 seconds and normal time to obtain the result is 10 seconds, the implementation would normally start obtaining the result 50 seconds after the previous update. If there is a location result otherwise available that is more recent than 40 seconds after the previous update, then the maxAge setting to 20 seconds allows to return this result and not start obtaining a new one.

Parameters:

listener

  • The listener to be registered.
  • If set to null the registration of any previously set listener is cancelled.

interval

  • The interval in seconds.
  • -1 is used for the default interval of this provider.
  • 0 is used to indicate that the application wants to receive only provider status updates and not location updates at all.

timeout

  • Timeout value in seconds
  • Must be greater than 0.
  • The default timeout for this provider is used if the value is -1.
  • If the interval is -1 to indicate the default, the value of this parameter has no effect and the default timeout for this provider is used.
  • This parameter has no effect if the interval is 0.

maxAge

  • Maximum age of the returned location in seconds
  • Must be greater than 0 or equal to -1 to indicate that the default maximum age for this provider is used.
  • If the interval is -1 to indicate the default, the value of this parameter has no effect and the default maximum age for this provider is used.
  • This parameter has no effect if the interval is 0.

This method throws:

java.lang.IllegalArgumentException

  • If interval < -1, or if (interval != -1) and (timeout > interval or maxAge > interval or (timeout < 1 and timeout != -1) or (maxAge < 1 and maxAge != -1))

java.lang.SecurityException

  • The calling application does not have a permission to query the location information


Class: Orientation

The Orientation class represents the physical orientation of the device. Orientation is described by azimuth to north (the horizontal pointing direction), pitch (the vertical elevation angle) and roll (the rotation of the device around its own longitudinal axis).

The device providse the compass bearing, pitch and roll information. Most commonly, this class will be used to obtain the current compass direction.

It is up to the device to define its own axes, but it is generally recommended that the longitudinal axis is aligned with the bottom-to-top direction of the screen. This means that the pitch is positive when the top of the screen is up and the bottom of the screen down (when roll is zero). The roll is positive when the device is tilted clockwise looking from the direction of the bottom of the screen, i.e. when the left side of the screen is up and the right side of the screen is down (when pitch is zero).

No accuracy data is given for Orientation.

This class is only a container for the information. The constructor does not validate the parameters passed in but just retains the values. The get* methods return the values passed in the constructor.

Constructor

Orientation
(
  float azimuth,
  boolean isMagnetic,
  float pitch,
  float roll
)

Constructs a new Orientation object with the bearing, pitch and roll parameters specified.

The values are expressed in degress using floating point values.

If the pitch or roll is undefined, the parameter should be given as Float.NaN.

Parameters:

bearing

  • The bearing relative to true or magnetic north.
  • Valid range: [0.0, 360.0)

isMagnetic

  • true if the bearing is relative to the magnetic field or the Earth
  • false if the bearing is relative to true north and gravity

pitch

  • The pitch of the terminal in degrees.
  • Valid range: [-90.0, 90.0]

roll

  • The roll of the terminal in degrees.
  • Valid range: [-180.0, 180.0)

Method:
Orientation.getCompassAzimuth

Syntax:

float getCompassAzimuth()
  

Description:

Returns the deviceís surface orientation in degrees relative to either magnetic or true north. The value is always in the range [0.0, 360.0) degrees. The isOrientationMagnetic() method indicates whether the returned bearing is relative to true north or magnetic north.

Method:
Orientation.getOrientation

Syntax:

static Orientation getOrientation()
  

Description:

Returns the deviceís current orientation or null if it canít be determined.

This method throws:

javax.microedition.location.LocationException

  • The implementation does not support orientation determination

java.lang.SecurityException

  • The calling application does not have permission to query the orientation

Method:
Orientation.getPitch

Syntax:

float getPitch()
  

Description:

Returns the deviceís tilt in degrees defined as an angle in the vertical plane orthogonal to the ground, and through the longitudinal axis of the device. The value is always in the range [-90.0, 90.0] degrees, or Float.NaN if not available. A negative value means that the top of the device is pointing towards the ground.

Method:
Orientation.getRoll

Syntax:

float getRoll()
  

Description:

Returns the deviceís rotation in degrees around its own longitudinal axis, or Float.NaN if not available. The value is always in the range [-180.0, 180.0) degrees. A negative value means that the device is orientated anti-clockwise from its default orientation.

Method:
Orientation.isOrientationMagnetic

Syntax:

boolean isOrientationMagnetic()
  

Description:

Returns a boolean value that indicates whether this Orientation is relative to the magnetic field of the Earth or relative to true north and gravity. If this method returns true, the compass bearing and pitch are relative to the magnetic field of the Earth. If this method returns false, the compass bearing is relative to true north and pitch is relative to gravity.


Class: QualifiedCoordinates

The QualifiedCoordinates class represents coordinates as latitude-longitude-altitude values that are associated with an accuracy value.

Fields inherited from class javax.microedition.location.Coordinates:

  • DD_MM
  • DD_MM_SS

Constructor

QualifiedCoordinates
(
  double latitude,
  double longitude,
  float altitude,
  float horizontalAccuracy,
  float verticalAccuracy
)

Constructs a new QualifiedCoordinates object with the values specified. The latitude and longitude parameters are expressed in degrees using floating point values. The degrees are in decimal values (rather than minutes/seconds).

The coordinate values always apply to the WGS84 datum.

The Float.NaN value can be used for altitude to indicate that altitude is not known.

Parameters:

latitude

  • The latitude of the location.
  • Valid range: [-90.0, 90.0]

longitude

  • The longitude of the location.
  • Valid range: [-180.0, 180.0)

altitude

  • The altitude of the location in meters, defined as height above WGS84 ellipsoid.
  • Float.NaN can be used to indicate that altitude is not known.

horizontalAccuracy

  • The horizontal accuracy of this location result in meters.
  • Float.NaN can be used to indicate that the accuracy is not known.
  • Must be greater or equal to 0.

verticalAccuracy

  • The vertical accuracy of this location result in meters.
  • Float.NaN can be used to indicate that the accuracy is not known.
  • Must be greater or equal to 0.

This method throws java.lang.IllegalArgumentException if an input parameter is out of the valid range.

Method:
QualifiedCoordinates.getHorizontalAccuracy

Syntax:

float getHorizontalAccuracy()
  

Description:

Returns the horizontal accuracy of the location in meters (1-sigma standard deviation). A value of Float.NaN means the horizontal accuracy could not be determined.

The horizontal accuracy is the RMS (root mean square) of east accuracy (latitudinal error in meters, 1-sigma standard deviation), north accuracy (longitudinal error in meters, 1-sigma).

Method:
QualifiedCoordinates.getHorizontalAccuracy

Syntax:

float getVerticalAccuracy()
  

Description:

Returns the accuracy of the location in meters in vertical direction (orthogonal to ellipsoid surface, 1-sigma standard deviation). A value of Float.NaN means the vertical accuracy could not be determined.

Method:
QualifiedCoordinates.setHorizontalAccuracy

Syntax:

void setHorizontalAccuracy
  (float horizontalAccuracy)
  

Description:

Sets the horizontal accuracy of the location in meters (1-sigma standard deviation). Must be greater or equal to 0. A value of Float.NaN means the horizontal accuracy could not be determined.

The horizontal accuracy is the RMS (root mean square) of east accuracy (latitudinal error in meters, 1-sigma standard deviation), north accuracy (longitudinal error in meters, 1-sigma).

Method:
QualifiedCoordinates.setVerticalAccuracy

Syntax:

void setVerticalAccuracy
  (float verticalAccuracy)
  

Description:

Sets the accuracy of the location in meters in vertical direction (orthogonal to ellipsoid surface, 1-sigma standard deviation). The number must be greater or equal to 0. A value of Float.NaN means the vertical accuracy could not be determined.


Exception: LandmarkException

The LandmarkException is thrown when an error related to handling landmarks has occurred.

Constructors

LandmarkException()
  • Constructs a LandmarkException with no detail message.
LandmarkException(java.lang.String s)
  • Constructs a LandmarkException with the specified detail message.


Exception: LocationException

The LocationException is thrown when a location API specific error has occurred. The detailed conditions when this exception is thrown are documented in the methods that throw this exception.

Constructors

LocationException()
  • Constructs a LocationException with no detail message.
LocationException(java.lang.String s)
  • Constructs a LocationException with the specified detail message.

In closing ...

It would be hard to beat the sample device and server-side code that comes with the BlackBerry JDE v4.01 update. As such, download and install the latest update, adjust the code to reflect the server where you will deploy the sample server component, compile then deploy the sample application on your BlackBerry 7520 handheld. After that, compile and deploy the GPS server sample, and give it a test spin.


Please email your comments, suggestions and editorial submissions to


Top |  Table of Contents |  Journal in PDF Format |  Legal Disclaimer
 
     
 Home | Products | Solutions | Purchasing | Support | Developers | Worldwide | News | About Us | Contact Us | Site Map
 Legal | Copyright © 2008 Research In Motion Limited, unless otherwise noted.