Class RPositioner

class RPositioner : public RPositionerSubSessionBase;

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.

Derivation

• RSubSessionBase - Client-side handle to a sub-session.

• RPositionerSubSessionBase - Abstract base class for all positioning sub-sessions, including RPositioner.

• RPositioner - This class is used to create a sub-session with the server for the purpose of ob...

Members

Defined in RPositioner:

• Close()Closes a sub-session with the positioning server.
• ConstructL()Leaving constructor for RPositioner. Just creates the ptr-holder.
• Destruct()Destruction method for RPositionServer. Just deletes the ptr-holder.
• ExtendedInterface(TInt,TAny *,TAny *)This method is used to allow polymorphic extensions to the API without breaking ...
• GetLastKnownPosition(TPositionInfoBase &,TRequestStatus &)constThis method returns cached position information if it is available. This method ...
• GetUpdateOptions(TPositionUpdateOptionsBase &)constThis method retrieves the current update options being used by this RPositioner ...
• NotifyPositionUpdate(TPositionInfoBase &,TRequestStatus &)constThis is an asynchronous method for obtaining position updates. It is possible to...
• Open(RPositionServer &)Creates a sub-session with the positioning server. One of three overloaded open ...
• Open(RPositionServer &,TPositionModuleId)Creates a sub-session with the positioning server. One of three overloaded open ...
• Open(RPositionServer &,const TPositionCriteriaBase &)Creates a sub-session with the positioning server. One of three overloaded open ...
• RPositioner()Constructor for RPositioner
• SetRequestor(const RRequestorStack &)Sets the many requestors of the location information that will be obtained throu...
• SetUpdateOptions(const TPositionUpdateOptionsBase &)This method can be used to modify the behaviour of RPositioner::NotifyPositionUp...

Inherited from RPositionerSubSessionBase:

• CancelRequest(TInt)Cancels a previously issued asynchronous request. The TRequestStatus of the orig...
• CompleteRequest(TInt)Completes the outstanding request method identified by aRequestId. This results ...

Inherited from RSubSessionBase:

• CloseSubSession(TInt)Closes the sub-session.
• CreateAutoCloseSubSession(RSessionBase &,TInt,const TIpcArgs &)Creates a new sub-session within an existing session. The new sub-session takes ...
• CreateSubSession(const RSessionBase &,TInt)Creates a new sub-session within an existing session.
• CreateSubSession(const RSessionBase &,TInt,const TIpcArgs &)Creates a new sub-session within an existing session.
• Send(TInt)constSends a blind message to the server - no reply is expected.
• Send(TInt,const TIpcArgs &)constSends a blind message to the server - no reply is expected.
• SendReceive(TInt)constSends a message to the server and waits synchronously for a reply.
• SendReceive(TInt,TRequestStatus &)constSends a message to the server and waits asynchronously for the reply.
• SendReceive(TInt,const TIpcArgs &)constSends a message to the server and waits synchronously for a reply.
• SendReceive(TInt,const TIpcArgs &,TRequestStatus &)constSends a message to the server and waits asynchronously for the reply.
• Session()constReturns a copy of the session associated with this sub-session.
• SubSessionHandle()constGets the sub-session handle number.

See also:

• RPositionServerThis is generally the first interface class used by all client applications. It ...

IMPORT_C RPositioner();

Description

Constructor for RPositioner

protected: IMPORT_C virtual void ConstructL();

Description

Leaving constructor for RPositioner. Just creates the ptr-holder.

IMPORT_C TInt Open(RPositionServer &aPosServer);

Description

Creates a sub-session with the positioning server. One of three overloaded open methods. This one uses the default module - as defined by the quality profile

Parameters

RPositionServer &aPosServer is a connected session with the positioning server.

Return value

TInt Standard Symbian OS error code.

IMPORT_C TInt Open(RPositionServer &aPosServer, TPositionModuleId aModuleId);

Description

Creates a sub-session with the positioning server. One of three overloaded open methods. This one explicitly specifies the ID of the module to use as specified by the the modules information.

