Privacy Controller

Purpose

This document explains the concept of a Privacy Controller and the Privacy Controller API that is used to create one. The Privacy Controller API is the interface through which a Privacy Controller application receives and responds to privacy requests from the LBS subsystem Network Request Handler.

How to use the Privacy Controller API has example code for the API described in this document.

See Privacy Requests Overview for an explanation of privacy request concepts.

Contents

• Introduction

• Privacy Controller startup and shutdown

• Privacy Controller API description

  • CLbsPrivacyController

  • MLbsPrivacyObserver

  • MLbsPrivacyObserver2

  • TLbsExternalRequestInfo

  • TLbsExternalRequestInfo2

• Sequence Diagrams

  • Privacy verification request

  • Privacy notification request

  • Privacy verification request is cancelled

• See also

Introduction

A Privacy Controller is a licensee application that receives privacy requests and responds to them. The response to the privacy request could involve user input (for example by showing privacy dialogs), or it could be automated (for example by a set of rules or policies that automatically accept or reject privacy requests based on the identity of the requester). The details of a Privacy Controller implementation are licensee-specific; the Privacy Controller API only specifies the interface over which privacy requests and responses are sent and received.

A Privacy Controller gives more control over responses to privacy requests than Privacy Notifiers. A licensee must implement either a Privacy Controller or use Privacy Notifiers to handle privacy requests.

Figure 1 shows a Privacy Controller in the context of the other components that make up the Full LBS configuration. A licensee can choose to handle privacy requests by using either a Privacy Controller or by using notifiers (using the Privacy Notifier API or the deprecated Privacy Query and Notification API).

A Privacy Controller is built as a separate application that runs outside of the LBS subsystem. See How to use the LBS Privacy Controller API for guidance on how to create a Privacy Controller. Symbian does not provide a reference Privacy Controller implementation.

Privacy Controller startup and shutdown

From Symbian OS v9.4 a licensee can configure the LBS subsystem to run in the Standalone Privacy Mode configuration in which the Symbian LBS subsystem handles privacy requests but does not calculate position fixes.

In the Standalone Privacy Mode, when a privacy request is received the LBS subsystem starts up if it is not already running and it starts the licensee Privacy Controller process. To configure the Privacy Controller for automatic startup and shutdown, a licensee must do the following:

• The licensee Privacy Controller executable UID (secure ID) must be added to the LBS Root central repository file as described in the LBS integration and configuration guide. This is necessary so that the LBS subsystem can automatically start the Privacy Controller process when a privacy request is received.

• The Privacy Controller implementation class must derive from MLbsPrivacyObserver2 (described in the API description section below) in order to receive notice to shutdown when the processing of all outstanding privacy requests is complete.

Privacy Controller API description

This section describes the classes of the LBS Privacy Controller API.

Privacy Controller API classes and types

The following table lists the classes and types that define the LBS Privacy Controller API. Further details can be found by following the links to other sections of this document and to Symbian Developer Library reference documentation.

The LBS Privacy Controller API has publishedPartner interface access.

The following table describes the request information classes used by the Privacy Controller API. Note that Privacy Notifiers also use these classes to get privacy request information from the LBS subsystem.

Privacy Controller API class diagram

Figure 2 shows the classes of the Privacy Controller API. MLbsPrivacyObserver has a dependency on TLbsExternalRequestInfo (which is shown in more detail in Figure 3).

Figure 3 shows the TLbsExternalRequestInfo and TLbsExternalRequestInfo2 classes. Either a TLbsExternalRequestInfo or TLbsExternalRequestInfo2 object reference is passed to the Privacy Controller via the MLbsPrivacyObserver::ProcessNetworkLocationRequest() function when a privacy request is received and a Privacy Controller is configured.

Note from figure 2 that the object reference is always passed as a TLbsExternalRequestInfo so it is only necessary to cast to the TLbsExternalRequestInfo2 derived class if the licensee is using large buffers for the requester ID and the client name. This may be the case only when LBS is being used in the Standalone Privacy Mode configuration and large buffer sizes are passed across the Network Privacy API or the Privacy Request API.

See the Network Privacy API documentation and the How to use the Privacy Controller API documentation for more information about handling large buffers.

Libraries

The Privacy Controller API is packaged in lbsprivacycontroller.dll. A licensee Privacy Controller links to lbsprivacycontroller.lib.

The API header files for the Privacy Controller API can be found in /epoc32/include/lbs.

