RPositionServer Class Reference

#include <lbs.h>

Link against: lbs.lib

class RPositionServer : public RSessionBase

Inherits from

RPositionServer
- RSessionBase
  - RHandleBase

Public Member Type Definitions
typedef	TInt TRequestId

Public Member Enumerations
enum	_TRequestId { EReqUnknown, EReqNotifyModuleStatusEvent, EReqEmptyLastKnownPositionStore }

Public Member Functions
	RPositionServer()
IMPORT_C TInt	CancelRequest(TRequestId)
IMPORT_C void	Close()
IMPORT_C TInt	Connect()
IMPORT_C void	EmptyLastKnownPositionStore(TRequestStatus &)
IMPORT_C TInt	GetDefaultModuleId(TPositionModuleId &)
IMPORT_C TInt	GetModuleInfoById(TPositionModuleId, TPositionModuleInfoBase &)
IMPORT_C TInt	GetModuleInfoByIndex(TInt, TPositionModuleInfoBase &)
IMPORT_C TInt	GetModuleStatus(TPositionModuleStatusBase &, TPositionModuleId)
IMPORT_C TInt	GetNumModules(TUint &)
IMPORT_C void	NotifyModuleStatusEvent(TPositionModuleStatusEventBase &, TRequestStatus &, const TPositionModuleId)
IMPORT_C TVersion	Version()

Inherited Attributes
	RHandleBase::iHandle

Inherited Enumerations
	RHandleBase:TAttributes
	RSessionBase:TAttachMode

Inherited Functions
	RHandleBase::Attributes()const
	RHandleBase::BTraceId()const
	RHandleBase::DoExtendedClose()
	RHandleBase::Duplicate(const RThread &,TOwnerType)
	RHandleBase::FullName()const
	RHandleBase::FullName(TDes &)const
	RHandleBase::Handle()const
	RHandleBase::HandleInfo(THandleInfo *)
	RHandleBase::Name()const
	RHandleBase::NotifyDestruction(TRequestStatus &)
	RHandleBase::Open(const TFindHandleBase &,TOwnerType)
	RHandleBase::OpenByName(const TDesC &,TOwnerType,TInt)
	RHandleBase::RHandleBase()
	RHandleBase::RHandleBase(TInt)
	RHandleBase::SetHandle(TInt)
	RHandleBase::SetHandleNC(TInt)
	RSessionBase::CreateSession(RServer2,const TVersion &)
	RSessionBase::CreateSession(RServer2,const TVersion &,TInt)
	RSessionBase::CreateSession(RServer2,const TVersion &,TInt,TIpcSessionType,const TSecurityPolicy ,TRequestStatus )
	RSessionBase::CreateSession(const TDesC &,const TVersion &)
	RSessionBase::CreateSession(const TDesC &,const TVersion &,TInt)
	RSessionBase::CreateSession(const TDesC &,const TVersion &,TInt,TIpcSessionType,const TSecurityPolicy ,TRequestStatus )
	RSessionBase::CreateSession(const TDesC &,const TVersion &,TInt,TRequestStatus *)
	RSessionBase::Open(RMessagePtr2,TInt,TOwnerType)
	RSessionBase::Open(RMessagePtr2,TInt,const TSecurityPolicy &,TOwnerType)
	RSessionBase::Open(TInt,TOwnerType)
	RSessionBase::Open(TInt,const TSecurityPolicy &,TOwnerType)
	RSessionBase::Send(TInt)const
	RSessionBase::Send(TInt,const TIpcArgs &)const
	RSessionBase::SendReceive(TInt)const
	RSessionBase::SendReceive(TInt,TRequestStatus &)const
	RSessionBase::SendReceive(TInt,const TIpcArgs &)const
	RSessionBase::SendReceive(TInt,const TIpcArgs &,TRequestStatus &)const
	RSessionBase::SetReturnedHandle(TInt)
	RSessionBase::SetReturnedHandle(TInt,RHandleBase &)
	RSessionBase::SetReturnedHandle(TInt,const TSecurityPolicy &)
	RSessionBase::ShareAuto()
	RSessionBase::ShareProtected()

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. It is also used for requests to clear(empty) the last known position store.

