RPositioner Class Reference

class RPositioner : public RPositionerSubSessionBase

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.

RPositionServer

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
IMPORT_C voidConstructL()
IMPORT_C voidDestruct()
IMPORT_C TAny *ExtendedInterface(TInt, TAny *, TAny *)
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 Enumerations
RPositionerSubSessionBase:_TRequestId
Private Attributes
CPositioningPtrHolder *iPtrHolder
TAny *iReserved

Constructor & Destructor Documentation

RPositioner()

IMPORT_CRPositioner()

Constructor for RPositioner

Member Functions 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
"Lbs Client 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]

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

Parameters

TInt aFunctionNumbercontains the Id of the function to be invoked.
TAny * aPtr1a pointer to any data
TAny * 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.

panic
"Lbs Client Fault" 6 If no sub session has been created with this session ( by calling RPositioner::Open() ).
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

TPositionInfoBase & aPosInfowill be set, upon successful completion, to the most recently determined location data.
TRequestStatus & 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.

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.

TPositionAreaInfo TPositionAreaExtendedInfoThe call is supported by the lbs.lib only.

capability
Location

Parameters

TPositionInfoBase & 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.
TPositionAreaInfoBase & 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.
TRequestStatus & 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.

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.

panic
"Lbs Client Fault" 6 If no sub session has been created with this session ( by calling RPositioner::Open() ).

Parameters

TPositionUpdateOptionsBase & aPosOptioncontains, upon successful completion, the set of update options for NotifyPositionUpdate() that are currently in use.

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.

panic
"Lbs Client Fault" 6 If no sub session has been created with this session ( by calling RPositioner::Open() ).
panic
"Lbs Client Fault" 15 If there is already an outstanding request pending for position information.
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

TPositionInfoBase & aPosInfowill hold, on successful completion, information on the devices' current position.
TRequestStatus & 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.

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.

panic
"Lbs Client Fault" 5 If open is called more than one time on the same RPositioner instance.
panic
"Lbs Client Fault" 6 If no connection has been established with Location Server ( by calling RPositionServer::Connect() ).
Pre-condition
a connection with the server should already have been created by calling RPositionServer::Connect().

Parameters

RPositionServer & aPosServeris a connected session with the positioning server.

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.

panic
"Lbs Client Fault" 6 If no connection has been established with Location Server ( by calling RPositionServer::Connect() ).
Pre-condition
a connection with the server should already have been created by calling RPositionServer::Connect().

Parameters

RPositionServer & aPosServeris a connected session with the positioning server.
TPositionModuleId 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()

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

RPositionServer & aPosServeris a connected session with the positioning server.
const TPositionCriteriaBase & aCriteriais the criteria that the server must use to choose an appropriate PSY for this sub-session.

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

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

Parameters

RPositionServer & aPosServer
TPositionModuleId aModuleId
const TPositionCriteriaBase & aCriteria
TBool aOpenedUsingModuleId

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.

panic
"Lbs Client Fault" 6 If no sub session has been created with this session ( by calling RPositioner::Open() ).
Pre-condition
RPositioner::Open() should have been called prior to this operation.

Parameters

CRequestor::TRequestorType aTypeidentifies the type of requestor, a service or a contact.
CRequestor::TRequestorFormat aFormatidentifies the format of the requestor.
const TDesC & aDataidentifies the requestor string. The requestor string can be a telephone number, a URL etc.

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.

panic
"Lbs Client Fault" 6 If no sub session has been created with this session ( by calling RPositioner::Open() ).
Pre-condition
RPositioner::Open() should have been called prior to this operation.

Parameters

const RRequestorStack & aRequestorStackis a collection of CRequestor objects.

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.

panic
"Lbs Client Fault" 6 If no sub session has been created with this session ( by calling RPositioner::Open() ).
Pre-condition
RPositioner::Open() should have been called prior to this operation.

Parameters

const TPositionUpdateOptionsBase & aPosOptioncontains the clients requested options for receiving location updates.

Member Data Documentation

CPositioningPtrHolder * iPtrHolder

CPositioningPtrHolder *iPtrHolder[private]

A pointer to a container that holds pointer descriptors, needed to point to the clients request data during asynchronous requests

TAny * iReserved

TAny *iReserved[private]

Unused variable for future expansion.