Collapse all Symbian^3 Product Developer Library

CPositioner Class Reference

class CPositioner : public CBase

This class is used when Location Framework needs to acquire a position and quality from the PSY. The interface of this class is used for loading and using PSYs and as a framework for developing PSYs. It requires that users define new subclasses to the API classes. It is also used for implementing more advanced PSY features, e.g. periodic position updates, and the maximum age for positions. It can also handle parallel requests.

Inherits from

CPositioner
- CBase

Public Member Functions
	~CPositioner()
void	CancelNotifyPositionUpdate()
IMPORT_C void	CancelNotifyPositionUpdate(TInt)
IMPORT_C TUid	ImplementationUid()
IMPORT_C CPositioner *	NewL(TAny *)
IMPORT_C CPositioner *	NewL(TUid, const CPositioner &)
void	NotifyPositionUpdate(TPositionInfoBase &, TRequestStatus &)
IMPORT_C void	ServiceL(RMessage2 &)
IMPORT_C void	StartTrackingL(const TTimeIntervalMicroSeconds &)
IMPORT_C void	StopTracking()
IMPORT_C TBool	TrackingOverridden()

Protected Member Functions
	CPositioner()
IMPORT_C void	BaseConstructL(TAny *)
IMPORT_C void	ExtendUpdateTimeOut(const TTimeIntervalMicroSeconds &)
IMPORT_C void	GetMaxAge(TTime &)
IMPORT_C TInt	GetRequiredPositionQuality(TPositionQuality &)
IMPORT_C void	GetUpdateTimeOut(TTimeIntervalMicroSeconds &)
IMPORT_C TBool	IsPartialUpdateAllowed()
IMPORT_C MPositionerStatus *	PositionerStatus()
IMPORT_C void	SetPsyDefaultUpdateTimeOut(const TTimeIntervalMicroSeconds &)

Private Member Functions
IMPORT_C void	CPositioner_Reserved2()

Inherited Functions
	CBase::CBase()
	CBase::Delete(CBase *)
	CBase::Extension_(TUint,TAny &,TAny )
	CBase::operator new(TUint)
	CBase::operator new(TUint,TAny *)
	CBase::operator new(TUint,TLeave)
	CBase::operator new(TUint,TLeave,TUint)
	CBase::operator new(TUint,TUint)
	CBase::~CBase()

Private Attributes
TUid	iDtorIdKey
CPositionerExtension *	iExtension

Constructor & Destructor Documentation

CPositioner()

IMPORT_C

CPositioner

(

)

[protected]

C++ default constructor.

~CPositioner()

IMPORT_C

~CPositioner

(

)

Destructor.

Member Functions Documentation

BaseConstructL(TAny *)

IMPORT_C void

BaseConstructL

(

TAny *

aConstructionParameters

)

[protected]

Creates the internals of the positioner.

This function must be called first thing in the positioner's ConstructL() method.

Parameters

TAny * aConstructionParameters

The construction parameters supplied in the factory call.

CPositioner_Reserved2()

IMPORT_C void

CPositioner_Reserved2

(

)

[private, virtual]

Reserved function

CancelNotifyPositionUpdate()

void

CancelNotifyPositionUpdate

(

)

[pure virtual]

Cancels position info request.

CancelNotifyPositionUpdate(TInt)

IMPORT_C void

CancelNotifyPositionUpdate

(

TInt

aError

)

[virtual]

Cancels the request with the error code provided.

Parameters

TInt aError

The error code to cancel request with.

ExtendUpdateTimeOut(const TTimeIntervalMicroSeconds &)

IMPORT_C void

ExtendUpdateTimeOut

(

const TTimeIntervalMicroSeconds &

aAdditionalTime

)

[protected]

Extends the active request timeout by the value specified. Only the current active request is affected and the changes are not stored. That is the value returned by GetUpdateTimeOut and the default PSY timeout set by SetPsyDefaultUpdateTimeOut are not changed. This method is used, for example, to apply FNP lag.

Parameters

const TTimeIntervalMicroSeconds & aAdditionalTime

GetMaxAge(TTime &)

IMPORT_C void

GetMaxAge

(

TTime &

aMaxAge

)

const [protected]

Get the earliest allowed time of an old position fix, based on the current max age set by the client.

The PSY may save the result from the latest position request and return the same result in the next position request if the client says it's ok. Max age tells the PSY how old the stored position is allowed to be. If the stored position is too old or the PSY does not support max age, a normal positioning should be performed.

Parameters

TTime & aMaxAge

On return, will contain the earliest allowed time of an old position fix. If no max age is defined aMaxAge will contain a time set to zero.

GetRequiredPositionQuality(TPositionQuality &)

IMPORT_C TInt

