<?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-ACD9E338-DF75-5811-B696-C3900B498218" xml:lang="en"><title>Privacy

Requester Classes</title><shortdesc>This document describes the classes that were used in earlier versions

of the Symbian platform to identify the requester of location information

to the LBS subsystem. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>Use of these classes is now optional. It is recommended that you still

use them if your LBS applications must run on devices based on earlier versions

of Symbian. </p>

<section><title>Purpose</title> <p>The privacy requester classes were defined

as part of the Location Acquisition API before platform security was introduced

in Symbian OS v9. On all platforms based on Symbian OS v9 and later, client

applications are required to have the <codeph>Location</codeph> capability

to use the Location Acquisition API. Platform security checks fulfil much

of the role of the privacy requester classes. </p> </section>

<section><title>Privacy requester classes</title> <p>This section describes

the privacy requester classes. </p> <p><b>Class

description</b> </p> <p>Figure 1 shows the Privacy classes provided by the

Location Acquisition API. </p> <fig id="GUID-BE65E6CB-5286-5DFE-B50C-8C088960432B">

<title>                 Figure 1. Location Acquisition API privacy classes.

              </title>

<image href="GUID-24F464D8-36C1-592A-9BDB-673E771A5707_d0e270493_href.png" placement="inline"/>

</fig> <p>A requester is defined as an agent

that requests location information. There are two requester types: </p> <ul>

<li id="GUID-79C7473E-C3DD-5011-BE50-F8D1075E9B07"><p>Service requesters </p> <p>A

service requester represents any terminal or network application or service. </p> </li>

<li id="GUID-FCEA02C9-CB00-5BD4-89FB-55D703DDE0B4"><p>Contact requesters </p> <p>A

contact requester represents an individual person requesting the location. </p> </li>

</ul> <p> <xref href="GUID-AA0D6BF8-DFD6-3A6D-8366-CFCB301D17CA.dita#GUID-AA0D6BF8-DFD6-3A6D-8366-CFCB301D17CA/GUID-B484D0AF-BEB1-3D08-8D14-8E510AB8C465"><apiname>CRequestor::RequestorType()</apiname></xref> defines the type

of the requester. The requester information is sent to Location Server before

requesting location estimates. </p> <p><b>Defining

requesters</b> </p> <p>Requesters may be defined in one of two ways: </p> <p><b>Defining a single requester</b> </p> <p>A single requester is defined by

calling <xref href="GUID-1EAEB7EF-0AC7-37C7-B35F-C9B780FFC575.dita#GUID-1EAEB7EF-0AC7-37C7-B35F-C9B780FFC575/GUID-E1B082DC-9C01-3852-B1D8-B2FD18235319"><apiname>RPositioner::SetRequestorL()</apiname></xref>. The method signature

is: <codeph>TInt SetRequestor(CRequestor::TRequestorType aType,          

      CRequestor::TRequestorFormat aFormat, const TDesC&             

   aData)</codeph>. </p> <p>The requester is defined directly by the values

supplied to the function’s parameters. This case is used by applications or

services if they are the only request source. </p> <p> <xref href="GUID-AA0D6BF8-DFD6-3A6D-8366-CFCB301D17CA.dita#GUID-AA0D6BF8-DFD6-3A6D-8366-CFCB301D17CA/GUID-5EE5AFBF-D212-34A9-8DF5-9B193673FA3F"><apiname>CRequestor::TRequestorType</apiname></xref> defines

the type of requester: a service or contact. </p> <p> <xref href="GUID-AA0D6BF8-DFD6-3A6D-8366-CFCB301D17CA.dita#GUID-AA0D6BF8-DFD6-3A6D-8366-CFCB301D17CA/GUID-EF476AFD-2F46-39FA-B6E2-74759B549223"><apiname>CRequestor::TRequestorFormat</apiname></xref> defines

the format of the requester identifier passed in <codeph>aData</codeph>: an

application name, contact, email address etc. </p> <p><b>Defining a stack of requesters</b> </p> <p>If an application requests

location information on behalf of another agent or agents, it can specify

the chain of requesters by calling a second variant of <xref href="GUID-1EAEB7EF-0AC7-37C7-B35F-C9B780FFC575.dita#GUID-1EAEB7EF-0AC7-37C7-B35F-C9B780FFC575/GUID-E1B082DC-9C01-3852-B1D8-B2FD18235319"><apiname>RPositioner::SetRequestorL()</apiname></xref>.

The method signature is: <codeph>TInt SetRequestor(const                 RRequestorStack&amp;

aRequestorStack)</codeph>  </p> <p> <xref href="GUID-BAB32310-D928-3314-B253-9685721EABE0.dita"><apiname>RRequestorStack</apiname></xref> is

a container for a list of the requesters on behalf of which the request is

made. Each requester in the stack is represented by a <xref href="GUID-AA0D6BF8-DFD6-3A6D-8366-CFCB301D17CA.dita"><apiname>CRequestor</apiname></xref> class. </p> <p>Note: Regardless of the number of requesters, there is always one service

requester, because the application executing the location request must be

always shown, even if it made the request on behalf of a contact requester.

For this reason, the last item in the requester stack must always be a service

requester (type <xref href="GUID-B59CCB2E-400A-3359-B27D-06F75AC588A6.dita#GUID-B59CCB2E-400A-3359-B27D-06F75AC588A6/GUID-33B2120D-3388-304B-A0DC-E08F86F696FB"><apiname>CRequestorBase::ERequestorService</apiname></xref>). </p> </section>

</conbody><related-links>

<link href="GUID-70E1117B-17F0-5CF4-A5D0-35D3BEBB0FEA.dita"><linktext>Position

Area Data Classes</linktext></link>

</related-links></concept>