Network Positioning Proxy Configuration API

Changes in Network Positioning Proxy Configuration API documentation

Version Date Status Description

1.0

03.11.2006

Approved

Changes in Network Positioning Proxy Configuration API

Version Description

1.0

First version

Purpose

Network Positioning Proxy Configuration API instructs the licensees on how to configure Network Positioning Proxy to have licensees' own PSY that implements the network-based positioning technology to be used by Network Positioning Proxy. This API is a type of setting API which defines Central Repository UID and keys.

Constraints

Network Positioning Proxy Configuration API is available for S60 release 3.1 onwards.

API description

The logical type of this API is Settings API based on Central Repository service and the technical type of the API is a Method call API. This API also defines basic rules of implementing network based positioning technology to be hidden behind Network Positioning Proxy.

Overview

In some terminal configurations, there might be multiple PSYs that implement network based positioning technologies. These technologies are similar to each other from the end user’s point of view. End users see them as similar functions, even though PSYs may use different protocols or techniques to obtain the position information. For example, SUPL PSY makes use of user plane protocols to obtain the location. Licensees can implement similar functions by using control plane protocols. What is common for these PSYs is that they have similar performance parameters, such as time to first fix, time to next fix, etc. These similar PSYs that implement network-based positioning technologies can be hidden behind Network Positioning Proxy (NPP PSY). NPP PSY show those PSYs as one technology to the end user. If the PSY needs to be hidden behind NPP PSY, it must list its UID to the specific central repository key defined by Network Positioning Proxy Configuration API. It must also set the visibility property "off" from its own Central Repository file as defined by Positioning Plug-in Information API. When location request is received by NPP PSY, it tries to obtain the position of each PSY defined in the PSY list in order. The PSY list is predefined in Central Repository. The order of the hidden PSYs on the PSY list can be varied at build time and changed during runtime.

All communication between the hidden PSYs and NPP PSY is handled via Positioining Plug-in API. SeePositioining Plug-in API and Positioning Plug-in Information API for detailed information on how to implement a PSY.

Prerequisites

There is a ROM image creation time feature flag for NPP PSY. The feature flag is __NP_PROXY and it can be found from \epoc32\include\oem\bldvariant.hrh. The feature flag must be defined to have Network Positioning Proxy included in ROM.

Implementation of a hidden PSY

The implementation of a hidden PSY is very similar to implementing a normal PSY. See Positioining Plug-in API and Positioning Plug-in Information API for a detailed description on how to implement a hidden PSY.

NPP PSY configuration

Any hidden PSY to be hidden behind NPP PSY must add its implementation UID in the PSY list. The PSY list is stored in Central Repository. The UID of the PSY list repository is 0x10206915. The key ID for PSY list is 0x01. The type of the PSY list key is string. The Central Repository UID and keys are defined in header file npppsyinternalcrkeys.h under \epoc32\include\domain\osextensions directory.

When Network Positioning Proxy receives a location request, it reads the PSY list from Central Repository. PSYs are tried in the listed priority order.

Normally the list is not updated during runtime. However, the system does not exclude such usage. When a hidden PSY is installed, it adds its UID to the PSY list during installation. If an installed hidden PSY is uninstalled, it removes its UID from the PSY list. Changing the PSY list does not affect the ongoing location request. If a hidden PSY's UID is removed from the PSY list before it is tried during the fallback execution, the PSY might still be used. A hidden PSY that is added to the list during the fallback execution is not tried. Furthermore, if the list has been updated during runtime before the location request arrives to Network Positioning Proxy, the new PSY list is taken into use immediately for the next location request.

There is a frozen flag in front of the PSY list. It indicates the freeze mode of the PSY list. The different freezing modes are as follows:

Freeze mode

Key value

Description

Normal mode

0

PSY list is not frozen but updated during the location request. In this mode, if a hidden PSY fails to return a location estimation, the hidden PSY is moved to the end of the list. The next hidden PSY on the PSY list is tried. If all the hidden PSYs on the PSY list are tried, Network Positioning Proxy returns the information received from the last PSY to Location FW.

Frozen with no fallback

1

Network Positioning Proxy does not modify the PSY list, and it uses only the first PSY on the list. If the first PSY fails, Network Positioning Proxy does not use any other PSYs.

Frozen with fallback

2

Network Positioning Proxy does not modify the PSY list, but if the first PSY fails, there is a fallback of Network Positioning Proxy to the next PSY (if available) on the list, until a tried PSY gives a fix or all listed PSYs have been tried.

