#include <lbslocator.h>
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 CLbsLocator * | NewL () |
static IMPORT_C CLbsLocator * | NewL (MLbsLocationObserver &aObserver) |
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.
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.
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.
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.
[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
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.
[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
[in] | aObserver | The observer to be added. |
EXPORT_C TInt CLbsLocator::GetLocatorOption | ( | TLbsLocatorOption | aOption, | |
TInt & | aValue | |||
) | const |
Retrieves the value for of an Option of the currently active profile.
[in] | aOption | The profile option to be modified from TLbsLocatorOption. |
[out] | aValue | The current value of option. |
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.
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.
[in] | aObserver | The observer will receive location updates. |
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
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().
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).
[in] | aObserver | The observer to be removed. |
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).
[in] | aObserver | The observer to be removed. |
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
For more information on target accuracies and supported options for each profile see SetLocatorProfile().
[in] | aOption | The profile option to be modified from TLbsLocatorOption. |
[in] | aValue | The new value of option. |
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:
The "Default" profile (KLbsProfileIdDefault) allows existing S60 location based applications to easily move to the CLbsLocator API.
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 "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.
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().
[in] | aProfileId | The UID of the profiles will receive location and status updates. |
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.
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.