Capabilities

A licensee Privacy Controller requires the following capabilities: Location, ReadDeviceData and WriteDeviceData.

LBS Configuration

The LBS Administration setting KLbsSettingPrivacyHandler must be set to CLbsAdmin::EPrivacyHandleByController to configure LBS to use a Privacy Controller. See LBS administration for details of how to configure this setting either through the LBS Administration API or in the LBS central repository initialisation file.

Multiple simultaneous privacy requests

The LBS administration setting KLbsSettingMaximumExternalLocateRequests has an important effect when LBS is configured to use a Privacy Controller.

The setting does not affect the behaviour of LBS in the Full LBS configuration because multiple simultaneous privacy requests are not supported with a Network Protocol Module.

The setting only affects how LBS behaves when a privacy request is received via the Network Privacy API or the Privacy Request API which are only supported in Standalone Privacy Mode:

• KLbsSettingMaximumExternalLocateRequests = 1 (the default setting)

  Privacy requests can only be handled sequentially by the LBS subsystem. Requests are sent sequentially to the Privacy Controller. Additional privacy requests may be received by the LBS subsystem while a previous request is still outstanding (being processed by the Privacy Controller) but these are always rejected by the LBS subsystem and are not sent to the Privacy Controller. For details of the return codes sent to a Privacy Request API client or Network Privacy API client see the Privacy Request API and Network Privacy API documentation.

• KLbsSettingMaximumExternalLocateRequests > 1

  For this case, a licensee must design their Privacy Controller so that it can process multiple simultaneous privacy requests. For example, the implementation of MLbsPrivacyObserver::ProcessNetworkLocationRequest() may be called multiple times in rapid succession and therefore must not block the Privacy Controller.

  The behaviour of the LBS subsystem depends on the number of outstanding privacy requests and the setting KLbsSettingMaximumExternalLocateRequests:

  • Number of outstanding privacy requests < KLbsSettingMaximumExternalLocateRequests

    A new privacy request is processed and causes a sequence of Privacy Controller API methods to be called. See the sequence diagrams of Network Privacy API and Privacy Request API for sequences that describe the processing of each request.

  • Number of outstanding privacy requests = KLbsSettingMaximumExternalLocateRequests

    A new privacy request is always rejected by the LBS subsystem and is not sent to the Privacy Controller. For details of the return codes sent to an API client see the Network Privacy API and Privacy Request API documentation.

CLbsPrivacyController

Purpose

CLbsPrivacyController is the class that a licensee Privacy Controller application uses to register itself as a Privacy Controller with the LBS subsystem. It is also used to respond to privacy requests. The licensee Privacy Controller must implement the MLbsPrivacyObserver interface or the derived MLbsPrivacyObserver2 interface.

Usage

CLbsPrivacyController::NewL() is used by a licensee Privacy Controller to register itself with the LBS subsystem.

CLbsPrivacyController::RespondNetworkLocationRequest() is used to send a privacy response to the LBS subsystem (in response to a privacy request that was previously sent to the Privacy Controller).

CLbsPrivacyController::CancelNetworkLocationRequest() is used to cancel an outstanding privacy request.

CLbsPrivacyController::TRequestVerificationResult

Purpose

CLbsPrivacyController::TRequestVerificationResult holds the privacy response that the Privacy Controller returns to the LBS subsystem.

Usage

The Privacy Controller passes a TRequestVerificationResult parameter to LBS in CLbsPrivacyController::RespondNetworkLocationRequest() to indicate if the privacy request was accepted, rejected or ignored.

MLbsPrivacyObserver

Purpose

MLbsPrivacyObserver is the interface class that a licensee Privacy Controller implements (or the derived MLbsPrivacyObserver2 interface).

Usage

MLbsPrivacyObserver::ProcessNetworkLocationRequest() is called by the LBS subsystem to cause the Privacy Controller to process a privacy request.

MLbsPrivacyObserver::ProcessNetworkPositionUpdate() is called by the LBS subsystem to send the Privacy Controller a position update.

MLbsPrivacyObserver::ProcessRequestComplete() is called by the LBS subsystem to notify the Privacy Controller that a privacy request is complete.

MLbsPrivacyObserver::TNotificationType

Purpose

MLbsPrivacyObserver::TNotificationType specifies the notification action defined by the received privacy request. It informs the Privacy Controller if the request requires verification or only notification to the user and whether the privacy request should be accepted or rejected if there is no response. The notification type can be one of the following values:

Important Note

The action specified by TNotificationType can be overridden by the LBS administration settings.

There are three settings that override the behaviour specified by TNotificationType:

LBS administration setting KLbsSettingHomeExternalLocate and KLbsSettingRoamingExternalLocate specify if external location requests (requests from the network) are turned on or off in the LBS subsystem (in the home network and when roaming) and whether such requests should always be verified. See CLbsAdmin::TExternalLocateService for more information about the values that these administration settings can take.

LBS administration setting KLbsSettingPrivacyTimeoutAction specifies the action that the LBS subsystem takes if a privacy request times out. See CLbsAdmin::TPrivacyTimeoutAction for more information about the values that this administration setting can take.

Usage

An MLbsPrivacyObserver::TNotificationType parameter is passed as a parameter in a call by the LBS subsystem to the Privacy Controller method MLbsPrivacyObserver::ProcessNetworkLocationRequest().

MLbsPrivacyObserver2

Purpose

MLbsPrivacyObserver2 is a Privacy Controller interface class derived from MLbsPrivacyObserver. A licensee Privacy Controller only needs to implement this interface instead of MLbsPrivacyObserver if it requires notification that LBS is shutting down.

Usage

MLbsPrivacyObserver2::ProcessCloseDownNotification() is called by the LBS subsystem root process to shutdown a licensee Privacy Controller when the LBS subsystem is in the Standalone Privacy Mode configuration.

TLbsExternalRequestInfo

Purpose

TLbsExternalRequestInfo is the class that LBS subsystem uses to pass request information to a licensee Privacy Controller.

This class is not strictly part of the Privacy Controller API. It is defined in lbsloccommon.h and is also used by Privacy Notifiers and by LBS internally. A Privacy Controller uses it to obtain information about the agent that sent the privacy request.

Usage

A TLbsExternalRequestInfo object reference is passed as a parameter from the LBS subsystem to the Privacy Controller in a call to MLbsPrivacyObserver::ProcessNetworkLocationRequest().

TLbsExternalRequestInfo contains buffers that contain the client name, the requester ID and the external requester ID as specified in 3GPP LBS specifications. This information is accessed via the following methods:

• TLbsExternalRequestInfo::GetRequesterId() gets the ID of the requester.

• TLbsExternalRequestInfo::GetClientName() gets the name of the client.

• TLbsExternalRequestInfo::GetClientExternalId() gets the client external ID.

A Privacy Controller can use other methods of TLbsExternalRequestInfo to get information about the format of the data and the encoding of the requester ID and the client name descriptors:

• TLbsExternalRequestInfo::RequesterIdFormat() returns a TLbsExternalRequestInfo::TFormatIndicator (a value from the enumeration TLbsExternalRequestInfo::_TFormatIndicator). This specifies the format of the data that TLbsExternalRequestInfo::GetRequesterId() returns (such as a MSISDN, URL, email address etc.)

• TLbsExternalRequestInfo::ClientNameFormat() returns a TFormatIndicator which describes the format of the data that TLbsExternalRequestInfo::GetClientName() returns.

• TLbsExternalRequestInfo::RequesterIdCodingScheme() returns a TLbsExternalRequestInfo::TCodingScheme (a value from the enumeration TLbsExternalRequestInfo::_TCodingScheme). This specifies the encoding of the data that TLbsExternalRequestInfo::GetRequesterId() returns (such as UCS-2, UTF-8 or GSM 7 bit).

• TLbsExternalRequestInfo::ClientNameCodingScheme() returns a TCodingScheme that specifies the encoding of the data that TLbsExternalRequestInfo::GetClientName() returns.

TLbsExternalRequestInfo::NetworkType() returns a TLbsExternalRequestInfo::TNetworkType (a value from the enumeration TLbsExternalRequestInfo::_TNetworkType). This specifies the type of network from which the privacy request was received (GSM, SUPL or WCDMA).

TLbsExternalRequestInfo::RequestSource() returns a TLbsExternalRequestInfo::TRequestSource (a value from the enumeration TLbsExternalRequestInfo::_TRequestSource). This specifies the source of the privacy request (a local application or the network). This value is checked by LBS when it is configured in the Standalone Privacy Mode, but is not checked in the Full LBS mode. A Privacy Request API client must set this value on the TLbsExternalRequestInfo object it passes across the API. It is used for policing client capabilities. See How to use the Privacy Request API for more information.

