--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/PDK/Source/GUID-D01CE5F5-CC66-4976-B67F-A6D2E02FFEA5.dita Fri Jan 22 18:26:19 2010 +0000
@@ -0,0 +1,203 @@
+<?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 <apiname>MLbsPrivacyObserver</apiname> interface
+(and the shutdown function of the <apiname>MLbsPrivacyObserver2</apiname> 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& info = static_cast<const TLbsExternalRequestInfo2&>(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> <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>
\ No newline at end of file