<?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 id="GUID-D857413A-D5A1-5F9F-A780-C980A9E0BEE0" xml:lang="en"><title>Privacy

Controller</title><shortdesc> A Privacy Controller is an application that a licensee can create

in order to process privacy requests. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<section><title>Purpose</title> <p>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. </p> <p> <xref href="GUID-3078D198-0FCB-58A0-8152-9CD319906D58.dita#GUID-3078D198-0FCB-58A0-8152-9CD319906D58/GUID-38E5625D-FFA4-56E2-97C8-12A5D1C361E4">How

to use the Privacy Controller API</xref> has example code for the API described

in this document. </p> <p>See <xref href="GUID-2E565B8E-D262-5769-96E6-A532154D57E6.dita#GUID-2E565B8E-D262-5769-96E6-A532154D57E6/GUID-47C88C54-6BDC-5777-A661-A3EB7162A89E">Privacy

Requests Overview</xref> for an explanation of privacy request concepts. </p> </section>

<section><title>Contents</title> <ul>

<li id="GUID-36E24ADF-B416-5D50-A986-DE7AB8EDF462"><p><xref href="GUID-D857413A-D5A1-5F9F-A780-C980A9E0BEE0.dita#GUID-D857413A-D5A1-5F9F-A780-C980A9E0BEE0/GUID-22440498-6540-5FFB-B5FE-D04EF92294E6">Introduction</xref>  </p> </li>

<li id="GUID-9E797581-5F00-5BD6-B4AB-9E3088659C36"><p><xref href="GUID-D857413A-D5A1-5F9F-A780-C980A9E0BEE0.dita#GUID-D857413A-D5A1-5F9F-A780-C980A9E0BEE0/GUID-55AB42E6-417C-55FD-A734-20871B544417">Privacy Controller startup and shutdown</xref>  </p> </li>

<li id="GUID-D5DE5EDB-A45F-5B5B-8699-FFC34DF651C5"><p><xref href="GUID-D857413A-D5A1-5F9F-A780-C980A9E0BEE0.dita#GUID-D857413A-D5A1-5F9F-A780-C980A9E0BEE0/GUID-098366A4-0262-5C59-8441-A5F5371150B0">Privacy Controller API description</xref>  </p> <ul>

<li id="GUID-45CA2D36-D20A-5CD4-85DC-6FB69C0DF102"><p><xref href="GUID-D857413A-D5A1-5F9F-A780-C980A9E0BEE0.dita#GUID-D857413A-D5A1-5F9F-A780-C980A9E0BEE0/GUID-C1DE6AB6-B521-568B-835B-FEA1FBE1F157">CLbsPrivacyController</xref> </p> </li>

<li id="GUID-0252ABE8-945C-5213-AFC4-07F0E4087184"><p><xref href="GUID-D857413A-D5A1-5F9F-A780-C980A9E0BEE0.dita#GUID-D857413A-D5A1-5F9F-A780-C980A9E0BEE0/GUID-50DD3996-3A4C-5FD1-9938-2F66DEECCFBB">MLbsPrivacyObserver</xref> </p> </li>

<li id="GUID-16236BB4-5F39-5891-BFDE-74C4F0555F55"><p><xref href="GUID-D857413A-D5A1-5F9F-A780-C980A9E0BEE0.dita#GUID-D857413A-D5A1-5F9F-A780-C980A9E0BEE0/GUID-4A7719C2-ED38-51B3-A16B-17B26DA87278">MLbsPrivacyObserver2</xref> </p> </li>

<li id="GUID-D5B5D625-78DC-50E3-B74E-BE96636C2A24"><p><xref href="GUID-D857413A-D5A1-5F9F-A780-C980A9E0BEE0.dita#GUID-D857413A-D5A1-5F9F-A780-C980A9E0BEE0/GUID-EF3695BB-5D29-519B-8410-41B82E9F2634">TLbsExternalRequestInfo</xref> </p> </li>

<li id="GUID-935996FF-F126-5CB1-BFB2-5E3CE59E8CFC"><p><xref href="GUID-D857413A-D5A1-5F9F-A780-C980A9E0BEE0.dita#GUID-D857413A-D5A1-5F9F-A780-C980A9E0BEE0/GUID-6CE66027-3F7C-505F-949F-4CFE1101C54A">TLbsExternalRequestInfo2</xref> </p> </li>

</ul> </li>

<li id="GUID-FB7837D6-FE3B-5FE3-B7A7-685EABF0A32D"><p><xref href="GUID-D857413A-D5A1-5F9F-A780-C980A9E0BEE0.dita#GUID-D857413A-D5A1-5F9F-A780-C980A9E0BEE0/GUID-40428027-BCF1-5A37-B3A8-E1DC9A37CD7A">Sequence Diagrams</xref>  </p> <ul>

<li id="GUID-FA581F5F-292C-55D0-A8A9-B218E4B11F14"><p><xref href="GUID-D857413A-D5A1-5F9F-A780-C980A9E0BEE0.dita#GUID-D857413A-D5A1-5F9F-A780-C980A9E0BEE0/GUID-5D870ABF-549C-5CB1-902C-D0E644E29E49">Privacy verification request</xref>  </p> </li>

<li id="GUID-2502BDB2-564F-5289-8CA4-F6E13D1D350B"><p><xref href="GUID-D857413A-D5A1-5F9F-A780-C980A9E0BEE0.dita#GUID-D857413A-D5A1-5F9F-A780-C980A9E0BEE0/GUID-227497D1-D8A7-579F-8B46-629D9833B6EC">Privacy notification request</xref>  </p> </li>

<li id="GUID-A796B57B-CF1E-5EE8-BA51-F245373C4DB6"><p><xref href="GUID-D857413A-D5A1-5F9F-A780-C980A9E0BEE0.dita#GUID-D857413A-D5A1-5F9F-A780-C980A9E0BEE0/GUID-2552D9A2-4563-58DC-80FE-AEE7797CFB28">Privacy verification request is cancelled</xref>  </p> </li>

</ul> </li>

<li id="GUID-92A45D56-1EEE-5012-A4D6-ADBF6599EB10"><p><xref href="GUID-D857413A-D5A1-5F9F-A780-C980A9E0BEE0.dita#GUID-D857413A-D5A1-5F9F-A780-C980A9E0BEE0/GUID-73569D0C-BB7D-54E9-B9AB-DC4FF87E133C">See also</xref>  </p> </li>

</ul> </section>

<section id="GUID-22440498-6540-5FFB-B5FE-D04EF92294E6"><title>Introduction</title> <p>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. </p> <p>A Privacy Controller gives more control over

responses to privacy requests than <xref href="GUID-F8C5A22F-8433-5F50-B12A-E964572E6C23.dita#GUID-F8C5A22F-8433-5F50-B12A-E964572E6C23/GUID-DC80984B-7B46-5C2D-A1EF-EDBB0983159D">Privacy

Notifiers</xref>. A licensee must implement either a Privacy Controller or