Asynchronous requests can be cancelled using the method CancelRequest() with a value from the enumeration _TReqestId corresponding to the particular operation being cancelled.

Member Type Definition Documentation

Typedef TRequestId

typedef TInt

TRequestId

Type for values defined in _TRequestId

Member Enumeration Documentation

Enum _TRequestId

Identification numbers used for cancelling requests. Note that the TRequestId enum may be extended in the future by adding more enumerated values. To maintain compatibility any unrecognized values must be handled as EReqUnknown.

Enumerator	Value	Description
EReqUnknown	0	Unknown/undefined Id
EReqNotifyModuleStatusEvent	1	The id of the RPositionServer::NotifyModuleStatusEvent request
EReqEmptyLastKnownPositionStore	2	The id of the RPositionServer::EmptyLastKnownPositionStore request

Constructor & Destructor Documentation

RPositionServer ( )

IMPORT_C

RPositionServer

(

)

RPositionServer::RPositionServer() C++ default constructor can NOT contain any code, that might leave.

Member Function Documentation

CancelRequest ( TRequestId )

IMPORT_C TInt

CancelRequest

(

TRequestId

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

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

Panic Codes
"Lbs	Client Fault" 6 If no connection has been established with Location Server ( by calling

Close ( )

IMPORT_C void

(

)

Reimplemented from RHandleBase::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 Codes
"Lbs	Client Fault" 16 If the outstanding notification requests are not cancelled before calling this method.

Connect ( )

IMPORT_C TInt

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.

Return Value: a Symbian OS error code.

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

EmptyLastKnownPositionStore ( TRequestStatus & )

IMPORT_C void

EmptyLastKnownPositionStore

(

TRequestStatus &

aStatus

)

Deletes all the cached positions accessible via the RPositioner::GetLastKnownPosition and the RPositioner:: GetLastKnownPositionArea methods.

Parameters
aStatus	[Out] Returns the result code after the asynchronous call completes. KErrNone if successful; any other system wide error code otherwise.

Capability
WriteUserData

GetDefaultModuleId ( TPositionModuleId & )

IMPORT_C TInt

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.

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

GetModuleInfoById ( TPositionModuleId, TPositionModuleInfoBase & )

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

Return details about a specified module.

Pre-condition: before calling this method RPositionServer::Connect() should be called.

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

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

Panic Codes
"Lbs	Client Fault" 6 If no connection has been established with Location Server ( by calling

GetModuleInfoByIndex ( TInt, TPositionModuleInfoBase & )

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

Return details about a specified module.

Pre-condition: before calling this method RPositionServer::Connect() should be called.

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

Return Value: a Symbian OS error code.

Panic Codes
"Lbs	Client Fault" 6 If no connection has been established with Location Server ( by calling

GetModuleStatus ( TPositionModuleStatusBase &, TPositionModuleId )

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

Obtains information about the specified positioning module.

Parameters
aPosModuleStatus	contains, on successful completion, the status of the specified positioning module
aModuleId	the unique identifier (UID) of a positioning module

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

GetNumModules ( TUint & )

IMPORT_C TInt

GetNumModules

(

TUint &

aNumModules

)

const

This method obtains the current number of available positioning modules.

Pre-condition: before calling this method RPositionServer::Connect() should be called.

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

Return Value: a Symbian OS error code.

Panic Codes
"Lbs	Client Fault" 6 If no connection has been established with Location Server ( by calling

NotifyModuleStatusEvent ( TPositionModuleStatusEventBase &, TRequestStatus &, const TPositionModuleId )

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. 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
aStatusEvent	contains, on successful completion, information regarding the status event and the new status of of the specified positioning module.
aStatus	contains the result code after the asynchronous call completes. It returnsKErrNotFound if the moduleId specified does not existKErrArgument is the requested event mask is zeroKErrCancel 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 Codes
"Lbs	Client Fault" 6 If no connection has been established with Location Server ( by calling
"Lbs	Client Fault" 15 If there is already is a pending notification for module status event.

Version ( )

IMPORT_C TVersion

Version

(

)

const

Obtains the current version number of the location server.

Return Value: the version of the client API.