--- a/Symbian3/PDK/Source/GUID-E1710E40-B8F5-5CF8-B9FE-698869A1770F.dita Fri Jul 02 12:51:36 2010 +0100
+++ b/Symbian3/PDK/Source/GUID-E1710E40-B8F5-5CF8-B9FE-698869A1770F.dita Fri Jul 16 17:23:46 2010 +0100
@@ -12,9 +12,9 @@
<concept xml:lang="en" id="GUID-E1710E40-B8F5-5CF8-B9FE-698869A1770F"><title>Privacy Request API</title><shortdesc>The Privacy Request API is an interface through which the LBS subsystem can receive and respond to privacy requests when it is built to include the Privacy Protocol Module. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody><section><title>Introduction</title> <p>The Privacy Request 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 API is an alternative to the Network Privacy API. The Privacy Request API is intended for processing multiple privacy requests either from local applications or from the network. </p> </section> <section><title>Description</title> <p>The Privacy Request API is implemented on the client-side by the Privacy Request Client DLL. This DLL is an interface to the Privacy Protocol Module. </p> <p>The Privacy Request API does not guarantee performance in low memory conditions for which a privacy request may fail. For this reason the Privacy Request API and the Privacy Protocol Module should 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 Privacy Request Client DLL in the context of the LBS subsystem. The most important points to note are: </p> <ul><li id="GUID-2F49D9C2-6301-5780-B449-A968F6E4E91C"><p>The Privacy Request Client DLL exposes the Privacy Request 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-41BB6F50-06F9-5CB7-9B94-1B4A1DA7604D"><p>The Privacy Request Client DLL connects to a server implementation in the Privacy Protocol Module. </p> </li> <li id="GUID-436EEC36-A4BA-5C4A-A449-E1CC467A7E21"><p>A device creator does not create their own implementation of the Privacy Request Client DLL or the Privacy Protocol Module. A device creator chooses to build a ROM containing the Privacy Protocol Module and the Privacy Request 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-3A873301-DE30-5076-A552-ECBBCEC3D8C4"><p>To use the Privacy Request API a device creator must implement some kind of client process in their domestic operating system which uses the Privacy Request API. </p> <p>The Privacy Request 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-8009082C-B2A2-5FEF-AE85-480B20922A06"><title>
Figure 1. The Privacy Request API in the LBS Standalone Privacy Mode
configuration.
- </title> <image href="GUID-11678281-9A86-5D8A-B907-D7940B3A07D4_d0e450474_href.png" placement="inline"/></fig> </section> <section><title>Privacy Request Client DLL responsibilities</title> <p>The Privacy Request Client DLL communicates with the Privacy Protocol Module via standard Symbian client-server IPC calls. The DLL performs two distinct functions: </p> <ol id="GUID-A1078A81-D95F-5E61-9FA2-27E8CE8F47DB"><li id="GUID-57FA28F7-EA7C-5CEF-8606-C4485D5808C6"><p>It starts up the LBS subsystem if it is not already running. </p> <p>The privacy handling components shown in figure 1 are transient. They are started only on demand when a client process creates an instance of a Privacy Request API class. </p> <p>The <xref href="GUID-D18B4715-3942-52EA-9D2F-E145037FA47A.dita">LBS Integration and Configuration Guide</xref> describes how to configure the components that are started when the first privacy request is received. <xref href="GUID-7A26F69B-D70D-502B-A9A2-918F13D33D6D.dita">Privacy Request API Reference</xref> contains sequences that describe startup and shutdown behaviour. </p> </li> <li id="GUID-28DDD066-3332-5080-AD00-90227DC73F3D"><p>It packages the Privacy Request 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> </section> <section><title>Privacy Request API description</title> <p>Figure 2 shows the classes of the Privacy Request API. </p> <fig id="GUID-C2D7D78C-0779-547D-97A1-19499687339A"><title>
+ </title> <image href="GUID-11678281-9A86-5D8A-B907-D7940B3A07D4_d0e456319_href.png" placement="inline"/></fig> </section> <section><title>Privacy Request Client DLL responsibilities</title> <p>The Privacy Request Client DLL communicates with the Privacy Protocol Module via standard Symbian client-server IPC calls. The DLL performs two distinct functions: </p> <ol id="GUID-A1078A81-D95F-5E61-9FA2-27E8CE8F47DB"><li id="GUID-57FA28F7-EA7C-5CEF-8606-C4485D5808C6"><p>It starts up the LBS subsystem if it is not already running. </p> <p>The privacy handling components shown in figure 1 are transient. They are started only on demand when a client process creates an instance of a Privacy Request API class. </p> <p>The <xref href="GUID-D18B4715-3942-52EA-9D2F-E145037FA47A.dita">LBS Integration and Configuration Guide</xref> describes how to configure the components that are started when the first privacy request is received. <xref href="GUID-7A26F69B-D70D-502B-A9A2-918F13D33D6D.dita">Privacy Request API Reference</xref> contains sequences that describe startup and shutdown behaviour. </p> </li> <li id="GUID-28DDD066-3332-5080-AD00-90227DC73F3D"><p>It packages the Privacy Request 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> </section> <section><title>Privacy Request API description</title> <p>Figure 2 shows the classes of the Privacy Request API. </p> <fig id="GUID-C2D7D78C-0779-547D-97A1-19499687339A"><title>
Figure 2. Privacy Request API classes
- </title> <image href="GUID-44872DF6-AEA6-554F-A231-D8C6D5F22958_d0e450520_href.png" placement="inline"/></fig> <p>The following table lists the classes and types that define the Privacy Request API. Further details can be found by following the links to other sections of this document and to the Symbian Developer Library reference documentation. </p> <p>The Privacy Request API has <codeph>publishedPartner</codeph> interface access. Licensees use the following classes to send privacy requests and receive privacy responses via the API. </p> <table id="GUID-43BE0436-0FA3-5260-BC2C-B28522EC17B6"><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-FA2B30DF-81BC-3BCD-9EE6-01A961291D47.dita"><apiname>CLbsPrivacyRequest</apiname></xref> </p> </entry> <entry><p>The main interface class of the Privacy Request API. It is used to send privacy requests into the LBS subsystem. </p> </entry> <entry><p> <filepath>lbsprivacyrequest.h</filepath> </p> </entry> </row> <row><entry><p> <xref href="GUID-BD22CA43-FDAF-3809-8172-6403B4D7529A.dita"><apiname> MLbsPrivacyRequestObserver</apiname></xref> </p> </entry> <entry><p>The observer class that must be implemented by a Privacy Request API client. Its methods are called by the LBS subsystem to send privacy responses to the client. </p> </entry> <entry><p> <filepath>lbsprivacyrequest.h</filepath> </p> </entry> </row> <row><entry><p> <xref href="GUID-DA7E60CF-52F9-3ACF-AB12-E647AD980C81.dita"><apiname>TLbsPrivacyRequest</apiname></xref> </p> </entry> <entry><p>A class derived from <codeph>TLbsPrivacyClassTypeBase</codeph> that holds privacy request parameters. </p> </entry> <entry><p> <filepath>lbsprivacyrequestcommon.h</filepath> </p> </entry> </row> <row><entry><p> <xref href="GUID-6DA81BD9-1FC2-31BC-8EC1-6F73D19228C0.dita"><apiname>TLbsPrivacyClassTypeBase</apiname></xref> </p> </entry> <entry><p>The base class of classes that stores privacy request parameters which are passed from the API client to the LBS subsystem. A Privacy Request API client does not use this class directly. </p> </entry> <entry><p> <filepath>lbsprivacyrequestcommon.h</filepath> </p> </entry> </row> <row><entry><p> <xref href="GUID-149882EB-3151-3486-96B1-B416231830B1.dita"><apiname>TLbsPrivacyRequestClassType</apiname></xref> </p> </entry> <entry><p>An enumeration that defines the type of privacy request class (derived from <codeph>TLbsPrivacyRequestClassType</codeph>) that is passed from the API client to the LBS subsystem. A Privacy Request API client does not use this type directly. It is used internally within the Privacy Request API. </p> </entry> <entry><p> <filepath>lbsprivacyrequestclasstypes.h</filepath> </p> </entry> </row> </tbody> </tgroup> </table> </section> <example><title>Capabilities</title> <p>The Privacy Request API is packaged in <filepath>lbsprivacyrequest.dll</filepath>. Clients link to <filepath>lbsprivacyrequest.lib</filepath>. </p> </example> <section><title>Libraries</title> <p>To use the Privacy Request API to handle privacy requests from a local application requires the capabilities <codeph>Location</codeph> and <codeph>ReadDeviceData</codeph>. To handle privacy requests from the network requires the additional <codeph>NetworkServices</codeph> capability. </p> </section> </conbody><related-links><link href="GUID-7A26F69B-D70D-502B-A9A2-918F13D33D6D.dita"><linktext>Privacy
+ </title> <image href="GUID-44872DF6-AEA6-554F-A231-D8C6D5F22958_d0e456365_href.png" placement="inline"/></fig> <p>The following table lists the classes and types that define the Privacy Request API. Further details can be found by following the links to other sections of this document and to the Symbian Developer Library reference documentation. </p> <p>The Privacy Request API has <codeph>publishedPartner</codeph> interface access. Licensees use the following classes to send privacy requests and receive privacy responses via the API. </p> <table id="GUID-43BE0436-0FA3-5260-BC2C-B28522EC17B6"><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-FA2B30DF-81BC-3BCD-9EE6-01A961291D47.dita"><apiname>CLbsPrivacyRequest</apiname></xref> </p> </entry> <entry><p>The main interface class of the Privacy Request API. It is used to send privacy requests into the LBS subsystem. </p> </entry> <entry><p> <filepath>lbsprivacyrequest.h</filepath> </p> </entry> </row> <row><entry><p> <xref href="GUID-BD22CA43-FDAF-3809-8172-6403B4D7529A.dita"><apiname> MLbsPrivacyRequestObserver</apiname></xref> </p> </entry> <entry><p>The observer class that must be implemented by a Privacy Request API client. Its methods are called by the LBS subsystem to send privacy responses to the client. </p> </entry> <entry><p> <filepath>lbsprivacyrequest.h</filepath> </p> </entry> </row> <row><entry><p> <xref href="GUID-DA7E60CF-52F9-3ACF-AB12-E647AD980C81.dita"><apiname>TLbsPrivacyRequest</apiname></xref> </p> </entry> <entry><p>A class derived from <codeph>TLbsPrivacyClassTypeBase</codeph> that holds privacy request parameters. </p> </entry> <entry><p> <filepath>lbsprivacyrequestcommon.h</filepath> </p> </entry> </row> <row><entry><p> <xref href="GUID-6DA81BD9-1FC2-31BC-8EC1-6F73D19228C0.dita"><apiname>TLbsPrivacyClassTypeBase</apiname></xref> </p> </entry> <entry><p>The base class of classes that stores privacy request parameters which are passed from the API client to the LBS subsystem. A Privacy Request API client does not use this class directly. </p> </entry> <entry><p> <filepath>lbsprivacyrequestcommon.h</filepath> </p> </entry> </row> <row><entry><p> <xref href="GUID-149882EB-3151-3486-96B1-B416231830B1.dita"><apiname>TLbsPrivacyRequestClassType</apiname></xref> </p> </entry> <entry><p>An enumeration that defines the type of privacy request class (derived from <codeph>TLbsPrivacyRequestClassType</codeph>) that is passed from the API client to the LBS subsystem. A Privacy Request API client does not use this type directly. It is used internally within the Privacy Request API. </p> </entry> <entry><p> <filepath>lbsprivacyrequestclasstypes.h</filepath> </p> </entry> </row> </tbody> </tgroup> </table> </section> <example><title>Capabilities</title> <p>The Privacy Request API is packaged in <filepath>lbsprivacyrequest.dll</filepath>. Clients link to <filepath>lbsprivacyrequest.lib</filepath>. </p> </example> <section><title>Libraries</title> <p>To use the Privacy Request API to handle privacy requests from a local application requires the capabilities <codeph>Location</codeph> and <codeph>ReadDeviceData</codeph>. To handle privacy requests from the network requires the additional <codeph>NetworkServices</codeph> capability. </p> </section> </conbody><related-links><link href="GUID-7A26F69B-D70D-502B-A9A2-918F13D33D6D.dita"><linktext>Privacy
Request API Reference</linktext> </link> <link href="GUID-5008C3E6-4D12-5BA3-A95A-7CAB02ED0594.dita"><linktext>Privacy
Request API Tutorial</linktext> </link> <link href="GUID-0BF06E5D-BEEF-5E15-894E-FA605FA12E33.dita"><linktext>Privacy
Protocol Module Overview</linktext> </link> <link href="GUID-D18B4715-3942-52EA-9D2F-E145037FA47A.dita"><linktext>LBS