GetRequiredPositionQuality

(

TPositionQuality &

aPositionQuality

)

const [protected]

Get the quality of service requested by the client.

This method can be used by positioning modules which have the ability to deliver different quality of service.

Parameters

TPositionQuality & aPositionQuality

The requested quality of service.

GetUpdateTimeOut(TTimeIntervalMicroSeconds &)

IMPORT_C void

GetUpdateTimeOut

(

TTimeIntervalMicroSeconds &

aUpdateTimeOut

)

const [protected]

Returns the location update timeout associated with the subsession. The method returns a real timeout, which is defined and used by the Location Server. It may be different from the timeout set by the client or default PSY timeout.

Parameters

TTimeIntervalMicroSeconds & aUpdateTimeOut

[Out] The location update timeout.

ImplementationUid()

IMPORT_C TUid

ImplementationUid

(

)

const

Called to return the implementation UID set when calling NewL.

IsPartialUpdateAllowed()

IMPORT_C TBool

IsPartialUpdateAllowed

(

)

const [protected]

Checks if the client allows a partial position update.

A partial update result does not need to contain all parameters. The only mandatory parameters are latitude, longitude and time of fix. Everything else is optional.

If a partial update is returned to the client in a NotifyPositionUpdate() call, the completion code must be set to KPositionPartialUpdate.

NewL(TAny *)

IMPORT_C CPositioner *

NewL

(

TAny *

aConstructionParameters

)

[static]

Creates a new instance of a CPositioner implementation.

Parameters

TAny * aConstructionParameters

Construction parameters for CPositioner.

NewL(TUid, const CPositioner &)

IMPORT_C CPositioner *	NewL	(	TUid	aImplementationUid,
			const CPositioner &	aPositioner
		)	[static]

Creates a new instance of a CPositioner implementation.

This variant of NewL takes a CPositioner as input. The new positioner will get a copy of the construction parameters of the specified positioner.

This NewL variant should be used by proxy positioners who need to load other positioners. A proxy positioner cannot use the other NewL method since the construction parameters are not public.

Parameters

TUid aImplementationUid	The implementation uid of the positioner which should be created.
const CPositioner & aPositioner	The positioner to copy construction parameters from.

NotifyPositionUpdate(TPositionInfoBase &, TRequestStatus &)

void	NotifyPositionUpdate	(	TPositionInfoBase &	aPosInfo,
			TRequestStatus &	aStatus
		)	[pure virtual]

Requests position info asynchronously.

Parameters

TPositionInfoBase & aPosInfo	A reference to a position info object. This object must be in scope until the request has completed. The position (TPosition) of this position info object must be in WGS84 geodetic datum.
TRequestStatus & aStatus	The request status

PositionerStatus()

IMPORT_C MPositionerStatus *

PositionerStatus

(

)

[protected]

Retrieve the interface for reporting positioner status.

ServiceL(RMessage2 &)

IMPORT_C void

ServiceL

(

RMessage2 &

aMessage

)

[virtual]

Service a PSY specific request.

The PSY uses the RMessage object to read input parameters, write return parameters and complete the request.

ServiceL() should be implemented to leave with code KErrNotSupported if the request id is not recognized.

Parameters

RMessage2 & aMessage

The client server request message object.

SetPsyDefaultUpdateTimeOut(const TTimeIntervalMicroSeconds &)

IMPORT_C void

SetPsyDefaultUpdateTimeOut

(

const TTimeIntervalMicroSeconds &

aUpdateTimeOut

)

[protected]

Called to inform the Location Server about the PSY default update timeout. The Location Server may use this value to calculate the update timeout it uses. When this method is called, it does not affect the currect request. So, it must be called in advance before a request comes from the Location Server.

Parameters

const TTimeIntervalMicroSeconds & aUpdateTimeOut

[In] The PSY default location update timeout.

StartTrackingL(const TTimeIntervalMicroSeconds &)

IMPORT_C void

StartTrackingL

(

const TTimeIntervalMicroSeconds &

aInterval

)

[virtual]

Initiate a tracking session.

Parameters

const TTimeIntervalMicroSeconds & aInterval

[in] Interval for position requests.

StopTracking()

IMPORT_C void

StopTracking

(

)

[virtual]

Stop a periodic update session. Any outstanding requests will be cancelled.

TrackingOverridden()

IMPORT_C TBool

TrackingOverridden

(

)

const [virtual]

Indicate if the PSY has overridden tracking. The default implementation returns EFalse. Override and return ETrue to use PSY:s own timer.

Member Data Documentation

TUid iDtorIdKey

TUid

iDtorIdKey

[private]

CPositionerExtension * iExtension

CPositionerExtension *

iExtension

[private]