CLbsLocator Class Reference

#include <lbslocator.h>

List of all members.

Public Types

enum  TLbsLocatorOption { ELocatorStatusTimer = 1 }

Public Member Functions

IMPORT_C ~CLbsLocator ()
IMPORT_C TInt SetLocatorProfile (TUid aProfileId)
IMPORT_C TUid LocatorProfile () const
IMPORT_C void StartUpdatesL ()
IMPORT_C void StopUpdates ()
IMPORT_C TInt SetLocatorOption (TLbsLocatorOption aOption, TInt aValue)
IMPORT_C TInt GetLocatorOption (TLbsLocatorOption aOption, TInt &aValue) const
IMPORT_C void AddLocationObserverL (MLbsLocationObserver &aObserver)
IMPORT_C TInt RemoveLocationObserver (MLbsLocationObserver &aObserver)
IMPORT_C void AddMovementObserverL (MLbsMovementObserver &aObserver)
IMPORT_C TInt RemoveMovementObserver (MLbsMovementObserver &aObserver)

Static Public Member Functions

static IMPORT_C CLbsLocatorNewL ()
static IMPORT_C CLbsLocatorNewL (MLbsLocationObserver &aObserver)

Detailed Description

CLbsLocator - Interface class to request location and movement information.

After creating a new instance of the interface via one of the NewL() methods, applications should set their desired profile using SetLocatorProfile(). To begin receiving updates, the StartUpdatesL() method must be called.

The frequency and accuracy of these updates and the power consumed is dependent on the profile being used.

Updates are sent to one or more Observers. The MLbsLocationObserver class is used to receive location updates (i.e. containing latitude and longitude). The MLbsMovementObserver class is used to receive events related to the movement of the device (for example stationary or moving).

A location observer may be supplied via the NewL() but observers can also be added using AddLocationObserverL() and AddMovementObserverL(). It is possible to have multiple observers for each type of update.

At least one observer should be present before the application calls StartUpdatesL().

Applications must have the Location capability to receive location updates.

See also:
MLbsLocationObserver
MLbsMovementObserver

Member Enumeration Documentation

Used a parameter to SetLocatorOption() to tailor the behaviour of the active profile. When the profile is changed, any previously modified option is returned to the default.

See also:
SetLocatorOption()
GetLocatorOption()
Enumerator:
ELocatorStatusTimer 

Controls when status updates are generated.


Constructor & Destructor Documentation

EXPORT_C CLbsLocator::~CLbsLocator (  ) 

Closes all open resources and stops updates being sent to the application.

If an application wishes to temporarily halt updates it should use the StopUpdates() method.

The destructor is normally called as the application is closing down. It is not a requirement to call StopUpdates() before deleting the interface but it is recommended to do so.

Note: The destructor must not be invoked during any form of callback from the interface to one of the application's observers. For example during a location or movement update. This is a programming error and is likely to result in an application crash.

It is however possible and legal to call StopUpdates() during an update callback.

See also:
StopUpdates()

Member Function Documentation

EXPORT_C void CLbsLocator::AddLocationObserverL ( MLbsLocationObserver aObserver  ) 

Adds a Location Observer.

The specified observer will start to receive location updates when they are next generated. It is possible to have multiple location observers.

Location observers can be specified using AddLocationObserverL() or (optionally) when the interface class is created via the NewL(MLbsLocationObserver& aObserver) overload. To begin receiving updates the application must first call StartUpdatesL().

Observers can be added before or after StartUpdatesL() is called. If an observer is after updates have been started it will automatically receive the next location update.

Attempting to add an observer that is already present has no effect. That is, duplicate observers are not added but the method does not leave.

Location observers can be removed using RemoveLocationObserver().

In order to add a location observer, the application must have the Location capability. Otherwise, this method will Leave with the error KErrPermissionDenied.

The observer will not be added if the method leaves.

Parameters:
[in] aObserver The observer to be added.

KErrPermissionDenied When the application does not have the Location capability. KErrNoMemory If there has been a memory allocation problem. OtherStatusCode When if some other issue prevents the observer being added Location

