RPositioner Class Reference

#include <lbs.h>

Link against: lbs.lib

class RPositioner : public RPositionerSubSessionBase
Public Member Functions
RPositioner()
IMPORT_C voidClose()
IMPORT_C voidGetLastKnownPosition(TPositionInfoBase &, TRequestStatus &)
IMPORT_C voidGetLastKnownPositionArea(TPositionInfoBase &, TPositionAreaInfoBase &, TRequestStatus &)
IMPORT_C TIntGetUpdateOptions(TPositionUpdateOptionsBase &)
IMPORT_C voidNotifyPositionUpdate(TPositionInfoBase &, TRequestStatus &)
IMPORT_C TIntOpen(RPositionServer &)
IMPORT_C TIntOpen(RPositionServer &, TPositionModuleId)
IMPORT_C TIntOpen(RPositionServer &, const TPositionCriteriaBase &)
TInt OpenImpl(RPositionServer &, TPositionModuleId, const TPositionCriteriaBase &, TBool)
IMPORT_C TIntSetRequestor(CRequestor::TRequestorType, CRequestor::TRequestorFormat, const TDesC &)
IMPORT_C TIntSetRequestor(const RRequestorStack &)
IMPORT_C TIntSetUpdateOptions(const TPositionUpdateOptionsBase &)
Protected Member Functions
virtual IMPORT_C voidConstructL()
virtual IMPORT_C voidDestruct()
virtual IMPORT_C TAny *ExtendedInterface(TInt, TAny *, TAny *)
Inherited Enumerations
RPositionerSubSessionBase:_TRequestId
Inherited Functions
RPositionerSubSessionBase::CancelRequest(TRequestId)
RPositionerSubSessionBase::CompleteRequest(TInt)
RPositionerSubSessionBase::RPositionerSubSessionBase()
RSubSessionBase::CloseSubSession(TInt)
RSubSessionBase::CreateAutoCloseSubSession(RSessionBase &,TInt,const TIpcArgs &)
RSubSessionBase::CreateSubSession(const RSessionBase &,TInt)
RSubSessionBase::CreateSubSession(const RSessionBase &,TInt,const TIpcArgs &)
RSubSessionBase::RSubSessionBase()
RSubSessionBase::Send(TInt)const
RSubSessionBase::Send(TInt,const TIpcArgs &)const
RSubSessionBase::SendReceive(TInt)const
RSubSessionBase::SendReceive(TInt,TRequestStatus &)const
RSubSessionBase::SendReceive(TInt,const TIpcArgs &)const
RSubSessionBase::SendReceive(TInt,const TIpcArgs &,TRequestStatus &)const
RSubSessionBase::Session()const
RSubSessionBase::SubSessionHandle()const
Inherited Type Definitions
RPositionerSubSessionBase::TRequestId

Detailed Description

This class is used to create a sub-session with the server for the purpose of obtaining the current position. In addition to actually obtaining position information, this class also provides mechanisms for obtaining the last known position, the last known position with area information, the general status of the positioning module, changing how often it wishes to receive position updates, as well as identifying itself to the location framework.

Before using the class, a primary connection must have already been established with the server.

See also: RPositionServer

Constructor & Destructor Documentation

RPositioner ( )

IMPORT_CRPositioner()

Constructor for RPositioner

Member Function Documentation

Close ( )

IMPORT_C voidClose()

Closes a sub-session with the positioning server. Before a sub-session is closed, the client application must ensure that all outstanding notification requests have been cancelled. In particular, the application must issue all the appropriate Cancel requests and then wait for a confirmation that the notifications have been terminated. A failure to do so results in a panic.

Panic Codes
"LbsClient Fault" 16 if the outstanding position request is not cancelled before calling this method.

ConstructL ( )

IMPORT_C voidConstructL()[protected, virtual]

symbian 2nd phase constructor

Destruct ( )

IMPORT_C voidDestruct()[protected, virtual]

destructs the data inside this class

ExtendedInterface ( TInt, TAny *, TAny * )

IMPORT_C TAny *ExtendedInterface(TIntaFunctionNumber,
TAny *aPtr1,
TAny *aPtr2
)[protected, virtual]

Reimplemented from RPositionerSubSessionBase::ExtendedInterface(TInt,TAny *,TAny *)

This method is used to allow polymorphic extensions to the API without breaking BC. See documentation for explanation.

Parameters
aFunctionNumbercontains the Id of the function to be invoked.
aPtr1a pointer to any data
aPtr2a pointer to any data.

GetLastKnownPosition ( TPositionInfoBase &, TRequestStatus & )

IMPORT_C voidGetLastKnownPosition(TPositionInfoBase &aPosInfo,
TRequestStatus &aStatus
)const

This method returns cached position information if it is available. This method can be an efficient mechanism - in terms of speed, cost and power consumption - of obtaining the devices' recent position.

Note:

To cancel this request use RPositioner::CancelRequest() with EPositionerGetLastKnownPosition as parameter.

