S60 SUPL Terminal Initiation API |
DN0623655 |
CONFIDENTIAL |
Version |
Date |
Status |
Description |
---|---|---|---|
4.0 |
05.10.2007 |
Approved |
Added changes to indicate whether the RunSession() request is the first one or not in the subsession. |
3.0 |
24.11.2006 |
Approved |
Changes for dynamic variation of SUPL feature flag. |
2.0 |
02.06.2006 |
Approved |
Changes to add new indication code |
1.0 |
23.03.2006 |
Approved |
|
![]() |
The following header file(s) have changed between S60 releases 3.2 and 5.1.
Type | Class | Change |
---|---|---|
New public methods | RSuplTerminalSubSession | TInt GetSlpList(RPointerArray(CSuplTerminalParams) &aSlpList) |
New public method | RSuplTerminalSubSession | RunSession(TRequestStatus& aStatus, TSuplTerminalQop& aQop, const TDesC& aHslpAddress, TBool aFallBack= EFalse, TInt aSETCaps=0, TInt aRequestId=0, TBool aFirstReq=ETrue) |
New public method | RSuplTerminalSubSession | TInt RunSession(TSuplTerminalQop& aQop, const TDesC& aHslpAddress, TBool aFallBack= EFalse, TInt aSETCaps=0, TInt aRequestId=0, TBool aFirstReq=ETrue) |
New public method | RSuplTerminalSubSession | RunSession(TRequestStatus& aStatus, const TDesC& aHslpAddress, TBool aFallBack= EFalse, TInt aSETCaps=0, TInt aRequestId=0, TBool aFirstReq=ETrue) |
New public method | RSuplTerminalSubSession | TInt RunSession(const TDesC& aHslpAddress, TBool aFallBack= EFalse, TInt aSETCaps=0, TInt aRequestId=0, TBool aFirstReq=ETrue) |
New public method | RSuplTerminalSubSession | TInt GetServerAddress(TDes& aHslpAddress) |
Type | Class | Change |
---|---|---|
New public method | CSuplTerminalParams | TInt Set() |
New public method | CSuplTerminalParams | TInt Get() |
![]() |
![]() |
SUPL Terminal Initiation API is a Virtual Machine API abstracting the client-server communication from the client. SUPL Terminal Initiation API belongs to the Domain API category.
SUPL Terminal Initiation API is dependent on Location Acquisition API for location data types. However, the methods in SUPL Terminal Initiation API can also return extended position information, such as speed, using extended position information defined by Location Acquisition API.
![]() |
The main use cases of SUPL Terminal Initiation API are as follows:
![]() |
The important methods in RSuplTerminalSubSession are RunSession() and GetPosition(). RunSession() is used for requesting SUPL Server to determine position information. This method is provided in both synchronous and asynchronous variants.
Client can specify the wanted quality of the fix by giving the TSuplTerminalQop class as parameter for RunSession(). The quality of position includes horizontal accuracy, vertical accuracy, maximum location age and response time. Horizontal accuracy is the radius of the error estimate circle specified in meters. Horizontal accuracy reflects the error for the latitude and longitude components of a position. Vertical accuracy is the error in the altitude component. Vertical accuracy specifies a linear value at a vertical distance from the origin of the error estimate circle within which the location of the point falls. Both horizontal accuracy and vertical accuracy values are specified in meters. Maximum location age is the maximum tolerable age of position estimates used for cached position fixes. Delay time is the desired response time for the location request issued. Maximum location age and delay are specified in seconds.
Parameter aSETCaps of type TInt is used for restricting the positioning technologies available for determining position information. This indicates the position technologies available which can be used during position determination. For example when using SUPL Server for retrieving assistance data this parameter is set to KGpsSETBased. Parameter aRequestId of type TInt can be used by the client to deliver request identification number for the tunneled positioning protocol handler. This is used by the client which is requesting for additional position information such as assistance data for A-GPS. It is the client's responsibility to generate and keep track of this request identifier. Tunneled protocol can use this value for example to match different assistance data requests and response received from SUPL Server.
Parameter aFirstReq of type TBool is used to indicate whether the request is the first request in the subsession or not. For example when making a location request or assistance data request for the first time in the subsession this parameter is set to ETrue. For subsequent requests this parameter is set to EFlase.
Parameter aHslpAddress of type String is used to specify SUPL server to be used during SUPL session.
Parameter aFallBack of type TBool is used to indicate whether fallback is allowed to next server in the SLP list if SUPL session with the server mentioned fails.
GetPosition as indicated is used to retrieve the position information from SUPL Server. The client requesting for assistance data for tunneled protocol does not need to use this method as assistance data is delivered during SUPL session. The method can return a variation of position values, such as basic position information and extended position information.
GetServerAddress can be used to retrieve the address of the server used in the last SUPL session.
Client can retrieve all the configured servers and their properties using CSuplTerminalParams class as parameter for GetSlpList(). From the retrieved server properties client can use the server address field as parameter for RunSession() to indicate which server should be used for SUPL session. Client can also specify whether fallback can be used or not if SUPL session with the specified server fails.
All methods in SUPL Terminal Initiation API are synchronous calls, except for asynchronous method requesting SUPL Server to determine position information.
The following diagram presents the class hierarchy and methods in both RSuplTerminalServer and RSuplTerminalSubSession.
![]() |
The client application using SUPL Terminal Initiation API must have the CommDD capability to use all methods.
Using SUPL Terminal Initiation API always contains the following steps:
RSuplTerminalSubSession::CanceRunSession() can be used to cancel an outstanding asynchronous RSuplTerminalSubSession::RunSession() request.
In case of asynchronous calls, the TRequestStatus parameter variable is used to indicate when SUPL Server has finished processing the request. For one IPC subsession, there can be only one request outstanding on each asynchronous method. It is recommended that the client should close the subsession and connection to SUPL Server when it is no longer required.
![]() |
This use case describes about the procedure to make the location determination request using SUPL and retrieving the position determined using SUPL Terminal Initiation API.
The following diagram illustrates the steps involved in executing the use case.
The following code snippets illustrate how to make the position determination request and how to retrieve position information using TPositionInfo. Asynchronous method is used to determine the position information here.
RSuplTerminalServer server; RSuplTerminalSubSession subSession; TInt ret = server.Connect(); // Connect to server if (ret != KErrNone) { // Handle error } ret = subSession.Open(server); // Open sub-session to server if (ret != KErrNone) { // Handle error } // Set terminal capabilities TInt setCaps=EGpsSETAssisted|EGpsSETBased; TRequestStatus status = KErrNone; TInt requestId = 1; TSuplTerminalQop qop; // Set desired quality of position ret = qop.Set(100, 990, 100, 8); // Make asynchronous position determination request subSession.RunSession(status, qop, setCaps, requestId); User::WaitForRequest(status); if (status.Int() != KErrNone) { // Handler error } TPositionInfo posInfo; //Retrieve determined position information ret = subSession.GetPosition(posInfo); if (ret != KErrNone) { // Handle error } subSession.Close(); // Close sub-session server.Close(); // Close connection
The following code snippets illustrate how to use the make position determination request and how to retrieve position information using HPositionGenericInfo. An asynchronous method is used to determine the position information here. For more information on how to use HPositionGenericInfo, please refer to reference document [3].
RSuplTerminalServer server; RSuplTerminalSubSession subSession; TInt ret = server.Connect(); // Connect to server if (ret != KErrNone) { // Handle error } ret = subSession.Open(server); // Open sub-session to server if (ret != KErrNone) { // Handle error } // Set terminal capabilities TInt setCaps=EGpsSETAssisted|EGpsSETBased; TRequestStatus status = KErrNone; TInt requestId = 1; TSuplTerminalQop qop; // Set desired quality of position ret = qop.Set(100, 990, 100, 8); // Make asynchronous position determination request subSession.RunSession(status, qop, setCaps, requestId); User::WaitForRequest(status); if (status.Int() != KErrNone) { // Handle error } HPositionGenericInfo* genericInfo = HPositionGenericInfo::NewLC(); //Request for Horizontal speed and Horizontal speed error genericInfo->SetRequestedField(EPositionFieldHorizontalSpeed); genericInfo->SetRequestedField(EPositionFieldHorizontalSpeedError); //Retrieve determined position information ret = subSession.GetPosition(*genericInfo); if (ret != KErrNone) { // Handle error } // Check if requested field is returned or not if (genericInfo->IsFieldAvailable(EPositionFieldHorizontalSpeed)) { TInt16 HorSpeed; genericInfo->GetValue(EPositionFieldHorizontalSpeed, HorSpeed); } if (genericInfo->IsFieldAvailable(EPositionFieldHorizontalSpeedError)) { TInt8 speedError; genericInfo->GetValue(EPositionFieldHorizontalSpeedError, speedError); } CleanupStack::PopAndDestroy(genericInfo); //genericInfo subSession.Close(); // Close sub-session server.Close(); // Close connection
![]() |
This use case describes the procedure to make the multiple location determination requests using SUPL and retrieving the position determined using SUPL Terminal Initiation API. Optionally client can specify whether the location request made is the first request in the sub-session or not.
The following diagram illustrates the steps involved in executing the use case.
The following code snippets illustrate how to make the multiple position determination request and how to retrieve position information using TPositionInfo. An asynchronous method is used to determine the position information here.
RSuplTerminalServer server; RSuplTerminalSubSession subSession; TInt ret = server.Connect(); // Connect to server if (ret != KErrNone) { // Handle error } ret = subSession.Open(server); // Open sub-session to server if (ret != KErrNone) { // Handle error } // Set terminal capabilities TInt setCaps=EGpsSETAssisted|EGpsSETBased; TRequestStatus status = KErrNone; TInt requestId = 1; TSuplTerminalQop qop; // Set desired quality of position ret = qop.Set(100, 990, 100, 8); // Make asynchronous position determination request subSession.RunSession(status, qop, setCaps, requestId); User::WaitForRequest(status); if (status.Int() != KErrNone) { // Handler error } TPositionInfo posInfo; //Retrieve determined position information ret = subSession.GetPosition(posInfo); if (ret != KErrNone) { // Handle error } status = KErrNone; // Make asynchronous position determination request subSession.RunSession(status, qop, setCaps, requestId, EFalse); User::WaitForRequest(status); if (status.Int() != KErrNone) { // Handle error } TPositionInfo posInfo; //Retrieve determined position information ret = subSession.GetPosition(posInfo); if (ret != KErrNone) { // Handle error } subSession.Close(); // Close sub-session server.Close(); // Close connection
![]() |
This use case describes the procedure to make assistance data request using SUPL Terminal Initiation API. Assistance data is delivered tunneled in SUPL protocol and the tunneled protocol handler receives assistance data for position determination. In this case, the client receives assistance data during SUPL session. For this reason the client does not need to call GetPosition to get position information.
The following diagram illustrates the steps involved in requesting assistance data using SUPL Terminal Initiation API.
The following code snippets illustrate how to use the make assistance data request. An asynchronous method is used to make the assistance data request.
RSuplTerminalServer server; RSuplTerminalSubSession subSession; TInt ret = server.Connect(); // Connect to server if (ret != KErrNone) { // Handle error } ret = subSession.Open(server); // Open sub-session to server if (ret != KErrNone) { // Handle error } // Set terminal capabilities TInt setCaps=EGpsSETAssisted|EGpsSETBased; TRequestStatus status = KErrNone; // Make asynchronous position determination request subSession.RunSession(setCaps, status); User::WaitForRequest(status); if (status.Int() != KErrNone) { // Handle error } subSession.Close(); // Close sub-session server.Close(); // Close connection
![]() |
This use case describes the procedure to make the asynchronous position determination request using SUPL Terminal Initiation API and cancelling the position determination request.
The following diagram illustrates the steps involved in executing the use case.
The following code snippets illustrate how to use the make position determination request using an asynchronous method and how to cancel the request.
RSuplTerminalServer server; RSuplTerminalSubSession subSession; TInt ret = server.Connect(); // Connect to server if (ret != KErrNone) { // Handle error } ret = subSession.Open(server); // Open sub-session to server if (ret != KErrNone) { // Handle error } // Set terminal capabilities TInt setCaps=EGpsSETAssisted|EGpsSETBased; TRequestStatus status = KErrNone; // Make asynchronous position determination request subSession.RunSession(setCaps, status); subSession.CancelRunSession(); User::WaitForRequest(status); if (ret != KErrCancel) { // Handle error } subSession.Close(); // Close sub-session server.Close(); // Close connection
![]() |
The following diagram illustrates the steps involved in executing the use case.
The following code snippets illustrate how to use the make position determination request using an asynchronous method and how to cancel the request.
RSuplTerminalServer server; RSuplTerminalSubSession subSession; TInt ret = server.Connect(); // Connect to server if (ret != KErrNone) { // Handle error } ret = subSession.Open(server); // Open sub-session to server if (ret != KErrNone) { // Handle error } // Get list of SLPs configured and retrieve parameters RPointerArray<CServerParams> aParamValues; HBufC* serverAddress = HBufC::New(255); HBufC* iapName = HBufC::New(255); TBool serverEnabled; TBool simChangeRemove; TBool usageInHomeNw; TBool editable; subSession.GetSlpList(aParamValues); // Retrieve first server properties in the list aParamValues[0]->Get(slpId,serverAddress->Des(),iapName->Des(),serverEnabled,simChangeRemove,usageInHomeNw,editable); // Set terminal capabilities TInt setCaps=EGpsSETAssisted|EGpsSETBased; TRequestStatus status = KErrNone; // Make asynchronous position determination request TBool fallBack = ETrue; subSession.RunSession(status, *serverAddress, fallBack, setCaps); User::WaitForRequest(status); if (ret != KErrCancel) { // Handle error } aParamValues.ResetAndDestroy(); // Retrieve server address used for SUPL session RBuf hslpAddr; RBuf hslpAddr.Create(KMaxHslpAddressLength); subSession.GetServerAddress(hslpAddr) hslpAddr.Close(); subSession.Close(); // Close sub-session server.Close(); // Close connection
![]() |
SUPL Terminal Initiation API uses the standard Symbian OS error reporting mechanism. In case of an irrecoverable error, panics are used. Otherwise, functions return error codes as their return values. SUPL Terminal Initiation API uses standard system error codes and certain panic codes defined in SUPL Terminal Initiation API. Those can be found in the files epos_suplterminalerrors.h and epos_suplterminalconstants.h.
![]() |
When using SUPL Terminal Initiation API, the memory overhead is dependent on the amount of instantiated classes but there are also some cases when extra memory usage can be involved. Nevertheless, the memory usage is always controlled by the client application and there are never any uncontrolled allocations of large amounts of memory that the client cannot prevent or avoid. Also the HPositionGenericInfo class uses a heap to store location data. However, in all cases, the amount of memory is defined by the client and thus cannot be exactly predicted. After use, the needed additional buffers (if any) are unallocated automatically. The number of simultaneous sessions and subsessions also has an impact on the overall memory usage. For this reason, unnecessary sessions and subsessions should be avoided.
![]() |
![]() |
Abbreviation | Description |
---|---|
API | Application Programming Interface |
FW | Framework |
HW | Hardware |
IPC | Inter process communication |
QoP | Quality of Position |
SET | SUPL Enabled Terminal |
SLP | SUPL Location Platform |
SUPL | Secure User Plane Location Protocol |
UI | User Interface |
![]() |
Definition | Description |
Framework | Usually denotes the collection of an engine and associated programming interfaces. This document mentions SUPL Framework. |
Terminal Initiated Location Request | Location request is issued by the mobile terminal to find out current location of the terminal. |
SUPL Enabled Terminal | A device that is capable of communicating with a SUPL Network. Examples of this could be UE in UMTS, MS in GSM or IS95. |
SUPL Location Platform (SLP) | Network entity responsible for Service management and Position determination. |
SUPL Server | Server application running in the terminal. |
![]() |
1. S60 3.2 SUPL Subsystem Architecture Description | |
2. S60 SUPL Subsystem Design Document | |
3. S60 SUPL Terminal Initiation Library Design Document | |
4. S60 Location Acquisition API Specification Document | |
5. OMA Secure User Plane Location Architecture | http://member.openmobilealliance.org/ftp/public_documents/loc/Permanent_documents/ |
6. OMA UserPlane Location Protocol | http://member.openmobilealliance.org/ftp/public_documents/loc/Permanent_documents/ |
![]() |