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

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

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.

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.