See also:
StartUpdatesL()
NewL(MLbsLocationObserver& aObserver)
RemoveLocationObserver()
EXPORT_C void CLbsLocator::AddMovementObserverL ( MLbsMovementObserver aObserver  ) 

Adds a Movement Observer.

The specified observer will start to receive movement event updates when they are next generated. It is possible to have multiple movement observers and no location observers.

To begin receiving updates the application must first call StartUpdatesL().

Observers can be added before or after StartUpdatesL() is called. If an observer is after updates have been started it will automatically receive the next movement update.

The range of movement detection supported and the power consumed is dependent on the profile being used. See SetLocatorProfile() for more information.

Attempting to add an observer that is already present has no effect. That is, duplicate observers are not added but the method does not leave.

Movement observers can be removed using RemoveMovementObserver().

Note: No security capabilities are required to add a movement observer or receive movement events.

The observer will not be added if the method leaves.

Parameters:
[in] aObserver The observer to be added.

KErrNoMemory If there has been a memory allocation problem. OtherStatusCode When if some other issue prevents the observer being added

Parameters:
[in] aObserver The observer to be added.
See also:
SetLocatorProfile()
StartUpdatesL()
NewL()
RemoveMovementObserver()
EXPORT_C TInt CLbsLocator::GetLocatorOption ( TLbsLocatorOption  aOption,
TInt &  aValue 
) const

Retrieves the value for of an Option of the currently active profile.

Parameters:
[in] aOption The profile option to be modified from TLbsLocatorOption.
[out] aValue The current value of option.
Returns:
KErrNone When the specified current value was successfully retrieved.
KErrNotSupported When parameter aOption is not supported by the current profile.
See also:
TLbsLocatorOption
SetLocatorOption
SetLocatorProfile()
EXPORT_C TUid CLbsLocator::LocatorProfile (  )  const

Return the ID of the profile in use.

If the application has not selected a profile, the "Default" profile is used. In this situation LocatorProfile() will return KLbsProfileIdDefault.

Returns:
The UID of the profile currently in use.
See also:
SetLocatorProfile()
EXPORT_C CLbsLocator * CLbsLocator::NewL ( MLbsLocationObserver aObserver  )  [static]

Creates a new instance of the CLbsLocator interface class.

After the instance of the interface has been created, the application should select the desired profile using SetLocatorProfile(). To begin receiving location and/or movement information, the application must call StartUpdatesL(). The frequency and accuracy of these updates depend on the profile selected.

Additional observers can be added by the methods AddLocationObserverL() or AddMovementObserverL().

Note: The application must have the Location capability to call this version of NewL(). Otherwise, the method will leave with the error KErrPermissionDenied.

Parameters:
[in] aObserver The observer will receive location updates.
Returns:
A pointer to a new instance of the CLbsLocator interface class. The calling application becomes the owner of the returned object and is responsible its disposal.

KErrPermissionDenied When the application does not have the Location capability. KErrNoMemory If there has been a memory allocation problem. OtherStatusCode When if some other issue prevents the observer being added

Location

See also:
NewL()
SetLocatorProfile()
StartUpdatesL()
StopUpdates()
AddLocationObserverL()
RemoveLocationObserver()
EXPORT_C CLbsLocator * CLbsLocator::NewL (  )  [static]

Creates a new instance of the CLbsLocator interface class.

After the instance of the interface has been created using this method, the application should select the desired profile using SetLocatorProfile() and add one or more observers. To begin receiving location and/or movement information, the application must call StartUpdatesL(). The frequency and accuracy of these updates depend on the profile selected.

Observers can be added by the methods AddLocationObserverL() or AddMovementObserverL().

Note: No platform capabilities are required to create an instance of the interface using this NewL() overload. However, the application must have the Location capability if it intends to received location updates. Platform security capabilities are checked when AddLocationObserverL() is called. No capabilities are required to receive movement events using AddMovementObserverL().

Returns:
A pointer to a new instance of the CLbsLocator interface class. The calling application becomes the owner of the returned class and is responsible its disposal.
See also:
NewL(MLbsLocationObserver& aObserver)
SetLocatorProfile()
AddLocationObserverL()
AddMovementObserverL()
StartUpdatesL()
StopUpdates()
EXPORT_C TInt CLbsLocator::RemoveLocationObserver ( MLbsLocationObserver aObserver  ) 

