<?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 concept
  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<concept xml:lang="en" id="GUID-7C1CF86B-5F03-55EE-96C6-79A88A195BEB"><title>Opening a Session - Reference</title><shortdesc>This topic provides additional information with regard to opening a session with Bluetooth GPS PSY. </shortdesc><prolog><metadata><keywords/></metadata></prolog><conbody><section><title>Required background</title> <p>Knowledge of the <xref href="GUID-D0318BB6-0B9F-5A1C-AB0B-61BA22D28661.dita">Location Acquisition API</xref> is helpful in understanding this topic. </p> </section> <section><title>Introduction</title> <p>Steps that describe how to open the default PSY or a Bluetooth GPS PSY Session are provided <xref href="GUID-51177BB6-D906-57BD-91DD-EC263F900225.dita">here</xref>. The sections that follow provide information on error codes and Bluetooth GPS PSY behavior during use. </p> </section> <section id="GUID-2C9F2B48-5E92-5C25-9C16-B93C34B223B7"><title>Error codes</title> <p>This section describes some of the error codes that can be returned on construction of the Bluetooth GPS PSY. A client must check for error codes when it calls <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> to create a subsession that uses the Bluetooth GPS PSY. </p> <table id="GUID-F6E6958C-3ABE-5EF8-9C54-377732F4E51A"><tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/><thead><row><entry>Error Code</entry> <entry>Conditions for code return</entry> </row> </thead> <tbody><row><entry><p> <codeph> KErrNone</codeph>  </p> </entry> <entry><p>An instance of the Bluetooth GPS PSY was successfully constructed. </p> </entry> </row> <row><entry><p> <codeph>KErrNoMemory</codeph>  </p> </entry> <entry><p>Construction of the PSY fails because the device is out of memory. </p> </entry> </row> <row><entry><p> <codeph>KErrAlreadyExists</codeph>  </p> </entry> <entry><p>The PSY instance is already registered. This means some internal error in the Location Server Framework or in the PSY itself. The client application may need to be restarted to reload the PSY. </p> </entry> </row> <row><entry><p> <codeph> KErrOverflow</codeph>  </p> </entry> <entry><p>One of the parameters set in the PSY Central Repository initialisation file <codeph>101FE999.txt</codeph> (<codeph>101FE999.cre</codeph>) is out of range. </p> </entry> </row> <row><entry><p> <codeph> KErrUnderflow</codeph>  </p> </entry> <entry><p>One of the parameters set in the PSY Central Repository initialisation file is out of range. </p> </entry> </row> <row><entry><p>Any other general Symbian platform error code </p> </entry> <entry><p>Any other system error. </p> </entry> </row> </tbody> </tgroup> </table> <p>The following sections give more information about the behaviour of the Bluetooth GPS PSY during use. </p> </section> <section id="GUID-B253E1BD-59C4-5725-9899-16E495233DAA"><title>Loading the PSY and device selection</title> <p>The Bluetooth GPS PSY is loaded dynamically when a client makes a request that requires its use (by one of the methods described above). </p> <p>If the mobile device is not already connected to a Bluetooth GPS device the PSY attempts to connect to one as follows: </p> <ol id="GUID-00F3A5C5-5758-5FBB-9ECD-21E713F97A73"><li id="GUID-383EE17B-8DE8-56D0-85EE-B825F8045996"><p>The PSY automatically attempts to connect to the GPS device to which it was last successfully connected. The device address used is the one stored in the Central Repository setting <xref href="GUID-2B93F706-EBA0-3201-BC03-CEEC2CDE3912.dita"><apiname>KBluetoothGpsPsyDeviceAddress</apiname></xref>. The user may be queried for a passkey as part of this process in order to pair with the Bluetooth GPS device. </p> <p>Figure 1 shows this procedure, followed by an exchange of NMEA initialisation messages between the PSY and the GPS device. </p> </li> <li id="GUID-9485F04B-ADA8-5DCF-B041-EE5702DB3AF9"><p>If the PSY cannot connect to the GPS device to which it was last connected, it tries to connect to each of the GPS devices in the list managed through the <xref href="GUID-2A137918-D949-5017-BB00-B93CFA8AA65F.dita">Bluetooth GPS PSY Configuration API</xref>. </p> </li> <li id="GUID-97D7A84D-AFB9-5EBB-83E4-0CF7DFBEFB20"><p>If the PSY still cannot connect to a Bluetooth GPS device, the Bluetooth subsystem displays a device selection dialog asking for the Bluetooth GPS device details. </p> <p>If a connection can be made to the device, its address is stored in the Central Repository setting <codeph>KBluetoothGpsPsyDeviceAddress</codeph>. The PSY tries to use this GPS device the next time it receives a client request (see [1] above). </p> <p>If a connection cannot be made to the device, or the device selection dialog is cancelled, the PSY remains loaded, but not connected to a Bluetooth GPS device. In this situation the PSY cannot obtain a position fix and must be reloaded. This can be achieved by restarting the application that loaded the PSY. </p> </li> </ol> <fig id="GUID-9508DDA6-15FC-5C5F-B296-BBB2FE0E5DEA"><title>
             Figure 1. Loading the Bluetooth GPS PSY 
          </title> <image href="GUID-6C9355AF-80BA-5DBD-81A4-E9475A118C94_d0e469875_href.png" placement="inline"/></fig> </section> <section id="GUID-6C12D640-CE1E-5368-90E5-D9EF34C6B1CF"><title>Bluetooth GPS Device initialisation</title> <p>After connecting to a Bluetooth GPS device, the PSY does the following: </p> <ul><li id="GUID-8DD56AFC-EE40-590A-AEE5-77CFA6986013"><p>Attempts to switch the GPS device to NMEA mode. </p> <p>If the device cannot be switched to NMEA mode it cannot be used by the PSY. </p> </li> <li id="GUID-9719862D-0824-599D-B3FE-972F6B24A159"><p>Queries if the device supports PNOK NMEA extensions. </p> <p>If it supports PNOK, the PSY sets low power mode. For PNOK capable devices, the PSY is able to receive and report hardware status change messages through the Bluetooth GPS PSY Events API. </p> </li> <li id="GUID-19C8DD06-8843-56E4-B0FB-739E44B9B372"><p>Requests that NMEA messages are sent with an interval of 1 second. </p> <p>NMEA messages are sent continuously to the PSY, but these are processed only when a location request is received from the Location Server. </p> </li> <li id="GUID-4E3EE2A5-26DE-5F39-8F16-E60C5C0F96DE"><p>Waits for requests for location from the Location Server. </p> </li> </ul> </section> <section id="GUID-CB2663ED-4711-5162-BE0C-FF2DB31C3B49"><title>Making a location request</title> <p>When a location request is received from the Location Server, the PSY returns any cached position fix it has if it meets the position quality specified with the request. The position quality includes the horizontal and vertical position accuracy and the age of the position fix. These parameters can be specified by a Location Acquisition API client as part of the location request (see <xref href="GUID-F6B5F777-D12F-5913-AECE-047DF8C72F1F.dita">How to Get Location Information</xref> for more information). </p> <p>If the cached position does not meet the quality criteria specified with the request, the PSY reads NMEA messages from the Bluetooth GPS device to obtain a position. The position is cached by the PSY and returned to the client. </p> <fig id="GUID-2573FE3F-E638-5245-9138-490D1567F74E"><title>
             Figure 2. Location request using the Bluetooth GPS PSY. 
          </title> <image href="GUID-B495BE4E-6567-5141-A857-31EF12B19362_d0e469934_href.png" placement="inline"/></fig> </section> <section id="GUID-CDA4A58C-EE1B-5C34-A786-C2FC112C3C74"><title>Tracking</title> <p>The term <i>tracking</i> is used to describe the situation where a client specifies that it wants to receive periodic position updates from the Location Server. To start tracking a client calls <xref href="GUID-E60595B9-B6E2-38E1-BE1E-A82113C7EC94.dita#GUID-E60595B9-B6E2-38E1-BE1E-A82113C7EC94/GUID-AF7F4C64-937E-306C-B6C1-9CE0457F37DF"><apiname>TPositionUpdateOptions::SetUpdateInterval()</apiname></xref> before making its first <xref href="GUID-1EAEB7EF-0AC7-37C7-B35F-C9B780FFC575.dita#GUID-1EAEB7EF-0AC7-37C7-B35F-C9B780FFC575/GUID-321F6046-3551-3ACE-B0A3-26D51FAEB477"><apiname>RPositioner::NotifyPositionUpdate()</apiname></xref> call. See <xref href="GUID-F6B5F777-D12F-5913-AECE-047DF8C72F1F.dita">How to Get Location Information</xref> for more information about using tracking. </p> <p>An NMEA-compliant Bluetooth GPS device sends periodic NMEA messages containing position fixes to the PSY. This is the required behaviour for tracking and means a client tracking request does not cause major changes to the behaviour of the PSY. A tracking request does prevent the PSY from entering the standby state, so that it is always ready to return the next position update. </p> </section> <section id="GUID-1C02463D-FBDF-5E04-9842-438C8ABD6DF4"><title>Cancelling a location request</title> <p>A client cancels a location request by calling <xref href="GUID-1EAEB7EF-0AC7-37C7-B35F-C9B780FFC575.dita#GUID-1EAEB7EF-0AC7-37C7-B35F-C9B780FFC575/GUID-BF6665C5-2FC2-3C0D-8C4C-C46DC39B2027"><apiname>RPositioner::CancelRequest()</apiname></xref>. Calling this method informs the PSY that the position fix is no longer required. However, the PSY still obtains the fix from hardware and caches it for possible future use. </p> <fig id="GUID-D9389737-6481-55F7-8CF7-02A43C6409AE"><title>
             Figure 3. Cancelling a location request. 
          </title> <image href="GUID-0554F7DB-9102-5BB4-AD10-D6FDE77F1117_d0e469977_href.png" placement="inline"/></fig> </section> <section id="GUID-C88E20CE-C7AD-5439-AE03-E83C18C3694B"><title>Unloading the Bluetooth GPS PSY</title> <p>The PSY is unloaded when the last client subsession using it is closed by calling <xref href="GUID-1EAEB7EF-0AC7-37C7-B35F-C9B780FFC575.dita#GUID-1EAEB7EF-0AC7-37C7-B35F-C9B780FFC575/GUID-DE09BADB-6D90-3995-A893-F949F9C37A2B"><apiname>RPositioner::Close()</apiname></xref>. The PSY closes the Bluetooth connection to the GPS device. </p> <fig id="GUID-7DAC1058-31B3-57D6-B1AD-EC3A384E6966"><title>
             Figure 4. Unloading the Bluetooth GPS PSY. 
          </title> <image href="GUID-BD347690-2644-59E5-8CC6-769A77274D51_d0e469995_href.png" placement="inline"/></fig> </section> </conbody><related-links><link href="GUID-51177BB6-D906-57BD-91DD-EC263F900225.dita"><linktext>
                Opening a Session with Bluetooth GPS PSY</linktext> </link> </related-links></concept>