use Privacy Notifiers to handle privacy requests. </p> <p>Figure 1 shows a

Privacy Controller in the context of the other components that make up the <xref href="GUID-D18B4715-3942-52EA-9D2F-E145037FA47A.dita">Full LBS configuration</xref>.

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). </p> <p>A Privacy Controller is built

as a separate application that runs outside of the LBS subsystem. See <xref href="GUID-3078D198-0FCB-58A0-8152-9CD319906D58.dita#GUID-3078D198-0FCB-58A0-8152-9CD319906D58/GUID-38E5625D-FFA4-56E2-97C8-12A5D1C361E4">How

to use the LBS Privacy Controller API</xref> for guidance on how to create

a Privacy Controller. Symbian does not provide a reference Privacy Controller

implementation. </p> <fig id="GUID-C364B7DC-0DE0-55F8-9928-EE1318700935">

<title>              Figure 1. The Privacy Controller API and part of the

LBS subsystem.            </title>

<image href="GUID-4C00FAF4-B500-5973-AC6C-79274122276A_d0e440375_href.png" placement="inline"/>

</fig> </section>

<section id="GUID-55AB42E6-417C-55FD-A734-20871B544417"><title>Privacy Controller

startup and shutdown</title> <p>From Symbian OS v9.4 a licensee can configure

the LBS subsystem to run in the <xref href="GUID-D18B4715-3942-52EA-9D2F-E145037FA47A.dita">Standalone

Privacy Mode configuration</xref> in which the Symbian LBS subsystem handles

privacy requests but does not calculate position fixes. </p> <p>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: </p> <ul>

<li id="GUID-4F6CB571-EFF0-53CF-8187-40A617848E7B"><p>The licensee Privacy

Controller executable UID (secure ID) must be added to the LBS Root central

repository file as described in the <xref href="GUID-D18B4715-3942-52EA-9D2F-E145037FA47A.dita">LBS

integration and configuration guide</xref>. This is necessary so that the

LBS subsystem can automatically start the Privacy Controller process when

a privacy request is received. </p> </li>

<li id="GUID-09562316-B168-5012-B9A1-1CC201172BA2"><p>The Privacy Controller

implementation class must derive from <xref href="GUID-D857413A-D5A1-5F9F-A780-C980A9E0BEE0.dita#GUID-D857413A-D5A1-5F9F-A780-C980A9E0BEE0/GUID-4A7719C2-ED38-51B3-A16B-17B26DA87278">MLbsPrivacyObserver2</xref> (described in the API description section below) in order to receive notice

to shutdown when the processing of all outstanding privacy requests is complete. </p> </li>

</ul> </section>

<section id="GUID-098366A4-0262-5C59-8441-A5F5371150B0"><title>Privacy Controller

API description</title> <p>This section describes the classes of the LBS Privacy

Controller API. </p> <p><b>Privacy Controller API classes and types </b> </p> <p>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. </p> <p>The LBS

Privacy Controller API has <codeph>publishedPartner</codeph> interface access. </p> <table id="GUID-C2B503F3-75E3-5D11-BA32-990D76667EA7">

<tgroup cols="3"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/>

<thead>

<row>

<entry>Class name</entry>

<entry>Description</entry>

<entry>Header file</entry>

</row>

</thead>

<tbody>

<row>

<entry><p><xref href="GUID-D857413A-D5A1-5F9F-A780-C980A9E0BEE0.dita#GUID-D857413A-D5A1-5F9F-A780-C980A9E0BEE0/GUID-C1DE6AB6-B521-568B-835B-FEA1FBE1F157">CLbsPrivacyController</xref>  </p> </entry>

<entry><p>A licensee application uses this class to register itself as a Privacy

Controller. The licensee Privacy Controller class must implement either the <xref href="GUID-D857413A-D5A1-5F9F-A780-C980A9E0BEE0.dita#GUID-D857413A-D5A1-5F9F-A780-C980A9E0BEE0/GUID-50DD3996-3A4C-5FD1-9938-2F66DEECCFBB">MLbsPrivacyObserver</xref> or

the <xref href="GUID-D857413A-D5A1-5F9F-A780-C980A9E0BEE0.dita#GUID-D857413A-D5A1-5F9F-A780-C980A9E0BEE0/GUID-4A7719C2-ED38-51B3-A16B-17B26DA87278">MLbsPrivacyObserver2</xref> interface. </p> </entry>

<entry><p> <filepath>lbsprivacycontroller.h</filepath>  </p> </entry>

</row>

<row>

<entry><p><xref href="GUID-D857413A-D5A1-5F9F-A780-C980A9E0BEE0.dita#GUID-D857413A-D5A1-5F9F-A780-C980A9E0BEE0/GUID-50DD3996-3A4C-5FD1-9938-2F66DEECCFBB">MLbsPrivacyObserver</xref> </p> </entry>

<entry><p>The interface that a licensee Privacy Controller implements to receive

privacy requests from the LBS subsystem. </p> </entry>

<entry><p> <filepath>lbsprivacycontroller.h</filepath>  </p> </entry>

</row>

<row>

<entry><p><xref href="GUID-D857413A-D5A1-5F9F-A780-C980A9E0BEE0.dita#GUID-D857413A-D5A1-5F9F-A780-C980A9E0BEE0/GUID-4A7719C2-ED38-51B3-A16B-17B26DA87278">MLbsPrivacyObserver2</xref> </p> </entry>

<entry><p>The interface (derived from <codeph>MLbsPrivacyObserver</codeph>)

that allows a Privacy Controller to receive privacy requests and shutdown

instructions from the LBS subsystem. </p> </entry>

<entry><p> <filepath>lbsprivacycontroller.h</filepath>  </p> </entry>

</row>

</tbody>

</tgroup>

</table> <p>The following table describes the request information classes

used by the Privacy Controller API. Note that <xref href="GUID-F8C5A22F-8433-5F50-B12A-E964572E6C23.dita#GUID-F8C5A22F-8433-5F50-B12A-E964572E6C23/GUID-DC80984B-7B46-5C2D-A1EF-EDBB0983159D">Privacy

Notifiers</xref> also use these classes to get privacy request information

from the LBS subsystem. </p> <table id="GUID-8B845EC4-B6AF-5CCE-867A-B9054AF79B48">

<tgroup cols="3"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/>

<thead>

<row>

<entry>Class name</entry>

<entry>Description</entry>

<entry>Header file</entry>

</row>

</thead>

<tbody>

<row>

<entry><p><xref href="GUID-D857413A-D5A1-5F9F-A780-C980A9E0BEE0.dita#GUID-D857413A-D5A1-5F9F-A780-C980A9E0BEE0/GUID-EF3695BB-5D29-519B-8410-41B82E9F2634">TLbsExternalRequestInfo</xref> </p> </entry>

<entry><p>Contains information about the agent who is requesting the device's

location. A reference to this class (or the derived class <codeph>TLbsExternalRequestInfo2</codeph>)

