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 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_d0e434787_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_d0e435061_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_d0e435114_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
> 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 < 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_d0e436090_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_d0e436106_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_d0e436122_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>