Addition of the PDK content and example code for Documentation_content according to Feature bug 1607 and bug 1608
<?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 task
PUBLIC "-//OASIS//DTD DITA Task//EN" "task.dtd">
<task id="GUID-F9BEC749-D535-55EA-8601-A961EA1E441B" xml:lang="en"><title>Modifying
the Bluetooth GPS PSY Settings </title><shortdesc>This topic describes how to modify the settings of the Bluetooth
GPS PSY. </shortdesc><prolog><metadata><keywords/></metadata></prolog><taskbody>
<context><p>The Central Repository initialisation file <codeph>101FE999.txt</codeph> contains
the default Bluetooth GPS PSY settings. You can modify the default values
in this file. There are two types of information stored in the initialisation
file: </p> <ul>
<li id="GUID-DC531E09-6CD3-5173-8AD7-37A2F63FB671"><p>Keys and values defined
by the Positioning Plug-in Information API. </p> <p>These keys and values
define the properties of the Bluetooth GPS PSY and GPS device, such as the
time to get a first fix and the typical position fix accuracy. </p> <p>The
default values describe the properties of a typical Bluetooth GPS device,
and for most purposes it is not necessary to modify them. </p> </li>
<li id="GUID-3B2DCDD6-659C-5FD5-92A0-DC84527BF223"><p>Keys and values that
define Bluetooth GPS operational properties. </p> <p>The properties describe
the behaviour of the Bluetooth GPS PSY in its operation with the GPS device.
Properties you can modify include timeouts and buffer size. </p> <p>The operational
properties can be read (and some can be set) at runtime using the <xref href="GUID-F84E7419-7F31-5E18-8854-27CB1F9F890E.dita">Bluetooth
GPS PSY Settings Storage API</xref>. </p> </li>
</ul> </context>
<steps id="GUID-9281FD96-F195-5C1B-ACC6-7E2FDC2B4C93">
<step id="GUID-76FFFE77-A7E7-5EEE-8936-9B99B29F9ADF"><cmd/>
<info>Modify the contents of the Central Repository file <codeph>101FE999.txt</codeph> as
described below. </info>
</step>
<step id="GUID-D38DB3A3-5051-583C-83A5-E298CEC265E0"><cmd/>
<info>Rebuild the Bluetooth PSY ROM or rebuild the PSY SIS file. </info>
<info>The Central Repository initialisation file <codeph>101FE999.txt</codeph> contains
default settings for the PSY. It is shown below: </info>
<stepxmp><codeblock id="GUID-2281A55D-259D-5FC4-BE3C-2FCA9E26CE08" xml:space="preserve">
cenrep
version 1
[owner]
0x101f97b2
[defaultmeta]
0
[platsec]
cap_rd=ReadDeviceData cap_wr=WriteDeviceData
[Main]
0x1 int 1 0 cap_rd=alwayspass cap_wr=alwaysfail
0x2 int 0 0 cap_rd=alwayspass cap_wr=alwaysfail
0x3 int 1 0 cap_rd=alwayspass cap_wr=alwaysfail
0x4 int 80000000 0 cap_rd=alwayspass cap_wr=alwaysfail
0x5 int 1000000 0 cap_rd=alwayspass cap_wr=alwaysfail
0x6 real 10 0 cap_rd=alwayspass cap_wr=alwaysfail
0x7 real 30 0 cap_rd=alwayspass cap_wr=alwaysfail
0x8 int 1 0 cap_rd=alwayspass cap_wr=alwaysfail
0x9 int 3 0 cap_rd=alwayspass cap_wr=alwaysfail
0xa int 1 0 cap_rd=alwayspass cap_wr=alwaysfail
0xb int 2 0 cap_rd=alwayspass cap_wr=alwaysfail
0xc int 95 0 cap_rd=alwayspass cap_wr=alwaysfail
0xd int 15 0 cap_rd=alwayspass cap_wr=alwaysfail
0xe int 1 0 cap_rd=alwayspass cap_wr=alwaysfail
0xf string "\\resource\\nlabtgpspsy_name.rsc" 0 cap_rd=alwayspass cap_wr=alwaysfail
0x10000000 int 0 16777216 cap_rd=alwayspass cap_wr=WriteDeviceData
0x10000001 int 1 16777216 cap_rd=alwayspass cap_wr=WriteDeviceData
0x10000002 int 1 16777216 cap_rd=alwayspass cap_wr=WriteDeviceData
0x10000003 int 1 16777216 cap_rd=alwayspass cap_wr=WriteDeviceData
0x10000004 int 1 16777216 cap_rd=alwayspass cap_wr=WriteDeviceData
0x10000005 int 1 16777216 cap_rd=alwayspass cap_wr=WriteDeviceData
0x10000006 int 1 16777216 cap_rd=alwayspass cap_wr=WriteDeviceData
0x10000007 string "" 16777216 cap_rd=alwayspass cap_wr=WriteDeviceData
0x10000008 int 0 16777216 cap_rd=alwayspass cap_wr=WriteDeviceData
0x11000001 int 100000 0 cap_rd=alwayspass cap_wr=alwaysfail
0x11000002 real 8 0 cap_rd=alwayspass cap_wr=alwaysfail
0x11000003 int 3 0 cap_rd=alwayspass cap_wr=alwaysfail
0x11000004 int 300000 0 cap_rd=alwayspass cap_wr=alwaysfail
0x11000005 int 10 0 cap_rd=alwayspass cap_wr=alwaysfail
0x11000006 int 5000000 0 cap_rd=alwayspass cap_wr=alwaysfail
0x11000007 int 10000000 0 cap_rd=alwayspass cap_wr=alwaysfail
0x11000008 int 60000000 0 cap_rd=alwayspass cap_wr=alwaysfail
0x11000009 int 1 0 cap_rd=alwayspass cap_wr=alwaysfail
0x1100000a int 20000000 0 cap_rd=alwayspass cap_wr=alwaysfail
0x1100000b int 5120 0 cap_rd=alwayspass cap_wr=alwaysfail
</codeblock> </stepxmp>
<info>The values with keys from 0x1 to 0xf describe the PSY properties defined
by the Positioning Plug-in Information API. </info>
<info>Generally, you do not need to change these values as they describe typical
capabilities of a Bluetooth GPS positioning device. </info>
<stepxmp><table id="GUID-CF6C22EF-981F-5271-A65E-6DCBA07E7B9C">
<tgroup cols="4"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/><colspec colname="col3"/>
<thead>
<row>
<entry>Key name</entry>
<entry>Key ID</entry>
<entry>Meaning</entry>
<entry>Default value and description</entry>
</row>
</thead>
<tbody>
<row>
<entry><p> <xref href="GUID-4C4DCA0A-E524-3383-8151-A68FF8DBF72F.dita"><apiname>KPSYInterfaceVersion</apiname></xref> </p> </entry>
<entry><p> <codeph>0x1</codeph> </p> </entry>
<entry><p>Version of the Positioning Plug-in Information API interface </p> </entry>
<entry><p>Version 1. </p> </entry>
</row>
<row>
<entry><p> <xref href="GUID-9E477072-14CC-3247-B39C-909802A49EA9.dita"><apiname>KPSYPriority </apiname></xref> </p> </entry>
<entry><p> <codeph>0x2</codeph> </p> </entry>
<entry><p>PSY priority on installation </p> </entry>
<entry><p>Value of 0 specifies this PSY has the highest priority. </p> </entry>
</row>
<row>
<entry><p> <xref href="GUID-C64C26DB-52A1-36B0-B890-6E2879AE4938.dita"><apiname> KPSYStatus</apiname></xref> </p> </entry>
<entry><p> <codeph>0x3</codeph> </p> </entry>
<entry><p>PSY status when it is installed on the system </p> </entry>
<entry><p>Value of 1 indicates this PSY is available on installation. </p> </entry>
</row>
<row>
<entry><p> <xref href="GUID-F0018CF3-8D7E-3E5C-8345-779EA09C514D.dita"><apiname>KPSYTimeToFirstFix</apiname></xref> </p> </entry>
<entry><p> <codeph>0x4</codeph> </p> </entry>
<entry><p>Time to First Fix </p> </entry>
<entry><p>Large value of 80 seconds because an external Bluetooth GPS device
uses autonomous GPS. </p> </entry>
</row>
<row>
<entry><p> <xref href="GUID-FA1D8202-F243-3271-BC24-0092BC803D3A.dita"><apiname>KPSYTimeToNextFix</apiname></xref> </p> </entry>
<entry><p> <codeph>0x5</codeph> </p> </entry>
<entry><p>Time to Next Fix </p> </entry>
<entry><p>Value of 1 second (specified as 1000000 microseconds). </p> </entry>
</row>
<row>
<entry><p> <xref href="GUID-7C18FF42-1D28-3C35-B950-80AFDEBCAEE8.dita"><apiname>KPSYHorizontalAccuracy</apiname></xref> </p> </entry>
<entry><p> <codeph>0x6</codeph> </p> </entry>
<entry><p>Horizontal Accuracy </p> </entry>
<entry><p>10 metres accuracy. </p> </entry>
</row>
<row>
<entry><p> <xref href="GUID-8F18F9EA-A90F-31BE-968C-C925D4428CBF.dita"><apiname>KPSYVerticalAccuracy</apiname></xref> </p> </entry>
<entry><p> <codeph>0x7</codeph> </p> </entry>
<entry><p>Vertical Accuracy </p> </entry>
<entry><p>30 metres accuracy. </p> </entry>
</row>
<row>
<entry><p> <xref href="GUID-0D9A6DA8-0705-3511-8381-E46AAC50E5AB.dita"><apiname>KPSYCostIndicator</apiname></xref> </p> </entry>
<entry><p>0x8 </p> </entry>
<entry><p>Cost Indicator </p> </entry>
<entry><p> <xref href="GUID-1AA235FA-CEC1-3853-8F96-C538C02B596D.dita#GUID-1AA235FA-CEC1-3853-8F96-C538C02B596D/GUID-6DFD5B58-D59C-33DC-A0E2-4D6A23190778"><apiname>TPositionQuality::ECostZero</apiname></xref> because the PSY
uses autonomous GPS. </p> </entry>
</row>
<row>
<entry><p> <xref href="GUID-CC3515E5-4A2D-3371-A4BF-3197AABE7B6F.dita"><apiname>KPSYPowerConsumption</apiname></xref> </p> </entry>
<entry><p> <codeph>0x9</codeph> </p> </entry>
<entry><p>Power Consumption </p> </entry>
<entry><p> <xref href="GUID-1AA235FA-CEC1-3853-8F96-C538C02B596D.dita#GUID-1AA235FA-CEC1-3853-8F96-C538C02B596D/GUID-5D12179A-FB8C-3E58-B728-B2DEC3A24231"><apiname>TPositionQuality::EPowerMedium</apiname></xref> indicates medium
power consumption. </p> </entry>
</row>
<row>
<entry><p> <xref href="GUID-715DB9BF-8C60-39AA-A653-3C4FFC38B94D.dita"><apiname>KPSYTechnologyType</apiname></xref> </p> </entry>
<entry><p> <codeph>0xa</codeph> </p> </entry>
<entry><p>Technology Type </p> </entry>
<entry><p> <xref href="GUID-B098F3DB-E2FE-3C5A-8508-4B04D954AB26.dita#GUID-B098F3DB-E2FE-3C5A-8508-4B04D954AB26/GUID-D9D66F7B-86FB-350F-9B12-4E7DEEA4D756"><apiname>TPositionModuleInfo::_ETechnologyTerminal</apiname></xref> indicates
the position fix is obtained from the device. </p> </entry>
</row>
<row>
<entry><p> <xref href="GUID-85153FA6-F39E-3654-B69E-D5ED0466F194.dita"><apiname>KPSYDeviceLocation</apiname></xref> </p> </entry>
<entry><p> <codeph>0xb</codeph> </p> </entry>
<entry><p>Device location </p> </entry>
<entry><p> <xref href="GUID-B098F3DB-E2FE-3C5A-8508-4B04D954AB26.dita#GUID-B098F3DB-E2FE-3C5A-8508-4B04D954AB26/GUID-67DB640A-4871-3B52-81E1-F69E026A0A56"><apiname>TPositionModuleInfo::EDeviceExternal</apiname></xref> = 2. Specifies
the GPS device is external to the mobile device. </p> </entry>
</row>
<row>
<entry><p> <xref href="GUID-C3FD0558-0C69-3587-ABFD-61AFBC328A7B.dita"><apiname>KPSYCapabilities</apiname></xref> </p> </entry>
<entry><p> <codeph>0xc</codeph> </p> </entry>
<entry><p>Device Capabilities </p> </entry>
<entry><p>Values from <xref href="GUID-B098F3DB-E2FE-3C5A-8508-4B04D954AB26.dita#GUID-B098F3DB-E2FE-3C5A-8508-4B04D954AB26/GUID-C798CBA5-39BE-3072-9E9B-5910C4835DCC"><apiname>TPositionModuleInfo::_TCapabilities</apiname></xref> indicate
the positioning capabilities supported. These are <codeph>ECapabilityHorizontal
| ECapabilityVertical | ECapabilitySpeed | ECapabilityDirection
| ECapabilitySatellite | ECapabilityNmea</codeph> =
95 decimal. </p> </entry>
</row>
<row>
<entry><p> <xref href="GUID-8B42A620-635D-34A6-B8D4-FA0BC33CDE4B.dita"><apiname>KPSYClassesSupported</apiname></xref> </p> </entry>
<entry><p> <codeph>0xd</codeph> </p> </entry>
<entry><p>Supported Positioning classes </p> </entry>
<entry><p>Values from <xref href="GUID-22228828-26F8-3AEE-A90E-29A6F71757BA.dita#GUID-22228828-26F8-3AEE-A90E-29A6F71757BA/GUID-D68E36AD-CEC2-3E2E-995A-92027C389389"><apiname>TPositionModuleInfoClassType::_TPositionInfoClassType</apiname></xref> indicate
the classes supported. These are: <codeph>EPositionInfoClass |
EPositionGenericInfoClass | EPositionCourseInfoClass |
EPositionSatelliteInfoClass </codeph> = 15 decimal. </p> </entry>
</row>
<row>
<entry><p> <xref href="GUID-9449A2EB-85B5-3221-9D12-A543BFD8CE3A.dita"><apiname>KPSYVisibility</apiname></xref> </p> </entry>
<entry><p> <codeph>0xe</codeph> </p> </entry>
<entry><p>Visibility of this PSY to the Location Server </p> </entry>
<entry><p>1 defines this PSY as visible. </p> </entry>
</row>
<row>
<entry><p> <xref href="GUID-A6348C78-825B-3CD5-A0B3-12885F9CCCB8.dita"><apiname>KPSYNameResource</apiname></xref> </p> </entry>
<entry><p> <codeph>0xf</codeph> </p> </entry>
<entry><p>PSY display name </p> </entry>
<entry><p> <codeph>\\resource\\nlabtgpspsy_name.rsc</codeph> </p> </entry>
</row>
</tbody>
</tgroup>
</table> </stepxmp>
<info>The values with keys from <codeph>0x11000001</codeph> to <codeph>0x1100000b</codeph> describe
the Bluetooth GPS PSY operational properties. You can change these values
from their defaults if you want to modify the behaviour of the PSY. </info>
<stepxmp><table id="GUID-234A3608-BFF0-5E7B-BF7E-4C87054461FF">
<tgroup cols="5"><colspec colname="col0"/><colspec colname="col1"/><colspec colname="col2"/><colspec colname="col3"/><colspec colname="col4"/>
<thead>
<row>
<entry>Key ID</entry>
<entry>Key Name</entry>
<entry>Meaning</entry>
<entry>Default Value</entry>
<entry>Valid Range</entry>
</row>
</thead>
<tbody>
<row>
<entry><p> <codeph>0x11000001</codeph> </p> </entry>
<entry><p> <xref href="GUID-5CA02509-35A4-3D49-9B3A-1C59274D2D11.dita"><apiname>KBluetoothGpsPsyMsgSendDelay</apiname></xref> </p> </entry>
<entry><p>The minimum delay between messages that are sent to the Bluetooth
device. </p> <p>Value is in microseconds. </p> </entry>
<entry><p>100000 </p> </entry>
<entry><p>[0,60] seconds </p> </entry>
</row>
<row>
<entry><p> <codeph> 0x11000002</codeph> </p> </entry>
<entry><p> <xref href="GUID-88A2ABD4-355E-38DC-A441-368B265258B3.dita"><apiname>KBluetoothGpsPsyUserEquivalentRangeError</apiname></xref> </p> </entry>
<entry><p>Defines the user equivalent range error used in GPS data error calculations.
User equivalent range error is used for examining GPS positioning accuracy. </p> <p>Value
is in metres. </p> </entry>
<entry><p>8</p> </entry>
<entry><p>[0,1000] metres </p> </entry>
</row>
<row>
<entry><p> <codeph>0x11000003 </codeph> </p> </entry>
<entry><p> <xref href="GUID-9E50BDBA-C1CB-3FF6-A4E7-8125D562F56D.dita"><apiname>KBluetoothGpsPsyNumTestNmeaSentences</apiname></xref> </p> </entry>
<entry><p>The number of test NMEA sentences expected. </p> </entry>
<entry><p>3</p> </entry>
<entry><p>[0,100000] </p> </entry>
</row>
<row>
<entry><p> <codeph>0x11000004 </codeph> </p> </entry>
<entry><p> <xref href="GUID-7D617B71-40A5-3937-A566-523A1D42316F.dita"><apiname>KBluetoothGpsPsyNormalGpsInitMsgDelay</apiname></xref> </p> </entry>
<entry><p>The delay between the initialisation messages sent to the GPS device. </p> <p>Value
is in microseconds. </p> </entry>
<entry><p>300000 </p> </entry>
<entry><p>[0,10] minutes </p> </entry>
</row>
<row>
<entry><p> <codeph>0x11000005</codeph> </p> </entry>
<entry><p> <xref href="GUID-6AF9A406-5BBB-3AA7-A77E-D99A3C3FAACA.dita"><apiname>KBluetoothGpsPsyNumSetFullPowerMsg</apiname></xref> </p> </entry>
<entry><p>The number of "set full power messages" to send when initialising
the GPS device. </p> </entry>
<entry><p>10 </p> </entry>
<entry><p>[0,100000] </p> </entry>
</row>
<row>
<entry><p> <codeph> 0x11000006</codeph> </p> </entry>
<entry><p> <xref href="GUID-AC1DE252-EC78-35DC-9DEC-5178557B6C26.dita"><apiname>KBluetoothGpsPsyPnokPollingDelay</apiname></xref> </p> </entry>
<entry><p>The delay in waiting for a PNOK compatible BT GPS device to respond
to a PNOK polling message. </p> <p>Value is in microseconds. </p> </entry>
<entry><p>5000000 </p> </entry>
<entry><p>[0,10] minutes </p> </entry>
</row>
<row>
<entry><p> <codeph> 0x11000007</codeph> </p> </entry>
<entry><p> <xref href="GUID-4C2673BA-9EFF-39DF-9AEF-7F6EDBF4C996.dita"><apiname>KBluetoothGpsPsyReconnectionTimeout</apiname></xref> </p> </entry>
<entry><p>The time to wait between re-connection attempts. </p> <p>Value is
in microseconds. </p> </entry>
<entry><p>10000000 </p> </entry>
<entry><p>[0,10] minutes </p> </entry>
</row>
<row>
<entry><p> <codeph>0x11000008</codeph> </p> </entry>
<entry><p> <xref href="GUID-99C00C9E-F69B-3321-BBCC-606CE3E3ECE5.dita"><apiname>KBluetoothGpsPsyInactiveDealy</apiname></xref> </p> </entry>
<entry><p>If the PSY has received no tracking session or location request
by the expiry of this timeout, the PSY goes into the standby state. </p> <p>In
the standby state, the connection to Bluetooth GPS device is disconnected. </p> <p>Value
is in microseconds. </p> </entry>
<entry><p>60000000 </p> </entry>
<entry><p>[0,10] minutes </p> </entry>
</row>
<row>
<entry><p> <codeph>0x11000009</codeph> </p> </entry>
<entry><p> <xref href="GUID-F268AD43-4229-34F5-8223-388496B2A851.dita"><apiname>KBluetoothGpsPsyUtilisePowerSaving</apiname></xref> </p> </entry>
<entry><p>Boolean value for disabling the sending of power saving NMEA message
to the GPS device. Set this to 0 to disable power saving command usage. Any
other value enables power saving. </p> </entry>
<entry><p>1</p> </entry>
<entry><p>0 or 1 </p> </entry>
</row>
<row>
<entry><p> <codeph> 0x1100000a</codeph> </p> </entry>
<entry><p> <xref href="GUID-55B69071-3020-3D35-848D-90E5B5942007.dita"><apiname>KBluetoothGpsPsySateInfoLifeTime</apiname></xref> </p> </entry>
<entry><p>Integer value that specifies the satellite information expiration
time. Cached satellite information older than this value is not used. </p> <p>Value
is in microseconds. </p> </entry>
<entry><p>20000000 </p> </entry>
<entry><p>[0,10000] seconds </p> </entry>
</row>
<row>
<entry><p> <codeph> 0x1100000b</codeph> </p> </entry>
<entry><p> <xref href="GUID-5CBB3A4C-67C5-39F5-9D4D-D0A8AD12E9FE.dita"><apiname>KBluetoothGpsPsyNmeaBufferSize</apiname></xref> </p> </entry>
<entry><p>Integer value that specifies the size of NMEA data buffer. The buffer
size must be large enough to hold all NMEA data messages that a BT GPS device
send in one second. </p> <p>A very large value increases run time RAM usage
by the Bluetooth GPS PSY. </p> </entry>
<entry><p>5012 </p> </entry>
<entry><p>[0, 50*1024] </p> </entry>
</row>
</tbody>
</tgroup>
</table> </stepxmp>
</step>
</steps>
</taskbody><related-links>
<link href="GUID-E73A181C-0C9B-513C-ABAE-585C80D566DF.dita"><linktext>Bluetooth
GPS PSY Overview</linktext></link>
<link href="GUID-38A84B6A-BA49-55ED-A4D7-9B4436D00A42.dita"><linktext>Including
the Bluetooth GPS PSY in ROM</linktext></link>
<link href="GUID-731CE582-91A4-59E0-9004-227FBCFC7D3F.dita"><linktext>Packaging
the Bluetooth GPS PSY in a SIS File</linktext></link>
<link href="GUID-DA2DC704-CE65-54FB-9049-4E1C73092EDF-GENID-1-7-1-15-1-1-10-1-5-1-5-1-8-1.dita"><linktext>Positioning
Plug-in Information API</linktext></link>
<link href="GUID-F84E7419-7F31-5E18-8854-27CB1F9F890E.dita"><linktext>Bluetooth
GPS PSY Settings Storage API</linktext></link>
</related-links></task>