Parameters

RPositionServer &aPosServer is a connected session with the positioning server. TUid aModuleId is the module ID for this sub-session to use to obtain location data.

Return value

TInt Standard Symbian OS error code.

IMPORT_C TInt Open(RPositionServer &aPosServer, const TPositionCriteriaBase &aCriteria);

Description

Creates a sub-session with the positioning server. One of three overloaded open methods. This one explicitly specifies the criteria. A module is chosen that meets the specfied criteria.

Parameters

RPositionServer &aPosServer is a connected session with the positioning server. const TPositionCriteriaBase &aCriteria is the criteria that the server must use to choose an appropriate PSY for this sub-session.

Return value

TInt Standard Symbian OS error code.

IMPORT_C void Close();

Description

Closes a sub-session with the positioning server.

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

Description

Sets the requestor of the location information that will be obtained through this sub-session.

Parameters

CRequestorBase::TRequestorType aType identifies the type of requestor, a service or a contact. CRequestorBase::TRequestorFormat aFormat determines the type of data held in aData const TDesC16 &aData is requestor data. Can be a telephone number, a URL etc.

Return value

TInt Standard Symbian OS error code.

IMPORT_C TInt SetRequestor(const RRequestorStack &aRequestorStack);

Description

Sets the many requestors of the location information that will be obtained through this sub-session.

Parameters

const RRequestorStack &aRequestorStack is a collection of CRequestor objects.

Return value

TInt Standard Symbian OS error code.

Capability:

Location

IMPORT_C TInt SetUpdateOptions(const TPositionUpdateOptionsBase &aPosOption);

Description

This method can be used to modify the behaviour of RPositioner::NotifyPositionUpdate(TPositionInfoBase &,TRequestStatus &)const requests. It enables the client to request an interval time for receiving position updates.

Parameters

const TPositionUpdateOptionsBase &aPosOption contains the clients requested options for receiving location updates.

Return value

TInt Standard Symbian OS error code.

Capability:

Location

IMPORT_C TInt GetUpdateOptions(TPositionUpdateOptionsBase &aPosOption) const;

Description

This method retrieves the current update options being used by this RPositioner sub-session.

Parameters

TPositionUpdateOptionsBase &aPosOption contains, upon successful completion, the set of update options for RPositioner::NotifyPositionUpdate(TPositionInfoBase &,TRequestStatus &)const that are currently in use.

Return value

TInt Standard Symbian OS error code.

Capability:

Location

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

Description

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

TPositionInfoBase &aPosInfo will be set, upon successful completion, to the most recently determined location data. TRequestStatus &aStatus returns the result code after the asynchronous call completes

Capability:

Location

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

Description

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.

On successful return, aStatus will hold KErrNone. However, if the returned position information does not meet the aplication's quality criteria, aStatus will hold KPositionQualityLoss.

If the application has selected the use of partial updates, aStatus will hold KPositionPartialUpdate when the position information is incomplete or does not meet the required accuracy.

When the request has been completed early via the use of RPositionerSubSessionBase::CompleteRequest(TInt), aStatus will contain KPositionEarlyComplete.

aStatus may also return other error codes defined in LBSErrors.h, or other non-Symbian OS defined status codes returned for example, by 3rd party A-GPS or Network Protocol modules

Parameters

TPositionInfoBase &aPosInfo will hold, on successful completion, information on the devices' current position. TRequestStatus &aStatus returns the result code after the asynchronous call completes

protected: IMPORT_C virtual void Destruct();

Description

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

protected: IMPORT_C virtual TAny* ExtendedInterface(TInt aFunctionNumber, TAny *aPtr1, TAny *aPtr2);

Description

This method is used to allow polymorphic extensions to the API without breaking BC. See documentation for explanation.

Parameters

TInt aFunctionNumber contains the Id of the function to be invoked. TAny *aPtr1 a pointer to any data TAny *aPtr2 a pointer to any data.

Return value

TAny * TAny* a pointer to any function