MLbsNetworkProtocolObserver Class Reference

class MLbsNetworkProtocolObserver

The MLbsNetworkProtocolObserver class is used in partnership with CLbsNetworkProtocolBase . The observer interface is used by a protocol module to forward network requests and information to the LBS subsystem. It is also the interface that a protocol module uses to provide responses to requests made by the LBS subsystem via CLbsNetworkProtocolBase .

When a network protocol module makes a request via the observer API the LBS subsystem provides a response via the corresponding notification method in the CLbsNetworkProtocolBase class. Although all the interface methods in the MLbsNetworkProtocolObserver are synchronous they will return quickly. The LBS subsystem will internally queue requests and process them asynchronously.

For example, when the network sends a message requesting the current location of the handset, the protocol module should forwarded this request via the method ProcessLocationRequest() . When the current position is eventually calculated, the LBS subsystem informs the protocol module by calling MLbsNetworkProtocolObserver::RespondLocationRequest().

Calls from the protocol module to the LBS subsystem may be unsolicited and/or in response to requests made by the observer. For example, if the subsystem requests GPS assistance data via CLbsNetworkProtocolBase::RequestAssistanceData() the protocol module will respond some time later via ProcessAssistanceData() . However, the protocol module is also allowed to provide assistance data updates at any time and not just in response to the requests from the observer.

CLbsNetworkProtocolBase

Member Functions Documentation

ExtendedInterface(TInt, TAny *, TAny *)

IMPORT_C TAny * ExtendedInterface ( TInt aFunctionNumber,
TAny * aPtr1,
TAny * aPtr2
) [private, virtual]

This methods is reserved for future expansion and should not be used. Currently not implemented.

Parameters

TInt aFunctionNumber
TAny * aPtr1
TAny * aPtr2

GetCurrentCapabilities(TLbsNetPosCapabilities &)

void GetCurrentCapabilities ( TLbsNetPosCapabilities & aCapabilities ) const [pure virtual]

Retrieves from the LBS subsystem the current capabilities of the device.

GetCurrentCapabilities() is used by the protocol module to obtain details of what types of network request the device is able to respond to. For example, this might include terminal based GPS but not terminal assisted.

The protocol module should call GetCurrentCapabilities() each time it needs to obtain the device's capabilities. The capabilities may vary as the user or network configures the device.

The device may support more than one positioning method, in which case the first one in the list is the preferred positioning method for the device. The preferred positioning method is the method returned by calling aCapabilities.GetPosMethod(0, method).

Parameters

TLbsNetPosCapabilities & aCapabilities Returns the current capabilities of the device.

ProcessAssistanceData(TLbsAsistanceDataGroup, const RLbsAssistanceDataBuilderSet &, TInt)

void ProcessAssistanceData ( TLbsAsistanceDataGroup aDataMask,
const RLbsAssistanceDataBuilderSet & aData,
TInt aReason
) [pure virtual]

Assistance data may arrive as a result of the LBS subsystem requesting it via a call to the CLbsNetworkProtocolBase methods RequestSelfLocation() or RequestAssistanceData(). However, assistance data can also be delivered unsolicited. For example, a MT-LR location request (e.g. measurement control) from the network will normally include a default set of assistance data.

This method can also be used by the network to request that the LBS subsystem deletes all of its cached assistance data, or a subset of it. This is done by setting aReason to KPositionAssistanceDataReset and aDataMask to specify which subset of assistance data must be reset. The parameter aDataMask must not be 0, and it must be a valid bitmask of values specified by TLbsAssistanceDataItem. When using this method to reset assistance data, the parameter aData can be left empty.

CLbsNetworkProtocolBase::RequestSelfLocation() CLbsNetworkProtocolBase::RequestAssistanceData()

Parameters

