Privacy Query and Notification Notifiers

Purpose

This document describes Privacy Query and Notification (Q&N) Notifiers and the Privacy Query and Notification API: a framework API that licensees can use to create a notifier for LBS privacy requests.

Note that the Privacy Query and Notification API is deprecated. It is documented here as it is now part of the Symbian platform LBS subsystem (it was formerly part of the S60 Privacy Framework). It is supported in Symbian LBS in order to allow licensees who have previously created Privacy Q&N Notifiers for the S60 Privacy Framework to continue to use them with the Symbian LBS subsystem.

Licensees who are developing new notifiers for LBS are encouraged to use the Symbian LBS Privacy Notifiers.

The Privacy Q&N API depends on the Extended Notifier Framework and on the Privacy Data Types to pass data between the notifiers and the LBS subsystem.

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

Contents

• Introduction

• API description

  • CPosPrivacyNotifier

• See also

Introduction

Figure 1 shows the Privacy Q&N API and related LBS subsystem components in the Full LBS configuration.

API description

This section describes the classes of the LBS Privacy Q&N Notification API.

Privacy Query and Notification API class diagram

Figure 2 shows the CPosPrivacyNotifier class of the Privacy Q&N Notifiers API. This is the only class defined in the API and is the base class for a Privacy Q&N Notifier implementation. CPosPrivacyNotifier contains virtual methods that must be implemented by a notifier implementation in order to receive notifications of privacy requests. Figure 2 also shows the enumerated types from the Privacy Data Types that are used to pass data between the LBS subsystem and a Privacy Q&N Notifier.

The Privacy Query and Notification API uses the Symbian Extended Notifier Framework. A notifier implementation must be wrapped in an ECOM plug-in class that contains a factory method to register the notifier with the framework. An MEikSrvNotifierBase2 interface can be obtained from CPosPrivacyNotifier that allows the notifier to be registered. This is explained in more detail in How to use the Privacy Query and Notification API.

Privacy Data Types classes and types

CPosPrivacyNotifier is the only class of the API and is the base class of Privacy Q&N Notifiers. It is defined in EPos_CPosPrivacyNotifier.h.

The implementation UID that should be used for licensee Privacy Q&N Notifiers is KPosPrivacyNotifierImplUid and is defined in EPos_PrivacyNotifier.hrh.

The Privacy Query and Notification API classes and types have publishedPartner interface access.

Libraries

CPosPrivacyNotifier is packaged in eposprvqnif.dll. A Privacy Q&N Notifier links to eposprvqnif.lib. It must also link to eposprvtyp.lib to use the Privacy Data Types on which the Privacy Q&N API depends.

Capabilities

As for all notifiers that use the Extended Notifier Framework, the licensee notifier ECom plug-in must be built with TrustedUI and ProtServ capabilities. The capabilities are specified in the plug-in's MMP file. See How to use the Privacy Query and Notification API for more details.

LBS Configuration

The LBS Administration setting KLbsSettingPrivacyHandler must be set to CLbsAdmin::EPrivacyHandleByAdvancedNotifier to configure LBS to use Privacy Q&N Notifiers. 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.

Sequential processing of privacy requests

The LBS subsystem sends privacy requests sequentially to Privacy Notifiers. If multiple privacy requests are received how they are handled depends on the interface via which the privacy request was received:

• Request received from a Network Protocol Module

  A second privacy request forces LBS to cancel an outstanding privacy request (but not emergency requests). The Privacy Notifier in use for the first privacy request is cancelled. The Privacy Notifier is then restarted to handle the second privacy request.

• Request received via the Network Privacy API or the Privacy Request API

  Privacy notification and verification requests are sent sequentially to Privacy Notifiers. A Privacy Notifier must have responded to one privacy request (or LBS must have sent a timeout response) before the next request can be sent to the notifier. The maximum number of privacy requests that can be outstanding in the LBS subsystem is defined by the LBS administration setting KLbsSettingMaximumExternalLocateRequests. Further requests are rejected by the LBS subsystem if the number of outstanding privacy requests exceeds KLbsSettingMaximumExternalLocateRequests.

