12 <concept xml:lang="en" id="GUID-DABBFC53-CC93-54AA-ADFD-6756B1EA878C"><title>Location Settings API</title><shortdesc>The Location Settings API allows an application to get and set the properties of a PSY. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody><p> </p> <section><title>Contents</title> <ul><li id="GUID-5C7D32AA-BBA2-55EF-BA32-5F2D461EAFC0"><p><xref href="GUID-DABBFC53-CC93-54AA-ADFD-6756B1EA878C.dita#GUID-DABBFC53-CC93-54AA-ADFD-6756B1EA878C/GUID-1122A71A-7868-5394-917B-5C5EB8E97EC8">Purpose</xref> </p> </li> <li id="GUID-FD73A08E-C032-5A49-8F95-CBF9DBF567A5"><p><xref href="GUID-DABBFC53-CC93-54AA-ADFD-6756B1EA878C.dita#GUID-DABBFC53-CC93-54AA-ADFD-6756B1EA878C/GUID-B6F9AB52-9375-5601-8760-1C3B72620E71">API description</xref> </p> <ul><li id="GUID-4E424394-F32F-594F-BD79-3BF54E292793"><p><xref href="GUID-DABBFC53-CC93-54AA-ADFD-6756B1EA878C.dita#GUID-DABBFC53-CC93-54AA-ADFD-6756B1EA878C/GUID-A45324D8-CF2A-52BD-A08F-7C3A56A8E9F8">PSY attributes</xref> </p> </li> </ul> </li> <li id="GUID-81B5646F-4EAA-5869-95BC-95832CC798B0"><p><xref href="GUID-DABBFC53-CC93-54AA-ADFD-6756B1EA878C.dita#GUID-DABBFC53-CC93-54AA-ADFD-6756B1EA878C/GUID-5A9DAD33-86D7-5066-9CED-36FEF03AEC80">API summary</xref> </p> </li> <li id="GUID-E599DD05-DA59-5CD2-A7B7-C4B46AABE1D0"><p><xref href="GUID-DABBFC53-CC93-54AA-ADFD-6756B1EA878C.dita#GUID-DABBFC53-CC93-54AA-ADFD-6756B1EA878C/GUID-F2BD6C21-25D7-5E3A-B24E-16D783EDDFA6">Using the API</xref> </p> <ul><li id="GUID-12DF3B2A-93B7-5F5D-8330-E7A25822B71C"><p><xref href="GUID-DABBFC53-CC93-54AA-ADFD-6756B1EA878C.dita#GUID-DABBFC53-CC93-54AA-ADFD-6756B1EA878C/GUID-54DC1DC0-290A-55DD-B5BD-D87BE8E3194F"> Retrieving information about installed PSYs</xref> </p> </li> <li id="GUID-90FA746B-3BAA-542F-9B3A-9888D8BC28EC"><p><xref href="GUID-DABBFC53-CC93-54AA-ADFD-6756B1EA878C.dita#GUID-DABBFC53-CC93-54AA-ADFD-6756B1EA878C/GUID-B5AC0535-5CFA-5A5F-A67F-F05A3D7F78D1">Modifying PSY attributes</xref> </p> </li> <li id="GUID-0B6F5C23-8D8B-5879-B91B-7D0793A1323B"><p><xref href="GUID-DABBFC53-CC93-54AA-ADFD-6756B1EA878C.dita#GUID-DABBFC53-CC93-54AA-ADFD-6756B1EA878C/GUID-0ADE50DD-84E3-5DAE-94E3-4BB424665734">Changing priority order of PSYs </xref> </p> </li> <li id="GUID-763E86DE-BBBD-567A-8F54-C2A521402CDE"><p><xref href="GUID-DABBFC53-CC93-54AA-ADFD-6756B1EA878C.dita#GUID-DABBFC53-CC93-54AA-ADFD-6756B1EA878C/GUID-1438A703-4F6F-5AC2-A52C-37BABE7AF5B9"> Listening to settings change events </xref> </p> </li> </ul> </li> <li id="GUID-56AF88DC-075C-5A2B-BE22-6F0450E19537"><p><xref href="GUID-DABBFC53-CC93-54AA-ADFD-6756B1EA878C.dita#GUID-DABBFC53-CC93-54AA-ADFD-6756B1EA878C/GUID-1EBC1700-209D-5AC2-ABF7-CB866A8728C8">Error handling</xref> </p> </li> <li id="GUID-F7769CE9-B43F-5578-A67D-B9C5C98DDFAD"><p><xref href="GUID-DABBFC53-CC93-54AA-ADFD-6756B1EA878C.dita#GUID-DABBFC53-CC93-54AA-ADFD-6756B1EA878C/GUID-5523F46D-5CDA-5E85-B4B8-193FD8B26E32">Memory overhead</xref> </p> </li> <li id="GUID-9455497D-1F38-5123-AFAB-239DDC553C12"><p><xref href="GUID-DABBFC53-CC93-54AA-ADFD-6756B1EA878C.dita#GUID-DABBFC53-CC93-54AA-ADFD-6756B1EA878C/GUID-FFEA130F-33FE-5E8D-AAE2-9AD8DF68DADE">See also</xref> </p> </li> </ul> </section> <section id="GUID-1122A71A-7868-5394-917B-5C5EB8E97EC8"><title>Purpose</title> <p>The Location Settings API is an interface for managing the settings of the Location Framework and of Positioning Plug-ins (PSYs). The settings consist of the relative priorities of PSYs installed on the mobile device and modifiable and read-only attributes of PSYs. </p> </section> <section id="GUID-B6F9AB52-9375-5601-8760-1C3B72620E71"><title>API description</title> <p>This API is intended for use by a system application (such as a settings UI) that allows the user of a phone to view and edit settings that affect the behaviour of the Location Framework. The API allows a user to manage the priority ordering of PSYs and to access their modifiable and non-modifiable attributes </p> <p>The priority ordering of PSYs is used when a client of the <xref href="GUID-D0318BB6-0B9F-5A1C-AB0B-61BA22D28661.dita">Location Acquisition API</xref> uses the <xref href="GUID-1EAEB7EF-0AC7-37C7-B35F-C9B780FFC575.dita"><apiname>RPositioner</apiname></xref> class without specifying particular positioning module ID (by calling <xref href="GUID-1EAEB7EF-0AC7-37C7-B35F-C9B780FFC575.dita#GUID-1EAEB7EF-0AC7-37C7-B35F-C9B780FFC575/GUID-AF3D9B5F-8025-3AFF-A101-82025520EBD6"><apiname>RPositioner::Open()</apiname></xref> without parameters). The Location Server uses the PSY with the highest priority if possible and falls back to next one in the priority list in case of failure. </p> <p id="GUID-A45324D8-CF2A-52BD-A08F-7C3A56A8E9F8"><b>PSY attributes</b> </p> <p>PSY attributes can be grouped by type: </p> <dl><dlentry><dt>Non-modifiable attributes</dt> <dd><p>These properties include a descriptive name, UID, positioning plug-in version, positioning technology, capabilities, time to first fix, positioning accuracy, power consumption etc. </p> <p>For more information about non-modifiable attributes see <xref href="GUID-DA2DC704-CE65-54FB-9049-4E1C73092EDF-GENID-1-10-1-16-1-1-10-1-5-1-5-1-8-1.dita">Positioning Plug-in Information API</xref>. </p> <p>Non-modifiable attributes are read from each PSY's repository file,. The PSY name is read from a resource file, which should be referenced by the repository file. If the resource file is not referenced in the repository file then the PSY name is taken from ECOM attributes of the PSY plug-in (which means that the name cannot be localized). </p> </dd> </dlentry> <dlentry><dt>Modifiable attributes</dt> <dd><p>These attributes include the availability status of the PSY (enabled or disabled), the cost of using the PSY and its visibility. </p> <p>Modifiable attributes are stored in the Central Repository. </p> <p>Table 1 describes the modifiable PSY attributes: </p> <table id="GUID-7330D155-DBE5-57C5-B6A6-B4AD5855ECBC"><tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/><thead><row><entry>Attribute</entry> <entry>Description</entry> </row> </thead> <tbody><row><entry><p>Cost </p> </entry> <entry><p>User-defined runtime setting for the cost of using a specific positioning technology. Possible values are defined by <xref href="GUID-1AA235FA-CEC1-3853-8F96-C538C02B596D.dita#GUID-1AA235FA-CEC1-3853-8F96-C538C02B596D/GUID-78C084A0-43F8-3040-BD98-70E2E62A5D45"><apiname>TPositionQuality::TCostIndicator</apiname></xref> from <xref href="GUID-D0318BB6-0B9F-5A1C-AB0B-61BA22D28661.dita">Location Acquisition API</xref>. </p> <p>The cost attribute is modifiable because in some cases the cost of using a PSY can be dependent on the user’s subscription model. </p> </entry> </row> <row><entry><p>Availability </p> </entry> <entry><p>Determines whether a PSY is enabled to be used through <xref href="GUID-D0318BB6-0B9F-5A1C-AB0B-61BA22D28661.dita">Location Acquisition API</xref> (<xref href="GUID-1EAEB7EF-0AC7-37C7-B35F-C9B780FFC575.dita"><apiname>RPositioner</apiname></xref>) or not. </p> </entry> </row> <row><entry><p>Visibility </p> </entry> <entry><p>Determines whether a PSY needs to be listed by the <xref href="GUID-3EC269A3-61A0-378B-A909-AB5881E47769.dita"><apiname>CPosModules</apiname></xref> class of this API. </p> </entry> </row> </tbody> </tgroup> </table> <p>Table 1. Modifiable PSY attributes. </p> </dd> </dlentry> <dlentry><dt>Positioning plug-in specific settings</dt> <dd><p>Each PSY can have any number of attributes that are specific for the positioning technology it encapsulates (for example, baud rate for external GPS). The Location Settings API does not provide access to these settings. </p> </dd> </dlentry> </dl> </section> <section id="GUID-5A9DAD33-86D7-5066-9CED-36FEF03AEC80"><title>API summary</title> <p>Figure 1 shows public classes of the Location Settings API. </p> <fig id="GUID-9F8E279C-A702-5557-A2CE-FD085EF15E4C"><title> |
12 <concept xml:lang="en" id="GUID-DABBFC53-CC93-54AA-ADFD-6756B1EA878C"><title>Location Settings API</title><shortdesc>The Location Settings API allows an application to get and set the properties of a PSY. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody><p> </p> <section><title>Contents</title> <ul><li id="GUID-5C7D32AA-BBA2-55EF-BA32-5F2D461EAFC0"><p><xref href="GUID-DABBFC53-CC93-54AA-ADFD-6756B1EA878C.dita#GUID-DABBFC53-CC93-54AA-ADFD-6756B1EA878C/GUID-1122A71A-7868-5394-917B-5C5EB8E97EC8">Purpose</xref> </p> </li> <li id="GUID-FD73A08E-C032-5A49-8F95-CBF9DBF567A5"><p><xref href="GUID-DABBFC53-CC93-54AA-ADFD-6756B1EA878C.dita#GUID-DABBFC53-CC93-54AA-ADFD-6756B1EA878C/GUID-B6F9AB52-9375-5601-8760-1C3B72620E71">API description</xref> </p> <ul><li id="GUID-4E424394-F32F-594F-BD79-3BF54E292793"><p><xref href="GUID-DABBFC53-CC93-54AA-ADFD-6756B1EA878C.dita#GUID-DABBFC53-CC93-54AA-ADFD-6756B1EA878C/GUID-A45324D8-CF2A-52BD-A08F-7C3A56A8E9F8">PSY attributes</xref> </p> </li> </ul> </li> <li id="GUID-81B5646F-4EAA-5869-95BC-95832CC798B0"><p><xref href="GUID-DABBFC53-CC93-54AA-ADFD-6756B1EA878C.dita#GUID-DABBFC53-CC93-54AA-ADFD-6756B1EA878C/GUID-5A9DAD33-86D7-5066-9CED-36FEF03AEC80">API summary</xref> </p> </li> <li id="GUID-E599DD05-DA59-5CD2-A7B7-C4B46AABE1D0"><p><xref href="GUID-DABBFC53-CC93-54AA-ADFD-6756B1EA878C.dita#GUID-DABBFC53-CC93-54AA-ADFD-6756B1EA878C/GUID-F2BD6C21-25D7-5E3A-B24E-16D783EDDFA6">Using the API</xref> </p> <ul><li id="GUID-12DF3B2A-93B7-5F5D-8330-E7A25822B71C"><p><xref href="GUID-DABBFC53-CC93-54AA-ADFD-6756B1EA878C.dita#GUID-DABBFC53-CC93-54AA-ADFD-6756B1EA878C/GUID-54DC1DC0-290A-55DD-B5BD-D87BE8E3194F"> Retrieving information about installed PSYs</xref> </p> </li> <li id="GUID-90FA746B-3BAA-542F-9B3A-9888D8BC28EC"><p><xref href="GUID-DABBFC53-CC93-54AA-ADFD-6756B1EA878C.dita#GUID-DABBFC53-CC93-54AA-ADFD-6756B1EA878C/GUID-B5AC0535-5CFA-5A5F-A67F-F05A3D7F78D1">Modifying PSY attributes</xref> </p> </li> <li id="GUID-0B6F5C23-8D8B-5879-B91B-7D0793A1323B"><p><xref href="GUID-DABBFC53-CC93-54AA-ADFD-6756B1EA878C.dita#GUID-DABBFC53-CC93-54AA-ADFD-6756B1EA878C/GUID-0ADE50DD-84E3-5DAE-94E3-4BB424665734">Changing priority order of PSYs </xref> </p> </li> <li id="GUID-763E86DE-BBBD-567A-8F54-C2A521402CDE"><p><xref href="GUID-DABBFC53-CC93-54AA-ADFD-6756B1EA878C.dita#GUID-DABBFC53-CC93-54AA-ADFD-6756B1EA878C/GUID-1438A703-4F6F-5AC2-A52C-37BABE7AF5B9"> Listening to settings change events </xref> </p> </li> </ul> </li> <li id="GUID-56AF88DC-075C-5A2B-BE22-6F0450E19537"><p><xref href="GUID-DABBFC53-CC93-54AA-ADFD-6756B1EA878C.dita#GUID-DABBFC53-CC93-54AA-ADFD-6756B1EA878C/GUID-1EBC1700-209D-5AC2-ABF7-CB866A8728C8">Error handling</xref> </p> </li> <li id="GUID-F7769CE9-B43F-5578-A67D-B9C5C98DDFAD"><p><xref href="GUID-DABBFC53-CC93-54AA-ADFD-6756B1EA878C.dita#GUID-DABBFC53-CC93-54AA-ADFD-6756B1EA878C/GUID-5523F46D-5CDA-5E85-B4B8-193FD8B26E32">Memory overhead</xref> </p> </li> <li id="GUID-9455497D-1F38-5123-AFAB-239DDC553C12"><p><xref href="GUID-DABBFC53-CC93-54AA-ADFD-6756B1EA878C.dita#GUID-DABBFC53-CC93-54AA-ADFD-6756B1EA878C/GUID-FFEA130F-33FE-5E8D-AAE2-9AD8DF68DADE">See also</xref> </p> </li> </ul> </section> <section id="GUID-1122A71A-7868-5394-917B-5C5EB8E97EC8"><title>Purpose</title> <p>The Location Settings API is an interface for managing the settings of the Location Framework and of Positioning Plug-ins (PSYs). The settings consist of the relative priorities of PSYs installed on the mobile device and modifiable and read-only attributes of PSYs. </p> </section> <section id="GUID-B6F9AB52-9375-5601-8760-1C3B72620E71"><title>API description</title> <p>This API is intended for use by a system application (such as a settings UI) that allows the user of a phone to view and edit settings that affect the behaviour of the Location Framework. The API allows a user to manage the priority ordering of PSYs and to access their modifiable and non-modifiable attributes </p> <p>The priority ordering of PSYs is used when a client of the <xref href="GUID-D0318BB6-0B9F-5A1C-AB0B-61BA22D28661.dita">Location Acquisition API</xref> uses the <xref href="GUID-1EAEB7EF-0AC7-37C7-B35F-C9B780FFC575.dita"><apiname>RPositioner</apiname></xref> class without specifying particular positioning module ID (by calling <xref href="GUID-1EAEB7EF-0AC7-37C7-B35F-C9B780FFC575.dita#GUID-1EAEB7EF-0AC7-37C7-B35F-C9B780FFC575/GUID-AF3D9B5F-8025-3AFF-A101-82025520EBD6"><apiname>RPositioner::Open()</apiname></xref> without parameters). The Location Server uses the PSY with the highest priority if possible and falls back to next one in the priority list in case of failure. </p> <p id="GUID-A45324D8-CF2A-52BD-A08F-7C3A56A8E9F8"><b>PSY attributes</b> </p> <p>PSY attributes can be grouped by type: </p> <dl><dlentry><dt>Non-modifiable attributes</dt> <dd><p>These properties include a descriptive name, UID, positioning plug-in version, positioning technology, capabilities, time to first fix, positioning accuracy, power consumption etc. </p> <p>For more information about non-modifiable attributes see <xref href="GUID-DA2DC704-CE65-54FB-9049-4E1C73092EDF-GENID-1-12-1-18-1-1-10-1-5-1-5-1-8-1.dita">Positioning Plug-in Information API</xref>. </p> <p>Non-modifiable attributes are read from each PSY's repository file,. The PSY name is read from a resource file, which should be referenced by the repository file. If the resource file is not referenced in the repository file then the PSY name is taken from ECOM attributes of the PSY plug-in (which means that the name cannot be localized). </p> </dd> </dlentry> <dlentry><dt>Modifiable attributes</dt> <dd><p>These attributes include the availability status of the PSY (enabled or disabled), the cost of using the PSY and its visibility. </p> <p>Modifiable attributes are stored in the Central Repository. </p> <p>Table 1 describes the modifiable PSY attributes: </p> <table id="GUID-7330D155-DBE5-57C5-B6A6-B4AD5855ECBC"><tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/><thead><row><entry>Attribute</entry> <entry>Description</entry> </row> </thead> <tbody><row><entry><p>Cost </p> </entry> <entry><p>User-defined runtime setting for the cost of using a specific positioning technology. Possible values are defined by <xref href="GUID-1AA235FA-CEC1-3853-8F96-C538C02B596D.dita#GUID-1AA235FA-CEC1-3853-8F96-C538C02B596D/GUID-78C084A0-43F8-3040-BD98-70E2E62A5D45"><apiname>TPositionQuality::TCostIndicator</apiname></xref> from <xref href="GUID-D0318BB6-0B9F-5A1C-AB0B-61BA22D28661.dita">Location Acquisition API</xref>. </p> <p>The cost attribute is modifiable because in some cases the cost of using a PSY can be dependent on the user’s subscription model. </p> </entry> </row> <row><entry><p>Availability </p> </entry> <entry><p>Determines whether a PSY is enabled to be used through <xref href="GUID-D0318BB6-0B9F-5A1C-AB0B-61BA22D28661.dita">Location Acquisition API</xref> (<xref href="GUID-1EAEB7EF-0AC7-37C7-B35F-C9B780FFC575.dita"><apiname>RPositioner</apiname></xref>) or not. </p> </entry> </row> <row><entry><p>Visibility </p> </entry> <entry><p>Determines whether a PSY needs to be listed by the <xref href="GUID-3EC269A3-61A0-378B-A909-AB5881E47769.dita"><apiname>CPosModules</apiname></xref> class of this API. </p> </entry> </row> </tbody> </tgroup> </table> <p>Table 1. Modifiable PSY attributes. </p> </dd> </dlentry> <dlentry><dt>Positioning plug-in specific settings</dt> <dd><p>Each PSY can have any number of attributes that are specific for the positioning technology it encapsulates (for example, baud rate for external GPS). The Location Settings API does not provide access to these settings. </p> </dd> </dlentry> </dl> </section> <section id="GUID-5A9DAD33-86D7-5066-9CED-36FEF03AEC80"><title>API summary</title> <p>Figure 1 shows public classes of the Location Settings API. </p> <fig id="GUID-9F8E279C-A702-5557-A2CE-FD085EF15E4C"><title> |
14 </title> <image href="GUID-E3F116C0-F133-5008-BD7A-421D66FB6588_d0e454068_href.png" placement="inline"/></fig> <p>Table 1 lists the classes and types of the API. </p> <table id="GUID-404231E8-601E-5D56-A3E2-D6DFFB266AC7"><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-3EC269A3-61A0-378B-A909-AB5881E47769.dita"><apiname>CPosModules</apiname></xref> </p> </entry> <entry><p>The main class of the Location Settings API. It is used for accessing PSY attributes and managing priority list of PSYs. A client can also register to listen for changes in the settings. </p> </entry> <entry><p> <codeph>EPos_CPosModuleIdList.h</codeph> </p> </entry> </row> <row><entry><p> <xref href="GUID-1AB3C182-B9F9-3C75-9FC2-C550500046CB.dita"><apiname>CPosModuleUpdate</apiname></xref> </p> </entry> <entry><p>Represents an update of the modifiable attributes of a PSY. An update is committed by calling <xref href="GUID-3EC269A3-61A0-378B-A909-AB5881E47769.dita#GUID-3EC269A3-61A0-378B-A909-AB5881E47769/GUID-590B754B-2ECB-313F-A8C5-44B2C2A1E37F"><apiname>CPosModules::UpdateModuleL()</apiname></xref>. </p> </entry> <entry><p> <codeph>EPos_CPosModuleUpdate.h</codeph> </p> </entry> </row> <row><entry><p> <xref href="GUID-2E3EB368-F820-3B1F-A025-939D78A5F9CE.dita"><apiname>CPosModuleIdList</apiname></xref> </p> </entry> <entry><p>Represents a list of PSY IDs. Used to get and set the priority list of PSYs. It contains methods for appending, inserting, removing and finding PSY IDs in the list. </p> </entry> <entry><p> <codeph>EPos_CPosModuleIdList.h</codeph> </p> </entry> </row> <row><entry><p> <xref href="GUID-2C027B56-CC69-307E-ABB4-BBB532D8F473.dita"><apiname>MPosModulesObserver</apiname></xref> </p> </entry> <entry><p>The interface that is implemented by clients in order to receive notifications of changes in the PSY settings. A client subscribes for notifications through the <xref href="GUID-3EC269A3-61A0-378B-A909-AB5881E47769.dita"><apiname>CPosModules</apiname></xref> class. </p> <p>Notification event information is given in a <xref href="GUID-5760EA9E-7720-31CD-B8F7-29370E2B6FCB.dita"><apiname>TPosModulesEvent</apiname></xref> structure. </p> <p>Typedef <xref href="GUID-9559BB6D-894E-3814-8D60-4102A465EC3D.dita"><apiname>TPosModulesEventType</apiname></xref> defines possible event types. </p> </entry> <entry><p> <codeph>EPos_MPosModulesObserver.h</codeph> </p> </entry> </row> </tbody> </tgroup> </table> <p>Table 1. Classes and types of the Location Settings API. </p> <p><b>Libraries </b> </p> <p>API classes are packaged in <filepath>eposmodset.dll</filepath>. Clients link with <filepath>eposmodset.lib</filepath>. </p> <p><b>Capabilities </b> </p> <p>API clients require <codeph>WriteDeviceData</codeph> capability to update modifiable settings (PSY priority order, modifiable PSY attributes). </p> <p>API clients require no capabilities to read PSY settings. </p> </section> <section id="GUID-F2BD6C21-25D7-5E3A-B24E-16D783EDDFA6"><title>Using the API</title> <p>Uses cases for the API are: </p> <ul><li id="GUID-299D0BA9-6630-5D30-9533-989BCED32F68"><p><xref href="GUID-DABBFC53-CC93-54AA-ADFD-6756B1EA878C.dita#GUID-DABBFC53-CC93-54AA-ADFD-6756B1EA878C/GUID-54DC1DC0-290A-55DD-B5BD-D87BE8E3194F"> Retrieving information about installed PSYs</xref> </p> </li> <li id="GUID-26BEDF7C-3354-57F2-AC90-FEAD79E7C5A3"><p><xref href="GUID-DABBFC53-CC93-54AA-ADFD-6756B1EA878C.dita#GUID-DABBFC53-CC93-54AA-ADFD-6756B1EA878C/GUID-B5AC0535-5CFA-5A5F-A67F-F05A3D7F78D1">Modifying PSY attributes</xref> </p> </li> <li id="GUID-8023AF65-8962-59D4-889E-440CF4C11677"><p><xref href="GUID-DABBFC53-CC93-54AA-ADFD-6756B1EA878C.dita#GUID-DABBFC53-CC93-54AA-ADFD-6756B1EA878C/GUID-0ADE50DD-84E3-5DAE-94E3-4BB424665734">Changing priority order of PSYs </xref> </p> </li> <li id="GUID-EFAF4AE9-5845-5882-88BC-B1B6A209324F"><p><xref href="GUID-DABBFC53-CC93-54AA-ADFD-6756B1EA878C.dita#GUID-DABBFC53-CC93-54AA-ADFD-6756B1EA878C/GUID-1438A703-4F6F-5AC2-A52C-37BABE7AF5B9"> Listening to settings change events </xref> </p> </li> </ul> <p id="GUID-54DC1DC0-290A-55DD-B5BD-D87BE8E3194F"><b>Retrieving information about installed PSYs </b> </p> <p>A client can read ordered list of PSYs by using <xref href="GUID-3EC269A3-61A0-378B-A909-AB5881E47769.dita#GUID-3EC269A3-61A0-378B-A909-AB5881E47769/GUID-5A626C61-0A95-3628-9CBB-FDBF04676281"><apiname>CPosModules::ModuleIdListL()</apiname></xref> or <xref href="GUID-3EC269A3-61A0-378B-A909-AB5881E47769.dita#GUID-3EC269A3-61A0-378B-A909-AB5881E47769/GUID-6A8BBAA1-3938-3572-BA4E-B7C9F8BCA82E"><apiname>CPosModules::ModuleIdListLC()</apiname></xref>. These methods return a list of IDs for the currently installed PSYs in priority order. Only the PSYs which have visibility attribute set to 1 (ETrue) are listed. </p> <p>The client may request information from a specific PSY by providing its ID to <xref href="GUID-3EC269A3-61A0-378B-A909-AB5881E47769.dita#GUID-3EC269A3-61A0-378B-A909-AB5881E47769/GUID-66188192-A70D-3CF4-B35F-50BEBE8431C4"><apiname>CPosModules::GetModuleInfoL()</apiname></xref>. If a PSY with the specified ID is found in the system, its data is returned in the <xref href="GUID-1E6620E4-F194-3482-BBD1-D85F3528D87D.dita"><apiname>TPositionModuleInfoBase</apiname></xref> derived object, supplied by client. Currently, the only supported subclass is <xref href="GUID-B098F3DB-E2FE-3C5A-8508-4B04D954AB26.dita"><apiname>TPositionModuleInfo</apiname></xref>. For more information, see <xref href="GUID-D0318BB6-0B9F-5A1C-AB0B-61BA22D28661.dita">Location Acquisition API</xref>. </p> <p>Figure 2 shows the client listing all available PSYs and retrieving their attributes: </p> <fig id="GUID-3C2F95B1-7F68-59B0-A1F9-8562432D43FD"><title> |
14 </title> <image href="GUID-E3F116C0-F133-5008-BD7A-421D66FB6588_d0e442635_href.png" placement="inline"/></fig> <p>Table 1 lists the classes and types of the API. </p> <table id="GUID-404231E8-601E-5D56-A3E2-D6DFFB266AC7"><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-3EC269A3-61A0-378B-A909-AB5881E47769.dita"><apiname>CPosModules</apiname></xref> </p> </entry> <entry><p>The main class of the Location Settings API. It is used for accessing PSY attributes and managing priority list of PSYs. A client can also register to listen for changes in the settings. </p> </entry> <entry><p> <codeph>EPos_CPosModuleIdList.h</codeph> </p> </entry> </row> <row><entry><p> <xref href="GUID-1AB3C182-B9F9-3C75-9FC2-C550500046CB.dita"><apiname>CPosModuleUpdate</apiname></xref> </p> </entry> <entry><p>Represents an update of the modifiable attributes of a PSY. An update is committed by calling <xref href="GUID-3EC269A3-61A0-378B-A909-AB5881E47769.dita#GUID-3EC269A3-61A0-378B-A909-AB5881E47769/GUID-590B754B-2ECB-313F-A8C5-44B2C2A1E37F"><apiname>CPosModules::UpdateModuleL()</apiname></xref>. </p> </entry> <entry><p> <codeph>EPos_CPosModuleUpdate.h</codeph> </p> </entry> </row> <row><entry><p> <xref href="GUID-2E3EB368-F820-3B1F-A025-939D78A5F9CE.dita"><apiname>CPosModuleIdList</apiname></xref> </p> </entry> <entry><p>Represents a list of PSY IDs. Used to get and set the priority list of PSYs. It contains methods for appending, inserting, removing and finding PSY IDs in the list. </p> </entry> <entry><p> <codeph>EPos_CPosModuleIdList.h</codeph> </p> </entry> </row> <row><entry><p> <xref href="GUID-2C027B56-CC69-307E-ABB4-BBB532D8F473.dita"><apiname>MPosModulesObserver</apiname></xref> </p> </entry> <entry><p>The interface that is implemented by clients in order to receive notifications of changes in the PSY settings. A client subscribes for notifications through the <xref href="GUID-3EC269A3-61A0-378B-A909-AB5881E47769.dita"><apiname>CPosModules</apiname></xref> class. </p> <p>Notification event information is given in a <xref href="GUID-5760EA9E-7720-31CD-B8F7-29370E2B6FCB.dita"><apiname>TPosModulesEvent</apiname></xref> structure. </p> <p>Typedef <xref href="GUID-9559BB6D-894E-3814-8D60-4102A465EC3D.dita"><apiname>TPosModulesEventType</apiname></xref> defines possible event types. </p> </entry> <entry><p> <codeph>EPos_MPosModulesObserver.h</codeph> </p> </entry> </row> </tbody> </tgroup> </table> <p>Table 1. Classes and types of the Location Settings API. </p> <p><b>Libraries </b> </p> <p>API classes are packaged in <filepath>eposmodset.dll</filepath>. Clients link with <filepath>eposmodset.lib</filepath>. </p> <p><b>Capabilities </b> </p> <p>API clients require <codeph>WriteDeviceData</codeph> capability to update modifiable settings (PSY priority order, modifiable PSY attributes). </p> <p>API clients require no capabilities to read PSY settings. </p> </section> <section id="GUID-F2BD6C21-25D7-5E3A-B24E-16D783EDDFA6"><title>Using the API</title> <p>Uses cases for the API are: </p> <ul><li id="GUID-299D0BA9-6630-5D30-9533-989BCED32F68"><p><xref href="GUID-DABBFC53-CC93-54AA-ADFD-6756B1EA878C.dita#GUID-DABBFC53-CC93-54AA-ADFD-6756B1EA878C/GUID-54DC1DC0-290A-55DD-B5BD-D87BE8E3194F"> Retrieving information about installed PSYs</xref> </p> </li> <li id="GUID-26BEDF7C-3354-57F2-AC90-FEAD79E7C5A3"><p><xref href="GUID-DABBFC53-CC93-54AA-ADFD-6756B1EA878C.dita#GUID-DABBFC53-CC93-54AA-ADFD-6756B1EA878C/GUID-B5AC0535-5CFA-5A5F-A67F-F05A3D7F78D1">Modifying PSY attributes</xref> </p> </li> <li id="GUID-8023AF65-8962-59D4-889E-440CF4C11677"><p><xref href="GUID-DABBFC53-CC93-54AA-ADFD-6756B1EA878C.dita#GUID-DABBFC53-CC93-54AA-ADFD-6756B1EA878C/GUID-0ADE50DD-84E3-5DAE-94E3-4BB424665734">Changing priority order of PSYs </xref> </p> </li> <li id="GUID-EFAF4AE9-5845-5882-88BC-B1B6A209324F"><p><xref href="GUID-DABBFC53-CC93-54AA-ADFD-6756B1EA878C.dita#GUID-DABBFC53-CC93-54AA-ADFD-6756B1EA878C/GUID-1438A703-4F6F-5AC2-A52C-37BABE7AF5B9"> Listening to settings change events </xref> </p> </li> </ul> <p id="GUID-54DC1DC0-290A-55DD-B5BD-D87BE8E3194F"><b>Retrieving information about installed PSYs </b> </p> <p>A client can read ordered list of PSYs by using <xref href="GUID-3EC269A3-61A0-378B-A909-AB5881E47769.dita#GUID-3EC269A3-61A0-378B-A909-AB5881E47769/GUID-5A626C61-0A95-3628-9CBB-FDBF04676281"><apiname>CPosModules::ModuleIdListL()</apiname></xref> or <xref href="GUID-3EC269A3-61A0-378B-A909-AB5881E47769.dita#GUID-3EC269A3-61A0-378B-A909-AB5881E47769/GUID-6A8BBAA1-3938-3572-BA4E-B7C9F8BCA82E"><apiname>CPosModules::ModuleIdListLC()</apiname></xref>. These methods return a list of IDs for the currently installed PSYs in priority order. Only the PSYs which have visibility attribute set to 1 (ETrue) are listed. </p> <p>The client may request information from a specific PSY by providing its ID to <xref href="GUID-3EC269A3-61A0-378B-A909-AB5881E47769.dita#GUID-3EC269A3-61A0-378B-A909-AB5881E47769/GUID-66188192-A70D-3CF4-B35F-50BEBE8431C4"><apiname>CPosModules::GetModuleInfoL()</apiname></xref>. If a PSY with the specified ID is found in the system, its data is returned in the <xref href="GUID-1E6620E4-F194-3482-BBD1-D85F3528D87D.dita"><apiname>TPositionModuleInfoBase</apiname></xref> derived object, supplied by client. Currently, the only supported subclass is <xref href="GUID-B098F3DB-E2FE-3C5A-8508-4B04D954AB26.dita"><apiname>TPositionModuleInfo</apiname></xref>. For more information, see <xref href="GUID-D0318BB6-0B9F-5A1C-AB0B-61BA22D28661.dita">Location Acquisition API</xref>. </p> <p>Figure 2 shows the client listing all available PSYs and retrieving their attributes: </p> <fig id="GUID-3C2F95B1-7F68-59B0-A1F9-8562432D43FD"><title> |
16 </title> <image href="GUID-E35C440C-4191-510A-AD33-2CF56E41EDD2_d0e454323_href.png" placement="inline"/></fig> <p>The following example shows the client getting list of names of enabled plug-ins: </p> <codeblock id="GUID-C82837F0-D44E-5046-84F6-DA74123F39B7" xml:space="preserve">void ListEnabledPluginsL( CDesCArray& aNames ) |
16 </title> <image href="GUID-E35C440C-4191-510A-AD33-2CF56E41EDD2_d0e442890_href.png" placement="inline"/></fig> <p>The following example shows the client getting list of names of enabled plug-ins: </p> <codeblock id="GUID-C82837F0-D44E-5046-84F6-DA74123F39B7" xml:space="preserve">void ListEnabledPluginsL( CDesCArray& aNames ) |