S60 Network Positioning Proxy Configuration API |
DN0687845 |
CONFIDENTIAL |
Version |
Date |
Status |
Description |
---|---|---|---|
1.0 |
03.11.2006 |
Approved |
|
![]() |
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.
![]() |
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.
![]() |
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.
![]() |
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.
![]() |
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.
![]() |
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.
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. |
<frozen flag> <hidden PSY1 Implementation UID> <hidden PSY2 Implementation UID>...
0 10123459 1012345a 1012345c
![]() |
![]() |
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
![]() |
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);
![]() |
![]() |
Abbreviation | Description |
---|---|
NPP PSY | Network Positioning Proxy |
SUPL | Secure User Plane Location |
![]() |
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. |
![]() |
None |
|
Symbian Central Repository API Specification Documentation | A Symbian document. |
S60 Positioning Plug-in API Specification Document | |
S60 Positioning Plug-in Information API Specification Document |
![]() |