API description
The terminal client uses SUPL Terminal Initiation API for following purposes:
-
To determine location information and to retrieve the location information
optionally with desired quality of position.
-
To retrieve additional positioning information such as assistance data
for A-GPS for tunneled positioning protocols. In this case, assistance data
is delivered to the client's plug-in from the SUPL framework during SUPL session.
-
To retreive configured server addresses and their properties
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.
Use cases
The main use cases of SUPL Terminal Initiation API are as follows:
-
Requesting position information
-
Multiple position information requests
-
Requesting Assistance Data
-
Cancelling position determination request
-
Retrieving configured server properties
API class structure
The important classes of SUPL Terminal Initiation API are
RSuplTerminalServer, RSuplTerminalSubSession, CSuplTerminalParams and TSuplTerminalQop. RSuplTerminalServer is
used to establish connection and close the connection to SUPL Server. During
connection establishment, SUPL Server checks whether SUPL is enabled or not
in the terminal. If SUPL is not enabled, SUPL Server returns an error code
and exits. If SUPL is enabled, connection establishment continues.RSuplTerminalSubSession is
used to
-
open and close IPC sub-session
-
request SUPL Server to determine the position information and retrieve
the position information
-
request SUPL Server for assistance data for A-GPS
-
cancel position determination request
-
retrieve all configured servers and their properties
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.
Related APIs
CSuplTerminalParamsEFlaseETrueGetPositionGetPosition()GetServerAddressGetSlpList()KGpsSETBasedRSuplTerminalServerRSuplTerminalSubSessionRunSessionRunSession()StringTBoolTIntTSuplTerminalQopaFallBackaFirstReqaHslpAddressaRequestIdaSETCaps
Using SUPL Terminal Initiation API
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:
-
Connect to SUPL server using the
RSuplTerminalServer::Connect() method.
-
Open a subsession to SUPL Server using the
RSuplTerminalSubSession::Open() method.
-
Optionally client can retrieve all the configured server address and their
properties using
RSuplTerminalSubSession::GetSlpList()
-
Determine the position information or get additional position information
such as assistance data for A-GPS using the
RSuplTerminalSubSession::RunSession() method.
The RunSession() method is available both in synchronous
and asynchronous variants. The client can also optionally specify the desired
Quality of Position (QoP), server address to be used and whether fallback
can be used or not.
-
Optionally get terminal's determined location information using the
RSuplTerminalSubSession::GetPosition() method.
-
Optionally get server used for SUPL session using the
RSuplTerminalSubSession::GetServerAddress() method.
-
Close subsession using the
RSuplTerminalSubSession::Close() method.
-
Close connection using the
RSuplTerminalServer::Close() method.
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.
Requesting position information
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
Related APIs
HPositionGenericInfoTPositionInfo
Multiple position information requests
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
Related APIs
Requesting assistance data
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
Related APIs
Canceling a position determination request
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
Requesting position information from specific server
This use case describes following
-
To retrieve configured servers and their properties
-
To make the location determination request using SUPL to particular server
with fallback enabled
-
Retrieving server address that was used for position determination
-
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 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
Error handling
SUPL Terminal Initiation API uses the standard 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.
Memory overhead
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.
Related APIs
Related APIs
CommDDRSuplTerminalServer::Close()RSuplTerminalServer::Connect()RSuplTerminalSubSession::CanceRunSession()RSuplTerminalSubSession::Close()RSuplTerminalSubSession::GetPosition()RSuplTerminalSubSession::GetServerAddress()RSuplTerminalSubSession::GetSlpList()RSuplTerminalSubSession::Open()RSuplTerminalSubSession::RunSession()RunSession()TRequestStatus