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

Detailed Description

This is generally the first interface class used by all client applications.

It is used to make the primary connection to the location server. After the primary connection has been established, its handle is passed as a parameter of the Open methods of RPositioner to create a sub-session.

The RPositionServer class can also be used to discover what position technology modules are available. However, this is only required if a client application actually needs to use a particular module.


Public Member Functions
IMPORT_C	RPositionServer ()
	Constructor for RPositionServer.
IMPORT_C TInt	Connect ()
	Creates a session with the positioning server.
IMPORT_C void	Close ()
	Closes a session with the positioning server.Before the connection to Location Server is closed, the client application must ensure that any outstanding notification requests have been cancelled.
IMPORT_C TVersion	Version () const
	Obtains the current version number of the location server.
IMPORT_C TInt	GetDefaultModuleId (TPositionModuleId &aModuleId) const
	This method obtains the identifier of the systems' default positioning module.
IMPORT_C TInt	GetNumModules (TUint &aNumModules) const
	This method obtains the current number of available positioning modules.
IMPORT_C TInt	GetModuleInfoByIndex (TInt aModuleIndex, TPositionModuleInfoBase &aModuleInfo) const
	Return details about a specified module.
IMPORT_C TInt	GetModuleInfoById (TPositionModuleId aModuleId, TPositionModuleInfoBase &aModuleInfo) const
	Return details about a specified module.
IMPORT_C TInt	GetModuleStatus (TPositionModuleStatusBase &aPosModuleStatus, TPositionModuleId aModuleId) const
	Obtains information about the specified positioning module.
IMPORT_C void	NotifyModuleStatusEvent (TPositionModuleStatusEventBase &aStatusEvent, TRequestStatus &aStatus, const TPositionModuleId aModuleId=KPositionNullModuleId) const
	This method reports status changes of either a single module or all positioning modules.
IMPORT_C TInt	CancelRequest (TInt aRequestId)
	Cancels a previously issued asynchronous request.

Constructor & Destructor Documentation

IMPORT_C RPositionServer::RPositionServer

(

)

Constructor for RPositionServer.

Member Function Documentation

IMPORT_C TInt RPositionServer::CancelRequest

(

TInt

aRequestId

)

Cancels a previously issued asynchronous request.

The TRequestStatus of the original request will be set to KErrCancel if the cancellation request was successful, or any other Symbian OS error code if CancelRequest was called too late.

Parameters:

aRequestId

is a number that specifies the request to be cancelled. It should be set to EPositionServerNotifyModuleStatusEvent to cancel a call to RPositionServer::NotifyModuleStatusEvent()

Returns:: a symbian OS error code.
KErrNotFound if there is no outstanding request for the specified request ID.

Panic:: "Lbs Client Fault" 6 If no connection has been established with Location Server ( by calling RPositionServer::Connect() ).

IMPORT_C void RPositionServer::Close

(

)

Closes a session with the positioning server.Before the connection to Location Server is closed, the client application must ensure that any outstanding notification requests have been cancelled.

In particular, applications must issue all appropriate cancel requests and then wait for a confirmation that the notifications have been terminated. A failure to do so results in a client side panic.

Panic:: "Lbs Client Fault" 16 If the outstanding notification requests are not cancelled before calling this method.

IMPORT_C TInt RPositionServer::Connect

(

)

Creates a session with the positioning server.

If there are no other sessions when this is called, the method will start the server. This method must be called before an attempt to obtain module information or on opening a sub-session.

Returns:: a Symbian OS error code.

Panic:: "Lbs Client Fault" 5 If this method is called when a connection is already present.

IMPORT_C TInt RPositionServer::GetDefaultModuleId

(

TPositionModuleId &

aModuleId

)

const

This method obtains the identifier of the systems' default positioning module.

This module will be used if no criteria is specified when an RPositioner sub-session is created.

See also:: RPositioner::Open()

Parameters:

[out] aModuleId will be set, upon successful completion, to the ID of the module that the positioning server uses by default.

Returns:: a Symbian OS error code.

Panic:: "Lbs Client Fault" 6 If no connection has been established with Location Server ( by calling RPositionServer::Connect() ). are not cancelled before calling close.

Precondition:: before calling this method RPositionServer::Connect() should be called.

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

Return details about a specified module.

Parameters:

	aModuleId	the unique identifier (UID) of a positioning module
`[out]`	aModuleInfo	contains, on successful completion, the information relating to the specified positioning module.

Returns:: a symbian OS error code.
KErrNotFound is returned if the specified moduleId is not valid.

Panic:: "Lbs Client Fault" 6 If no connection has been established with Location Server ( by calling RPositionServer::Connect() ).

Precondition:: before calling this method RPositionServer::Connect() should be called.

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

Return details about a specified module.

Parameters:

	aModuleIndex	a logical index (0...GetNumModules()-1) of a positioning module.
`[out]`	aModuleInfo	contains, on successful completion, the information relating to the specified positioning module.

Returns:: a Symbian OS error code.

Panic:: "Lbs Client Fault" 6 If no connection has been established with Location Server ( by calling RPositionServer::Connect() ).

Precondition:: before calling this method RPositionServer::Connect() should be called.

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

Obtains information about the specified positioning module.

Parameters:

`[out]`	aPosModuleStatus	contains, on successful completion, the status of the specified positioning module
	aModuleId	the unique identifier (UID) of a positioning module

Returns:: a symbian OS error code.
KErrNotFound is returned if the specified moduleId is not valid.

IMPORT_C TInt RPositionServer::GetNumModules

(

TUint &

aNumModules

)

const

This method obtains the current number of available positioning modules.

Parameters:

[out] aNumModules will be set, upon successful completion, to the number of positioning modules (PSYs) that are currently available.

Returns:: a Symbian OS error code.

Panic:: "Lbs Client Fault" 6 If no connection has been established with Location Server ( by calling RPositionServer::Connect() ).

Precondition:: before calling this method RPositionServer::Connect() should be called.

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

This method reports status changes of either a single module or all positioning modules.

It is an asynchronous request and the client should use it appropriately using active objects.

After a notification has been received, the client application must re-issue the status change request if it wishes to obtain further updates.

To cancel this request use RPositionServer::CancelRequest() with EPositionServerNotifyModuleStatusEvent as parameter

Parameters:

`[out]`	aStatusEvent	contains, on successful completion, information regarding the status event and the new status of of the specified positioning module.
`[out]`	aStatus	contains the result code after the asynchronous call completes. It returns KErrNotFound if the moduleId specified does not exist KErrArgument is the requested event mask is zero KErrCancel if the notification is cancelled.
	aModuleId	the unique identifier (UID) of a positioning module. If the parameter is zero, then a status update is provided for all positioning modules.

Panic:: "Lbs Client Fault" 6 If no connection has been established with Location Server ( by calling RPositionServer::Connect() ).

Panic:: "Lbs Client Fault" 15 If there is already is a pending notification for module status event.

IMPORT_C TVersion RPositionServer::Version

(

)

const

Obtains the current version number of the location server.

Returns:: the version of the client API.

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

lbs.h

RPositionServer Class Reference

Capability Information

Detailed Description

Public Member Functions

Constructor & Destructor Documentation

Member Function Documentation