is passed in <xref href="GUID-76C6B540-DCA5-33CB-9ABD-8951A2F1DD5D.dita#GUID-76C6B540-DCA5-33CB-9ABD-8951A2F1DD5D/GUID-74F567E4-1BD8-38A0-AF7E-51031DBFA625"><apiname>MLbsPrivacyObserver::ProcessNetworkLocationRequest()</apiname></xref>. </p> </entry>

<entry><p> <filepath> lbsloccommon.h</filepath>  </p> </entry>

</row>

<row>

<entry><p><xref href="GUID-D857413A-D5A1-5F9F-A780-C980A9E0BEE0.dita#GUID-D857413A-D5A1-5F9F-A780-C980A9E0BEE0/GUID-6CE66027-3F7C-505F-949F-4CFE1101C54A">TLbsExternalRequestInfo2</xref> </p> </entry>

<entry><p>This class extends <codeph>TLbsExternalRequestInfo</codeph> to allow

for long Requester ID and Client Name descriptors. Note that this class is

deprecated as <codeph>TLbsExternalRequestInfo</codeph> should be sufficient

for most licensee Privacy Controllers. </p> </entry>

<entry><p> <filepath> lbsloccommon.h</filepath>  </p> </entry>

</row>

</tbody>

</tgroup>

</table> <p><b>Privacy Controller API class diagram </b> </p> <p>Figure 2 shows the classes

of the Privacy Controller API. <xref href="GUID-D857413A-D5A1-5F9F-A780-C980A9E0BEE0.dita#GUID-D857413A-D5A1-5F9F-A780-C980A9E0BEE0/GUID-50DD3996-3A4C-5FD1-9938-2F66DEECCFBB">MLbsPrivacyObserver</xref> has a dependency on <xref href="GUID-D857413A-D5A1-5F9F-A780-C980A9E0BEE0.dita#GUID-D857413A-D5A1-5F9F-A780-C980A9E0BEE0/GUID-EF3695BB-5D29-519B-8410-41B82E9F2634">TLbsExternalRequestInfo</xref> (which is shown in more detail in Figure 3). </p> <fig id="GUID-3ED0FA49-FB2A-50E4-A40A-9CCBDF810CA6">

<title>              Figure 2. Privacy Controller API classes and types  

         </title>

<image href="GUID-4AE98C9B-03A9-5F26-BD0F-2A60B01A67F4_d0e440649_href.png" placement="inline"/>

</fig> <p>Figure 3 shows the <xref href="GUID-D6E1F012-8C98-3B10-9601-3F665CFD5F08.dita"><apiname>TLbsExternalRequestInfo</apiname></xref> and <xref href="GUID-EB52E7D5-55AE-3539-A212-AB2B5430D407.dita"><apiname>TLbsExternalRequestInfo2</apiname></xref> classes.

Either a <codeph>TLbsExternalRequestInfo</codeph> or <codeph>TLbsExternalRequestInfo2</codeph> object

reference is passed to the Privacy Controller via the <xref href="GUID-76C6B540-DCA5-33CB-9ABD-8951A2F1DD5D.dita#GUID-76C6B540-DCA5-33CB-9ABD-8951A2F1DD5D/GUID-74F567E4-1BD8-38A0-AF7E-51031DBFA625"><apiname>MLbsPrivacyObserver::ProcessNetworkLocationRequest()</apiname></xref> function

when a privacy request is received and a Privacy Controller is configured. </p> <p>Note

from figure 2 that the object reference is always passed as a <codeph>TLbsExternalRequestInfo</codeph> so

it is only necessary to cast to the <codeph>TLbsExternalRequestInfo2</codeph> derived

class if the licensee is using large buffers for the requester ID and the

client name. This may be the case <i>only</i> when LBS is being used in the <xref href="GUID-D18B4715-3942-52EA-9D2F-E145037FA47A.dita">Standalone Privacy Mode configuration</xref> <i>and</i> large

buffer sizes are passed across the Network Privacy API or the Privacy Request

API. </p> <p>See the Network Privacy API documentation and the <xref href="GUID-3078D198-0FCB-58A0-8152-9CD319906D58.dita#GUID-3078D198-0FCB-58A0-8152-9CD319906D58/GUID-38E5625D-FFA4-56E2-97C8-12A5D1C361E4">How to use the Privacy Controller API</xref> documentation for more information

about handling large buffers. </p> <fig id="GUID-B7748A22-266B-54C1-9C73-C77A8220B0FA">

<title>              Figure 3. TLbsExternalRequestInfo, TLbsExternalRequestInfo2

and              related types.            </title>

<image href="GUID-648D4AEB-4BCD-552A-BCAF-F049F79F04FC_d0e440702_href.png" placement="inline"/>

</fig> <p><b>Libraries </b> </p> <p>The Privacy Controller API is packaged in <filepath>lbsprivacycontroller.dll</filepath>.

A licensee Privacy Controller links to <filepath>lbsprivacycontroller.lib</filepath>. </p> <p>The

API header files for the Privacy Controller API can be found in <filepath>/epoc32/include/lbs</filepath>. </p> <p><b>Capabilities </b> </p> <p>A licensee Privacy Controller requires the following

capabilities: <b>Location</b>, <b>ReadDeviceData</b> and <b>WriteDeviceData</b>. </p> <p><b>LBS Configuration </b> </p> <p>The LBS Administration setting <codeph>KLbsSettingPrivacyHandler</codeph> must

be set to <codeph>CLbsAdmin::EPrivacyHandleByController</codeph> to configure

LBS to use a Privacy Controller. 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>Multiple simultaneous privacy requests</b>  </p> <p>The

LBS administration setting <codeph>KLbsSettingMaximumExternalLocateRequests</codeph> has

an important effect when LBS is configured to use a Privacy Controller. </p> <p>The

setting does not affect the behaviour of LBS in the <xref href="GUID-D18B4715-3942-52EA-9D2F-E145037FA47A.dita">Full

LBS configuration</xref> because multiple simultaneous privacy requests are

not supported with a <xref href="GUID-CB6B4D1A-ACB9-5571-8C23-4BC095209782.dita">Network

Protocol Module</xref>. </p> <p>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 <xref href="GUID-D18B4715-3942-52EA-9D2F-E145037FA47A.dita">Standalone

Privacy Mode</xref>: </p> <ul>

<li id="GUID-CFA0BE7D-21B8-549D-9BF3-FEC0CB2CC1AC"><p> <codeph>KLbsSettingMaximumExternalLocateRequests

= 1</codeph> (the default setting) </p> <p>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 <xref href="GUID-E1710E40-B8F5-5CF8-B9FE-698869A1770F.dita">Privacy

Request API</xref> and <xref href="GUID-B3000A78-3BE5-5E0A-A718-87BC9BA03726.dita">Network

Privacy API</xref> documentation. </p> </li>

<li id="GUID-2B7A6F2C-DDB9-5462-9935-1B5534A834CC"><p> <codeph>KLbsSettingMaximumExternalLocateRequests

&gt; 1</codeph>  </p> <p> <b>For this case, a licensee must design their Privacy

