--- a/Symbian3/PDK/Source/GUID-B3000A78-3BE5-5E0A-A718-87BC9BA03726.dita Fri Jul 02 12:51:36 2010 +0100
+++ b/Symbian3/PDK/Source/GUID-B3000A78-3BE5-5E0A-A718-87BC9BA03726.dita Fri Jul 16 17:23:46 2010 +0100
@@ -12,9 +12,9 @@
<concept xml:lang="en" id="GUID-B3000A78-3BE5-5E0A-A718-87BC9BA03726"><title>Network Privacy API</title><shortdesc>The Network Privacy API is an interface through which the LBS subsystem can receive and respond to privacy requests when it is built to include the <codeph>Privacy
Protocol Module</codeph>. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody><section><title>Introduction</title> <p>The Network Privacy API supports device creators who wish to use the Symbian LBS subsystem to handle only privacy requests but not to perform position fix calculations. </p> <p>The Network Privacy API is intended to be used to process privacy requests received from the network. To process multiple privacy requests from local applications, it is recommended that the Privacy Request API be used. </p> </section> <section><title>Description</title> <p>The Network Privacy API is implemented on the client-side by the Network Privacy Client DLL. This DLL is the interface to the Privacy Protocol Module. </p> <p>The Network Privacy API does not guarantee performance in low memory conditions for which a privacy request may fail. For this reason the Privacy Protocol Module must not be used when there is a need to support emergency services privacy requests from the network (MT-LR or NI-LR). A Protocol Module that handles location requests must be used if emergency services requests must be supported. </p> <p>Figure 1 shows the Network Privacy Client DLL in the context of the LBS subsystem. The most important points to note are: </p> <ul><li id="GUID-7C4EBECC-F64C-5A5C-908C-F3F3A452B43B"><p>The Network Privacy Client DLL exposes the Network Privacy API which is described in this document. The DLL is used to send privacy requests into the Symbian LBS subsystem from a component running in the licensee's domestic OS (outside of the Symbian platform). </p> </li> <li id="GUID-3AE2940E-C6B2-5512-99DB-0F9EFC42D2C0"><p>The Network Privacy Client DLL connects to a server implementation in the Privacy Protocol Module. </p> </li> <li id="GUID-1B984C37-C187-5927-9660-1C5C7F232F0C"><p>A device creator does not create their own implementation of the Network Privacy Client DLL or the Privacy Protocol Module. A device creator chooses to build a ROM containing the Privacy Protocol Module and the Network Privacy Client DLL. See <xref href="GUID-D18B4715-3942-52EA-9D2F-E145037FA47A.dita">LBS Integration and Configuration Guide</xref> for more information about building and configuring the LBS subsystem. </p> </li> <li id="GUID-AA6B5EB8-5F24-5747-9311-0A79DC13E2CD"><p>To use the Network Privacy API a device creator must implement some kind of client process in their domestic operating system which uses the Network Privacy API. </p> <p>The Network Privacy API client process must implement the API observer interface to receive privacy responses. The client process, and not Symbian LBS is responsible for sending these privacy responses to the network. </p> </li> </ul> <fig id="GUID-707F7508-95E6-5700-A39C-3DE5DF745F51"><title>
Figure 1. The Network Privacy API and the Privacy Protocol Module.
- </title> <image href="GUID-1B07A953-D652-59A7-8863-32875955B837_d0e449475_href.png" placement="inline"/></fig> </section> <section><title/></section> <example><title>Network Privacy Client DLL responsibilities</title> <p>The Network Privacy Client DLL communicates with the Privacy Protocol Module via standard Symbian client-server IPC calls. The DLL performs <i>two</i> distinct functions: </p> <ol id="GUID-C6EC3041-31A5-53CC-BF07-60D3BA52E20D"><li id="GUID-F1E9C4FD-C3C0-5F34-9943-786F119EF8FB"><p>It starts up the LBS subsystem if it is not already running when the first privacy request is received via the Network Privacy API. <xref href="GUID-746866CE-809A-5598-BA60-2947763E5EE9.dita">Network Privacy API reference</xref> contains sequences describe startup and shutdown behaviour. </p> </li> <li id="GUID-06FD4BCA-BA94-5AFD-9399-817EBE6AC040"><p>It packages the Network Privacy API, which forwards privacy requests from a licensee client process into the Symbian LBS subsystem. Privacy responses returned from a Privacy Controller or Privacy Notifiers are returned to the client. </p> </li> </ol> </example> <section><title>Network Privacy API description</title> <p>Figure 2 shows the classes of the Network Privacy API. </p> <fig id="GUID-77AA24D8-875F-5447-B9F6-BFC5A0F8A7A3"><title>
+ </title> <image href="GUID-1B07A953-D652-59A7-8863-32875955B837_d0e455320_href.png" placement="inline"/></fig> </section> <section><title/></section> <example><title>Network Privacy Client DLL responsibilities</title> <p>The Network Privacy Client DLL communicates with the Privacy Protocol Module via standard Symbian client-server IPC calls. The DLL performs <i>two</i> distinct functions: </p> <ol id="GUID-C6EC3041-31A5-53CC-BF07-60D3BA52E20D"><li id="GUID-F1E9C4FD-C3C0-5F34-9943-786F119EF8FB"><p>It starts up the LBS subsystem if it is not already running when the first privacy request is received via the Network Privacy API. <xref href="GUID-746866CE-809A-5598-BA60-2947763E5EE9.dita">Network Privacy API reference</xref> contains sequences describe startup and shutdown behaviour. </p> </li> <li id="GUID-06FD4BCA-BA94-5AFD-9399-817EBE6AC040"><p>It packages the Network Privacy API, which forwards privacy requests from a licensee client process into the Symbian LBS subsystem. Privacy responses returned from a Privacy Controller or Privacy Notifiers are returned to the client. </p> </li> </ol> </example> <section><title>Network Privacy API description</title> <p>Figure 2 shows the classes of the Network Privacy API. </p> <fig id="GUID-77AA24D8-875F-5447-B9F6-BFC5A0F8A7A3"><title>
Figure 2. Network Privacy API classes
- </title> <image href="GUID-EFC72FB6-5FA0-537C-978D-50FC67A6F857_d0e449518_href.png" placement="inline"/></fig> <p>The following table lists the classes and types that define the Network Privacy API. Further details can be found by following the links to other sections of this document and to Symbian Developer Library reference documentation. </p> <p>The Network Privacy API has <codeph>publishedPartner</codeph> interface access. </p> <table id="GUID-2BB6D675-FE67-57CA-95E8-424DA0C2196A"><tgroup cols="3"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/><thead><row><entry>Class name</entry> <entry>Description</entry> <entry>Header file</entry> </row> </thead> <tbody><row><entry><p> <xref href="GUID-F5E959D8-3457-3385-9978-96FDD917D767.dita"><apiname>CPosNetworkPrivacy</apiname></xref> </p> </entry> <entry><p>Main interface class of the Network Privacy API </p> </entry> <entry><p> <filepath>EPos_CPosNetworkPrivacy.h</filepath> </p> </entry> </row> <row><entry><p> <xref href="GUID-9A3406EF-3FEF-3F6F-9CB1-DFC1D09782B6.dita"><apiname>MPosVerificationObserver</apiname></xref> </p> </entry> <entry><p>Observer class to be implemented by an API client </p> </entry> <entry><p> <filepath>EPos_MPosVerificationObserver.h</filepath> </p> </entry> </row> <row><entry><p> <xref href="GUID-B747E435-087F-3130-8847-25B83067F404.dita"><apiname>CPosNetworkPrivacyRequestInfo</apiname></xref> </p> </entry> <entry><p>Abstract base class for privacy request information </p> </entry> <entry><p> <filepath>EPos_CPosNetworkPrivacyRequestInfo.h</filepath> </p> </entry> </row> <row><entry><p> <xref href="GUID-32DA9EFC-D11D-3A56-A70E-045F7F0E849A.dita"><apiname>CPosGSMPrivacyRequestInfo</apiname></xref> </p> </entry> <entry><p>Request info class for requests from a GSM network </p> </entry> <entry><p> <filepath>EPos_CPosGSMPrivacyRequestInfo.h</filepath> </p> </entry> </row> <row><entry><p> <xref href="GUID-1C0102CD-2F1C-3E8C-9357-06CFED618936.dita"><apiname>CPosSUPLPrivacyRequestInfo</apiname></xref> </p> </entry> <entry><p>Request info class for requests received via SUPL </p> </entry> <entry><p> <filepath>EPos_CPosSUPLPrivacyRequestInfo.h</filepath> </p> </entry> </row> <row><entry><p> <xref href="GUID-0B022E16-132F-3B4F-B598-C5B83BA91E39.dita"><apiname>TPosNetworkPrivacyPanic</apiname></xref> </p> </entry> <entry><p>Panic codes used by the API </p> </entry> <entry><p> <filepath>EPos_NetworkPrivacyPanic.h</filepath> </p> </entry> </row> </tbody> </tgroup> </table> </section> <section><title>Libraries</title> <p>The Network Privacy API is packaged in <filepath>eposnwprv.dll</filepath>. Clients link to <filepath>eposnwprv.lib</filepath>. </p> </section> <section><title>Capabilities</title> <p>To use the Network Privacy API a client requires the following capabilities: <codeph>Location</codeph>, <codeph>NetworkServices</codeph> and <codeph>ReadDeviceData</codeph>. </p> <p>To maintain backwards compatibility with existing clients of the Network Privacy API the alternative capability <codeph>CommDD</codeph> is also supported. However, new clients should be created to have the three capabilities listed above. </p> </section> <section><title>LBS configuration</title> <p>The Network Privacy API is only available when the Privacy Protocol Module is included in an LBS subsystem. See <xref href="GUID-D18B4715-3942-52EA-9D2F-E145037FA47A.dita">LBS Integration and Configuration Guide</xref> for details about how to build a ROM image that supports the Network Privacy API. </p> <p><b>Multiple simultaneous privacy requests</b> </p> <p>The LBS subsystem can be configured to handle multiple simultaneous privacy requests from the Network Privacy API. The <xref href="GUID-23BBC1D8-B3A0-5148-A4F1-22ECF3043E4E.dita">LBS Administration</xref> setting <xref href="GUID-6D5954C5-3B6A-3BAA-AB75-D1ECE90BAEDB.dita"><apiname>KLbsSettingMaximumExternalLocateRequests</apiname></xref> defines the maximum number of privacy requests that can be handled simultaneously by the LBS subsystem. </p> <p>If an additional privacy request is sent into the LBS subsystem such that the total number of requests exceeds <codeph>KLbsSettingMaximumExternalLocateRequests</codeph>, the additional request is always rejected i.e. the LBS subsystem calls <xref href="GUID-9A3406EF-3FEF-3F6F-9CB1-DFC1D09782B6.dita#GUID-9A3406EF-3FEF-3F6F-9CB1-DFC1D09782B6/GUID-D1BDF319-CCFD-33CB-8779-CF56849BAA5B"><apiname>MPosVerificationObserver::HandleVerifyComplete()</apiname></xref> with <codeph>aCompletionCode = KErrAccessDenied.</codeph> </p> <p><b>Maximum number of API sessions</b> </p> <p>The <xref href="GUID-23BBC1D8-B3A0-5148-A4F1-22ECF3043E4E.dita">LBS Administration</xref> setting <xref href="GUID-8C74590B-658A-384F-B260-50DEB0263646.dita"><apiname>KLbsSettingPrivacyMaxNetworkSessions</apiname></xref> defines the maximum number of concurrent sessions allowed with the Network Privacy API. </p> <p><b>Session timeouts</b> </p> <p>The <xref href="GUID-23BBC1D8-B3A0-5148-A4F1-22ECF3043E4E.dita">LBS Administration</xref> setting <xref href="GUID-F725725F-195A-33E8-A804-AB48689F2003.dita"><apiname>KLbsSettingPrivacyConnectionTimeout</apiname></xref> controls the connection timeout for sessions using the Network Privacy API. This value can be overriden by an API client by calling <xref href="GUID-F5E959D8-3457-3385-9978-96FDD917D767.dita#GUID-F5E959D8-3457-3385-9978-96FDD917D767/GUID-73993FA4-ABB9-3126-AADF-97BCBC64FBAC"><apiname>CPosNetworkPrivacy::SetConnectionTimeout()</apiname></xref>. </p> <p><b>LBS shutdown delay</b> </p> <p>The LBS subsystem is transient when it is built to include a Privacy Protocol Module and the Network Privacy API. The <xref href="GUID-23BBC1D8-B3A0-5148-A4F1-22ECF3043E4E.dita">LBS Administration</xref> setting <xref href="GUID-6DBF0A21-011D-38B2-BEF5-824C2A77871F.dita"><apiname>KLbsSettingPrivacyShutdownDelay</apiname></xref> sets the delay between closure of the last client connection and LBS subsystem shutdown. </p> </section> </conbody><related-links><link href="GUID-746866CE-809A-5598-BA60-2947763E5EE9.dita"><linktext>Network
+ </title> <image href="GUID-EFC72FB6-5FA0-537C-978D-50FC67A6F857_d0e455363_href.png" placement="inline"/></fig> <p>The following table lists the classes and types that define the Network Privacy API. Further details can be found by following the links to other sections of this document and to Symbian Developer Library reference documentation. </p> <p>The Network Privacy API has <codeph>publishedPartner</codeph> interface access. </p> <table id="GUID-2BB6D675-FE67-57CA-95E8-424DA0C2196A"><tgroup cols="3"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/><thead><row><entry>Class name</entry> <entry>Description</entry> <entry>Header file</entry> </row> </thead> <tbody><row><entry><p> <xref href="GUID-F5E959D8-3457-3385-9978-96FDD917D767.dita"><apiname>CPosNetworkPrivacy</apiname></xref> </p> </entry> <entry><p>Main interface class of the Network Privacy API </p> </entry> <entry><p> <filepath>EPos_CPosNetworkPrivacy.h</filepath> </p> </entry> </row> <row><entry><p> <xref href="GUID-9A3406EF-3FEF-3F6F-9CB1-DFC1D09782B6.dita"><apiname>MPosVerificationObserver</apiname></xref> </p> </entry> <entry><p>Observer class to be implemented by an API client </p> </entry> <entry><p> <filepath>EPos_MPosVerificationObserver.h</filepath> </p> </entry> </row> <row><entry><p> <xref href="GUID-B747E435-087F-3130-8847-25B83067F404.dita"><apiname>CPosNetworkPrivacyRequestInfo</apiname></xref> </p> </entry> <entry><p>Abstract base class for privacy request information </p> </entry> <entry><p> <filepath>EPos_CPosNetworkPrivacyRequestInfo.h</filepath> </p> </entry> </row> <row><entry><p> <xref href="GUID-32DA9EFC-D11D-3A56-A70E-045F7F0E849A.dita"><apiname>CPosGSMPrivacyRequestInfo</apiname></xref> </p> </entry> <entry><p>Request info class for requests from a GSM network </p> </entry> <entry><p> <filepath>EPos_CPosGSMPrivacyRequestInfo.h</filepath> </p> </entry> </row> <row><entry><p> <xref href="GUID-1C0102CD-2F1C-3E8C-9357-06CFED618936.dita"><apiname>CPosSUPLPrivacyRequestInfo</apiname></xref> </p> </entry> <entry><p>Request info class for requests received via SUPL </p> </entry> <entry><p> <filepath>EPos_CPosSUPLPrivacyRequestInfo.h</filepath> </p> </entry> </row> <row><entry><p> <xref href="GUID-0B022E16-132F-3B4F-B598-C5B83BA91E39.dita"><apiname>TPosNetworkPrivacyPanic</apiname></xref> </p> </entry> <entry><p>Panic codes used by the API </p> </entry> <entry><p> <filepath>EPos_NetworkPrivacyPanic.h</filepath> </p> </entry> </row> </tbody> </tgroup> </table> </section> <section><title>Libraries</title> <p>The Network Privacy API is packaged in <filepath>eposnwprv.dll</filepath>. Clients link to <filepath>eposnwprv.lib</filepath>. </p> </section> <section><title>Capabilities</title> <p>To use the Network Privacy API a client requires the following capabilities: <codeph>Location</codeph>, <codeph>NetworkServices</codeph> and <codeph>ReadDeviceData</codeph>. </p> <p>To maintain backwards compatibility with existing clients of the Network Privacy API the alternative capability <codeph>CommDD</codeph> is also supported. However, new clients should be created to have the three capabilities listed above. </p> </section> <section><title>LBS configuration</title> <p>The Network Privacy API is only available when the Privacy Protocol Module is included in an LBS subsystem. See <xref href="GUID-D18B4715-3942-52EA-9D2F-E145037FA47A.dita">LBS Integration and Configuration Guide</xref> for details about how to build a ROM image that supports the Network Privacy API. </p> <p><b>Multiple simultaneous privacy requests</b> </p> <p>The LBS subsystem can be configured to handle multiple simultaneous privacy requests from the Network Privacy API. The <xref href="GUID-23BBC1D8-B3A0-5148-A4F1-22ECF3043E4E.dita">LBS Administration</xref> setting <xref href="GUID-6D5954C5-3B6A-3BAA-AB75-D1ECE90BAEDB.dita"><apiname>KLbsSettingMaximumExternalLocateRequests</apiname></xref> defines the maximum number of privacy requests that can be handled simultaneously by the LBS subsystem. </p> <p>If an additional privacy request is sent into the LBS subsystem such that the total number of requests exceeds <codeph>KLbsSettingMaximumExternalLocateRequests</codeph>, the additional request is always rejected i.e. the LBS subsystem calls <xref href="GUID-9A3406EF-3FEF-3F6F-9CB1-DFC1D09782B6.dita#GUID-9A3406EF-3FEF-3F6F-9CB1-DFC1D09782B6/GUID-D1BDF319-CCFD-33CB-8779-CF56849BAA5B"><apiname>MPosVerificationObserver::HandleVerifyComplete()</apiname></xref> with <codeph>aCompletionCode = KErrAccessDenied.</codeph> </p> <p><b>Maximum number of API sessions</b> </p> <p>The <xref href="GUID-23BBC1D8-B3A0-5148-A4F1-22ECF3043E4E.dita">LBS Administration</xref> setting <xref href="GUID-8C74590B-658A-384F-B260-50DEB0263646.dita"><apiname>KLbsSettingPrivacyMaxNetworkSessions</apiname></xref> defines the maximum number of concurrent sessions allowed with the Network Privacy API. </p> <p><b>Session timeouts</b> </p> <p>The <xref href="GUID-23BBC1D8-B3A0-5148-A4F1-22ECF3043E4E.dita">LBS Administration</xref> setting <xref href="GUID-F725725F-195A-33E8-A804-AB48689F2003.dita"><apiname>KLbsSettingPrivacyConnectionTimeout</apiname></xref> controls the connection timeout for sessions using the Network Privacy API. This value can be overriden by an API client by calling <xref href="GUID-F5E959D8-3457-3385-9978-96FDD917D767.dita#GUID-F5E959D8-3457-3385-9978-96FDD917D767/GUID-73993FA4-ABB9-3126-AADF-97BCBC64FBAC"><apiname>CPosNetworkPrivacy::SetConnectionTimeout()</apiname></xref>. </p> <p><b>LBS shutdown delay</b> </p> <p>The LBS subsystem is transient when it is built to include a Privacy Protocol Module and the Network Privacy API. The <xref href="GUID-23BBC1D8-B3A0-5148-A4F1-22ECF3043E4E.dita">LBS Administration</xref> setting <xref href="GUID-6DBF0A21-011D-38B2-BEF5-824C2A77871F.dita"><apiname>KLbsSettingPrivacyShutdownDelay</apiname></xref> sets the delay between closure of the last client connection and LBS subsystem shutdown. </p> </section> </conbody><related-links><link href="GUID-746866CE-809A-5598-BA60-2947763E5EE9.dita"><linktext>Network
Privacy API Reference</linktext> </link> <link href="GUID-6526C440-34EA-50C2-B550-2C655DCC2ED8.dita"><linktext>Network
Privacy API Tutorial</linktext> </link> <link href="GUID-0BF06E5D-BEEF-5E15-894E-FA605FA12E33.dita"><linktext>Privacy
Protocol Module Overview</linktext> </link> <link href="GUID-E1710E40-B8F5-5CF8-B9FE-698869A1770F.dita"><linktext>Privacy