Week 28 contribution of PDK documentation content. See release notes for details. Fixes bugs Bug 1897, Bug 344, Bug 2681, Bug 463, Bug 1522.
<?xml version="1.0" encoding="utf-8"?>
<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->
<!-- This component and the accompanying materials are made available under the terms of the License
"Eclipse Public License v1.0" which accompanies this distribution,
and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->
<!-- Initial Contributors:
Nokia Corporation - initial contribution.
Contributors:
-->
<!DOCTYPE concept
PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<concept xml:lang="en" id="GUID-8226320F-2F3A-575F-9950-B98C67472DAD"><title>Privacy Query and Notification Notifiers</title><prolog><metadata><keywords/></metadata></prolog><conbody><section><title>Purpose</title> <p> 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. </p> <p> <i>Note that the Privacy Query and Notification API is deprecated</i>. 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. </p> <p>Licensees who are developing new notifiers for LBS are encouraged to use the Symbian <xref href="GUID-F8C5A22F-8433-5F50-B12A-E964572E6C23.dita#GUID-F8C5A22F-8433-5F50-B12A-E964572E6C23/GUID-DC80984B-7B46-5C2D-A1EF-EDBB0983159D">LBS Privacy Notifiers</xref>. </p> <p>The Privacy Q&N API depends on the <xref href="GUID-E049772D-A96F-592F-AF59-C9B69E8D24C1-GENID-1-12-1-4-1-1-4-1-4-1.dita">Extended Notifier Framework</xref> and on the <xref href="GUID-3170E641-E3A9-58D5-82B9-391A2F5AC140.dita#GUID-3170E641-E3A9-58D5-82B9-391A2F5AC140/GUID-86A9DF94-B242-51D5-924A-68A0D526078B">Privacy Data Types</xref> to pass data between the notifiers and the LBS subsystem. </p> <p>See <xref href="GUID-2E565B8E-D262-5769-96E6-A532154D57E6.dita">Privacy Requests Overview</xref> for an explanation of privacy request concepts. </p> </section> <section><title>Contents</title> <ul><li id="GUID-2E6265D0-FD64-5CF2-A2FE-4508A7781F5B"><p><xref href="GUID-8226320F-2F3A-575F-9950-B98C67472DAD.dita#GUID-8226320F-2F3A-575F-9950-B98C67472DAD/GUID-C05316EE-C228-5CEC-B940-8EEAFDA578B1">Introduction</xref> </p> </li> <li id="GUID-CE1623CD-ED32-5D93-88B7-09B4CC2266D5"><p><xref href="GUID-8226320F-2F3A-575F-9950-B98C67472DAD.dita#GUID-8226320F-2F3A-575F-9950-B98C67472DAD/GUID-ACB911D4-077C-55B4-914E-D34E4CC4E274">API description</xref> </p> <ul><li id="GUID-CF471AD6-487E-5ECD-8E8B-BCB2457009B1"><p><xref href="GUID-8226320F-2F3A-575F-9950-B98C67472DAD.dita#GUID-8226320F-2F3A-575F-9950-B98C67472DAD/GUID-615C9AEE-8B20-54F7-90A9-D6F8AD0B99A4">CPosPrivacyNotifier</xref> </p> </li> </ul> </li> <li id="GUID-A12481B5-516C-5A21-9846-68B9B97FC7CA"><p><xref href="GUID-8226320F-2F3A-575F-9950-B98C67472DAD.dita#GUID-8226320F-2F3A-575F-9950-B98C67472DAD/GUID-5F8226BA-9918-52A9-97B9-6186F197A8AD">See also</xref> </p> </li> </ul> </section> <section id="GUID-C05316EE-C228-5CEC-B940-8EEAFDA578B1"><title>Introduction</title> <p>Figure 1 shows the Privacy Q&N API and related LBS subsystem components in the <xref href="GUID-A898867E-0C50-583E-979F-132504C24C9A.dita">Full LBS configuration</xref>. </p> <fig id="GUID-71DEA395-E082-5CD2-9C88-B9FC94C023BB"><title>
Figure 1. The Privacy Q&N Notifier API and related LBS subsystem
components.
</title> <image href="GUID-6EAC30BC-B8F6-5007-A672-DF1D4895599F_d0e436682_href.png" placement="inline"/></fig> </section> <section id="GUID-ACB911D4-077C-55B4-914E-D34E4CC4E274"><title>API description</title> <p>This section describes the classes of the LBS Privacy Q&N Notification API. </p> <p><b>Privacy Query and Notification API class diagram </b> </p> <p>Figure 2 shows the <xref href="GUID-56C8D5AB-7D9A-3B20-B699-07F17A87A61C.dita"><apiname>CPosPrivacyNotifier</apiname></xref> 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. <codeph>CPosPrivacyNotifier</codeph> 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 <xref href="GUID-3170E641-E3A9-58D5-82B9-391A2F5AC140.dita#GUID-3170E641-E3A9-58D5-82B9-391A2F5AC140/GUID-86A9DF94-B242-51D5-924A-68A0D526078B">Privacy Data Types</xref> that are used to pass data between the LBS subsystem and a Privacy Q&N Notifier. </p> <p>The Privacy Query and Notification API uses the Symbian <xref href="GUID-E049772D-A96F-592F-AF59-C9B69E8D24C1-GENID-1-12-1-4-1-1-4-1-4-1.dita">Extended Notifier Framework</xref>. 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 <xref href="GUID-DE445C4B-22EF-3A1F-8A69-57CB703BFAD0.dita"><apiname>MEikSrvNotifierBase2</apiname></xref> interface can be obtained from <codeph>CPosPrivacyNotifier</codeph> that allows the notifier to be registered. This is explained in more detail in <xref href="GUID-D4AB2D70-D49E-5F59-80F6-3D90F1D76BD5.dita#GUID-D4AB2D70-D49E-5F59-80F6-3D90F1D76BD5/GUID-AEE162B1-706D-56E6-9703-D54D1CC29F35">How to use the Privacy Query and Notification API.</xref> </p> <fig id="GUID-1E30EE82-3504-54D2-925D-DCFAD55333D8"><title>
Figure 2. Classes and types of the Privacy Q&N Notifiers.
</title> <image href="GUID-CB82C5D5-5714-5F31-A24F-E2259E6E9BD6_d0e436730_href.png" placement="inline"/></fig> <p><b>Privacy Data Types classes and types </b> </p> <p> <xref href="GUID-56C8D5AB-7D9A-3B20-B699-07F17A87A61C.dita"><apiname>CPosPrivacyNotifier</apiname></xref> is the only class of the API and is the base class of Privacy Q&N Notifiers. It is defined in <filepath>EPos_CPosPrivacyNotifier.h</filepath>. </p> <p>The implementation UID that should be used for licensee Privacy Q&N Notifiers is <codeph>KPosPrivacyNotifierImplUid</codeph> and is defined in <filepath>EPos_PrivacyNotifier.hrh</filepath>. </p> <p>The Privacy Query and Notification API classes and types have <codeph>publishedPartner</codeph> interface access. </p> <p><b>Libraries </b> </p> <p> <xref href="GUID-56C8D5AB-7D9A-3B20-B699-07F17A87A61C.dita"><apiname>CPosPrivacyNotifier</apiname></xref> is packaged in <filepath>eposprvqnif.dll</filepath>. A Privacy Q&N Notifier links to <filepath>eposprvqnif.lib</filepath>. It must also link to <filepath>eposprvtyp.lib</filepath> to use the <xref href="GUID-3170E641-E3A9-58D5-82B9-391A2F5AC140.dita#GUID-3170E641-E3A9-58D5-82B9-391A2F5AC140/GUID-86A9DF94-B242-51D5-924A-68A0D526078B">Privacy Data Types</xref> on which the Privacy Q&N API depends. </p> <p><b>Capabilities </b> </p> <p>As for all notifiers that use the Extended Notifier Framework, the licensee notifier ECom plug-in must be built with <codeph>TrustedUI</codeph> and <codeph>ProtServ</codeph> capabilities. The capabilities are specified in the plug-in's MMP file. See <xref href="GUID-D4AB2D70-D49E-5F59-80F6-3D90F1D76BD5.dita#GUID-D4AB2D70-D49E-5F59-80F6-3D90F1D76BD5/GUID-AEE162B1-706D-56E6-9703-D54D1CC29F35">How to use the Privacy Query and Notification API</xref> for more details. </p> <p><b>LBS Configuration </b> </p> <p>The LBS Administration setting <codeph>KLbsSettingPrivacyHandler</codeph> must be set to <codeph>CLbsAdmin::EPrivacyHandleByAdvancedNotifier</codeph> to configure LBS to use Privacy Q&N Notifiers. See <xref href="GUID-23BBC1D8-B3A0-5148-A4F1-22ECF3043E4E.dita">LBS Administration</xref> for details of how to configure this setting either through the LBS Administration API or in the LBS central repository initialisation file. </p> <p> <b>Sequential processing of privacy requests</b> </p> <p>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: </p> <ul><li id="GUID-4B682EA4-4D4E-5DE1-B39C-EC29879A9D90"><p>Request received from a <xref href="GUID-CB6B4D1A-ACB9-5571-8C23-4BC095209782.dita">Network Protocol Module</xref> </p> <p>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. </p> </li> <li id="GUID-06FEFD8F-1639-535B-933C-D0CEB0A2A009"><p>Request received via the <xref href="GUID-B3000A78-3BE5-5E0A-A718-87BC9BA03726.dita">Network Privacy API</xref> or the <xref href="GUID-E1710E40-B8F5-5CF8-B9FE-698869A1770F.dita">Privacy Request API</xref> </p> <p>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 <codeph>KLbsSettingMaximumExternalLocateRequests</codeph>. Further requests are rejected by the LBS subsystem if the number of outstanding privacy requests exceeds <codeph>KLbsSettingMaximumExternalLocateRequests</codeph>. </p> </li> </ul> <p id="GUID-615C9AEE-8B20-54F7-90A9-D6F8AD0B99A4"><b>CPosPrivacyNotifier</b> </p> <p><b>Purpose </b> </p> <p> <xref href="GUID-56C8D5AB-7D9A-3B20-B699-07F17A87A61C.dita"><apiname>CPosPrivacyNotifier</apiname></xref> 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. </p> <p> <b>Note that a licensee should create one single derived notifier class to handle both privacy verification requests and privacy notification requests.</b> <codeph/> </p> <p> <codeph>CPosPrivacyNotifier</codeph> defines two types of methods: </p> <ol id="GUID-2C60765F-6317-5CB5-8CE9-EDBC9FA55FD0"><li id="GUID-94A892D7-FB2B-504A-A838-61C19BD2F7CB"><p>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: </p> <ul><li id="GUID-0B38A251-9F94-5A1C-BA89-681B2207721A"><p> <codeph>CPosPrivacyNotifier::HandleNewRequestL()</codeph> </p> </li> <li id="GUID-594DC6CA-CB9C-5440-9E53-4FF82CC6B639"><p> <codeph>CPosPrivacyNotifier::HandleRequestCancelledL()</codeph> </p> </li> <li id="GUID-F71DCD70-6FF4-543C-8827-46DDD7D4A3E0"><p> <codeph>CPosPrivacyNotifier::HandleAllRequestsCancelled()</codeph> </p> </li> </ul> </li> <li id="GUID-E4B9B5C1-A85A-514A-BBF1-E8FFE778E06A"><p>Methods for obtaining information about a request and for responding to it. </p> </li> </ol> <p><b>Usage </b> </p> <p>A licensee creates a single Privacy Q&N Notifier class that derives from <xref href="GUID-56C8D5AB-7D9A-3B20-B699-07F17A87A61C.dita"><apiname>CPosPrivacyNotifier</apiname></xref> to handle both privacy verification requests and privacy notification requests. </p> <p><b>Implementing the virtual event methods </b> </p> <p>The following are the pure virtual event methods defined in <xref href="GUID-56C8D5AB-7D9A-3B20-B699-07F17A87A61C.dita"><apiname>CPosPrivacyNotifier</apiname></xref> that a licensee notifier must implement. Links can be followed to API reference documentation for full descriptions of method parameters and return types. </p> <ul><li id="GUID-CBDBB056-DE90-58D4-A194-DD3B9BC8BFCC"><p> <xref href="GUID-56C8D5AB-7D9A-3B20-B699-07F17A87A61C.dita#GUID-56C8D5AB-7D9A-3B20-B699-07F17A87A61C/GUID-33E317F9-A8C0-34AF-B17A-72D46B2E4DBD"><apiname>CPosPrivacyNotifier::HandleNewRequestL()</apiname></xref> </p> <p>This method is called when a new privacy request is sent from the LBS subsystem to the notifier. It takes a <codeph>TPosQNRequestId</codeph> 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. </p> </li> <li id="GUID-81FF507E-105B-54E9-BC45-EF8F9F4D01E5"><p> <xref href="GUID-56C8D5AB-7D9A-3B20-B699-07F17A87A61C.dita#GUID-56C8D5AB-7D9A-3B20-B699-07F17A87A61C/GUID-3417B07B-DE69-3719-8634-B979CBA77AFE"><apiname>CPosPrivacyNotifier::HandleRequestCancelled()</apiname></xref> </p> <p>This method is called by the LBS subsystem to cancel a specified outstanding request. The method takes a <codeph>TPosQNRequestId</codeph> parameter that specifies the ID of the request to be cancelled. It is not necessary to call <xref href="GUID-56C8D5AB-7D9A-3B20-B699-07F17A87A61C.dita#GUID-56C8D5AB-7D9A-3B20-B699-07F17A87A61C/GUID-57739A9E-F6CD-3079-8B6F-9B80AAFE4D8B"><apiname>CPosPrivacyNotifier::CompleteRequest()</apiname></xref> for a request that was cancelled by calling this method. </p> <p>When this method is called the Privacy Q&N Notifier can check the reason why the request was cancelled by calling <xref href="GUID-56C8D5AB-7D9A-3B20-B699-07F17A87A61C.dita#GUID-56C8D5AB-7D9A-3B20-B699-07F17A87A61C/GUID-54EB2437-9070-376D-8FCD-C1D4758113E6"><apiname>CPosPrivacyNotifier::CancelReason()</apiname></xref>. </p> </li> <li id="GUID-5632A47C-8574-5144-A5D2-4962C12482A9"><p> <codeph>CPosPrivacyNotifier::HandleAllRequestsCancelled()</codeph> </p> <p>This method is called by the LBS subsystem to cancel all outstanding requests. </p> </li> </ul> <p>See <xref href="GUID-D4AB2D70-D49E-5F59-80F6-3D90F1D76BD5.dita#GUID-D4AB2D70-D49E-5F59-80F6-3D90F1D76BD5/GUID-AEE162B1-706D-56E6-9703-D54D1CC29F35">How to use the Privacy Query and Notification API</xref> for examples of how to implement these methods. </p> <p><b>Other methods </b> </p> <p>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. </p> <ul><li id="GUID-7F25BF0F-CC1C-5092-975A-B0CB1F443214"><p> <xref href="GUID-56C8D5AB-7D9A-3B20-B699-07F17A87A61C.dita#GUID-56C8D5AB-7D9A-3B20-B699-07F17A87A61C/GUID-5E946C2A-0AC5-3B37-B1D7-06C73C934F48"><apiname>CPosPrivacyNotifier::NotifierBase()</apiname></xref> </p> <p>This method returns an <xref href="GUID-DE445C4B-22EF-3A1F-8A69-57CB703BFAD0.dita"><apiname>MEikSrvNotifierBase2</apiname></xref> pointer. When a developer writes the notifier ECom plug-in wrapper class factory method, this method should be called to return an <codeph>MEikSrvNotifierBase2</codeph> pointer. </p> </li> <li id="GUID-296C9712-978D-5084-943D-3DA1F1F7EEB1"><p> <xref href="GUID-56C8D5AB-7D9A-3B20-B699-07F17A87A61C.dita#GUID-56C8D5AB-7D9A-3B20-B699-07F17A87A61C/GUID-BB214179-0B04-33CB-82CD-AAEABE36DAA1"><apiname>CPosPrivacyNotifier::CheckClientSecureId()</apiname></xref> </p> <p>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 <xref href="GUID-E924490C-D174-3CE8-98BB-85A1D10BC90B.dita"><apiname>TSecureId</apiname></xref> parameter and compares it to the <codeph>TSecureId</codeph> of the process that is making the request. It returns true if the two are the same. </p> <p>A licensee notifier should call this method in its implementation of <xref href="GUID-56C8D5AB-7D9A-3B20-B699-07F17A87A61C.dita#GUID-56C8D5AB-7D9A-3B20-B699-07F17A87A61C/GUID-33E317F9-A8C0-34AF-B17A-72D46B2E4DBD"><apiname>CPosPrivacyNotifier::HandleNewRequestL()</apiname></xref> as a validation check. The SID of the LBS Network Request Handler process that sends requests to the notifier is <codeph>0x10281D45</codeph>. </p> </li> <li id="GUID-2C6BF144-3686-5FE7-8AA6-A2FC6C4EE751"><p> <xref href="GUID-56C8D5AB-7D9A-3B20-B699-07F17A87A61C.dita#GUID-56C8D5AB-7D9A-3B20-B699-07F17A87A61C/GUID-54EB2437-9070-376D-8FCD-C1D4758113E6"><apiname>CPosPrivacyNotifier::CancelReason()</apiname></xref> </p> <p>This method can be used to check the reason why a request was cancelled. This method can be called while one of the methods <xref href="GUID-56C8D5AB-7D9A-3B20-B699-07F17A87A61C.dita#GUID-56C8D5AB-7D9A-3B20-B699-07F17A87A61C/GUID-3417B07B-DE69-3719-8634-B979CBA77AFE"><apiname>CPosPrivacyNotifier::HandleRequestCancelled()</apiname></xref> or <xref href="GUID-56C8D5AB-7D9A-3B20-B699-07F17A87A61C.dita#GUID-56C8D5AB-7D9A-3B20-B699-07F17A87A61C/GUID-2AFB10BF-DEAC-3BC5-B280-47BABF83A767"><apiname>CPosPrivacyNotifier::HandleAllRequestsComplete()</apiname></xref> is running. </p> <p>The return value is of type <xref href="GUID-8E445582-5821-36B3-A8FB-EE706D7C40EF.dita"><apiname>TPosVerifyCancelReason</apiname></xref> and specifies the reason why a request was cancelled. An unknown value should be treated as <xref href="GUID-A77356B9-0126-37E6-9583-6B2165E4C8F6.dita"><apiname>EPosCancelReasonNotAvailable</apiname></xref>. </p> </li> <li id="GUID-1DD588A1-0BA8-50E4-8045-09843000C85A"><p> <xref href="GUID-56C8D5AB-7D9A-3B20-B699-07F17A87A61C.dita#GUID-56C8D5AB-7D9A-3B20-B699-07F17A87A61C/GUID-1EC8EC6A-C6BF-377E-B50A-AD8668A2EDDD"><apiname>CPosPrivacyNotifier::BaseConstructL()</apiname></xref> </p> <p>This method must be called first in the <codeph>ConstructL()</codeph> of the licensee notifier implementation. The method takes a channel UID and a priority as parameters which are used by the Extended Notifier Framework. </p> </li> <li id="GUID-2F7BAA9F-2F94-51AE-8F25-188A79EBB67B"><p> <xref href="GUID-56C8D5AB-7D9A-3B20-B699-07F17A87A61C.dita#GUID-56C8D5AB-7D9A-3B20-B699-07F17A87A61C/GUID-4E117090-89E5-33DA-AC4B-494906B4BAF9"><apiname>CPosPrivacyNotifier::GetRequestsL()</apiname></xref> </p> <p>This method returns a list of all of the outstanding privacy verification requests (query requests) and notification requests. </p> </li> <li id="GUID-23F97EBA-1F1A-5BFB-A1A3-B06BB9EDF182"><p> <xref href="GUID-56C8D5AB-7D9A-3B20-B699-07F17A87A61C.dita#GUID-56C8D5AB-7D9A-3B20-B699-07F17A87A61C/GUID-5F934A37-B937-3AE4-AC1D-817D1BBA10B9"><apiname>CPosPrivacyNotifier::RequestTypeL()</apiname></xref> </p> <p>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 <codeph>KErrNotFound</codeph>. </p> </li> <li id="GUID-DC8FC238-9597-5DE3-A1FE-984A3A1B273D"><p> <xref href="GUID-56C8D5AB-7D9A-3B20-B699-07F17A87A61C.dita#GUID-56C8D5AB-7D9A-3B20-B699-07F17A87A61C/GUID-A041F06C-8A22-37D3-B634-894AFE9B7FF0"><apiname>CPosPrivacyNotifier::SetCurrentRequestL()</apiname></xref> </p> <p>The current request is the request that is currently being handled. </p> <p>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 <codeph>KErrNotFound</codeph>. </p> </li> <li id="GUID-BF050576-CE40-52E9-9D04-7D66B73FB740"><p> <xref href="GUID-56C8D5AB-7D9A-3B20-B699-07F17A87A61C.dita#GUID-56C8D5AB-7D9A-3B20-B699-07F17A87A61C/GUID-2576115E-8E73-3E2C-A7CF-A978C13E3542"><apiname>CPosPrivacyNotifier::CurrentRequest()</apiname></xref> </p> <p>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, <codeph>KPosNullQNRequestId</codeph> is returned. </p> </li> <li id="GUID-4C204154-2C45-5CD0-839C-307B51E873A5"><p> <xref href="GUID-56C8D5AB-7D9A-3B20-B699-07F17A87A61C.dita#GUID-56C8D5AB-7D9A-3B20-B699-07F17A87A61C/GUID-73244BA6-E796-383B-BA9F-507B25AA98EA"><apiname>CPosPrivacyNotifier::QueryTimeoutStrategy()</apiname></xref> </p> <p>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, <codeph>EPosDecisionNotAvailable</codeph> will be returned. </p> <p>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 <codeph>EPosDecisionNotAvailable</codeph>. </p> </li> <li id="GUID-85C3BF4D-D5CC-5A30-AEDF-4F275C78B2EC"><p> <xref href="GUID-56C8D5AB-7D9A-3B20-B699-07F17A87A61C.dita#GUID-56C8D5AB-7D9A-3B20-B699-07F17A87A61C/GUID-4EFE3E2B-92A4-3DC2-A02B-4AEE260DD682"><apiname>CPosPrivacyNotifier::RequestSource()</apiname></xref> </p> <p>The notifier can find out the source by calling this method. The request source enumeration <xref href="GUID-B2BA5881-DCF9-305B-A192-9F90CBA6BD55.dita"><apiname>TPosRequestSource</apiname></xref> is defined by the <xref href="GUID-3170E641-E3A9-58D5-82B9-391A2F5AC140.dita#GUID-3170E641-E3A9-58D5-82B9-391A2F5AC140/GUID-86A9DF94-B242-51D5-924A-68A0D526078B">Privacy Data Types</xref>. </p> <p>If a request source is not defined, <codeph>EPosRequestSourceNotAvailable</codeph> is be returned. </p> <p>Note that <xref href="GUID-B2BA5881-DCF9-305B-A192-9F90CBA6BD55.dita"><apiname>TPosRequestSource</apiname></xref> may be extended in the future. Therefore, any unknown value must be treated as <codeph>EPosRequestSourceNotAvailable</codeph>. </p> </li> <li id="GUID-641A20DA-3D44-58C1-B9A8-833267B4A553"><p> <xref href="GUID-56C8D5AB-7D9A-3B20-B699-07F17A87A61C.dita#GUID-56C8D5AB-7D9A-3B20-B699-07F17A87A61C/GUID-DDAC932E-1093-38AB-8CA6-3B2B06CC2BC0"><apiname>CPosPrivacyNotifier::LocationRequestDecision()</apiname></xref> </p> <p>This method returns whether the privacy request was accepted or rejected. </p> <p>This information is mainly used in notification requests. The request decision enumeration <xref href="GUID-5836362B-C341-311E-ABBE-D403DFA0DD62.dita"><apiname>TPosRequestDecision</apiname></xref> is defined by the <xref href="GUID-3170E641-E3A9-58D5-82B9-391A2F5AC140.dita#GUID-3170E641-E3A9-58D5-82B9-391A2F5AC140/GUID-86A9DF94-B242-51D5-924A-68A0D526078B">Privacy Data Types</xref>. </p> <p>For privacy verification queries, this method returns <codeph>EPosDecisionNotAvailable</codeph>. </p> <p>If the request decision is unknown in a notification request, <codeph>EPosDecisionNotAvailable</codeph> is returned. </p> </li> <li id="GUID-D5C1CB9F-B395-57DE-A22D-BCEFD47988B2"><p> <xref href="GUID-56C8D5AB-7D9A-3B20-B699-07F17A87A61C.dita#GUID-56C8D5AB-7D9A-3B20-B699-07F17A87A61C/GUID-22FFC3B2-A6B9-3501-AD89-1DB31027F53C"><apiname>CPosPrivacyNotifier::NotificationReason()</apiname></xref> </p> <p>For notification requests, this method returns the reason for notification, for example the request verification timed out. </p> <p>The notification reason enumeration <xref href="GUID-E4C7354B-3F7F-3279-AD6E-BA9574AD3A47.dita"><apiname>TPosNotificationReason</apiname></xref> is defined by the <xref href="GUID-3170E641-E3A9-58D5-82B9-391A2F5AC140.dita#GUID-3170E641-E3A9-58D5-82B9-391A2F5AC140/GUID-86A9DF94-B242-51D5-924A-68A0D526078B">Privacy Data Types</xref>. If the reason for the notification request is not provided, this method returns <codeph>EPosNotificationReasonNotAvailable</codeph>. </p> <p>Note that the notification reason enumeration <xref href="GUID-E4C7354B-3F7F-3279-AD6E-BA9574AD3A47.dita"><apiname>TPosNotificationReason</apiname></xref> may be extended in the future. Therefore, any unknown value must be treated as <codeph>EPosNotificationReasonNotAvailable</codeph>. </p> <p>If the notification reason is unknown by the notifier, the notification request should be completed with the error code <codeph>KErrNotSupported</codeph>, i.e. <codeph>CompleteRequest(KErrNotSupported)</codeph> should be called. </p> </li> <li id="GUID-E1FAD90F-22B2-5D86-A758-424E55586952"><p> <xref href="GUID-56C8D5AB-7D9A-3B20-B699-07F17A87A61C.dita#GUID-56C8D5AB-7D9A-3B20-B699-07F17A87A61C/GUID-E9CE021E-6971-39CC-B535-4A2367E93239"><apiname>CPosPrivacyNotifier::RequestorCountL()</apiname></xref> </p> <p>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 <codeph>KErrNotFound</codeph>. </p> <p>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. </p> </li> <li id="GUID-1A5A239A-1579-5761-AC28-930B47110AC5"><p> <xref href="GUID-56C8D5AB-7D9A-3B20-B699-07F17A87A61C.dita#GUID-56C8D5AB-7D9A-3B20-B699-07F17A87A61C/GUID-3A1AFEE8-0905-3567-A3B3-FCF0FFFEC124"><apiname>CPosPrivacyNotifier::RequestorLC()</apiname></xref> </p> <p>This method reads information about a requester from the request that is set as current by <xref href="GUID-56C8D5AB-7D9A-3B20-B699-07F17A87A61C.dita#GUID-56C8D5AB-7D9A-3B20-B699-07F17A87A61C/GUID-A041F06C-8A22-37D3-B634-894AFE9B7FF0"><apiname>CPosPrivacyNotifier::SetCurrentRequestL()</apiname></xref>. </p> <p>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 <codeph>KErrArgument</codeph>. If no request is set as current, or if the current request has been completed, this method leaves with the error code <codeph>KErrNotFound</codeph>. </p> </li> <li id="GUID-D4765257-9499-596A-A962-1761294CA105"><p> <xref href="GUID-56C8D5AB-7D9A-3B20-B699-07F17A87A61C.dita#GUID-56C8D5AB-7D9A-3B20-B699-07F17A87A61C/GUID-57739A9E-F6CD-3079-8B6F-9B80AAFE4D8B"><apiname>CPosPrivacyNotifier::CompleteRequest()</apiname></xref> </p> <p>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. </p> <p>A few completion codes have specific meanings. For query requests, the following completion codes should be noted: </p> <ul><li id="GUID-DEBCFBF7-4E2B-54FE-AC06-738513424BA4"><p> <codeph>KErrNone</codeph> if the phone user accepts the query. </p> </li> <li id="GUID-957FB682-65E6-503A-A98D-1A4D3900B425"><p> <codeph>KErrAccessDenied</codeph> if the phone user rejects the query. </p> </li> <li id="GUID-A8D9965E-6797-5454-9D16-8E9A84AA0D65"><p> <codeph>KErrTimedOut</codeph> if the query times out. The notifier should use a timer and abort it if the phone user does not respond to the dialog. </p> </li> </ul> <p>For notification requests, the following completion codes should be noted: </p> <ul><li id="GUID-506B8EB8-0592-56A4-B365-4C1E427F24CC"><p> <codeph>KErrNone</codeph> if the phone user dismisses the dialog. </p> </li> <li id="GUID-A1DF6E1E-FA71-5F37-A830-2B3EC8C055EA"><p> <codeph>KErrTimedOut</codeph> if the notification request times out. The notifier should implement a timeout if the phone user does not respond to the dialog. </p> </li> <li id="GUID-3E8145FF-8960-524C-B5F3-E23C6B3D1BC5"><p> <codeph>KErrNotSupported</codeph> if the notification reason is not known by the Privacy UI. </p> </li> </ul> </li> </ul> </section> </conbody></concept>