<?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-D01CE5F5-CC66-4976-B67F-A6D2E02FFEA5" xml:lang="en"><title>Implementing

the MLbsPrivacyObserver Methods</title><shortdesc>A Privacy Controller must implement the virtual functions of the <codeph>MLbsPrivacyObserver</codeph> interface

(and the shutdown function of the <codeph>MLbsPrivacyObserver2</codeph> interface

if appropriate).   </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>Note that because the design of a Privacy Controller is a licensee task,

it is only possible to describe the implementation of these functions in broad

outline here. <xref href="GUID-76C6B540-DCA5-33CB-9ABD-8951A2F1DD5D.dita"><apiname>MLbsPrivacyObserver</apiname></xref> defines three methods: </p>

<ul>

<li><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 to process a privacy request. The code example below shows the following:</p><ul>

<li><p>How the encoding of the requester ID and client name parameters (as

defined by 3GPP specifications) can be obtained from the <codeph>TLbsExternalRequestInfo</codeph> parameter.

The parameter encoding schemes are defined by <codeph>TLbsExternalRequestInfo::_TCodingScheme</codeph>. </p></li>

<li><p>How the format of the requester ID and client name parameters are obtained.

The formats are defined by <codeph>TLbsExternalRequestInfo::_TFormatIndicator</codeph>. </p><p>The

parameter <codeph>aRequestId</codeph> is a unique identifier for a privacy

request.</p><p>The parameter <codeph>aNotifyType</codeph> specifies whether

the request is a privacy verification request or a privacy notification request.</p><codeblock xml:space="preserve">// Process a privacy verification request or a location notification request

void CMyLbsPrivacyControllerObserver::ProcessNetworkLocationRequest

   (TUint aRequestId, const TLbsExternalRequestInfo& aRequestInfo,

    const TNotificationType& aNotifyType)

	{

	// Get the Requester Id, Client name and external requester Id as specified by 3GPP specifications

	// Coding scheme and format for the requester id and client name

	TLbsExternalRequestInfo::TCodingScheme requesterIdScheme, nameScheme;

	TLbsExternalRequestInfo::TFormatIndicator requesterIdFormat, nameFormat;

	// Get the coding schemes for the requester ID and the client name

	requesterIdScheme = aRequestInfo.RequesterIdCodingScheme();

	nameScheme = aRequestInfo.ClientNameCodingScheme();

	// Get the data format for the requester ID and the client name

	requesterIdFormat = aRequestInfo.RequesterIdFormat();

	nameFormat = aRequestInfo.ClientNameFormat();

	TLbsClientName clientName;

	TLbsRequesterId requesterId;

	TLbsClientExternalId externalId;

	// Get the ids and client name from the request info object

	aRequestInfo.GetClientName(clientName);

	aRequestInfo.GetRequesterId(requesterId);

	aRequestInfo.GetClientExternalId(externalId);

	// Check the encoding schemes of requesterId and clientScheme

	switch (requesterIdScheme)

		{

		case TLbsExternalRequestInfo::ECodingSchemeUCS2 :

		/*

		Handle any character conversion that may

		be required by the licensee Privacy Controller

		Details are licensee specific...

		*/

		break;

		case TLbsExternalRequestInfo::ECodingSchemeUTF8:

		/*

		Handle any character conversion that may

		be required by the licensee Privacy Controller

		Details are licensee specific...

		*/

		break;

		case TLbsExternalRequestInfo::ECodingSchemeGSMDefault :

		/*

		Handle any character conversion that may

		be required by the licensee Privacy Controller

		Details are licensee specific...

		*/

		break;

		}

	/*

	And similar to the above for the clientName parameter

	Details omitted...

 */

 /*

	Check the format of the data held by requesterId and clientName

	e.g. Email address, MSISDN etc.

	*/

	switch (requesterIdFormat)

		{

		case TLbsExternalRequestInfo::EFormatLogicalName :

			/*

			requesterId is a name

			Licensee Privacy Controller can use the name to lookup the user in contacts

			or format it for display to the user

			Implementation details omitted...

			*/

			break;

		case TLbsExternalRequestInfo::EFormatEmailAddress :

			/*

			requesterId is an email address

			Licensee Privacy Controller can use the email address to lookup the user in contacts

			or format it for display to the user

			Implementation details omitted...

			*/

			break;

			/*

			And so on to check for the other possible formats

			defined in TLbsExternalRequestInfo::_TFormatIndicator

	  ...

			*/

		}

	/*

	 After getting the data encoding and the data format, the Privacy Controller

	 can either :

	 1. Automatically process the privacy request based on privacy rules

	 2. Use privacy dialogs to obtain a response from the user

	 3. Some combination of 1 & 2

	 These are implementation details for the licensee...

	*/ 

	}</codeblock><p>As described in LBS <xref href="GUID-D857413A-D5A1-5F9F-A780-C980A9E0BEE0.dita">Privacy

Controller</xref>, when LBS is configured in the <xref href="GUID-3618ECE9-C22B-5AE2-837E-FEBC55D42330.dita">Standalone

Privacy Mode</xref> configuration it is possible for large buffers to be passed

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

API</xref> from the licensee domestic operating system into Symbian LBS. In

this case it is necessary to cast the received <codeph>TLbsExternalRequestInfo</codeph> reference

to a <codeph>TLbsExternalRequestInfo2</codeph> reference before using it.

Failure to do so may result in truncated data being returned if the length

of the requester descriptors exceeds the size of the buffers in <codeph>TLbsExternalRequestInfo</codeph>.

A simple static case is required:</p><codeblock xml:space="preserve">const TLbsExternalRequestInfo2&amp; info = static_cast&lt;const TLbsExternalRequestInfo2&amp;&gt;(aRequestInfo);

// Now use info instead of aRequestInfo...</codeblock></li>

</ul></li>

<li><p><codeph>MLbsPrivacyObserver::ProcessNetworkPositionUpdate()</codeph> notifies

the Privacy Controller that a position fix has been calculated or received

from the network. When a Privacy Controller receives such a notification a

licensee can choose to notify the user. The parameter <codeph>aRequestId</codeph> associates

a position update with a previous <xref href="GUID-0592B2C5-15A4-3574-9844-10CCF418DAA4.dita"><apiname>ProcessNetworkLocationRequest()</apiname></xref> call. </p><codeblock xml:space="preserve">// Handle notification of a position update

void CMyLbsPrivacyControllerObserver::ProcessNetworkPositionUpdate(TUint aRequestId, 

                                                                   const TPositionInfo& aPosInfo)

	{

		/*

		A Privacy Controller is informed when the LBS subsystem calculates or receives a position update

		The user can be informed if the licensee chooses to do so

	    This is an implementation task for the licensee...

	 */

	}</codeblock></li>

<li><p><xref href="GUID-76C6B540-DCA5-33CB-9ABD-8951A2F1DD5D.dita#GUID-76C6B540-DCA5-33CB-9ABD-8951A2F1DD5D/GUID-B800119C-C15A-3FCE-9CEE-DCDA72499CC4"><apiname>MLbsPrivacyObserver::ProcessNetworkRequestComplete()</apiname></xref> notifies

the Privacy Controller that the privacy request uniquely identified by <codeph>aRequestId</codeph> is

complete. The parameter <codeph>aReason</codeph> specifies why the request

was completed and is <codeph>KErrNone</codeph> for normal processing, <codeph>KErrCancel</codeph> if

the network cancels the request or <codeph>KErrTimedOut</codeph> if the network

times out the request because the Privacy Controller has not returned a response. </p><codeblock xml:space="preserve">// Privacy controller is notified that a request is completed

void CMyLbsPrivacyControllerObserver::ProcessRequestComplete(TUint aRequestId, TInt aReason)

	{

		/*

		The LBS subsystem notifies the Privacy Controller 

		when a request is complete

		*/

	}</codeblock></li>

</ul>

<section id="GUID-3420C82C-9B15-43A6-89BC-32B23A368041">       <title>Implementing the MLbsPrivacyObserver2 shutdown method</title> 

     <p>A Privacy Controller observer must implement <xref href="GUID-BF88837F-1ADC-3DB2-98E5-CFBF75E2BE86.dita"><apiname>MLbsPrivacyObserver2</apiname></xref> if

it is to receive notice to shutdown when the LBS subsystem shuts down (this

is only supported in the LBS <xref href="GUID-3618ECE9-C22B-5AE2-837E-FEBC55D42330.dita">Standalone

Privacy Mode</xref> configuration). The implementation should ensure that

any owned resources are freed. </p><codeblock xml:space="preserve">// Privacy Controller is told to shutdown

void CMyLbsPrivacyControllerObserver2::ProcessCloseDownNotification()

	{

		/*

		Free up all resources allocated by the Privacy Controller

		such as dialog resources, file sessions etc.

		The implementation of this method is specific

		to the licensee Privacy Controller, but all owned resources must be freed

		*/

	}</codeblock>     </section>

</conbody></concept>