RPositioner Class Reference

API published in: S60 2nd Ed FP 2

Link against: lbs.lib

Capability Information

Required Capabilities

None

Exceptions

The capability Location is required in:

TInt RPositionServer::GetDefaultModuleId(TPositionModuleId& aModuleId) const;

TInt RPositionServer::GetNumModules(TUint& aNumModules) const;

TInt RPositionServer::GetModuleInfoByIndex(TInt aModuleIndex, TPositionModuleInfoBase& aModuleInfo) const;

TInt RPositionServer::GetModuleInfoById(TPositionModuleId aModuleId, TPositionModuleInfoBase& aModuleInfo) const;

TInt RPositionServer::GetModuleStatus(TPositionModuleStatusBase& aPosModuleStatus, TPositionModuleId aModuleId) const;

void RPositionServer::NotifyModuleStatusEvent(TPositionModuleStatusEventBase& aStatusEvent,TRequestStatus& aStatus,const TPositionModuleId aModuleId = KPositionNullModuleId) const;

TInt RPositioner::SetRequestor(CRequestor::TRequestorType aType,CRequestor::TRequestorFormat aFormat,const TDesC& aData);

TInt RPositioner::SetRequestor(const RRequestorStack& aRequestorStack);

TInt RPositioner::SetUpdateOptions(const TPositionUpdateOptionsBase& aPosOption);

TInt RPositioner::GetUpdateOptions(TPositionUpdateOptionsBase& aPosOption) const;

void RPositioner::GetLastKnownPosition(TPositionInfoBase& aPosInfo,TRequestStatus& aStatus) const;

void RPositioner::NotifyPositionUpdate(TPositionInfoBase& aPosInfo,TRequestStatus& aStatus) const;

#include <lbs.h>

Inherits RPositionerSubSessionBase.

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


Public Member Functions
IMPORT_C	RPositioner ()
	Constructor for RPositioner.
IMPORT_C TInt	Open (RPositionServer &aPosServer)
	Creates a sub-session with the positioning server.
IMPORT_C TInt	Open (RPositionServer &aPosServer, TPositionModuleId aModuleId)
	Creates a sub-session with the positioning server.
IMPORT_C TInt	Open (RPositionServer &aPosServer, const TPositionCriteriaBase &aCriteria)
	Creates a sub-session with the positioning server.
IMPORT_C void	Close ()
	Closes a sub-session with the positioning server.
IMPORT_C TInt	SetRequestor (CRequestor::TRequestorType aType, CRequestor::TRequestorFormat aFormat, const TDesC &aData)
	Set the requestor for this sub-session.
IMPORT_C TInt	SetRequestor (const RRequestorStack &aRequestorStack)
	Sets the requestors for this sub-session.
IMPORT_C TInt	SetUpdateOptions (const TPositionUpdateOptionsBase &aPosOption)
	This method can be used to modify the current options set for this sub-session.
IMPORT_C TInt	GetUpdateOptions (TPositionUpdateOptionsBase &aPosOption) const
	This method retrieves the current options set for this sub-session.
IMPORT_C void	GetLastKnownPosition (TPositionInfoBase &aPosInfo, TRequestStatus &aStatus) const
	This method returns cached position information if it is available.
IMPORT_C void	NotifyPositionUpdate (TPositionInfoBase &aPosInfo, TRequestStatus &aStatus) const
	This is an asynchronous method for obtaining position updates.
Protected Member Functions
virtual IMPORT_C void	ConstructL ()
	symbian 2nd phase constructor
virtual IMPORT_C void	Destruct ()
	destructs the data inside this class
virtual IMPORT_C TAny *	ExtendedInterface (TInt aFunctionNumber, TAny aPtr1, TAny aPtr2)

Constructor & Destructor Documentation

IMPORT_C RPositioner::RPositioner

(

)

Constructor for RPositioner.

Member Function Documentation

IMPORT_C void RPositioner::Close

(

)

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.

virtual IMPORT_C void RPositioner::ConstructL ( ) [protected, virtual]

symbian 2nd phase constructor

