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
The Privacy Q&N API depends on the
See
Figure 1 shows the Privacy Q&N API and related LBS subsystem components in the
This section describes the classes of the LBS Privacy Q&N Notification API.
Privacy Query and Notification API class diagram
Figure 2 shows the
The Privacy Query and Notification API uses the Symbian
Privacy Data Types classes and types
The implementation UID that should be used for licensee Privacy Q&N Notifiers is
The Privacy Query and Notification API classes and types have
Libraries
Capabilities
As for all notifiers that use the Extended Notifier Framework, the licensee notifier ECom plug-in must be built with
LBS Configuration
The LBS Administration setting
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
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
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
CPosPrivacyNotifier
Purpose
Note that a licensee should create one single derived notifier class to handle both privacy verification requests and privacy notification requests.
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:
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
Implementing the virtual event methods
The following are the pure virtual event methods defined in
This method is called when a new privacy request is sent from the LBS subsystem to the notifier. It takes a
This method is called by the LBS subsystem to cancel a specified outstanding request. The method takes a
When this method is called the Privacy Q&N Notifier can check the reason why the request was cancelled by calling
This method is called by the LBS subsystem to cancel all outstanding requests.
See
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.
This method returns an
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
A licensee notifier should call this method in its implementation of
This method can be used to check the reason why a request was cancelled. This method can be called while one of the methods
The return value is of type
This method must be called first in the
This method returns a list of all of the outstanding privacy verification requests (query requests) and notification requests.
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
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
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,
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,
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
The notifier can find out the source by calling this method. The request source enumeration
If a request source is not defined,
Note that
This method returns whether the privacy request was accepted or rejected.
This information is mainly used in notification requests. The request decision enumeration
For privacy verification queries, this method returns
If the request decision is unknown in a notification request,
For notification requests, this method returns the reason for notification, for example the request verification timed out.
The notification reason enumeration
Note that the notification reason enumeration
If the notification reason is unknown by the notifier, the notification request should be completed with the error code
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
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.
This method reads information about a requester from the request that is set as current by
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
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:
For notification requests, the following completion codes should be noted:
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
The Privacy Q&N API depends on the
See
Figure 1 shows the Privacy Q&N API and related LBS subsystem components in the
This section describes the classes of the LBS Privacy Q&N Notification API.
Privacy Query and Notification API class diagram
Figure 2 shows the
The Privacy Query and Notification API uses the Symbian
Privacy Data Types classes and types
The implementation UID that should be used for licensee Privacy Q&N Notifiers is
The Privacy Query and Notification API classes and types have
Libraries
Capabilities
As for all notifiers that use the Extended Notifier Framework, the licensee notifier ECom plug-in must be built with
LBS Configuration
The LBS Administration setting
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
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
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
CPosPrivacyNotifier
Purpose
Note that a licensee should create one single derived notifier class to handle both privacy verification requests and privacy notification requests.
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:
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
Implementing the virtual event methods
The following are the pure virtual event methods defined in
This method is called when a new privacy request is sent from the LBS subsystem to the notifier. It takes a
This method is called by the LBS subsystem to cancel a specified outstanding request. The method takes a
When this method is called the Privacy Q&N Notifier can check the reason why the request was cancelled by calling
This method is called by the LBS subsystem to cancel all outstanding requests.
See
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.
This method returns an
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
A licensee notifier should call this method in its implementation of
This method can be used to check the reason why a request was cancelled. This method can be called while one of the methods
The return value is of type
This method must be called first in the
This method returns a list of all of the outstanding privacy verification requests (query requests) and notification requests.
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
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
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,
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,
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
The notifier can find out the source by calling this method. The request source enumeration
If a request source is not defined,
Note that
This method returns whether the privacy request was accepted or rejected.
This information is mainly used in notification requests. The request decision enumeration
For privacy verification queries, this method returns
If the request decision is unknown in a notification request,
For notification requests, this method returns the reason for notification, for example the request verification timed out.
The notification reason enumeration
Note that the notification reason enumeration
If the notification reason is unknown by the notifier, the notification request should be completed with the error code
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
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.
This method reads information about a requester from the request that is set as current by
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
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:
For notification requests, the following completion codes should be noted: