Opening a Session - Reference

Required background

Knowledge of the Location Acquisition API is helpful in understanding this topic.

Introduction

Steps that describe how to open the default PSY or a Bluetooth GPS PSY Session are provided here. The sections that follow provide information on error codes and Bluetooth GPS PSY behavior during use.

Error codes

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 RPositioner::Open() to create a subsession that uses the Bluetooth GPS PSY.

The following sections give more information about the behaviour of the Bluetooth GPS PSY during use.

Loading the PSY and device selection

The Bluetooth GPS PSY is loaded dynamically when a client makes a request that requires its use (by one of the methods described above).

If the mobile device is not already connected to a Bluetooth GPS device the PSY attempts to connect to one as follows:

1. 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 KBluetoothGpsPsyDeviceAddress. The user may be queried for a passkey as part of this process in order to pair with the Bluetooth GPS device.

   Figure 1 shows this procedure, followed by an exchange of NMEA initialisation messages between the PSY and the GPS device.

2. 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 Bluetooth GPS PSY Configuration API.

3. 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.

   If a connection can be made to the device, its address is stored in the Central Repository setting KBluetoothGpsPsyDeviceAddress. The PSY tries to use this GPS device the next time it receives a client request (see [1] above).

   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.

Figure 1. Figure 1. Loading the Bluetooth GPS PSY

Bluetooth GPS Device initialisation

After connecting to a Bluetooth GPS device, the PSY does the following:

• Attempts to switch the GPS device to NMEA mode.

  If the device cannot be switched to NMEA mode it cannot be used by the PSY.

• Queries if the device supports PNOK NMEA extensions.

  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.

• Requests that NMEA messages are sent with an interval of 1 second.

  NMEA messages are sent continuously to the PSY, but these are processed only when a location request is received from the Location Server.

• Waits for requests for location from the Location Server.

Making a location request

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 How to Get Location Information for more information).

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.

Figure 2. Figure 2. Location request using the Bluetooth GPS PSY.

Tracking

The term tracking 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 TPositionUpdateOptions::SetUpdateInterval() before making its first RPositioner::NotifyPositionUpdate() call. See How to Get Location Information for more information about using tracking.

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.

Cancelling a location request

A client cancels a location request by calling RPositioner::CancelRequest(). 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.

Figure 3. Figure 3. Cancelling a location request.

Unloading the Bluetooth GPS PSY

The PSY is unloaded when the last client subsession using it is closed by calling RPositioner::Close(). The PSY closes the Bluetooth connection to the GPS device.

Figure 4. Figure 4. Unloading the Bluetooth GPS PSY.