Removes a Location Observer. The specified observer will no longer receive location updates.

It is possible to remove any of the current observers - including that supplied via NewL(MLbsLocationObserver& aObserver) overload.

Removing all observes without calling StopUpdates() may continue to consume resources and is not recommended.

Observers may be removed whilst the application is currently processing an update. For example, from within one observer's MLbsLocationObserver::HandleLocationUpdate() method. In this situation, the removed observer will not receive the current update (if it has has still to be delivered to it).

Parameters:
[in] aObserver The observer to be removed.
Returns:
KErrNone When the specified observer has been removed.
KErrNotFound When aObserver could not be found in the current list of location observers
See also:
NewL(MLbsLocationObserver& aObserver)
AddLocationObserverL()
StopUpdates()
EXPORT_C TInt CLbsLocator::RemoveMovementObserver ( MLbsMovementObserver aObserver  ) 

Removes a Movement Observer. The specified observer will no longer receive Movement updates.

Removing all observes without calling StopUpdates() may continue to consume resources and is not recommended.

Observers may be removed whilst the application is currently processing an update. For example, from within one observer's MLbsMovementObserver::HandleMovementUpdate() method. In this situation, the removed observer will not receive the current update (if it has has still to be delivered to it).

Parameters:
[in] aObserver The observer to be removed.
Returns:
KErrNone When the specified observer has been removed.
KErrNotFound When aObserver could not be found in the current list of Movement observers
See also:
AddMovementObserverL()
StopUpdates()
EXPORT_C TInt CLbsLocator::SetLocatorOption ( TLbsLocatorOption  aOption,
TInt  aValue 
)

Modifies the behaviour of the currently active profile.

When an application changes the active profile using SetLocatorProfile()any previously modified option is lost. Applications must re-specify its desired options each time it changes profiles.

Changing a profile option has effect immediately.

Parameter aOption can be one of the following

  • ELocatorStatusTimer
    • Parameter aValue is the timer period in seconds.

    • The status timer indicates how long the subsystem should wait before informing the application that it has not been able to obtain a position of the target accuracy for the current profile. The method MLbsLocationObserver::HandleLocationStatus() is called after that period.

      Note: The status timer does NOT indicate how long the subsystem should try and get accurate positions. It only controls when the application is informed about the accuracy or position loss.

      The location subsystem will continue to try and obtain accurate positions until the application calls StopUpdates().

    • A value of -1 is the default and indicates that profile specific logic should be used.

    • A value of 0 can be used by the application when it wants to know if a cached position for the current location is NOT available.

      When a cached position is available, it is always the first location sent to the application after it calls StartUpdatesL(). When there is no cache position available the subsystem will (normally) start to calculate a new position start away.

      Setting the Status Timer to 0 gives the application an opportunity to prevent a new position being calculated when there is no cached position. In this situation, the status message KPositionNotAvailable is sent to the application after it calls StartUpdatesL(). If the application does not want a new location to be calculated it should call StopUpdates() during the status callback. If updates are not stopped at this stage then a new position will be calculated.

      After the cached position or the initial status message has been sent to the application, the default value of the status timer is then used.

      Note: Although this mechanism allows an application to query the cached position it is not intended for "listening" for location updates. Applications should use one of the alternative intefaces if this is required.

For more information on target accuracies and supported options for each profile see SetLocatorProfile().

Parameters:
[in] aOption The profile option to be modified from TLbsLocatorOption.
[in] aValue The new value of option.
Returns:
KErrNone When the specified option and value were accepted.
KErrNotSupported When parameter aOption is not supported by the current profile.
KErrArgument When the parameter aValue is not with the allowed range for aOption.
See also:
TLbsLocatorOption
MLbsLocationObserver::HandleLocationStatus()
SetLocatorProfile()
GetLocatorOption()
EXPORT_C TInt CLbsLocator::SetLocatorProfile ( TUid  aProfileId  ) 

Specify the active profile to use for location and status updates.

The profile should initially be selected before StartUpdatesL() is called but can be changed at any time. Selecting a profile automatically affects subsequent updates. There is no need to request that updates are stopped and/or re-started.