Controller so that it can process multiple simultaneous privacy requests.</b> For

example, the implementation of <xref href="GUID-76C6B540-DCA5-33CB-9ABD-8951A2F1DD5D.dita#GUID-76C6B540-DCA5-33CB-9ABD-8951A2F1DD5D/GUID-74F567E4-1BD8-38A0-AF7E-51031DBFA625"><apiname>MLbsPrivacyObserver::ProcessNetworkLocationRequest()</apiname></xref> may

be called multiple times in rapid succession and therefore must not block

the Privacy Controller. </p> <p>The behaviour of the LBS subsystem depends

on the number of outstanding privacy requests and the setting <codeph>KLbsSettingMaximumExternalLocateRequests</codeph>: </p> <ul>

<li id="GUID-77A9E950-DE48-524F-A9B5-29B2129D2708"><p> <codeph>Number of outstanding

privacy requests &lt;                      KLbsSettingMaximumExternalLocateRequests</codeph>  </p> <p>A

new privacy request is processed and causes a sequence of Privacy Controller

API methods to be called. See the sequence diagrams of <xref href="GUID-B3000A78-3BE5-5E0A-A718-87BC9BA03726.dita">Network

Privacy API</xref> and <xref href="GUID-E1710E40-B8F5-5CF8-B9FE-698869A1770F.dita">Privacy

Request API</xref> for sequences that describe the processing of each request. </p> </li>

<li id="GUID-73A49D47-A3DC-5EFF-A343-B8CF04D2E312"><p> <codeph>Number of outstanding

privacy requests =                      KLbsSettingMaximumExternalLocateRequests</codeph>  </p> <p>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 <xref href="GUID-B3000A78-3BE5-5E0A-A718-87BC9BA03726.dita">Network

Privacy API</xref> and <xref href="GUID-E1710E40-B8F5-5CF8-B9FE-698869A1770F.dita">Privacy

Request API</xref> documentation. </p> </li>

</ul> </li>

</ul> <p id="GUID-C1DE6AB6-B521-568B-835B-FEA1FBE1F157"><b>CLbsPrivacyController</b> </p> <p><b>Purpose </b> </p> <p> <xref href="GUID-DA9AD188-944E-36C0-98A6-4F9B6FB2A091.dita"><apiname>CLbsPrivacyController</apiname></xref> 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 <xref href="GUID-76C6B540-DCA5-33CB-9ABD-8951A2F1DD5D.dita"><apiname>MLbsPrivacyObserver</apiname></xref> interface

or the derived <xref href="GUID-BF88837F-1ADC-3DB2-98E5-CFBF75E2BE86.dita"><apiname>MLbsPrivacyObserver2</apiname></xref> interface. </p> <p><b>Usage </b> </p> <p> <xref href="GUID-DA9AD188-944E-36C0-98A6-4F9B6FB2A091.dita#GUID-DA9AD188-944E-36C0-98A6-4F9B6FB2A091/GUID-DB38D39A-780E-3F36-BD02-E770AC1C513B"><apiname>CLbsPrivacyController::NewL()</apiname></xref> is

used by a licensee Privacy Controller to register itself with the LBS subsystem. </p> <p> <xref href="GUID-DA9AD188-944E-36C0-98A6-4F9B6FB2A091.dita#GUID-DA9AD188-944E-36C0-98A6-4F9B6FB2A091/GUID-D3C37C92-5609-31F1-82AB-01AEC99671BB"><apiname>CLbsPrivacyController::RespondNetworkLocationRequest()</apiname></xref> 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). </p> <p> <xref href="GUID-DA9AD188-944E-36C0-98A6-4F9B6FB2A091.dita#GUID-DA9AD188-944E-36C0-98A6-4F9B6FB2A091/GUID-C2FC9C84-DB18-3741-BD2F-AC214D679A13"><apiname>CLbsPrivacyController::CancelNetworkLocationRequest()</apiname></xref> is used to cancel an outstanding privacy request. </p> <p><b>CLbsPrivacyController::TRequestVerificationResult</b> </p> <p><b>Purpose </b> </p> <p> <xref href="GUID-DA9AD188-944E-36C0-98A6-4F9B6FB2A091.dita#GUID-DA9AD188-944E-36C0-98A6-4F9B6FB2A091/GUID-6F3104C6-C47F-35F5-9CDA-5AFD44CBFE32"><apiname>CLbsPrivacyController::TRequestVerificationResult</apiname></xref> holds

the privacy response that the Privacy Controller returns to the LBS subsystem. </p> <p><b>Usage </b> </p> <p>The Privacy Controller passes a <codeph>TRequestVerificationResult</codeph> parameter

to LBS in <xref href="GUID-DA9AD188-944E-36C0-98A6-4F9B6FB2A091.dita#GUID-DA9AD188-944E-36C0-98A6-4F9B6FB2A091/GUID-D3C37C92-5609-31F1-82AB-01AEC99671BB"><apiname>CLbsPrivacyController::RespondNetworkLocationRequest()</apiname></xref> to

indicate if the privacy request was accepted, rejected or ignored. </p> <p id="GUID-50DD3996-3A4C-5FD1-9938-2F66DEECCFBB"><b>MLbsPrivacyObserver</b> </p> <p><b>Purpose </b> </p> <p> <xref href="GUID-76C6B540-DCA5-33CB-9ABD-8951A2F1DD5D.dita"><apiname>MLbsPrivacyObserver</apiname></xref> is the interface

class that a licensee Privacy Controller implements (or the derived <xref href="GUID-BF88837F-1ADC-3DB2-98E5-CFBF75E2BE86.dita"><apiname>MLbsPrivacyObserver2</apiname></xref> interface). </p> <p><b>Usage </b> </p> <p> <xref href="GUID-76C6B540-DCA5-33CB-9ABD-8951A2F1DD5D.dita#GUID-76C6B540-DCA5-33CB-9ABD-8951A2F1DD5D/GUID-74F567E4-1BD8-38A0-AF7E-51031DBFA625"><apiname>MLbsPrivacyObserver::ProcessNetworkLocationRequest()</apiname></xref> is

called by the LBS subsystem to cause the Privacy Controller to process a privacy

request. </p> <p> <xref href="GUID-76C6B540-DCA5-33CB-9ABD-8951A2F1DD5D.dita#GUID-76C6B540-DCA5-33CB-9ABD-8951A2F1DD5D/GUID-EC9BC8C5-F634-36FB-BD69-D932891F8CF9"><apiname>MLbsPrivacyObserver::ProcessNetworkPositionUpdate()</apiname></xref> is

called by the LBS subsystem to send the Privacy Controller a position update. </p> <p> <xref href="GUID-76C6B540-DCA5-33CB-9ABD-8951A2F1DD5D.dita#GUID-76C6B540-DCA5-33CB-9ABD-8951A2F1DD5D/GUID-19A15BEC-7F45-3E8C-9EC3-8D0BCA6A90B3"><apiname>MLbsPrivacyObserver::ProcessRequestComplete()</apiname></xref> is called by the LBS subsystem to notify the Privacy Controller that a privacy

request is complete. </p> <p><b>MLbsPrivacyObserver::TNotificationType</b> </p> <p><b>Purpose </b> </p> <p> <xref href="GUID-76C6B540-DCA5-33CB-9ABD-8951A2F1DD5D.dita#GUID-76C6B540-DCA5-33CB-9ABD-8951A2F1DD5D/GUID-3318F6A6-4371-3304-AE0B-BF68D9B01CDA"><apiname>MLbsPrivacyObserver::TNotificationType</apiname></xref> 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: </p> <table id="GUID-1A913B1D-3967-51D0-9FC6-92776693C373">

<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>

<thead>

<row>

<entry>Value</entry>

<entry>Meaning</entry>

</row>

</thead>

<tbody>

<row>

<entry><p> <codeph>ENotifyLocationAccepted</codeph>  </p> </entry>

<entry><p>Accept the privacy request and notify the user </p> </entry>

</row>

<row>

<entry><p> <codeph>ENotifyAndVerifyLocationAcceptedIfNoReponse</codeph>  </p> </entry>

<entry><p>Verify the privacy request (query user or use privacy rules). Accept

if no response </p> </entry>

</row>

<row>

<entry><p> <codeph>ENotifyAndVerifyLocationRejectedIfNoReponse</codeph>  </p> </entry>

<entry><p>Verify the privacy request (query user or use privacy rules). Reject

if no response </p> </entry>

</row>

<row>

<entry><p> <codeph>ENotifyLocationRejected</codeph>  </p> </entry>

<entry><p>Reject the request and and notify user </p> </entry>

</row>

</tbody>

</tgroup>

</table> <p> <b>Important Note</b>  </p> <p>The action specified by <codeph>TNotificationType</codeph> can

be overridden by the <xref href="GUID-23BBC1D8-B3A0-5148-A4F1-22ECF3043E4E.dita">LBS

administration</xref> settings. </p> <p>There are three settings that override

the behaviour specified by <codeph>TNotificationType</codeph>: </p> <p>LBS

administration setting <codeph>KLbsSettingHomeExternalLocate</codeph> and <codeph>KLbsSettingRoamingExternalLocate</codeph> 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 <xref href="GUID-E8B4B321-6B45-3764-ADD2-CD05A5533945.dita#GUID-E8B4B321-6B45-3764-ADD2-CD05A5533945/GUID-74AF5A08-F6D9-36F7-A904-710C18248569"><apiname>CLbsAdmin::TExternalLocateService</apiname></xref> for

more information about the values that these administration settings can take. </p> <p>LBS

administration setting <codeph>KLbsSettingPrivacyTimeoutAction</codeph> specifies

the action that the LBS subsystem takes if a privacy request times out. See <xref href="GUID-E8B4B321-6B45-3764-ADD2-CD05A5533945.dita#GUID-E8B4B321-6B45-3764-ADD2-CD05A5533945/GUID-F063FE21-9996-3F0E-9BE2-95067EF5B5E6"><apiname>CLbsAdmin::TPrivacyTimeoutAction</apiname></xref> for

more information about the values that this administration setting can take. </p> <p><b>Usage </b> </p> <p>An <xref href="GUID-76C6B540-DCA5-33CB-9ABD-8951A2F1DD5D.dita#GUID-76C6B540-DCA5-33CB-9ABD-8951A2F1DD5D/GUID-3318F6A6-4371-3304-AE0B-BF68D9B01CDA"><apiname>MLbsPrivacyObserver::TNotificationType</apiname></xref> parameter

is passed as a parameter in a call by the LBS subsystem to the Privacy Controller

method <xref href="GUID-76C6B540-DCA5-33CB-9ABD-8951A2F1DD5D.dita#GUID-76C6B540-DCA5-33CB-9ABD-8951A2F1DD5D/GUID-74F567E4-1BD8-38A0-AF7E-51031DBFA625"><apiname>MLbsPrivacyObserver::ProcessNetworkLocationRequest()</apiname></xref>. </p> <p id="GUID-4A7719C2-ED38-51B3-A16B-17B26DA87278"><b>MLbsPrivacyObserver2</b> </p> <p><b>Purpose </b> </p> <p> <xref href="GUID-BF88837F-1ADC-3DB2-98E5-CFBF75E2BE86.dita"><apiname>MLbsPrivacyObserver2</apiname></xref> is a Privacy

Controller interface class derived from <xref href="GUID-76C6B540-DCA5-33CB-9ABD-8951A2F1DD5D.dita"><apiname>MLbsPrivacyObserver</apiname></xref>.

A licensee Privacy Controller only needs to implement this interface instead

of <codeph>MLbsPrivacyObserver</codeph> if it requires notification that LBS

is shutting down. </p> <p><b>Usage </b> </p> <p> <xref href="GUID-BF88837F-1ADC-3DB2-98E5-CFBF75E2BE86.dita#GUID-BF88837F-1ADC-3DB2-98E5-CFBF75E2BE86/GUID-D0474BB9-6CD6-3F5E-842C-1531A663AAB8"><apiname>MLbsPrivacyObserver2::ProcessCloseDownNotification()</apiname></xref> is

called by the LBS subsystem root process to shutdown a licensee Privacy Controller

when the LBS subsystem is in the <xref href="GUID-D18B4715-3942-52EA-9D2F-E145037FA47A.dita">Standalone

Privacy Mode configuration</xref>. </p> <p id="GUID-EF3695BB-5D29-519B-8410-41B82E9F2634"><b>TLbsExternalRequestInfo</b> </p> <p><b>Purpose </b> </p> <p> <xref href="GUID-D6E1F012-8C98-3B10-9601-3F665CFD5F08.dita"><apiname>TLbsExternalRequestInfo</apiname></xref> is the

class that LBS subsystem uses to pass request information to a licensee Privacy

Controller. </p> <p>This class is not strictly part of the Privacy Controller

API. It is defined in <filepath>lbsloccommon.h</filepath> and is also used

by <xref href="GUID-F8C5A22F-8433-5F50-B12A-E964572E6C23.dita#GUID-F8C5A22F-8433-5F50-B12A-E964572E6C23/GUID-DC80984B-7B46-5C2D-A1EF-EDBB0983159D">Privacy

Notifiers</xref> and by LBS internally. A Privacy Controller uses it to obtain

information about the agent that sent the privacy request. </p> <p><b>Usage </b> </p> <p>A <xref href="GUID-D6E1F012-8C98-3B10-9601-3F665CFD5F08.dita"><apiname>TLbsExternalRequestInfo</apiname></xref> object

reference is passed as a parameter from the LBS subsystem to the Privacy Controller