CPosPrivacyNotifier

Purpose

CPosPrivacyNotifier is the base class for a Privacy Q&N Notifier. It defines the interface between the LBS subsystem and a Privacy Q&N Notifier. A licensee Privacy Q&N Notifier must derive from this class.

Note that a licensee should create one single derived notifier class to handle both privacy verification requests and privacy notification requests.

CPosPrivacyNotifier defines two types of methods:

1. Pure virtual event methods that must be implemented by the Privacy Q&N Notifier implementation in order to receive information from the LBS subsystem about privacy requests:

   • CPosPrivacyNotifier::HandleNewRequestL()

   • CPosPrivacyNotifier::HandleRequestCancelledL()

   • CPosPrivacyNotifier::HandleAllRequestsCancelled()

2. Methods for obtaining information about a request and for responding to it.

Usage

A licensee creates a single Privacy Q&N Notifier class that derives from CPosPrivacyNotifier to handle both privacy verification requests and privacy notification requests.

Implementing the virtual event methods

The following are the pure virtual event methods defined in CPosPrivacyNotifier that a licensee notifier must implement. Links can be followed to API reference documentation for full descriptions of method parameters and return types.

• CPosPrivacyNotifier::HandleNewRequestL()

  This method is called when a new privacy request is sent from the LBS subsystem to the notifier. It takes a TPosQNRequestId parameter that specifies the unique ID for the request. The ID can be used to identify the request in other method calls, such as to cancel the request at some later time.

• CPosPrivacyNotifier::HandleRequestCancelled()

  This method is called by the LBS subsystem to cancel a specified outstanding request. The method takes a TPosQNRequestId parameter that specifies the ID of the request to be cancelled. It is not necessary to call CPosPrivacyNotifier::CompleteRequest() for a request that was cancelled by calling this method.

  When this method is called the Privacy Q&N Notifier can check the reason why the request was cancelled by calling CPosPrivacyNotifier::CancelReason().

• CPosPrivacyNotifier::HandleAllRequestsCancelled()

  This method is called by the LBS subsystem to cancel all outstanding requests.

See How to use the Privacy Query and Notification API for examples of how to implement these methods.

Other methods

The following is a list of the other (non pure virtual) methods defined by the Privacy Query and Notification API. Links can be followed to API reference documentation for full descriptions of the method parameters and return types.

• CPosPrivacyNotifier::NotifierBase()

  This method returns an MEikSrvNotifierBase2 pointer. When a developer writes the notifier ECom plug-in wrapper class factory method, this method should be called to return an MEikSrvNotifierBase2 pointer.

• CPosPrivacyNotifier::CheckClientSecureId()

  This method should be used in a notifier implementation to check the SID of the client process that is making the request. The method takes a TSecureId parameter and compares it to the TSecureId of the process that is making the request. It returns true if the two are the same.

  A licensee notifier should call this method in its implementation of CPosPrivacyNotifier::HandleNewRequestL() as a validation check. The SID of the LBS Network Request Handler process that sends requests to the notifier is 0x10281D45.

• CPosPrivacyNotifier::CancelReason()

  This method can be used to check the reason why a request was cancelled. This method can be called while one of the methods CPosPrivacyNotifier::HandleRequestCancelled() or CPosPrivacyNotifier::HandleAllRequestsComplete() is running.

  The return value is of type TPosVerifyCancelReason and specifies the reason why a request was cancelled. An unknown value should be treated as EPosCancelReasonNotAvailable.

• CPosPrivacyNotifier::BaseConstructL()

  This method must be called first in the ConstructL() of the licensee notifier implementation. The method takes a channel UID and a priority as parameters which are used by the Extended Notifier Framework.

• CPosPrivacyNotifier::GetRequestsL()

  This method returns a list of all of the outstanding privacy verification requests (query requests) and notification requests.

• CPosPrivacyNotifier::RequestTypeL()

  This method is called to find out whether a request is a privacy verification request (a query request) or a notification request. If a privacy request with the specified ID does not exist, the method leaves with the error code KErrNotFound.

