<?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&amp; aRequestInfo,
    const TNotificationType&amp; 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 &amp; 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&amp; 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>