TLbsAsistanceDataGroup aDataMask Is a bitmask that specifies which subsets of GPS assistance data are included in the aData parameter, or which subsets of GPS assistance data should be reset.
const RLbsAssistanceDataBuilderSet & aData A container that holds all of the GPS assistance data to be delivered.
TInt aReason Delivery status for the GPS assistance data being supplied. KErrNone is passed if the specified assistance data has been successfully retrieved from the network and delivered. KPositionAssistanceDataReset can be passed to ask the LBS subsystem to reset its cached assistance data, or a subset of it. Otherwise, an error code is passed indicating the reason why the assistance data referenced in aData could not be obtained.

ProcessLocationRequest(const TLbsNetSessionId &, TBool, TLbsNetProtocolService, const TLbsNetPosRequestQuality &, const TLbsNetPosRequestMethod &)

void ProcessLocationRequest ( const TLbsNetSessionId & aSessionId,
TBool aEmergency,
TLbsNetProtocolService aService,
const TLbsNetPosRequestQuality & aQuality,
const TLbsNetPosRequestMethod & aMethod
) [pure virtual]

Location (e.g. measurement control) requests are received from the network, instructing the terminal to calculate and return its current position.

When the network protocol module calls ProcessLocationRequest() the method will return quickly. This initiates a position calculation by the LBS subsystem. When the current position is available, the subsystem return the location to the module via a call to CLbsNetworkProtocolBase::RespondLocationRequest() .

The parameter aType indicates why the network has generated the location request and can take the following values:

(a) It is the second stage of a MT-LR. This is normally generated by the network if device has responded positively to the preceding privacy request.

(b) Location requests may also generated by the network when the terminal wishes to obtain assistance data - for example via a Mobile Originated Location Request (MO-LR).

(c) A request from the terminal to transmit its current location to a remote third-party (X3P) can also result in the network generating a location request.

(d) Under some location protocols, a request from the terminal for a network based location calculation (e.g. cell-id) may also result in the network asking the terminal for its position.

(e) It is also possible for the network to send location requests without any preamble. These Network Induced Location Requests (NI-LR) are generated by the network and instruct the terminal to calculate and return its current position.

The session ID parameter is used to connect a series of requests and responses. If this location request is the result of a MT-LR the session ID will be the same as that passed in the privacy request.

Similarly, when performing a transmit to third-party (X3P), the session ID of the location request will be the same as that used to initiate the transfer.

However, in the other cases the location request starts a new session. In this situation, the session ID will be unrelated to any previous request.

Note: The aMethod parameter contains a network preferred list of positioning modes, however in order to determine the final positioning mode the LBS subsystem is using more information, like the default positioning mode ( CLbsAdmin); the number and the type of other positioning sessions and the capabilities of the AGPS positioning module (see the module configuration file). CLbsNetworkProtocolBase::RespondLocationRequest() ProcessPrivacyRequest() CLbsNetworkProtocolBase::RequestTransmitLocation() CLbsNetworkProtocolBase::RequestSelfLocation() CLbsNetworkProtocolBase::RequestNetworkLocation() ProcessSessionComplete() TLbsExternalRequestInfo TLbsNetRequestQuality TLbsNetRequestMode

Parameters

const TLbsNetSessionId & aSessionId The Id of the location request within the LBS sub-system.
TBool aEmergency ETrue if this is an emergency request, EFalse otherwise.
TLbsNetProtocolService aService Specifies the type of the service/session the request is related to.
const TLbsNetPosRequestQuality & aQuality Stipulates both the desired accuracy of the location information and the maximum time the network is prepared to wait. Zero values for these fields indicates there are no accuracy or time constraints.
const TLbsNetPosRequestMethod & aMethod contains a list of the positioning methods that should be used to obtain the device's position in the network's order of preference

ProcessLocationUpdate(const TLbsNetSessionId &, const TPositionInfoBase &)

void ProcessLocationUpdate ( const TLbsNetSessionId & aSessionId,
const TPositionInfoBase & aPosInfo
) [pure virtual]