If no profile is selected by an application the "Default" profile is used (KLbsProfileIdDefault).

Available Profiles are:

  • KLbsProfileIdDefault
  • KLbsProfileIdAreaMonitor
  • KLbsProfileIdLazyTracker

The "Default" profile (KLbsProfileIdDefault) allows existing S60 location based applications to easily move to the CLbsLocator API.

  • The target accuracy of this profile is 20 meters or better.
  • Applications will initially receive a cached location if available.
  • The minimum time between location updates is 1 second.
  • No movement information is supported.

The "Area Monitor" profile (KLbsProfileIdAreaMonitor) is designed to allow applications to discover the town or which part of a city the device is currently situated. The profile is designed to be power efficient and is suitable for long running applications that only need to know when their approximate location changes.

  • The target accuracy of this profile is 3km.
  • Applications will initially receive a cached location if available.
  • Location updates are generated when the device moves between 100m and 3km.
  • Stationary and Movement detection are supported.
  • Movement updates indicate the device has moved more than 100m (but more typically 3km).

The "Lazy Tracker" profile (KLbsProfileIdLazyTracker) enables applications to record the movements of the device over an extended period of time. A key goal of this profile is to be more power efficient than the default profile. This profile will attempt to save power by various techniques including switching GPS off if the device has been stationary for an extended period. It will also attempt to use other positioning technologies such as WLAN (if available) when it is not possible to obtain a satellite based location. The profile is not normally suited to turn-by-turn navigation.

  • The target accuracy of this profile is 20m or better.
  • Applications will initially receive a cached location if available.
  • Location updates are generated when the device moves 30 meters or more.
  • Stationary, Movement and Walking detection are supported.

For all profiles, if position of the target accuracy cannot be obtained within the time out period, the location observer will receive an error notification of KErrTimedOut. See SetLocatorOption().

Parameters:
[in] aProfileId The UID of the profiles will receive location and status updates.
Returns:
KErrNone When the specified profile was successfully selected.
KErrArgument When parameter aProfileId contains an invalid profile ID.
KErrNotSupported When parameter aProfileId contains a profile that is not currently available.
See also:
StartUpdatesL()
StopUpdates()
LocatorProfile()
SetLocatorOption()
EXPORT_C void CLbsLocator::StartUpdatesL (  ) 

Requests the location related updates are sent to the observers.

After the instance of the interface has been created, the application should select the desired profile using SetLocatorProfile() and ensure there is at least one observer. To begin receiving location information, the application must call StartUpdatesL().

After calling StartUpdatesL(), the observers will receive a cached location and current movement status if available. The frequency and accuracy of subsequent updates depend on the active profile. See SetLocatorProfile() for more information.

The StopUpdates() method should be used when an application no longer wishes to receive any new location, movement or status updates.

Calling StartUpdatesL() when there are no specified observers will not result in an error but will consume system resources and may drain additional battery power.

NewL()

See also:
SetLocatorProfile()
StopUpdates()
AddLocationObserverL()
RemoveLocationObserver()
EXPORT_C void CLbsLocator::StopUpdates (  ) 

Requests that all location and status updates are stopped.

The StopUpdates() method is used when an application no longer wishes to receive new location, movement or status updates. It can be used to temporarily or permanently halt updates. It is recommended (but not obligatory) to call StopUpdates() before the destructor is called.

It is legal and often convenient to call StopUdatesL() during an update callback. For example, within the application's HandleLocationUpdate() method. This pattern can be used when the application only wants to find the current location and has received an update of satisfactory accuracy.

When there are multiple observers and the application calls StopUpdates() from within an observer's callback, the current update will continue to be delivered to any remaining observers. That is, StopUpdates() prevents subsequent (i.e. new) updates being generated.

To re-start updates the StartUpdatesL() method must be used. That re-activates the profile from the beginning. In particular, a cached position will initially be sent to the application.

See also:
StartUpdatesL()
RemoveLocationObserver()
~CLbsLocator()

The documentation for this class was generated from the following files:

Copyright (c) 2005-2010 Nokia Corporation and/or its subsidiary(-ies).
All rights reserved. These materials are provided under the terms of the Eclipse Public License v1.0.