The Positioning Plug-in Information API defines Publish and Subscribe (P&S) keys for publishing and receiving PSY settings. The API is intended for device creators who write their own PSYs.
The Positioning Plug-in Information API defines Central Repository keys for publishing Positioning Plug-in (PSY) static capabilities and basic setup information related to the PSY. These keys published by the PSYs are used by Location Framework. This API is intended for developers who write their own positioning plug-ins.
The licensee also needs to implement the Positioning Plug-in API to create a PSY.
The Positioning Plug-in Information API is a Central Repository interface for defining keys. It specifies the parameters associated with a positioning module. It does not define any classes but defines the keys that each Positioning Plug-in needs to declare.
To use the Positioning Plug-in Information API, a developer must create a Central Repository file with the same UID as the PSY’s UID. This file must contain all the defined keys for the positioning plug-in. If the values for the keys are incorrect the Location Framework will ignore the plug-in and it will not be usable. If this file is to be backed up during a backup operation, the owner of this file should be set to 0x101f97b2, which is the Location Server’s UID.
To implement a PSY, the developer must do the following:
Create a PSY by implementing the Positioning Plug-in API.
Create a Central Repository file to publish PSY information according to the Positioning Plug-in Information API.
Test the positioning module implementation using the PSY tester application. The PSY tester application tests whether a particular PSY implementation conforms to the Positioning Plug-in API and the Positioning Plug-in Information API specifications.
Positioning Plug-in Information API published keys
Every Positioning Plug-in has its own repository identified with the implementation UID of the plug-in. This repository contains the predefined keys published by the Positioning Plug-in Information API. These keys include the properties of the positioning plug-in. The keys are defined in the PositioningPluginFWInternalCRKeys.h header file.
| Central Repository key | Description |
|---|---|
The version of the Positioning Plug-in Information API interface. |
|
The Positioning plug-in priority set for the PSY on installation. |
|
The Positioning plug-in status set for the PSY when installed to the system. |
|
The estimated time to the first fix from the positioning plug-in after a connection is established. It is defined as a double and should not be a negative number. The definition for time to the first fix can be found in the Location Acquisition API. |
|
This should be a conservative estimate of the time between consecutive fixes once the plug-in has been loaded and started. It is defined as a double and should not be a negative number. The definition of the time to the next fix can be found in the Location Acquisition API. |
|
This should be a conservative estimate of the expected horizontal accuracy and should be given in metres. The definition of horizontal accuracy can be found in the Location Acquisition API. |
|
This should be a conservative estimate of the expected vertical accuracy and should be given in metres. The definition of vertical accuracy can be found in the Location Acquisition API. |
|
The cost of using the positioning technology. The cost indicator takes one of the discrete values unknown, zero, possible or charge. There is no mapping to any fixed sum of money. The cost indicator is only a default value. The actual value can be changed by the user. The definition for possible cost indicator values can be found in the Location Acquisition API. |
|
The power consumption of the plug-in. Power consumption takes one of the discrete values unknown, zero, low, medium or high. There is no mapping to any fixed power. The definition for possible power consumption values can be found in the Location Acquisition API. |
|
The type of technology used to get the location. Specifies whether the positioning technology is terminal-based or network-based, or if it is using assistance data from the network. The definition for all available values for technology can be found in the Location Acquisition API. |
|
The positioning hardware deployment. Specifies whether the actual positioning hardware is internal or external to the phone. The definition for all available values for this device location can be found in the Location Acquisition API. |
|
The positioning capabilities of the positioning plug-in. This is a bitmap specifying the PSY’s capabilities, for example whether the PSY is capable of handling vertical measurements, NMEA reading, addresses, compass information, building information. The definition for all available values for capabilities can be found in the Location Acquisition API. |
|
The supported Location Framework position data classes. This is a bitmap specifying which TPositionInfoBase classes can be handled by the PSY. A PSY must always support at least TPositionInfo. The definition for all available values for supported classes can be found in the Location Acquisition API. |
|
This key specifies whether the plug-in is visible to Location Framework. |
|
This key specifies the name for the resource file that contains the localised text for the PSY name. If the key does not exist or the resource file does not exist, the name mentioned in the ECOM implementation resource file is used as the PSY name. |
Example
The Positioning Plug-in keys are specified as part of a Central Repository file. The example below is a typical Central Repository file created for a PSY.
/* The Header of the central repository text file */ cenrep /* Version of central repository */ version 1 [owner] /* The owner for this central repository file, which is Location Server */ 0x101f97b2 [defaultmeta] /* Central Repository related headers */ 0 [platsec] /* Capability required to access(read / write) these central repository keys */ cap_rd=ReadDeviceData cap_wr=WriteDeviceData [Main] /* * The keys defined by the Positioning Plug-in Information API interface. * These key values are read by Location Server using Central Repository. */ /* version 1 of the Positioning plug-in Information API. */ 0x1 int 1 16777216 cap_rd=ReadDeviceData cap_wr=alwaysfail /* * PSY Priority 0 which means that Location Server will decide the priority * of the PSY. */ 0x2 int 0 16777216 cap_rd=ReadDeviceData cap_wr=alwaysfail /* * The PSY is available when it is installed in the system. * The availability can be changed later through the Location UI. */ 0x3 int 1 16777216 cap_rd=ReadDeviceData cap_wr=alwaysfail /* * The estimated time to obtain the initial location fix 80000000 microseconds * i.e. 80 seconds. */ 0x4 int 80000000 16777216 cap_rd=ReadDeviceData cap_wr=alwaysfail /* * The estimated time to obtain a fix knowing the current position is 1000000 microseconds * i.e. 1 second. */ 0x5 int 1000000 16777216 cap_rd=ReadDeviceData cap_wr=alwaysfail /* * The estimated error for the latitude and longitude * components of a position determined by this PSY is 10 metres. */ 0x6 real 10 16777216 cap_rd=ReadDeviceData cap_wr=alwaysfail /* * The estimated error for the altitude components of * a position determined by this PSY is 30 metres. */ 0x7 real 30 16777216 cap_rd=ReadDeviceData cap_wr=alwaysfail /* * The user will not incur any charge when using this PSY * to make a position determination. */ 0x8 int 1 16777216 cap_rd=ReadDeviceData cap_wr=alwaysfail /* * This PSY will consume a resonable amount of battery power when * used for position determination. */ 0x9 int 3 16777216 cap_rd=ReadDeviceData cap_wr=alwaysfail /* * The PSY uses a positioning techonology that works stand-alone * on the terminal. */ 0xa int 1 16777216 cap_rd=ReadDeviceData cap_wr=alwaysfail /* * The PSY uses a technology external to the terminal. */ 0xb int 2 16777216 cap_rd=ReadDeviceData cap_wr=alwaysfail /* * The PSY is capable of returning information about * latitude, longitude, speed, address and satellite. */ 0xc int 95 16777216 cap_rd=ReadDeviceData cap_wr=alwaysfail /* * This PSY is capable of returning location information * through all position information data classes namely * TPositionInfo, TPositionCourseInfo, TPositionSatelliteInfo * and HGenericPositionInfo. */ 0xd int 15 16777216 cap_rd=ReadDeviceData cap_wr=alwaysfail /* * This PSY is visible to the user through the Location UI. */ 0xe int 1 16777216 cap_rd=ReadDeviceData cap_wr=alwaysfail /* * The localised PSY name is specified in psylocalised_name.rsc * resource file. */ 0xf string "\\resource\\psylocalised_name.rsc" 16777216 cap_rd=ReadDeviceData cap_wr=alwaysfail
PSY-specific settings
Any PSY-specific settings can be implemented as part of the same Central Repository file as the PSY common settings. In this case, the PSY must publish a header for the PSY-specific settings. The header must contain the Central Repository UID value and the key values for the PSY-specific settings.
The PSY-specific settings key are bound by the following constraints:
IDs should start from the value 0x10000000. The values from 0x0000000F to 0x0FFFFFFF are reserved for expansion of the Positioning Plug-in Information API.
The required capabilities for the keys should be:
Alternatively the PSY can implement these settings through any other mechanism such as database or file stores.
An example of PSY-specific settings are those of the Bluetooth PSY Settings.
PSY-specific Configuration UI
The PSY can implement a configuration UI for reading and setting the PSY-specific settings keys. Creating a configuration UI for a PSY is a licensee-specific task as it uses platform-dependent UI framework.
| Abbreviation | Description |
|---|---|
API |
Application Programming Interface |
LBS |
Location Based Services |
PSY |
Positioning Technology Plug-in |
SDK |
Software Development Kit |
UML |
Unified Modeling Language |
Copyright ©2010 Nokia Corporation and/or its subsidiary(-ies).
All rights
reserved. Unless otherwise stated, these materials are provided under the terms of the Eclipse Public License
v1.0.