Location Information may arrive as a result of the LBS subsystem requesting it via a call to CLbsNetworkProtocolBase::RequestNetworkLocation() . However, location information can be delivered unsolicited. For example, a location request (e.g. measurement control) from the network will typically include a reference location that is derived from the terminal's serving cell. The reference location is injected at most once a session. This is valid even if assistance data is reset during the positioning request in order to avoid impacting the standard behaviour of the LBS sub-system when reset message is being received.

The Session ID parameter indicates which request led to the location information being delivered. For a MT-LR, the session ID will be the ID assigned by the protocol module. This is the ID passed by the protocol module when it calls ProcessPrivacyRequest() .

If the location information was delivered as a result of a request generated by the terminal, the session ID should be the identifier used by the LBS subsystem when it initiated that request. This will be the ID passed to RequestSelfLocation(), RequestNetworkLocation() or RequestTransmitLocation() by the LBS subsystem.

Parameters

const TLbsNetSessionId & aSessionId The Id of the request under which the assistance data has arrived.
const TPositionInfoBase & aPosInfo Location details of terminal as provided by the network. The parameter aPosInfo is normally of type TPositionInfo.

ProcessPrivacyRequest(const TLbsNetSessionId &, TBool, const TLbsNetPosRequestPrivacy &, const TLbsExternalRequestInfo &)

void ProcessPrivacyRequest ( const TLbsNetSessionId & aSessionId,
TBool aEmergency,
const TLbsNetPosRequestPrivacy & aPrivacy,
const TLbsExternalRequestInfo & aRequestInfo
) [pure virtual]

Ask the LBS subsystem to process a privacy request from the network.

Privacy requests (for example an LCS-Notification) are typically the first stage of a Mobile Terminated Location Request (MT-LR). They are received from the network to determine if the handset is willing to reveal its location to an external third-party.

ProcessPrivacyRequest() supplies information about the external requestor but does not actually ask the device for its position. If the LBS subsystem responds indicating it is willing to reveal its location, the network will normally send the second stage of the MT-LR. This follow-on message is forward by the protocol module via a separate method (ProcessLocationRequest) and is the trigger for the LBS subsystem to calculate the current position.

The ProcessPrivacyRequest() method will return quickly. However, it does not indicate if request should be accepted or rejected. After the LBS subsystem has determined the user's preferences, it responds to the protocol module via a call to CLbsNetworkProtocolBase::RespondPrivacyRequest() . The response indicates if handset is willing to accept a location request.

If the terminal does indicate it is willing to accept a location request, the network will typically send a follow-on request (measurement control) that asks for the devivce's location. The protocol module forwards this second request via the method ProcessLocationRequest() .

In all subsequent requests and responses, the same unique session ID (aSessionId) must be used in order to connect the various requests and responses.

CLbsNetworkProtocolBase::RespondPrivacyRequest() ProcessLocationRequest() CLbsNetworkProtocolBase::RespondLocationRequest() ProcessSessionComplete() TLbsExternalRequestInfo TLbsLocationNotification

Parameters

const TLbsNetSessionId & aSessionId The Id of the privacy request. This is generated by the protocol module and is used by the LBS subsystem when it responses to the privacy request via CLbsNetworkProtocolBase::RespondPrivacyRequest(). The same session identifier must be also be used by the protocol module if and when it receives the corresponding location request from the network.
TBool aEmergency ETrue if this is an emergency privacy request, EFalse otherwise.
const TLbsNetPosRequestPrivacy & aPrivacy Privacy procedure requested by the network on how to advise the user,
const TLbsExternalRequestInfo & aRequestInfo The identity of the external third party that is requesting the handsets position.

ProcessSessionComplete(const TLbsNetSessionId &, TInt)

void ProcessSessionComplete ( const TLbsNetSessionId & aSessionId,
TInt aReason
) [pure virtual]

The protocol module issues a single call to ProcessSessionComplete() to close a session and to return the final result code to the LBS subsystem.

The aReason parameter indicates the overall success or failure for the request.

The session ID parameter identifies the session that is being closed. This ID is allocated when a new request is created:

In the case of MT-LR, the session ID is created by the protocol module when it issues the initial privacy request ( ProcessPrivacyRequest() ). That session extends through the various responses and, if appropriate, the subsequent location request ( ProcessLocationRequest() ). The protocol modules issues a single call to ProcessSessionComplete() to indicate the overall success or failure of the MT-LR.

In normal situations, ProcessSessionComplete() will be invoked when the overall request has finished. However, it may occur at any stage - for example, in the case of a MT-LR the protocol module will complete the session immediately if there was an error transmitting the initial privacy response back to the network.

Similarly, ProcessSessionComplete() is also used by the protocol module to terminate a request if a protocol conflict has arisen. For example, the location protocol may be unable to simulateously perform two requests.

For a MT-LRs and NI-LRs the session ID are assigned by the network protocol module. For other requests, the session ID is generated by the LBS subsystem. In either situation, the assigned session ID is used by both the protocol module and the LBS subsystem to connect requests and responses arising from a particular request.

Parameters

const TLbsNetSessionId & aSessionId The Id of the request being closed.
TInt aReason Reason for the completion of the request. KErrNone if the request is succecsfully completed, or one of a range of error codes otherwise.

ProcessStatusUpdate(TLbsNetProtocolServiceMask)

void ProcessStatusUpdate ( TLbsNetProtocolServiceMask aActiveServiceMask ) [pure virtual]

Provides the LBS subsystem with details of the current status of the network protocol module

ProcessStatusUpdate() provides a bit mask of values from TLbsNetProtocolService. The bit-mask indicates which services are currently being handled by the protocol module.

For example, if the protocol module is currently processing a Mobile Terminated Location Request and a local request for assistance data, aActiveServiceMask will be set to EServiceMobileTerminated + EServiceAssistanceData.

The method is called each time the services that are active in the protocol module change.

Parameters

TLbsNetProtocolServiceMask aActiveServiceMask This parameter indicates which services are currently active in the the protocol module. The parameter contains a bit-mask of values from TLbsNetProtocolService. If the protocol module is idle, the parameter is set to zero.

Version()

IMPORT_C TVersion Version ( ) const [virtual]

Get the current version of the observer interface

Member Enumerations Documentation

Enum TLbsNetProtocolService

Values of type TLbsNetProtocolService describe the processes that can be active or queued in network protocol module.

A single value is supplied as a parameter in ProcessLocationRequest() to indicate why the location request was generated.

ProcessStatusUpdate() provides a mask of TLbsNetProtocolService values to indicate all the various tasks being performed or queued by the protocol module.

ProcessLocationRequest() TLbsNetProtocolServiceMask ProcessStatusUpdate()

Enumerators

EServiceNone = 0x00

No service

EServiceNetworkLocation = 0x01

Indicates that the protocol module has currently a request from the handset to perform a network calculation of the device s position.

EServiceSelfLocation = 0x02

Indicates that the protocol module has currently a request to perform a self location.

EServiceMobileTerminated = 0x04

Indicates that the protocol module has currently a MT-LR request by an external party. This initially results in the protocol module issuing a privacy request, that contains the details of the request originator, followed by a location request.

EServiceTransmitThirdParty = 0x08

Indicates that the protocol module has currently a request to to send the device's current position to a remote third party.

EServiceNetworkInduced = 0x10

Indicates that the protocol module has currently a location request that was generated by the network (NI-LR). In this situation, the protocol module will only generate a location request. There is no preceding privacy request.

EServiceTriggeredMolr = 0x20

Indicates that the protocol module has currently a location request that was generated by the network (Triggered MOLR, SUPL 2.0).

Member Type Definitions Documentation

Typedef TLbsNetProtocolServiceMask

typedef TUint32 TLbsNetProtocolServiceMask

TLbsNetProtocolServiceMask is used to hold a bit mask of values of TLbsNetProtocolService. This is used by ProcessStatusUpdate() to indicate the tasks currently being processed or queued by the network protocol module

ProcessStatusUpdate() TLbsNetProtocolService