TLbsExternalRequestInfo::RequestType() returns a TLbsExternalRequestInfo::TRequestType (a value from the enumeration TLbsExternalRequestInfo::_TRequestType). This specifies the type of request (single shot, periodic or area event). These values are not implemented and are reserved for future use.

Note that the TLbsExternalRequestInfo setter functions are for use in licensee Network Protocol Module implementations and not by Privacy Controllers (which only need to read data from a TLbsExternalRequestInfo object).

TLbsExternalRequestInfo2

Purpose

TLbsExternalRequestInfo2 is an extended request info class that derives from TLbsExternalRequestInfo.

A Privacy Controller only needs to use this class if large buffers are used to pass data across the Network Privacy API. In other circumstances, the Privacy Controller need only use the TLbsExternalRequestInfo class.

The maximum buffer sizes for TLbsPrivacyRequestInfo are defined as KLbsMaxRequesterIdSize, KLbsMaxClientNameSize and KLbsMaxClientExternalIdSize in lbsprivacycontroller.h.

TLbsPrivacyRequestInfo2 defines additional buffers for holding requester data when a licensee wants to use larger buffers for requester ID and the client name. The maximum buffer sizes for TLbsExternalRequestInfo2 are defined as KLbsMaxRequesterIdSize2 and KLbsMaxClientNameSize2 in lbsprivacycontroller.h.

Usage

A Privacy Controller is always passed a TLbsExternalRequestInfo reference when the LBS subsystem calls MLbsPrivacyObserver::ProcessNetworkLocationRequest(). However this reference may be to a derived TLbsExternalRequestInfo2 object. The following cases should be considered:

1. LBS is being used in the Full LBS configuration.

   The Privacy Controller can use the TLbsExternalRequestInfo reference parameter directly without casting it.

2. LBS is being used in the Standalone Privacy Mode configuration (the Network Privacy API is used to send privacy requests into the LBS subsystem):

   • If buffers no larger than KLbsMaxRequesterIdSize and KLbsMaxClientNameSize are used by the licensee across the Network Privacy API then the Privacy Controller can use the TLbsExternalRequestInfo reference parameter directly without casting it.

   • If larger buffers up to KLbsMaxRequesterIdSize2 and KLbsMaxClientNameSize2 in size are used across the Network Privacy API then the Privacy Controller must cast the TLbsExternalRequestInfo reference parameter to derived class TLbsExternalRequestInfo2 before using it. Failure to cast to the derived class may result in truncated data being returned from the accessor functions TLbsExternalRequestInfo::GetClientName() and TLbsExternalRequestInfo::GetRequesterId().

How to use the LBS Privacy Controller API gives an example of how to use TLbsExternalRequestInfo and TLbsExternalRequestInfo2.

Sequence Diagrams

This section describes the main use cases for the Privacy Controller API. A set of sequence diagrams explain the behaviour of the API.

Note that these use cases and sequences only document Privacy Controller behaviour with the Full LBS configuration (in which the LBS subsystem handles both privacy requests and location calculations).

For sequences that describe the behaviour of a Privacy Controller with the Network Privacy API in the Standalone Privacy Mode configuration see the Network Privacy API documentation.

The following are the main use cases involving a Privacy Controller and the LBS subsystem:

• Privacy verification request

  A non-emergency MT-LR is received from the network and causes a privacy verification request to be sent to the registered Privacy Controller by the LBS subsystem.

• Privacy notification request

  An emergency services MT-LR is received from the network and causes a privacy notification request to be sent to the registered Privacy Controller by the LBS subsystem.

• Privacy verification request is cancelled

  The network can send a message to cancel an outstanding privacy request.

Sequence Diagrams

These sequence diagrams describe the interaction of a Privacy Controller with the LBS subsystem in the Full LBS configuration. See Network Privacy API documentation for sequences that describe Privacy Controller interaction with the Network Privacy API.

Privacy verification request (request accepted, rejected or timeout)

Figure 4.1 shows the case when a privacy request is received from the network. The Privacy Controller can respond by either accepting or rejecting the request, or by not responding at all, in which case the LBS subsystem times out the privacy request.

Privacy notification request

Figure 4.2 shows the case when the Privacy Controller receives a privacy notification request. The Privacy Controller is notified of the request and can also receive notification of position calculation updates.

Privacy verification request is cancelled

Figure 4.3 shows the case when a privacy verification request is cancelled.