The GetLastKnownPosition does not use any of the options specified using SetUpdateOptions() (namely update interval, maximum age, timeout and partial updates).

Pre-condition
The application should have called RPositioner::SetRequestor() before calling this method.
Parameters
aPosInfowill be set, upon successful completion, to the most recently determined location data.
aStatusreturns the result code after the asynchronous call completes. The parameter can contain the following values,KErrNone on successful completion.KErrUnknown if no cached position information is available.KErrArgument if the parameter aPosInfo is of a non-supported type. The only parameter type that is guaranteed to be supported is TPositionInfo.KErrAccessDenied if no requestor information has been specified or if privacy check fails.KErrPositionBufferOverflow if there is insufficient space to return the required information back to the client. This situation can occur when using HPositionGenericInfo if the application has not allocated a large enough buffer.
Panic Codes
"LbsClient Fault" 6 If no sub session has been created with this session ( by calling

GetLastKnownPositionArea ( TPositionInfoBase &, TPositionAreaInfoBase &, TRequestStatus & )

IMPORT_C voidGetLastKnownPositionArea(TPositionInfoBase &aPosInfo,
TPositionAreaInfoBase &aAreaInfo,
TRequestStatus &aStatus
)const

This method returns the area specific latest cached position information if it is available.

Unlike GetLastKnownPosition(), GetLastKnownPositionArea() does not just return the latest cached position. It analyses the current area and finds the best match (for more information about match criteria see TPositionAreaInfo and derived classes) in an internal database of known positions instead. If complete match is not available, the best matching position is returned. If complete match is not available, and there are multiple cached positions with the same, highest match level, the latest position is returned.

Many different techniques may be applied to retrieve area information quickly and power/cost effectively. The most common one uses information from a mobile network to determine the country, or the mobile cell the phone is connected to. Other techniques may involve scanning available WLAN networks.

The user of the API can request the LBS subsystem to provide the basic or the extended area information. If the type of the aAreaInfo parameter is TPositionAreaInfo, then the LBS subsystem will return the basic information only. Passing a parameter of the TPositionAreaExtendedInfo type will instruct the LBS subsystem to return detailed information.

Please note that when calculating area the LBS subsystem assumes the worst case scenario (e.g. mobile cells are big - 10s of km radius). In the centres of big cities the cell sizes are normally much smaller, taking the area from a City to a District or even Street level. A mapping application having that specialised knowledge about the nature and the topography of the location can therefore adjust the area accordingly before presenting the final results to a user.

Currently, the only supported source of area information is the mobile network.

See also: TPositionAreaInfo TPositionAreaExtendedInfo

The call is supported by the lbs.lib only.

Parameters
aPosInfo[InOut] Upon successful, asynchronous completion, the parameter will be set to the best matching known location. Please note that the embedded accuracy information is historical information about the quality of the position when it was captured and not the current accuracy. Use the aAreaInfo parameter to estimate the current accuracy of the position.
aAreaInfo[Out] Upon successful, asynchronous completion, the parameter will contain information about area of the position returned in the aPosInfo parameter to the currently known area info.
aStatus[Out] Returns the result code after the asynchronous call completes. KErrNone if successful; KErrNotFound if a matching entry has not been found; KErrNotSupported if the functionality is not supported; any other system wide error code otherwise.
Capability
Location

GetUpdateOptions ( TPositionUpdateOptionsBase & )

IMPORT_C TIntGetUpdateOptions(TPositionUpdateOptionsBase &aPosOption)const

This method retrieves the current options set for this sub-session. These options are related to receiving the position update from the server.

Parameters
aPosOptioncontains, upon successful completion, the set of update options for NotifyPositionUpdate() that are currently in use.
Return Value
a Symbian OS error code.
Panic Codes
"LbsClient Fault" 6 If no sub session has been created with this session ( by calling

NotifyPositionUpdate ( TPositionInfoBase &, TRequestStatus & )

IMPORT_C voidNotifyPositionUpdate(TPositionInfoBase &aPosInfo,
TRequestStatus &aStatus
)const

This is an asynchronous method for obtaining position updates. It is possible to pass any class that is derived from TPositionInfoBase. However, the standard data retrieval class is TPositionInfo. The standard means of retrieving extended information is to use HPositionGenericInfo.

Note:

To cancel this request use RPositioner::CancelRequest() with EPositionerNotifyPositionUpdate as parameter.

Pre-condition
The application should have called RPositioner::SetRequestor() before calling this method.
Parameters
aPosInfowill hold, on successful completion, information on the devices' current position.
aStatusreturns the result code after the asynchronous call completes. On completion, the parameter can contain the following values,KErrNone on successful completion.KPositionQualityLoss if the positioning module is unable to return any position information.KPositionPartialUpdate if position information has been retrieved but it is incomplete.KErrNotFound is returned if the currently used module is invalid. A previously correct module may become invalid if the positioning module has been uninstalled or disabled by user.KErrTimedOut if the requested location information could not be retrieved within the maximum period as specified in the current update options.KErrArgument if the positioning module is unable to support the type of the class passed in aPosInfo. All positioning modules are required to support both TPositionInfo and HPositionGenericInfo.KErrAccessDenied if no requestor information has been specified or if privacy check fails.KErrPositionBufferOverflow if there is insufficient space to return the required information back to the client. This situation can occur when using HPositionGenericInfo if the application has not allocated a large enough buffer.KErrCancel if the request was successfully cancelled.
Panic Codes
"LbsClient Fault" 6 If no sub session has been created with this session ( by calling
"LbsClient Fault" 15 If there is already an outstanding request pending for position information.

Open ( RPositionServer & )

IMPORT_C TIntOpen(RPositionServer &aPosServer)

Creates a sub-session with the positioning server. The server uses the positioning module with the highest priority by default. If the highest priority positioning module is not available or if it returns an error for a position request then the positioning module with the next highest priority is used.

Pre-condition
a connection with the server should already have been created by calling RPositionServer::Connect().
Parameters
aPosServeris a connected session with the positioning server.
Return Value
a Symbian OS error code.
Panic Codes
"LbsClient Fault" 5 If open is called more than one time on the same
"LbsClient Fault" 6 If no connection has been established with Location Server ( by calling

Open ( RPositionServer &, TPositionModuleId )

IMPORT_C TIntOpen(RPositionServer &aPosServer,
TPositionModuleIdaModuleId
)

Creates a sub-session with the positioning server. The client specifies the module ID of the positioning module to be used for obtaining position information.

Pre-condition
a connection with the server should already have been created by calling RPositionServer::Connect().
Parameters
aPosServeris a connected session with the positioning server.
aModuleIdis the module ID for this sub-session to use to obtain location information. The module ID of different positioning modules can be obtained by calling RPositionServer::GetNumModules() and RPositionServer::GetModuleInfoByIndex()
Return Value
a symbian OS error code. KErrNotFound if the module ID is not valid. panic "Lbs Client Fault" 5 If open is called more than one time on the same RPositioner instance.
Panic Codes
"LbsClient Fault" 6 If no connection has been established with Location Server ( by calling

Open ( RPositionServer &, const TPositionCriteriaBase & )

IMPORT_C TIntOpen(RPositionServer &aPosServer,
const TPositionCriteriaBase &aCriteria
)

Creates a sub-session with the positioning server. The client specifies the criteria for choosing the positioning module. The server chooses the positioning module that satisfies the criteria parameter.

Note:

This function is not supported and it returns KErrNotFound.

Parameters
aPosServeris a connected session with the positioning server.
aCriteriais the criteria that the server must use to choose an appropriate PSY for this sub-session.
Return Value
a Symbian OS error code.

OpenImpl ( RPositionServer &, TPositionModuleId, const TPositionCriteriaBase &, TBool )

TInt OpenImpl(RPositionServer &aPosServer,
TPositionModuleIdaModuleId,
const TPositionCriteriaBase &aCriteria,
TBoolaOpenedUsingModuleId
)

SetRequestor ( CRequestor::TRequestorType, CRequestor::TRequestorFormat, const TDesC & )

IMPORT_C TIntSetRequestor(CRequestor::TRequestorTypeaType,
CRequestor::TRequestorFormataFormat,
const TDesC &aData
)

Set the requestor for this sub-session. This method is used when there is only one requestor involved in the positioning request.

Pre-condition
RPositioner::Open() should have been called prior to this operation.
Parameters
aTypeidentifies the type of requestor, a service or a contact.
aFormatidentifies the format of the requestor.
aDataidentifies the requestor string. The requestor string can be a telephone number, a URL etc.
Return Value
KErrNone
Panic Codes
"LbsClient Fault" 6 If no sub session has been created with this session ( by calling

SetRequestor ( const RRequestorStack & )

IMPORT_C TIntSetRequestor(const RRequestorStack &aRequestorStack)

Sets the requestors for this sub-session. This method is used when a chain of requestors is involved in the positioning request.

Pre-condition
RPositioner::Open() should have been called prior to this operation.
Parameters
aRequestorStackis a collection of CRequestor objects.
Return Value
KErrNone.
Panic Codes
"LbsClient Fault" 6 If no sub session has been created with this session ( by calling

SetUpdateOptions ( const TPositionUpdateOptionsBase & )

IMPORT_C TIntSetUpdateOptions(const TPositionUpdateOptionsBase &aPosOption)

This method can be used to modify the current options set for this sub-session. It enables the client to request an interval time for receiving position updates.

Pre-condition
RPositioner::Open() should have been called prior to this operation.
Parameters
aPosOptioncontains the clients requested options for receiving location updates.
Return Value
a Symbian OS error code. KErrArgument if the specified options conflict for example, if the timeout period is less than the specified update interval. KErrNotSupported if the positioning module is unable to support the required options for example, if the update interval period is too short.
Panic Codes
"LbsClient Fault" 6 If no sub session has been created with this session ( by calling