in a call to <xref href="GUID-76C6B540-DCA5-33CB-9ABD-8951A2F1DD5D.dita#GUID-76C6B540-DCA5-33CB-9ABD-8951A2F1DD5D/GUID-74F567E4-1BD8-38A0-AF7E-51031DBFA625"><apiname>MLbsPrivacyObserver::ProcessNetworkLocationRequest()</apiname></xref>. </p> <p> <xref href="GUID-D6E1F012-8C98-3B10-9601-3F665CFD5F08.dita"><apiname>TLbsExternalRequestInfo</apiname></xref> 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: </p> <ul>

<li id="GUID-3FEE3437-1C39-5CA9-A215-A44E3E20E250"><p> <xref href="GUID-D6E1F012-8C98-3B10-9601-3F665CFD5F08.dita#GUID-D6E1F012-8C98-3B10-9601-3F665CFD5F08/GUID-DAE108AE-80F4-3136-B7A4-BF2E50A76864"><apiname>TLbsExternalRequestInfo::GetRequesterId()</apiname></xref> gets

the ID of the requester. </p> </li>

<li id="GUID-07E8994D-D98E-5B1B-8F80-A1F61E7E9603"><p> <xref href="GUID-D6E1F012-8C98-3B10-9601-3F665CFD5F08.dita#GUID-D6E1F012-8C98-3B10-9601-3F665CFD5F08/GUID-E486B61F-FF83-3D6D-BA83-1A9839AE4090"><apiname>TLbsExternalRequestInfo::GetClientName()</apiname></xref> gets

the name of the client. </p> </li>

<li id="GUID-047B24E3-B49C-5790-B70F-7A40246382E2"><p> <xref href="GUID-D6E1F012-8C98-3B10-9601-3F665CFD5F08.dita#GUID-D6E1F012-8C98-3B10-9601-3F665CFD5F08/GUID-0BC7BC4B-83DF-3C5F-8E96-4EAF4C7B107C"><apiname>TLbsExternalRequestInfo::GetClientExternalId()</apiname></xref> gets

the client external ID. </p> </li>

</ul> <p>A Privacy Controller can use other methods of <codeph>TLbsExternalRequestInfo</codeph> to

get information about the format of the data and the encoding of the requester

ID and the client name descriptors: </p> <ul>

<li id="GUID-D67309F3-11CC-585E-8C17-98F999BC9E40"><p> <xref href="GUID-D6E1F012-8C98-3B10-9601-3F665CFD5F08.dita#GUID-D6E1F012-8C98-3B10-9601-3F665CFD5F08/GUID-1DE5ECB6-A4BE-3D8A-B2CA-4C856818FBD7"><apiname>TLbsExternalRequestInfo::RequesterIdFormat()</apiname></xref> returns

a <xref href="GUID-D6E1F012-8C98-3B10-9601-3F665CFD5F08.dita#GUID-D6E1F012-8C98-3B10-9601-3F665CFD5F08/GUID-BE59DD81-E3C7-3BC9-85BB-EFBC152F7C85"><apiname>TLbsExternalRequestInfo::TFormatIndicator</apiname></xref> (a value from

the enumeration <xref href="GUID-D6E1F012-8C98-3B10-9601-3F665CFD5F08.dita#GUID-D6E1F012-8C98-3B10-9601-3F665CFD5F08/GUID-4A0CFFE5-B5FA-33B1-AC61-0F8E21C56384"><apiname>TLbsExternalRequestInfo::_TFormatIndicator</apiname></xref>).

This specifies the format of the data that <codeph>TLbsExternalRequestInfo::GetRequesterId()</codeph> returns

(such as a MSISDN, URL, email address etc.) </p> </li>

<li id="GUID-753F57B2-A88C-55E8-A954-491988003128"><p> <xref href="GUID-D6E1F012-8C98-3B10-9601-3F665CFD5F08.dita#GUID-D6E1F012-8C98-3B10-9601-3F665CFD5F08/GUID-7648CE80-2702-3FEA-A3CC-FFAFA39C8FE9"><apiname>TLbsExternalRequestInfo::ClientNameFormat()</apiname></xref> returns

a <codeph>TFormatIndicator</codeph> which describes the format of the data

that <codeph>TLbsExternalRequestInfo::GetClientName()</codeph> returns. </p> </li>

<li id="GUID-EBD5CD41-EB9C-526F-AEFA-504555276B6A"><p> <xref href="GUID-D6E1F012-8C98-3B10-9601-3F665CFD5F08.dita#GUID-D6E1F012-8C98-3B10-9601-3F665CFD5F08/GUID-4D04EBF9-CDED-32EC-B993-E10036682FA3"><apiname>TLbsExternalRequestInfo::RequesterIdCodingScheme()</apiname></xref> returns

a <xref href="GUID-D6E1F012-8C98-3B10-9601-3F665CFD5F08.dita#GUID-D6E1F012-8C98-3B10-9601-3F665CFD5F08/GUID-9C6D27D5-DFA6-31C5-9223-0692C6DD133F"><apiname>TLbsExternalRequestInfo::TCodingScheme</apiname></xref> (a value from

the enumeration <xref href="GUID-D6E1F012-8C98-3B10-9601-3F665CFD5F08.dita#GUID-D6E1F012-8C98-3B10-9601-3F665CFD5F08/GUID-0F58F35A-B83D-3259-8E79-CCE8E311D52A"><apiname>TLbsExternalRequestInfo::_TCodingScheme</apiname></xref>).

This specifies the encoding of the data that <codeph>TLbsExternalRequestInfo::GetRequesterId()</codeph> returns

(such as UCS-2, UTF-8 or GSM 7 bit). </p> </li>

<li id="GUID-BAB695DD-1DF8-594A-9D64-00482DC30933"><p> <xref href="GUID-D6E1F012-8C98-3B10-9601-3F665CFD5F08.dita#GUID-D6E1F012-8C98-3B10-9601-3F665CFD5F08/GUID-022A7856-019F-3E52-BF69-31CAB8D3E99C"><apiname>TLbsExternalRequestInfo::ClientNameCodingScheme()</apiname></xref> returns

a <codeph>TCodingScheme</codeph> that specifies the encoding of the data that <codeph>TLbsExternalRequestInfo::GetClientName()</codeph> returns. </p> </li>

</ul> <p> <xref href="GUID-D6E1F012-8C98-3B10-9601-3F665CFD5F08.dita#GUID-D6E1F012-8C98-3B10-9601-3F665CFD5F08/GUID-941B8D64-1A14-3212-91A8-F34C251DF324"><apiname>TLbsExternalRequestInfo::NetworkType()</apiname></xref> returns

a <xref href="GUID-D6E1F012-8C98-3B10-9601-3F665CFD5F08.dita#GUID-D6E1F012-8C98-3B10-9601-3F665CFD5F08/GUID-8A8A5988-7824-3FCD-8DDD-3EDE1EE5F91D"><apiname>TLbsExternalRequestInfo::TNetworkType</apiname></xref> (a value from the

enumeration <xref href="GUID-D6E1F012-8C98-3B10-9601-3F665CFD5F08.dita#GUID-D6E1F012-8C98-3B10-9601-3F665CFD5F08/GUID-E1629237-2510-33E1-8DD9-E5A02F0CFAC6"><apiname>TLbsExternalRequestInfo::_TNetworkType</apiname></xref>). This

