Criteria for retrieving location information

The criteria object specifies what type of device location information is returned and how.

The Location Service supports two types of location information:

  • Basic

    Basic location information includes longitude, latitude, and altitude estimates.

  • Generic

    Generic location information includes all possible location data.

The criteria object has two main properties: LocationInformationClass and Updateoptions. These are described in the following table. Properties enclosed in brackets are optional.

Table: Criteria object properties

Property

Description

Type

Value

[criteria.LocationInformationClass]

Specifies the type of location information to retrieve. It has two possible values:

  • BasicLocationInformation includes longitude, latitude, and altitude estimates. This is the default value for this argument.

  • GenericLocationInfo includes all possible location data.

Note: There is no guarantee that all the requested information is returned, whether basic or generic. The availability of specific information depends on the positioning system used and on other factors such as the number of satellites that are available when a location fix is obtained.

For information on how to ensure that you get at least certain information, see the Updateoptions.PartialUpdates property.

string

Possible values:

  • "BasicLocationInformation"

  • "GenericLocationInfo"

[criteria.Updateoptions]

Specifies the update options used while retrieving the location information.

If you do not define a particular option, then its default value is used.

Note: The option values must conform to the following order of magnitude:

UpdateTimeOut > UpdateInterval > UpdateMaxAge

If this order is not maintained, the method returns the SErrArgument error.

object

Object with the properties specified below

[criteria.Updateoptions.UpdateInterval]

Specifies the time interval (in microseconds) between two consecutive location estimates.

This is only used with Trace, which requests location estimates until cancelled. GetLocation only requests the location estimate once.

The default value is 1000000 (= 1 second).

number

0 or a positive integer

[criteria.Updateoptions.UpdateTimeOut]

If the location server does not provide location estimates within the time specified in UpdateTimeOut (in microseconds), the method returns the SErrTimedOut error.

The default value is 15000000 (= 15 seconds).

number

0 or a positive integer

[criteria.Updateoptions.UpdateMaxAge]

Specifies the expiry time for the location information cache (in microseconds). When a location request is made, the location information is returned from the cache (managed by the location server) as long as the cache is not older than UpdateMaxAge.

The default value is 0, meaning that the location information is never returned from the cache.

number

0 or a positive integer

[criteria.Updateoptions.PartialUpdates]

Specifies whether longitude, latitude, and altitude information is always guaranteed.

Setting PartialUpdates to false ensures that the user receives at least BasicLocationInformation (longitude, latitude, and altitude).

Note: Altitude information is returned only if the positioning system supports it. You can change the positioning system used by an S60 device from the Settings > General > Positioning > Positioning methods menu.

If you set this property to true, there are no guarantees on any specific information being returned, including longitude, latitude, and altitude.

The default value is false.

boolean

Possible values:

  • true

  • false
© Nokia 2009.