virtual IMPORT_C void RPositioner::Destruct ( ) [protected, virtual]

destructs the data inside this class

virtual IMPORT_C TAny* RPositioner::ExtendedInterface	(	TInt	aFunctionNumber,
		TAny *	aPtr1,
		TAny *	aPtr2
	)	`[protected, virtual]`

Reimplemented from RPositionerSubSessionBase.

IMPORT_C void RPositioner::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.

Parameters:

`[out]`	aPosInfo	will be set, upon successful completion, to the most recently determined location data.
`[out]`	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.

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

Precondition:: The application should have called RPositioner::SetRequestor() before calling this method.

IMPORT_C TInt RPositioner::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.

Parameters:

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

Returns:: a Symbian OS error code.

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

IMPORT_C void RPositioner::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.

Parameters:

`[out]`	aPosInfo	will hold, on successful completion, information on the devices' current position.
`[out]`	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.

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.

Precondition:: The application should have called RPositioner::SetRequestor() before calling this method.

IMPORT_C TInt RPositioner::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.

Parameters:

`[in]`	aPosServer	is a connected session with the positioning server.
`[in]`	aCriteria	is the criteria that the server must use to choose an appropriate PSY for this sub-session.

Returns:: a Symbian OS error code.

Note:: This function is not supported and it returns KErrNotFound.

IMPORT_C TInt RPositioner::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.

Parameters:

`[in]`	aPosServer	is a connected session with the positioning server.
	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()

Returns:: 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:: "Lbs Client Fault" 6 If no connection has been established with Location Server ( by calling RPositionServer::Connect() ).

Precondition:: a connection with the server should already have been created by calling RPositionServer::Connect().

IMPORT_C TInt RPositioner::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.

Parameters:

[in] aPosServer is a connected session with the positioning server.

Returns:: a Symbian OS error code.

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() ).

Precondition:: a connection with the server should already have been created by calling RPositionServer::Connect().

IMPORT_C TInt RPositioner::SetRequestor

(

const RRequestorStack &

aRequestorStack

)

Sets the requestors for this sub-session.

These requestors will be used to verify privacy whenever a location request is made through this sub-session. This method is used when a chain of requestors is involved in the positioning request.

Parameters:

[in] aRequestorStack is a collection of CRequestor objects.

Returns:: a Symbian OS error code.
KErrArgument if aRequestorStack contains no requestors, or if the length of aData exceeds 255 characters.

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

Precondition:: RPositioner::Open() should have been called prior to this operation.

Postcondition:: This sets the requestor for this session. Further location information requests will result in a privacy check being done with this requestor information.

IMPORT_C TInt RPositioner::SetRequestor	(	CRequestor::TRequestorType	aType,
		CRequestor::TRequestorFormat	aFormat,
		const TDesC &	aData
	)

Set the requestor for this sub-session.

This requestor will be used to verify privacy whenever a location request is made through this sub-session. This method is used when there is only one requestor involved in the positioning request.

Parameters:

	aType	identifies the type of requestor, a service or a contact.
	aFormat	identifies the format of the requestor.
`[in]`	aData	identifies the requestor string. The requestor string can be a telephone number, a URL etc.

Returns:: a Symbian OS error code.
KErrArgument is returned if the format or type of the specified requestor parameter (aRequestor) is incorrect, or if the EFormatApplication format is used with an ERequestorContact type of requestor,or if the length of aData exceeds 255 characters.

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

Precondition:: RPositioner::Open() should have been called prior to this operation.

Postcondition:: This sets the requestor for this session. Further location information requests will result in a privacy check being done with this requestor information.

IMPORT_C TInt RPositioner::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.

Parameters:

[in] aPosOption contains the clients requested options for receiving location updates.

Returns:

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

Precondition:: RPositioner::Open() should have been called prior to this operation.

The documentation for this class was generated from the following file:

lbs.h

RPositioner Class Reference

Capability Information

Detailed Description

Public Member Functions

Protected Member Functions

Constructor & Destructor Documentation

Member Function Documentation