specifies the type of network from which the privacy request was received

(GSM, SUPL or WCDMA). </p> <p> <xref href="GUID-D6E1F012-8C98-3B10-9601-3F665CFD5F08.dita#GUID-D6E1F012-8C98-3B10-9601-3F665CFD5F08/GUID-FC25815D-18CB-3C0C-BC4B-B9B0AD989D4A"><apiname>TLbsExternalRequestInfo::RequestSource()</apiname></xref> returns

a <xref href="GUID-D6E1F012-8C98-3B10-9601-3F665CFD5F08.dita#GUID-D6E1F012-8C98-3B10-9601-3F665CFD5F08/GUID-96423BB7-2412-3E51-B457-6D99CECCDB1C"><apiname>TLbsExternalRequestInfo::TRequestSource</apiname></xref> (a value from

the enumeration <xref href="GUID-D6E1F012-8C98-3B10-9601-3F665CFD5F08.dita#GUID-D6E1F012-8C98-3B10-9601-3F665CFD5F08/GUID-08527BDC-45E9-3EE1-9F82-618B9EEAE932"><apiname>TLbsExternalRequestInfo::_TRequestSource</apiname></xref>).

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 <xref href="GUID-E1710E40-B8F5-5CF8-B9FE-698869A1770F.dita">Privacy

Request API</xref> client must set this value on the <codeph>TLbsExternalRequestInfo</codeph> object

it passes across the API. It is used for policing client capabilities. See <xref href="GUID-5008C3E6-4D12-5BA3-A95A-7CAB02ED0594.dita">How to use the Privacy Request

API</xref> for more information. </p> <p> <xref href="GUID-D6E1F012-8C98-3B10-9601-3F665CFD5F08.dita#GUID-D6E1F012-8C98-3B10-9601-3F665CFD5F08/GUID-A945D0A5-0BD3-3644-A202-1F0DC86B6DD0"><apiname>TLbsExternalRequestInfo::RequestType()</apiname></xref> returns

a <xref href="GUID-D6E1F012-8C98-3B10-9601-3F665CFD5F08.dita#GUID-D6E1F012-8C98-3B10-9601-3F665CFD5F08/GUID-6DD2B933-A4C0-38A7-ACF8-9408297928AD"><apiname>TLbsExternalRequestInfo::TRequestType</apiname></xref> (a value from the

enumeration <xref href="GUID-D6E1F012-8C98-3B10-9601-3F665CFD5F08.dita#GUID-D6E1F012-8C98-3B10-9601-3F665CFD5F08/GUID-70F3669A-B543-3312-A625-BB5769256AC7"><apiname>TLbsExternalRequestInfo::_TRequestType</apiname></xref>). This

specifies the type of request (single shot, periodic or area event). These

values are not implemented and are reserved for future use. </p> <p>Note that

the <codeph>TLbsExternalRequestInfo</codeph> setter functions are for use

in licensee Network Protocol Module implementations and not by Privacy Controllers

(which only need to read data from a <codeph>TLbsExternalRequestInfo</codeph> object). </p> <p id="GUID-6CE66027-3F7C-505F-949F-4CFE1101C54A"><b>TLbsExternalRequestInfo2</b> </p> <p><b>Purpose </b> </p> <p> <xref href="GUID-EB52E7D5-55AE-3539-A212-AB2B5430D407.dita"><apiname>TLbsExternalRequestInfo2</apiname></xref> is an

extended request info class that derives from <xref href="GUID-D6E1F012-8C98-3B10-9601-3F665CFD5F08.dita"><apiname>TLbsExternalRequestInfo</apiname></xref>. </p> <p>A

Privacy Controller only needs to use this class if large buffers are used

to pass data across the <xref href="GUID-B3000A78-3BE5-5E0A-A718-87BC9BA03726.dita">Network

Privacy API</xref>. In other circumstances, the Privacy Controller need only

use the <codeph>TLbsExternalRequestInfo</codeph> class. </p> <p>The maximum

buffer sizes for <codeph>TLbsPrivacyRequestInfo</codeph> are defined as <xref href="GUID-966AD1BE-78A2-35A8-8BBF-FEC5E6515757.dita"><apiname>KLbsMaxRequesterIdSize</apiname></xref>, <xref href="GUID-CFB09B2C-7BB7-30CC-B914-AC809FD74FEC.dita"><apiname>KLbsMaxClientNameSize</apiname></xref> and <xref href="GUID-001E09F9-B7C6-36AC-8750-9E8AFD23A381.dita"><apiname>KLbsMaxClientExternalIdSize</apiname></xref> in <filepath>lbsprivacycontroller.h</filepath>. </p> <p> <codeph>TLbsPrivacyRequestInfo2</codeph> 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 <codeph>TLbsExternalRequestInfo2</codeph> are defined as <xref href="GUID-65A04124-8B71-3A21-9BE6-3A8E5C7EBB96.dita"><apiname>KLbsMaxRequesterIdSize2</apiname></xref> and <xref href="GUID-F87B009E-1DEC-327D-9496-3C277BFD1563.dita"><apiname>KLbsMaxClientNameSize2</apiname></xref> in <filepath>lbsprivacycontroller.h</filepath>. </p> <p><b>Usage </b> </p> <p>A Privacy Controller is always passed a <codeph>TLbsExternalRequestInfo</codeph> reference

when the LBS subsystem calls <xref href="GUID-76C6B540-DCA5-33CB-9ABD-8951A2F1DD5D.dita#GUID-76C6B540-DCA5-33CB-9ABD-8951A2F1DD5D/GUID-74F567E4-1BD8-38A0-AF7E-51031DBFA625"><apiname>MLbsPrivacyObserver::ProcessNetworkLocationRequest()</apiname></xref>.

However this reference may be to a derived <codeph>TLbsExternalRequestInfo2</codeph> object.

The following cases should be considered: </p> <ol id="GUID-C99A3C03-05F2-581A-8761-F483C944C51F">

<li id="GUID-F7D86881-C56E-59AA-9117-40AB342E3970"><p>LBS is being used in

the <xref href="GUID-D18B4715-3942-52EA-9D2F-E145037FA47A.dita">Full LBS configuration</xref>. </p> <p>The

Privacy Controller can use the <codeph>TLbsExternalRequestInfo</codeph> reference

parameter directly without casting it. </p> </li>

<li id="GUID-20CB3AB4-760C-514B-A491-2B3AEB0271BC"><p>LBS is being used in

the <xref href="GUID-D18B4715-3942-52EA-9D2F-E145037FA47A.dita">Standalone Privacy

Mode configuration</xref> (the <xref href="GUID-B3000A78-3BE5-5E0A-A718-87BC9BA03726.dita">Network

Privacy API</xref> is used to send privacy requests into the LBS subsystem): </p> <ul>