PSY list value in Central Repository is a string in the following format:

<frozen flag> <hidden PSY1 Implementation UID> <hidden PSY2 Implementation UID>...

After the frozen flag, all implementation UIDs of hidden PSYs are listed in hexadecimal according to the priority. The hidden PSY with the highest priority is listed first. The case is unimportant, and the field separation is any white space character. The following example shows a PSY list in normal mode with three hidden PSYs:

0 10123459 1012345a 1012345c

Related APIs
  • 0x01
  • 0x10206915

Use cases

These are main use cases of Network Positioning Proxy Configuration API:

  • Configures PSY list during build time

  • Configures PSY list during runtime

API class structure

Network Positioning Proxy configuration API is a Central Repository type of API. It defines Central Repository UID and keys.

Using Network Positioning Proxy Configuration API

Configures PSY list during build time

To configure PSY list during build time, the Central Repository initialization file of NPP PSY must be updated. This default PSY list setting is generated from the file keys_npppsy.xls released under the \cenrep directory.

The Central Repository initialization file generated from key_npppsy.xls is 10206915.txt. This file is in Unicode format. The generated TXT file is stored to the private data cage of Central Repository server on the Z drive during the ROM building process: z:\private\10202BE9.

The following example shows the Central Repository initialization file of NPP PSY. Note, the last line is the PSY list configuration key. This key shall be configured by licensees.

cenrep
version 1
[owner]
0x101f97b2  
[defaultmeta]
 0
[platsec]
 cap_rd=alwayspass
[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 12000000 0 cap_rd=alwayspass cap_wr=alwaysfail
0x5 int 12000000 0 cap_rd=alwayspass cap_wr=alwaysfail
0x6 real 200 0 cap_rd=alwayspass cap_wr=alwaysfail
0x7 real 0 0 cap_rd=alwayspass cap_wr=alwaysfail
0x8 int 2 0 cap_rd=alwayspass cap_wr=alwaysfail
0x9 int 2 0 cap_rd=alwayspass cap_wr=alwaysfail
0xa int 2 0 cap_rd=alwayspass cap_wr=alwaysfail
0xb int 1 0 cap_rd=alwayspass cap_wr=alwaysfail
0xc int 1 0 cap_rd=alwayspass cap_wr=alwaysfail
0xd int 3 0 cap_rd=alwayspass cap_wr=alwaysfail
0xe int 1 0 cap_rd=alwayspass cap_wr=alwaysfail
0xf string "\\resource\\nlanpppsy_name.rsc" 0 cap_rd=alwayspass cap_wr=alwaysfail
0x10000001 string "0 10123459 1012345a 1012345c " 16777216 cap_rd=alwayspass cap_wr=WriteDeviceData

Configures PSY list during runtime

The PSY list can be configured during runtime. The following code clip shows how to update PSY list during runtime.

LIT(KSetting, “0 10123459 1012345a 1012345c”);
CRepository* repository = CRepository::NewL(TUid::Uid(0x10206915));
   CleanupStack::PushL(repository);
   User::LeaveIfError(repository->Set(0x10000001, KSetting));
        
   CleanupStack::PopAndDestroy(repository);

Error handling

All exceptions are defined in the Central Repository API.

Memory overhead

Memory overhead is described in the Central Repository API.

Extensions to the API

Network Positioning Proxy Configuration API does not support any kinds of extensions to it.

Glossary

Abbreviations

Abbreviations

Abbreviation Description

NPP PSY

Network Positioning Proxy

SUPL

Secure User Plane Location

Definitions

Definitions

Definition

Description

Fallback

Fallback refers to the procedure that NPP PSY tries to use the next hidden PSY on the priority list to retrieve the location information, when previous PSY fails to give a fix.

Hidden PSY

In this API, hidden PSY refers to those PSYs that implement network base location technology and are hidden behind NPP PSY. Those PSYs are not visible from Location FW and to the end users.

PSY

Positioning plug-in. An adaptation plug-in to connect Location FW with a specific positioning technology implementation.

PSY list

PSY list stored in Central Repository that lists all the UIDs of hidden PSYs. The same Central Repository key also defines whether the list is frozen or not.

Request bundling

The method for serving multiple simultaneous location requests. All the simultaneous requests are completed with the same fix.

References

References

None

Central Repository API Specification Documentation

Positioning Plug-in API Specification Document

Positioning Plug-in Information API Specification Document