|
1 <?xml version="1.0" encoding="utf-8"?> |
|
2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. --> |
|
3 <!-- This component and the accompanying materials are made available under the terms of the License |
|
4 "Eclipse Public License v1.0" which accompanies this distribution, |
|
5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". --> |
|
6 <!-- Initial Contributors: |
|
7 Nokia Corporation - initial contribution. |
|
8 Contributors: |
|
9 --> |
|
10 <!DOCTYPE concept |
|
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
|
12 <concept id="GUID-D01CE5F5-CC66-4976-B67F-A6D2E02FFEA5" xml:lang="en"><title>Implementing |
|
13 the MLbsPrivacyObserver Methods</title><shortdesc>A Privacy Controller must implement the virtual functions of the <apiname>MLbsPrivacyObserver</apiname> interface |
|
14 (and the shutdown function of the <apiname>MLbsPrivacyObserver2</apiname> interface |
|
15 if appropriate). </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
16 <p>Note that because the design of a Privacy Controller is a licensee task, |
|
17 it is only possible to describe the implementation of these functions in broad |
|
18 outline here. <xref href="GUID-76C6B540-DCA5-33CB-9ABD-8951A2F1DD5D.dita"><apiname>MLbsPrivacyObserver</apiname></xref> defines three methods: </p> |
|
19 <ul> |
|
20 <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 |
|
21 called to process a privacy request. The code example below shows the following:</p><ul> |
|
22 <li><p>How the encoding of the requester ID and client name parameters (as |
|
23 defined by 3GPP specifications) can be obtained from the <codeph>TLbsExternalRequestInfo</codeph> parameter. |
|
24 The parameter encoding schemes are defined by <codeph>TLbsExternalRequestInfo::_TCodingScheme</codeph>. </p></li> |
|
25 <li><p>How the format of the requester ID and client name parameters are obtained. |
|
26 The formats are defined by <codeph>TLbsExternalRequestInfo::_TFormatIndicator</codeph>. </p><p>The |
|
27 parameter <codeph>aRequestId</codeph> is a unique identifier for a privacy |
|
28 request.</p><p>The parameter <codeph>aNotifyType</codeph> specifies whether |
|
29 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 |
|
30 void CMyLbsPrivacyControllerObserver::ProcessNetworkLocationRequest |
|
31 (TUint aRequestId, const TLbsExternalRequestInfo& aRequestInfo, |
|
32 const TNotificationType& aNotifyType) |
|
33 { |
|
34 // Get the Requester Id, Client name and external requester Id as specified by 3GPP specifications |
|
35 |
|
36 // Coding scheme and format for the requester id and client name |
|
37 TLbsExternalRequestInfo::TCodingScheme requesterIdScheme, nameScheme; |
|
38 TLbsExternalRequestInfo::TFormatIndicator requesterIdFormat, nameFormat; |
|
39 |
|
40 // Get the coding schemes for the requester ID and the client name |
|
41 requesterIdScheme = aRequestInfo.RequesterIdCodingScheme(); |
|
42 nameScheme = aRequestInfo.ClientNameCodingScheme(); |
|
43 |
|
44 // Get the data format for the requester ID and the client name |
|
45 requesterIdFormat = aRequestInfo.RequesterIdFormat(); |
|
46 nameFormat = aRequestInfo.ClientNameFormat(); |
|
47 |
|
48 TLbsClientName clientName; |
|
49 TLbsRequesterId requesterId; |
|
50 TLbsClientExternalId externalId; |
|
51 |
|
52 // Get the ids and client name from the request info object |
|
53 aRequestInfo.GetClientName(clientName); |
|
54 aRequestInfo.GetRequesterId(requesterId); |
|
55 aRequestInfo.GetClientExternalId(externalId); |
|
56 |
|
57 // Check the encoding schemes of requesterId and clientScheme |
|
58 switch (requesterIdScheme) |
|
59 { |
|
60 case TLbsExternalRequestInfo::ECodingSchemeUCS2 : |
|
61 |
|
62 /* |
|
63 Handle any character conversion that may |
|
64 be required by the licensee Privacy Controller |
|
65 Details are licensee specific... |
|
66 */ |
|
67 |
|
68 break; |
|
69 |
|
70 case TLbsExternalRequestInfo::ECodingSchemeUTF8: |
|
71 |
|
72 /* |
|
73 Handle any character conversion that may |
|
74 be required by the licensee Privacy Controller |
|
75 Details are licensee specific... |
|
76 */ |
|
77 |
|
78 break; |
|
79 |
|
80 case TLbsExternalRequestInfo::ECodingSchemeGSMDefault : |
|
81 |
|
82 /* |
|
83 Handle any character conversion that may |
|
84 be required by the licensee Privacy Controller |
|
85 Details are licensee specific... |
|
86 */ |
|
87 |
|
88 break; |
|
89 |
|
90 } |
|
91 |
|
92 /* |
|
93 And similar to the above for the clientName parameter |
|
94 Details omitted... |
|
95 */ |
|
96 |
|
97 /* |
|
98 Check the format of the data held by requesterId and clientName |
|
99 e.g. Email address, MSISDN etc. |
|
100 */ |
|
101 |
|
102 switch (requesterIdFormat) |
|
103 { |
|
104 case TLbsExternalRequestInfo::EFormatLogicalName : |
|
105 |
|
106 /* |
|
107 requesterId is a name |
|
108 Licensee Privacy Controller can use the name to lookup the user in contacts |
|
109 or format it for display to the user |
|
110 Implementation details omitted... |
|
111 */ |
|
112 |
|
113 break; |
|
114 |
|
115 case TLbsExternalRequestInfo::EFormatEmailAddress : |
|
116 |
|
117 /* |
|
118 requesterId is an email address |
|
119 Licensee Privacy Controller can use the email address to lookup the user in contacts |
|
120 or format it for display to the user |
|
121 Implementation details omitted... |
|
122 */ |
|
123 |
|
124 break; |
|
125 |
|
126 /* |
|
127 And so on to check for the other possible formats |
|
128 defined in TLbsExternalRequestInfo::_TFormatIndicator |
|
129 ... |
|
130 |
|
131 */ |
|
132 } |
|
133 |
|
134 /* |
|
135 After getting the data encoding and the data format, the Privacy Controller |
|
136 can either : |
|
137 |
|
138 1. Automatically process the privacy request based on privacy rules |
|
139 2. Use privacy dialogs to obtain a response from the user |
|
140 3. Some combination of 1 & 2 |
|
141 |
|
142 These are implementation details for the licensee... |
|
143 */ |
|
144 }</codeblock><p>As described in LBS <xref href="GUID-D857413A-D5A1-5F9F-A780-C980A9E0BEE0.dita">Privacy |
|
145 Controller</xref>, when LBS is configured in the <xref href="GUID-3618ECE9-C22B-5AE2-837E-FEBC55D42330.dita">Standalone |
|
146 Privacy Mode</xref> configuration it is possible for large buffers to be passed |
|
147 over the <xref href="GUID-B3000A78-3BE5-5E0A-A718-87BC9BA03726.dita">Network Privacy |
|
148 API</xref> from the licensee domestic operating system into Symbian LBS. In |
|
149 this case it is necessary to cast the received <codeph>TLbsExternalRequestInfo</codeph> reference |
|
150 to a <codeph>TLbsExternalRequestInfo2</codeph> reference before using it. |
|
151 Failure to do so may result in truncated data being returned if the length |
|
152 of the requester descriptors exceeds the size of the buffers in <codeph>TLbsExternalRequestInfo</codeph>. |
|
153 A simple static case is required:</p><codeblock xml:space="preserve">const TLbsExternalRequestInfo2& info = static_cast<const TLbsExternalRequestInfo2&>(aRequestInfo); |
|
154 |
|
155 // Now use info instead of aRequestInfo...</codeblock></li> |
|
156 </ul></li> |
|
157 <li><p><codeph>MLbsPrivacyObserver::ProcessNetworkPositionUpdate()</codeph> notifies |
|
158 the Privacy Controller that a position fix has been calculated or received |
|
159 from the network. When a Privacy Controller receives such a notification a |
|
160 licensee can choose to notify the user. The parameter <codeph>aRequestId</codeph> associates |
|
161 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 |
|
162 void CMyLbsPrivacyControllerObserver::ProcessNetworkPositionUpdate(TUint aRequestId, |
|
163 const TPositionInfo& aPosInfo) |
|
164 { |
|
165 /* |
|
166 A Privacy Controller is informed when the LBS subsystem calculates or receives a position update |
|
167 The user can be informed if the licensee chooses to do so |
|
168 |
|
169 This is an implementation task for the licensee... |
|
170 */ |
|
171 }</codeblock></li> |
|
172 <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 |
|
173 the Privacy Controller that the privacy request uniquely identified by <codeph>aRequestId</codeph> is |
|
174 complete. The parameter <codeph>aReason</codeph> specifies why the request |
|
175 was completed and is <codeph>KErrNone</codeph> for normal processing, <codeph>KErrCancel</codeph> if |
|
176 the network cancels the request or <codeph>KErrTimedOut</codeph> if the network |
|
177 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 |
|
178 void CMyLbsPrivacyControllerObserver::ProcessRequestComplete(TUint aRequestId, TInt aReason) |
|
179 { |
|
180 /* |
|
181 The LBS subsystem notifies the Privacy Controller |
|
182 when a request is complete |
|
183 */ |
|
184 }</codeblock></li> |
|
185 </ul> |
|
186 <section> <title>Implementing the MLbsPrivacyObserver2 shutdown method</title> |
|
187 <p>A Privacy Controller observer must implement <xref href="GUID-BF88837F-1ADC-3DB2-98E5-CFBF75E2BE86.dita"><apiname>MLbsPrivacyObserver2</apiname></xref> if |
|
188 it is to receive notice to shutdown when the LBS subsystem shuts down (this |
|
189 is only supported in the LBS <xref href="GUID-3618ECE9-C22B-5AE2-837E-FEBC55D42330.dita">Standalone |
|
190 Privacy Mode</xref> configuration). The implementation should |
|
191 ensure that any owned resources are freed. </p><codeblock xml:space="preserve">// Privacy Controller is told to shutdown |
|
192 |
|
193 void CMyLbsPrivacyControllerObserver2::ProcessCloseDownNotification() |
|
194 { |
|
195 /* |
|
196 Free up all resources allocated by the Privacy Controller |
|
197 such as dialog resources, file sessions etc. |
|
198 |
|
199 The implementation of this method is specific |
|
200 to the licensee Privacy Controller, but all owned resources must be freed |
|
201 */ |
|
202 }</codeblock> </section> |
|
203 </conbody></concept> |