S60 Network Positioning Proxy Configuration API

DN0687845
CONFIDENTIAL

©Nokia Corporation and/or its subsidiaries 2006
This material, including documentation and any related computer programs, is protected by copyright controlled by Nokia. All rights are reserved. Copying, including reproducing, storing, adapting or translating, any or all of this material requires the prior written consent of Nokia. This material also contains confidential information, which may not be disclosed to others without the prior written consent of Nokia.

Nokia is a registered trademark of Nokia Corporation. S60 and logo is a trademark of Nokia Corporation. Java and all Java-based marks are trademarks or registered trademarks of Sun Microsystems, Inc. Other company and product names mentioned herein may be trademarks or tradenames of their respective owners.

Change History

Version

Date

Status

Description

1.0

03.11.2006

Approved

 


Table of Contents

Purpose
S60 or Symbian OS exceptions
API description
Overview
Prerequisites
Implementation of a hidden PSY
NPP PSY configuration
Use cases
API class structure
Using Network Positioning Proxy Configuration API
Configures PSY list during build time
Configures PSY list during runtime
Error handling
Memory overhead
Extensions to the API
Glossary
Abbreviations
Definitions
References

 


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.

 


S60 or Symbian OS exceptions

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

 


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 Symbian Central Repository API.

 


Memory overhead

Memory overhead is described in Symbian Central Repository API.

 


Extensions to the API

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

 


Glossary

 


Abbreviations

Table: Abbreviations
Abbreviation Description
NPP PSY Network Positioning Proxy
SUPL Secure User Plane Location

 


Definitions

Table: 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

Table: References

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  

Back to top