<li id="GUID-87A8E1C7-7ABC-5A50-B08E-6E2FDC2A39D2"><p>If buffers no larger

than <codeph>KLbsMaxRequesterIdSize</codeph> and <codeph>KLbsMaxClientNameSize</codeph> are

used by the licensee across the Network Privacy API then the Privacy Controller

can use the <codeph>TLbsExternalRequestInfo</codeph> reference parameter directly

without casting it. </p> </li>

<li id="GUID-29785BFB-1EF7-5F63-B392-C2E03BC174F0"><p>If larger buffers up

to <codeph>KLbsMaxRequesterIdSize2</codeph> and <codeph>KLbsMaxClientNameSize2</codeph> in

size are used across the Network Privacy API then the Privacy Controller must

cast the <codeph>TLbsExternalRequestInfo</codeph> reference parameter to derived

class <codeph>TLbsExternalRequestInfo2</codeph> before using it. Failure to

cast to the derived class may result in truncated data being returned from

the accessor functions <xref href="GUID-D6E1F012-8C98-3B10-9601-3F665CFD5F08.dita#GUID-D6E1F012-8C98-3B10-9601-3F665CFD5F08/GUID-E486B61F-FF83-3D6D-BA83-1A9839AE4090"><apiname>TLbsExternalRequestInfo::GetClientName()</apiname></xref> and <xref href="GUID-D6E1F012-8C98-3B10-9601-3F665CFD5F08.dita#GUID-D6E1F012-8C98-3B10-9601-3F665CFD5F08/GUID-DAE108AE-80F4-3136-B7A4-BF2E50A76864"><apiname>TLbsExternalRequestInfo::GetRequesterId()</apiname></xref>. </p> </li>

</ul> </li>

</ol> <p> <xref href="GUID-3078D198-0FCB-58A0-8152-9CD319906D58.dita#GUID-3078D198-0FCB-58A0-8152-9CD319906D58/GUID-38E5625D-FFA4-56E2-97C8-12A5D1C361E4">How

to use the LBS Privacy Controller API</xref> gives an example of how to use <codeph>TLbsExternalRequestInfo</codeph> and <codeph>TLbsExternalRequestInfo2</codeph>. </p> </section>

<section id="GUID-40428027-BCF1-5A37-B3A8-E1DC9A37CD7A"><title>Sequence Diagrams</title> <p>This

section describes the main use cases for the Privacy Controller API. A set

of sequence diagrams explain the behaviour of the API. </p> <p>Note that these

use cases and sequences only document Privacy Controller behaviour with the <xref href="GUID-D18B4715-3942-52EA-9D2F-E145037FA47A.dita">Full LBS configuration</xref> (in

which the LBS subsystem handles both privacy requests and location calculations). </p> <p>For

sequences that describe the behaviour of a Privacy Controller with the Network

Privacy API in the <xref href="GUID-D18B4715-3942-52EA-9D2F-E145037FA47A.dita">Standalone

Privacy Mode configuration</xref> see the <xref href="GUID-B3000A78-3BE5-5E0A-A718-87BC9BA03726.dita">Network

Privacy API</xref> documentation. </p> <p>The following are the main use cases

involving a Privacy Controller and the LBS subsystem: </p> <ul>

<li id="GUID-388F8613-29AD-500F-B947-4585D85DC610"><p><xref href="GUID-D857413A-D5A1-5F9F-A780-C980A9E0BEE0.dita#GUID-D857413A-D5A1-5F9F-A780-C980A9E0BEE0/GUID-5D870ABF-549C-5CB1-902C-D0E644E29E49">Privacy verification request</xref>  </p> <p>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. </p> </li>

<li id="GUID-97DCDF97-F425-5B3E-AE96-91C1E451D4DC"><p><xref href="GUID-D857413A-D5A1-5F9F-A780-C980A9E0BEE0.dita#GUID-D857413A-D5A1-5F9F-A780-C980A9E0BEE0/GUID-227497D1-D8A7-579F-8B46-629D9833B6EC">Privacy notification request</xref>  </p> <p>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. </p> </li>

<li id="GUID-9F36ADFB-8036-5FC7-B447-945B5FA20B7A"><p><xref href="GUID-D857413A-D5A1-5F9F-A780-C980A9E0BEE0.dita#GUID-D857413A-D5A1-5F9F-A780-C980A9E0BEE0/GUID-2552D9A2-4563-58DC-80FE-AEE7797CFB28">Privacy verification request is cancelled</xref>  </p> <p>The network can

send a message to cancel an outstanding privacy request. </p> </li>

</ul> <p><b>Sequence Diagrams </b> </p> <p>These sequence diagrams describe the interaction

of a Privacy Controller with the LBS subsystem in the <xref href="GUID-D18B4715-3942-52EA-9D2F-E145037FA47A.dita">Full

LBS configuration</xref>. See <xref href="GUID-B3000A78-3BE5-5E0A-A718-87BC9BA03726.dita">Network

Privacy API</xref> documentation for sequences that describe Privacy Controller

interaction with the Network Privacy API. </p> <p id="GUID-5D870ABF-549C-5CB1-902C-D0E644E29E49"><b> Privacy verification request

(request accepted, rejected or timeout)</b> </p> <p>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. </p> <fig id="GUID-3EB95BD2-B78C-5A40-8239-D06C8F95273C">

<title>                 Figure 4.1 Privacy verification               </title>

<image href="GUID-2B5C905C-CEE7-5B7B-8143-A73D3352949A_d0e441678_href.png" placement="inline"/>

</fig> <p id="GUID-227497D1-D8A7-579F-8B46-629D9833B6EC"><b> Privacy notification request</b> </p> <p>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. </p> <fig id="GUID-EA3FA6C0-10C4-57D4-A44E-D6F1C705E149">

<title>                 Figure 4.2. Privacy notification               </title>

<image href="GUID-A6598739-2BB5-546E-931B-B202E3DD49E0_d0e441694_href.png" placement="inline"/>

</fig> <p id="GUID-2552D9A2-4563-58DC-80FE-AEE7797CFB28"><b>Privacy verification request

is cancelled</b> </p> <p>Figure 4.3 shows the case when a privacy verification

request is cancelled. </p> <fig id="GUID-16093966-FFB9-53A8-9612-2B8F06FF616E">

<title>                 Figure 4.3. Privacy verification is cancelled    

          </title>

<image href="GUID-BAD38A27-5A46-5A72-B0AD-A095C207CD2B_d0e441710_href.png" placement="inline"/>

</fig> </section>

</conbody><related-links>

<linklist>

<link href="GUID-CB6B4D1A-ACB9-5571-8C23-4BC095209782.dita"><linktext>Network Protocol

Module API</linktext></link>

<link href="GUID-B3000A78-3BE5-5E0A-A718-87BC9BA03726.dita"><linktext>Network Privacy

API</linktext></link>

<link href="GUID-E1710E40-B8F5-5CF8-B9FE-698869A1770F.dita"><linktext>Privacy Request

API</linktext></link>

</linklist>

</related-links></concept>