Collapse all Symbian^3 Application Developer Library

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

Inherits from

RPositioner
- RPositionerSubSessionBase
  - RSubSessionBase

Public Member Functions
	RPositioner ()
IMPORT_C void	Close ()
IMPORT_C void	GetLastKnownPosition ( TPositionInfoBase &, TRequestStatus &)
IMPORT_C void	GetLastKnownPositionArea ( TPositionInfoBase &, TPositionAreaInfoBase &, TRequestStatus &)
IMPORT_C TInt	GetUpdateOptions ( TPositionUpdateOptionsBase &)
IMPORT_C void	NotifyPositionUpdate ( TPositionInfoBase &, TRequestStatus &)
IMPORT_C TInt	Open ( RPositionServer &)
IMPORT_C TInt	Open ( RPositionServer &, TPositionModuleId )
IMPORT_C TInt	Open ( RPositionServer &, const TPositionCriteriaBase &)
TInt	OpenImpl ( RPositionServer &, TPositionModuleId , const TPositionCriteriaBase &, TBool )
IMPORT_C TInt	SetRequestor ( CRequestor::TRequestorType , CRequestor::TRequestorFormat , const TDesC &)
IMPORT_C TInt	SetRequestor (const RRequestorStack &)
IMPORT_C TInt	SetUpdateOptions (const TPositionUpdateOptionsBase &)

Protected Member Functions
IMPORT_C void	ConstructL ()
IMPORT_C void	Destruct ()
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_C

RPositioner

(

)

Constructor for RPositioner

Member Functions Documentation

Close()

IMPORT_C void

(

)

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 void

ConstructL

(

)

[protected, virtual]

symbian 2nd phase constructor

Destruct()

IMPORT_C void

Destruct

(

)

[protected, virtual]

destructs the data inside this class

ExtendedInterface(TInt, TAny , TAny )

IMPORT_C TAny *	ExtendedInterface	(	TInt	aFunctionNumber,
			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 aFunctionNumber	contains the Id of the function to be invoked.
TAny * aPtr1	a pointer to any data
TAny * aPtr2	a pointer to any data.

GetLastKnownPosition(TPositionInfoBase &, TRequestStatus &)

IMPORT_C void	GetLastKnownPosition	(	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 & aPosInfo

will be set, upon successful completion, to the most recently determined location data.

TRequestStatus & aStatus

returns 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 void	GetLastKnownPositionArea	(	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 TPositionAreaExtendedInfo The 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 TInt

GetUpdateOptions

(

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 & aPosOption

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

NotifyPositionUpdate(TPositionInfoBase &, TRequestStatus &)

IMPORT_C void	NotifyPositionUpdate	(	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 & aPosInfo

will hold, on successful completion, information on the devices' current position.

TRequestStatus & aStatus

returns 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 TInt

Open

(

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 & aPosServer

is a connected session with the positioning server.

Open(RPositionServer &, TPositionModuleId)

IMPORT_C TInt	Open	(	RPositionServer &	aPosServer,
			TPositionModuleId	aModuleId
		)

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 & aPosServer	is a connected session with the positioning server.
TPositionModuleId aModuleId	is 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 TInt	Open	(	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 & aPosServer	is a connected session with the positioning server.
const TPositionCriteriaBase & aCriteria	is 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,
			TPositionModuleId	aModuleId,
			const TPositionCriteriaBase &	aCriteria,
			TBool	aOpenedUsingModuleId
		)

Parameters

RPositionServer & aPosServer
TPositionModuleId aModuleId
const TPositionCriteriaBase & aCriteria
TBool aOpenedUsingModuleId

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

IMPORT_C TInt	SetRequestor	(	CRequestor::TRequestorType	aType,
			CRequestor::TRequestorFormat	aFormat,
			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 aType	identifies the type of requestor, a service or a contact.
CRequestor::TRequestorFormat aFormat	identifies the format of the requestor.
const TDesC & aData	identifies the requestor string. The requestor string can be a telephone number, a URL etc.

SetRequestor(const RRequestorStack &)

IMPORT_C TInt

SetRequestor

(

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 & aRequestorStack

is a collection of CRequestor objects.

SetUpdateOptions(const TPositionUpdateOptionsBase &)

IMPORT_C TInt

SetUpdateOptions

(

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 & aPosOption

contains 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.

RPositioner Class Reference

Inherits from

Constructor & Destructor Documentation

RPositioner()

Member Functions Documentation

Close()

ConstructL()

Destruct()

ExtendedInterface(TInt, TAny *, TAny *)

Parameters

GetLastKnownPosition(TPositionInfoBase &, TRequestStatus &)

Parameters

GetLastKnownPositionArea(TPositionInfoBase &, TPositionAreaInfoBase &, TRequestStatus &)

Parameters

GetUpdateOptions(TPositionUpdateOptionsBase &)

Parameters

NotifyPositionUpdate(TPositionInfoBase &, TRequestStatus &)

Parameters

Open(RPositionServer &)

Parameters

Open(RPositionServer &, TPositionModuleId)

Parameters

Open(RPositionServer &, const TPositionCriteriaBase &)

Parameters

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

Parameters

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

Parameters

SetRequestor(const RRequestorStack &)

Parameters

SetUpdateOptions(const TPositionUpdateOptionsBase &)

Parameters

Member Data Documentation

CPositioningPtrHolder * iPtrHolder

TAny * iReserved

ExtendedInterface(TInt, TAny , TAny )