Collapse all Symbian^3 Application Developer Library

RPositionServer Class Reference

class RPositionServer : public RSessionBase

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.

Inherits from

RPositionServer
- RSessionBase
  - RHandleBase

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

Private Member Functions
void	ConstructL ()
void	Destruct ()
TInt	StartServer ()

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

Public Member Enumerations
enum	_TRequestId { EReqUnknown = 0, EReqNotifyModuleStatusEvent = 1, EReqEmptyLastKnownPositionStore = 2 }

Inherited Enumerations
	RHandleBase:TAttributes
	RSessionBase:TAttachMode

Public Member Type Definitions
typedef	TInt TRequestId

Private Attributes
CServerPositioningPtrHolder *	iPtrHolder
TAny *	iReserved

Inherited Attributes
	RHandleBase::iHandle

Constructor & Destructor Documentation

RPositionServer()

IMPORT_C

RPositionServer

(

)

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

Member Functions 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.

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

Parameters

TRequestId aRequestId

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

Close()

IMPORT_C void

(

)

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.

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.

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

ConstructL()

void

ConstructL

(

)

[private]

RPositionServer::ConstructL Symbian 2nd phase constructor can leave.

Destruct()

void

Destruct

(

)

[private]

RPositionServer::Destruct Destruction method for RPositionServer . Just deletes the ptr-holder.

EmptyLastKnownPositionStore(TRequestStatus &)

IMPORT_C void

EmptyLastKnownPositionStore

(

TRequestStatus &

aStatus

)

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

RPositioner::GetLastKnownPosition RPositioner::GetLastKnownPositionArea

capability: WriteUserData

Parameters

TRequestStatus & aStatus

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

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.

RPositioner::Open()

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

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

Parameters

TPositionModuleId & 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.

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

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

Parameters

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

GetModuleInfoByIndex(TInt, TPositionModuleInfoBase &)

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

Return details about a specified module.

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

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

Parameters

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

GetModuleStatus(TPositionModuleStatusBase &, TPositionModuleId)

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

Obtains information about the specified positioning module.

Parameters

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

GetNumModules(TUint &)

IMPORT_C TInt

GetNumModules

(

TUint &

aNumModules

)

const

This method obtains the current number of available positioning modules.

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

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

Parameters

TUint & aNumModules

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

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

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.

Parameters

TPositionModuleStatusEventBase & aStatusEvent	contains, on successful completion, information regarding the status event and the new status of of the specified positioning module.
TRequestStatus & 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.
const TPositionModuleId aModuleId = KPositionNullModuleId	the unique identifier (UID) of a positioning module. If the parameter is zero, then a status update is provided for all positioning modules.

StartServer()

TInt

StartServer

(

)

[private, static]

Start the server process/thread which lives in an EPOCEXE object.

Version()

IMPORT_C TVersion

Version

(

)

const

Obtains the current version number of the location server.

Member Enumerations 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.

Enumerators

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

Member Type Definitions Documentation

Typedef TRequestId

typedef TInt

TRequestId

Type for values defined in _TRequestId

Member Data Documentation

CServerPositioningPtrHolder * iPtrHolder

CServerPositioningPtrHolder *

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]

Variable for future expansion.