• CPosPrivacyNotifier::SetCurrentRequestL()

  The current request is the request that is currently being handled.

  In order to read detailed information (the requesters) about a request, it must be set as current.This is achieved by calling this method. If a request with the specified ID does not exist, the method leaves with the error code KErrNotFound.

• CPosPrivacyNotifier::CurrentRequest()

  This method gets the request that is set as current. If no request is set as current, or if the current request has been completed, KPosNullQNRequestId is returned.

• CPosPrivacyNotifier::QueryTimeoutStrategy()

  For a privacy verification request, a timeout strategy may be provided. The timeout strategy specifies whether the location request will be accepted or rejected if the privacy request times out. If no timeout strategy is provided, EPosDecisionNotAvailable will be returned.

  Note that a timeout strategy is only available for privacy queries, never for notifications. If this method is called for a notification, it will always return EPosDecisionNotAvailable.

• CPosPrivacyNotifier::RequestSource()

  The notifier can find out the source by calling this method. The request source enumeration TPosRequestSource is defined by the Privacy Data Types.

  If a request source is not defined, EPosRequestSourceNotAvailable is be returned.

  Note that TPosRequestSource may be extended in the future. Therefore, any unknown value must be treated as EPosRequestSourceNotAvailable.

• CPosPrivacyNotifier::LocationRequestDecision()

  This method returns whether the privacy request was accepted or rejected.

  This information is mainly used in notification requests. The request decision enumeration TPosRequestDecision is defined by the Privacy Data Types.

  For privacy verification queries, this method returns EPosDecisionNotAvailable.

  If the request decision is unknown in a notification request, EPosDecisionNotAvailable is returned.

• CPosPrivacyNotifier::NotificationReason()

  For notification requests, this method returns the reason for notification, for example the request verification timed out.

  The notification reason enumeration TPosNotificationReason is defined by the Privacy Data Types. If the reason for the notification request is not provided, this method returns EPosNotificationReasonNotAvailable.

  Note that the notification reason enumeration TPosNotificationReason may be extended in the future. Therefore, any unknown value must be treated as EPosNotificationReasonNotAvailable.

  If the notification reason is unknown by the notifier, the notification request should be completed with the error code KErrNotSupported, i.e. CompleteRequest(KErrNotSupported) should be called.

• CPosPrivacyNotifier::RequestorCountL()

  This method returns the number of requesters in the current request. A requester is a contact or service, which is the originator or a proxy for the position request. If no request is set as current, or if the current request has been completed, this method leaves with the error code KErrNotFound.

  Note that the requester count can be zero if there is no requestor information available. In this case, the notifier should consider showing an alternative message.

• CPosPrivacyNotifier::RequestorLC()

  This method reads information about a requester from the request that is set as current by CPosPrivacyNotifier::SetCurrentRequestL().

  The notifier specifies which requestor to read by index. The index must be a number between 0 and RequestorCountL() – 1. If an invalid index is passed to this method, it leaves with the error code KErrArgument. If no request is set as current, or if the current request has been completed, this method leaves with the error code KErrNotFound.

• CPosPrivacyNotifier::CompleteRequest()

  The Privacy UI must call this method when a request has been handled. The ID of the privacy request to complete and the completion code are passed as input parameters. If there is no outstanding privacy request with the specified ID, the call is ignored. The completion code can be any system wide error code.

  A few completion codes have specific meanings. For query requests, the following completion codes should be noted:

  • KErrNone if the phone user accepts the query.

  • KErrAccessDenied if the phone user rejects the query.

  • KErrTimedOut if the query times out. The notifier should use a timer and abort it if the phone user does not respond to the dialog.

  For notification requests, the following completion codes should be noted:

  • KErrNone if the phone user dismisses the dialog.

  • KErrTimedOut if the notification request times out. The notifier should implement a timeout if the phone user does not respond to the dialog.

  • KErrNotSupported if the notification reason is not known by the Privacy UI.