API description
Location Centre API is a Server-Client type API that acts as a client interface
to the Location Centre Server, which provides the Location Centre related
services to all client applications.
Using this API, the Client application can:
-
Show a list of location based applications in a popup dialog and launch
them based on user selection.
-
Show a list of location based applications in a popup dialog and return
back the identifier for the user selected application.
-
Retrieve a list of location based applications registered with Location
Centre.
-
Launch a particular location based application directly.
-
Listen for notifications about changes to the state of location based
applications.
The logical type of this API is Virtual Machine API and Library API. The
technical type if this API is Server Client API.
Overview
Location Centre is an umbrella application from where other location based
applications can be viewed and launched. Location Centre API provides the
provision of incorporating Location Centre and Location Centre related services
into the Client applications. On launching, Location Centre is displayed as
a popup dialog as displayed below.
When the terminal user selecting any of these location based applications,
the selected item is launched either in the standalone mode or in the chained
(embedded) mode.
There are two types of registered applications:
Location based applications which can be displayed in Location Centre
|
|
|
Applications
|
Applications which can be launched using the generic Application framework.
|
|
Services/Content
|
Location based services/content which can be provided with certain
associated applications. Location Centre uses the Document handler class for
interpreting these services/contents and launching them in the associated
application.
|
Each location based application can be identified by a set of characteristics.
These characteristics are either specified by these applications when they
register with Location Centre (see
Location Centre
Registration API for details regarding registration with Location Centre)
or they are assigned to them by Location Centre on registration. Each application
can exhibit none, one or more of these characteristics. The characteristics
are of two types:
-
System characteristics:
The system characteristics are the characteristics
assigned by Location Centre to location based applications which register
with it. The registering applications are agnostic of this characteristics.
The system characteristics defined are:
System characteristics for Location applications
|
|
|
ROM based applications
|
This characteristic is associated with all location based applications
which are installed on the ROM.
|
-
Application characteristics:
The application characteristics
are the characteristics published by location based applications when registering
with Location Centre. These characteristics generally define the functionality
of the registering application which it wants to publish to the Client applications.
The characteristics attributes defined are describe in the following table:
Application characteristics for Location applications
|
|
|
Settings application
|
This characteristic is associated with all location based applications
which have Settings related functionality. These applications are used to
configure the user's terminal or the remote server for all Location related
features.
|
|
Personal data management application
|
This characteristic is associated with all location based applications
which have Personal Data Management related functionality. These applications
enable the user to manage his personal information either on the terminal
or on a remote server.
|
|
Navigation application
|
This characteristic is associated with all location based applications
which have Navigation related functionality. These applications help the terminal
user to navigate from one location to another.
|
|
Location based events application.
|
This characteristic is associated with all location based applications
which are related to Location based events. These applications are generally
based to trigger certain events based on the terminal's current Location.
|
|
Remote positioning application
|
This characteristic is associated with all location based applications
which have Remote positioning related functionality. These applications are
generally involved in determining the current location of other terminals
or objects.
|
|
Network service
|
This characteristic is associated with all location based applications
which are related to Network services. These applications are generally involved
in the exchange of Location related information and services over the network.
|
|
Application sending location enhanced messages
|
This characteristic is associated with all location based applications
which are used to send Location enhanced messages.
|
|
Application providing on device location based content
|
This characteristic is associated with all location based applications
which provide Location based content which is stored on the terminal.
|
|
Application providing remote location based content
|
This characteristic is associated with all location based applications
which provide Location based content that is stored remotely and needs to
be accessed from the remote server. These applications would need connection
to the network to access the Location based content.
|
|
Map based application
|
This characteristic is associated with all location based applications
which position a particular geographic location of a map.
|
The application characteristics and System characteristics mentioned above
can be extended in the future to accommodate further additions.
These characteristics can be used by the client applications when using
Location Centre API to customize the list of applications displayed in Location
Centre or when retrieving the list of applications.
Use cases
The use cases of Location Centre API are:
-
Launch Location Centre pop-up dialog with location based applications.
-
Select a location based application from Location Centre pop-up dialog.
-
Get a list of all location based applications.
-
Launch a specified location based application directly.
-
Listening for notifications from Location Centre.
API class structure
Location Centre API consists of client side interface classes to Location
Centre Server and data classes for applications registered with Location Centre.
Location Centre class descriptions
|
|
|
CLcService
|
CLcService class is a client side interface to Location
Centre. This class allows the Client application to incorporate Location Centre
and Location Centre related features into their application. Using this class,
the Client application can
-
Launch Location Centre as a popup dialog with all or a subset of location
based applications.
-
Select a location based application from Location Centre popup dialog.
-
Retrieve all or a subset of location based applications.
-
Launch a specified location based application directly.
-
Listening for notifications from Location Centre.
|
|
CLcLaunchParam
|
The class
CLcLaunchParam acts as the input to Location
Centre when the Client application wants to launch Location Centre with a
specified set of location based application. Each such object contains an
the Identifier of the application and the mode in which it must be launched
if the terminal user selects it.
|
|
CLcLocationAppInfo
|
The class
CLcLocationAppInfo holds information pertaining
to location based applications. Each CLcLocationAppInfo object
contains an unique identifier identifying the application, the name, icon
and the characteristics of the application.
|
|
CLcLocationAppInfoArray
|
The class
CLcLocationCentreAppInfoArray is a place
holder for the all location based application information objects. The class
contains a list of individual CLcLocationAppInfo objects.
|
|
TLcLocationAppFilter
|
The class
TLcLocationAppFilter defines the filtering
options that can be used for customizing Location Centre pop-up dialog. The
filtering can be done based on the System characteristics and the Application
characteristics defined in the Overview section.
|
|
MLcAppExitObserver
|
The class
MLcAppExitObserver acts as the interface
class definition which the Client application has to implement if it wants
to be notified of the application exit event incase the location based application
is launched as a chained (embedded) application.
|
|
MLcNotification
|
The class
MLcNotification acts as the interface class
definition which the Client Application has to implement if it wants to receive
notifications regarding the changes in status of the location based applications.
|
Related APIs
CLcLaunchParamCLcLocationAppInfoCLcLocationAppInfoArrayCLcLocationCentreAppInfoArrayCLcServiceMLcAppExitObserverMLcNotificationTLcLocationAppFilter
Using the Location Centre API
In order to use any service from Location Centre, the Client application
must first construct its own instance of the Location Centre Interface. This
can be done by calling the
CLcService::NewL() function which
creates a Location Centre interface object on the heap. All other operations
can be made on this instance. After the completion of all the desired operations,
the Client application must delete the instance of the created object to free
all the associated Location Centre resources.
If the Client application intends to provide a facility to the terminal
user to be able to launch location based applications as a chained (embedded)
application, then it must ensure that
CLcService the instance
is not deleted until the chained (embedded) application is closed (see use
case: Launch Location Centre pop-up dialog with an application exit observer for obtaining the termination event
from the chained (embedded) application) or until the destruction of the Client
application itself. If this is not ensured, on deleting the CLcService object,
there is a possibility that the chained (embedded) application would be closed
and no callback notification is issued.
In general, since Location Centre API is a client side interface to the
Location Centre server it is recommended that the Client application creates
an instance of this class in its constructor and deletes it in the destructor.
class CMyLcClient : public CBase
{
// ... Member functions
private:
CLcService iLcService;
// ... Other Data members
};
CMyLcClient::ConstructL()
{
// …..
// …..
// Create Location Centre interface.
iLcService = CLcService::NewL();
// …..
// …..
}
CMyLcClient::~CMyLcClient()
{
// …..
// …..
delete iLcService
// …..
// …..
}
The Client application does not require any capability to use Location
centre API.
Launch Location Centre pop-up dialog
Location Centre API can be used by Client applications to launch Location
Centre as a pop-up dialog. On launching Location Centre as a pop-up dialog,
all the Location based applications which are currently present on the user's
terminal would be displayed. The terminal user can then select any of the
listed location based applications and that the corresponding application
would be launched in the default mode. (The default mode for launching would
be the mode with which the application has registered with Location Centre.
See
Location Centre Registration API for more
details). When selecting an item from the displayed list, Location Centre
first validates it for its registration with Location Centre and only on successful
validation does it proceed with the launching.
When Location Centre is being displayed as a pop-up dialog, any changes
to the list of location based applications would be automatically reflected
in the pop-up and the Client application does not need to explicitly listen
to the notification events (see use case:
Listening for notifications for details on how to register for notifications
from Location Centre).
The following example illustrates Launching Location Centre pop up dialog
with all location based applications.
CMyLcClient::MyLocationCentreOperationL()
{
// Client operations
// ...
// ...
// Launch Location Centre popup in its default configuration
// This would launch the popup dialog with all location based applications
// The user can select any location based application from the list and the
// corresponding application would be launched in its default mode
iLcService->LaunchLocationCentreL();
// Other client operations
// ...
// ...
// ...
}
Launch Location Centre pop-up dialog with a filtered list of location
based applications
The Client application can launch Location Centre as a pop-up dialog with
a filtered list of location based applications. This can be achieved by passing
the filtering options to the use case:
Launch Location Centre pop-up dialog.
The filtering of applications can be based on two aspects, namely, the
System Characteristics and the Application Characteristics. In addition to
it, it can also specify the Launching mode for all the applications displayed
in the list. This would override the default launching mode that these applications
would have specified during their registration.
On invoking this use-case, Location Centre displays the requested applications
in a pop-up dialog. The terminal user can then select any of the listed applications
and that the corresponding application or content/service would be launched
in the specified mode (in case, the Client application has not specified any
mode for launching then the application would be launched in their default
mode).
In the example discussed below, the Client application uses Location Centre
to display all ROM based Settings related location based applications.
CMyLcClient::MyLocationCentreOperationL()
{
// Set the filter parameters
TLcLocationAppFilter filter;
// Only ROM based applications would be used for filtering
filter.SetSystemCharacteristic( CLcLocationAppInfo::ESysCharRomBased );
// Include only those those charatceristics specified by the System characteristics filter
filter.SetSysCharFilterConfiguration( TLcLocationAppFilter::EFilterStrict );
// Only Settings related applications would be used for filtering
filter.SetApplicationCharacteristic( CLcLocationAppInfo::EAppCharSettings );
// Include only those those charatceristics specified by the application characteristics filter
filter.SetAppCharFilterConfiguration( TLcLocationAppFilter::EFilterStrict );
// Launch Location Centre popup with the above filter
// This would launch the popup dialog with all ROM based Settings applications
// The user can select any Settings application from the list and the
// corresponding application would be launched in its default mode
iLcService->LaunchLocationCentreL( filter );
}
Launch Location Centre pop-up dialog with a specified list of location
based applications
The Client application can launch Location Centre as a pop-up dialog with
a specified list of location based applications. It can pass the list of applications
that it wants Location Centre to display (see use case:
Launch Location Centre pop-up dialog for details regarding the displaying
of Location Centre pop-up dialog).
In the example discussed below, the Client application uses Location Centre
to display GPS data and Landmarks application. It also specifies that GPS
data must be launched in the standalone mode if the user selects it and Landmarks
application in the chained (embedded) mode.
CMyLcClient::MyLocationCentreOperationL()
{
// Create the paramters array
RPointerArray<CLcLaunchParam> array;
// Set the first item of the array to be GPS data application which needs
// to be launched in the stand alone mode.
CLcLaunchParam* param1 = CLcLaunchParam::NewL( KGpsDataIdentifier, CLcLocationAppInfo::EStandAloneMode );
array.Append( param1 );
// Set the second item of the array to be Landmarks application which needs
// to be launched in the stand alone mode.
CLcLaunchParam* param2 = CLcLaunchParam::NewL( KLandmarksIdentifier, CLcLocationAppInfo::EChainedMode );
array.Append( param2 );
// Launch Location Centre popup with the above list of location based applications
// This would launch the popup dialog with GPS data and Landmarks application.
iLcService->LaunchLocationCentreL( array );
}
Launch Location Centre popup dialog without a specified list of location
based applications
The Client application can launch Location Centre as a popup dialog without
a specified list of location based applications. It can pass the list of applications
that it does not want Location Centre to display (see use case:
Launch Location Centre pop-up dialog for details regarding the displaying
of Location Centre pop-up dialog).
In the example discussed below, the Client application uses Location Centre
to display all location based applications other than GPS data and Landmarks
application. It also specifies that these applications must be launched in
the chained (embedded) mode when the terminal user selects on any of them.
CMyLcClient::MyLocationCentreOperationL()
{
// Create the paramters array
RArray<TPtrC> array;
// Append the GPS Data parameter object
array.Append( KGpsDataIdentifier );
// Append the Landmarks parameter object
array.Append( KLandmarksIdentifier );
// Launch Location Centre popup with the above list of location based applications
// This would launch the popup dialog with GPS data and Landmarks application.
iLcService->LaunchLocationCentreL( array, CLcLocationAppInfo::EStandAloneMode );
}
Launch Location Centre pop-up dialog with an Application exit observer
Location Centre API provides the Client application with a provision of
registering an observer to notify the exit of the selected location based
application. While using use case:
Launch Location Centre pop-up dialog the client application can also specify an observer.
Incase, the associated application content/service is launched as a chained
(embedded) application then on user exiting this application a notification
would be provided to Location Centre using the observer.
In the example discussed below, the Client application uses Location Centre
to display all location based applications. The class
CLcMyClient inherits
from MLcAppExitObserver and acts an observer to receive notifications
from Location Centre for termination of the launched application. Since, the CMyLcClient listens
for the termination of the launched application it is necessary that this
class holds the CLcService object as a member variable and
destroys it only after the application exit observer is invoked.
class CMyLcClient : public MLcAppExitObserver
{
// ...
// ...
// CMyLcClient member functions
// ...
// ...
public: // Inherited from MLcAppExitObserver
void HandleChainedLocationAppExitL( TInt aReason );
private:
// ..
// Other data members
// ..
CLcService iLcService;
}
void CMyLcClient::ConstructL()
{
iLcService = CLcService::NewL();
}
CMyLcClient::~CMyLcClient()
{
// ...
// Delete other variables.
// ...
delete iLcService;
}
void CMyLcClient::HandleChainedLocationAppExitL( TInt aReason )
{
// Handle Application exit operations
}
CMyLcClient::MyLocationCentreOperationL()
{
// Launch Location Centre popup in its default configuration
// The CMyLcClient also inherits from MLcAppExitObserver and passes itself as
// an observer for notification regarding the termination of the selected
// Location based Applicaiton
// This would launch the popup dialog with all location based applications
// The user can select any location based application from the list and the
// corresponding application would be launched in the chained mode
iLcService->LaunchLocationCentreL( CLcLocationAppInfo::EChainedMode, this );
}
Related APIs
CLcMyClientCLcServiceCMyLcClientMLcAppExitObserver
Select a location based application from the Location Centre pop-up
dialog
The Client application can select a location based application from Location
Centre popup dialog. When invoking this use-case, Location Centre displays
all the available (or a filtered list of location based applications) in a
pop-up dialog. The terminal user can then select any of the listed applications
and the identifier corresponding to it is returned.
The terminal user can now use the selected application identifier to launch
it in a particular mode directly (see use case:
Launch a specified location based application directly for launching a location
based application) or store it for future reference.
When Location Centre is being displayed as a pop-up dialog, any changes
to the list of location based applications would be automatically reflected
in the pop-up and the Client application does not need to explicitly listen
to the notification events (see use case:
Listening for notifications for details on how to register for notifications
from Location Centre)
CMyLcClient::MyLocationCentreOperationL()
{
// Place holder for the selected location based application
TPtrC identifer;
// Launch Location Centre popup in its default configuration
// This would launch the popup dialog with all location based applications
// The user can select any location based application from the list and the
// corresponding application's identifier would be returned to the caller.
identifier.Set( iLcService->SelectLocationApplicationL());
// The client can now operate on the identifier
}
Select a location based application from a filtered list of location
based applications
The Client application can select a location based application as specified
in use case:
Select a location based application from the Location Centre popup dialog. But instead of displaying all
applications the Client application can configure Location Centre to display
only a subset of the registered applications. The filtering can be imposed
in the same manner as described in use case: Launch Location Centre pop-up dialog with a filtered list of location based applications.
In the example discussed below, the Client application uses Location Centre
to select a location based application from all ROM based Settings related
location based applications.
CMyLcClient::MyLocationCentreOperationL()
{
// Set the filter parameters
TLcLocationAppFilter filter;
// Only ROM based applications would be used for filtering
filter.SetSystemCharacteristic( CLcLocationAppInfo::ESysCharRomBased );
// Include only those those charatceristics specified by the System characteristics filter
filter.SetSysCharFilterConfiguration( TLcLocationAppFilter::EFilterStrict );
// Only Settings related applications would be used for filtering
filter.SetApplicationCharacteristic( CLcLocationAppInfo::EAppCharSettings );
// Include only those those charatceristics specified by the application characteristics filter
filter.SetAppCharFilterConfiguration( TLcLocationAppFilter::EFilterStrict );
// Place holder for the selected location based application
TPtrC identifer;
// Launch Location Centre popup with the above filter
// This would launch the popup dialog with all ROM based Settings related location based applications
// The user can select any location based application from the list and the
// corresponding application's identifier would be returned to the caller.
identifier.Set( iLcService->SelectLocationApplicationL( filter ));
// The client can now operate on the identifier
}
Get a list of all location based applications
The Client application can obtain a list of all location based applications
that are currently registered and not-absent. This is the default behavior
which the Client Application would experience when the retrieval function
is invoked without any customizing. On invoking this use-case, Location Centre
returns back a list of the available location based applications.
The Client application can use this functionality either in the synchronous
mode or in the asynchronous mode. The Client application when using this function
in the asynchronous mode must use an Active object and not use
User::WaitForRequest(
).
CMyLcClient::MyLocationCentreOperationL()
{
CLcLocationAppInfoArray* locArray = NULL;
// Get all the location based applications which as currently present on the mobile terminal
locArray = iLcService->GetLocationApplicationsL();
// Assume ownership of the App info array
CleanupStack::PushL( locArray );
// ...
// ...
// Array Operations
// ...
// ...
// Pop and Destroy the Application information array
CleanupStack::PopAndDestroy( locArray );
}
class CMyLcClient : public CActive
{
public:
// ...
// Other member functions
// ...
public: // Ineherited from CActive
void RunL();
void DoCanel();
private:
// ...
// Other data members
// ...
CLcService iLcService;
CLcLocationAppInfoArray* iAppInfoArray;
};
void CMyLcClient::RunL()
{
if( iStatus.Int() == KErrNone )
{
// Now the iAppInfoArray is updated with the latest list from Location Centre.
// ...
// ...
// Array Operations
// ...
// ...
}
}
CMyLcClient::MyLocationCentreOperationL( CLcService& aLcService )
{
// Get all the location based applications which as currently present on the mobile terminal
iLcService->GetLocationApplicationsL( iStatus, iAppInfoArray );
SetActive();
}
Get a filtered list of location based applications
The Client application can obtain a filtered list of all location based
applications that are currently registered and not-absent. On invoking this
use-case, Location Centre returns back a list of the available applications
which satisfy the filtering criterion. The filtering can be imposed in the
same manner as described in use case:
Launch Location Centre pop-up dialog with a filtered list of location based applications.
The Client application can use this functionality either in the synchronous
mode or in the asynchronous mode.
Since, the list of applications is returned to the Client application in
this Use case, any changes to the list of location based applications would
not be communicated implicitly to the Client application. On the occurrence
of such an event, the list maintained by the Client application would be stale.
Its the responsibility of the Client application to listen for such notifications
by registering an observer to Location Centre and re-fetch the list as and
when the notifications are received.
In the example discussed below, the Client application uses Location Centre
to retrieve all ROM based Settings related location based applications.
The following code snippet explains the synchronous mode of retrieving
all ROM based Settings related location based applications.
CMyLcClient::MyLocationCentreOperationL()
{
// Set the filter parameters
TLcLocationAppFilter filter;
// Only ROM based applications would be used for filtering
filter.SetSystemCharacteristic( CLcLocationAppInfo::ESysCharRomBased );
// Include only those those charatceristics specified by the System characteristics filter
filter.SetSysCharFilterConfiguration( TLcLocationAppFilter::EFilterStrict );
// Only Settings related applications would be used for filtering
filter.SetApplicationCharacteristic( CLcLocationAppInfo::EAppCharSettings );
// Include only those those charatceristics specified by the application characteristics filter
filter.SetAppCharFilterConfiguration( TLcLocationAppFilter::EFilterStrict );
CLcLocationAppInfoArray* locArray = NULL;
// Get all the location based applications which as currently present on the mobile terminal
locArray = iLcService->GetLocationApplicationsL( &filter );
// Assume ownership of the App info array
CleanupStack::PushL( locArray );
// ...
// ...
// Array Operations
// ...
// ...
// Pop and Destroy Location Centre interface and the Application information array
CleanupStack::PopAndDestroy( locArray );
}
The following code snippet explains the asynchronous mode of retrieving
all ROM based Settings related location based applications.
class CMyLcClient : public CActive
{
public:
// ...
// Other member functions
// ...
public: // Ineherited from CActive
void RunL();
void DoCanel();
private:
// ...
// Other data members
// ...
CLcService iLcService;
CLcLocationAppInfoArray* iAppInfoArray;
};
void CMyLcClient::RunL()
{
if( iStatus.Int() == KErrNone )
{
// Now the iAppInfoArray is updated with the latest list from Location Centre.
// ...
// ...
// Array Operations
// ...
// ...
}
}
CMyLcClient::MyLocationCentreOperationL()
{
// Set the filter parameters
TLcLocationAppFilter filter;
// Only ROM based applications would be used for filtering
filter.SetSystemCharacteristic( CLcLocationAppInfo::ESysCharRomBased );
// Include only those those charatceristics specified by the System characteristics filter
filter.SetSysCharFilterConfiguration( TLcLocationAppFilter::EFilterStrict );
// Only Settings related applications would be used for filtering
filter.SetApplicationCharacteristic( CLcLocationAppInfo::EAppCharSettings );
// Include only those those charatceristics specified by the application characteristics filter
filter.SetAppCharFilterConfiguration( TLcLocationAppFilter::EFilterStrict );
// Get all the location based applications which as currently present on the mobile terminal
iLcService->GetLocationApplicationsL( iStatus, &filter, iAppInfoArray );
SetActive();
}
Launch a specified location based application directly
The Client application can launch a specified location based application
in the desired mode directly. The application that is to be launched is identified
by a Unique identifier which is specified by the Application or Content/Service
when it registers with Location Centre. See
Location
Centre Registration API for details regarding the registration procedure.
Location Centre first validates whether the application corresponding to
the identifier is currently registered with itself and on successful validation,
it launches the corresponding location based application. The Client application
can also specify the mode in which the applications must be launched.
In the example discussed below, the Client application uses Location Centre
to launch Landmarks application in the standalone mode.
CMyLcClient::MyLocationCentreOperationL()
{
// Launch Landmarks application in the Stand alone mode
iLcService->LaunchLocationApplicationL( KLandmarksIdentifier, CLcLocationAppInfo::EStandAloneMode );
}
Listening for notifications
The Client application can register for receiving notification of changes
in the state of the location based applications. The changes in states can
occur in the following contexts:
-
When a new application registers into Location Centre. In this case, the
application would be immediately available for all Location Centre operations.
-
When an already registered application de-registers. In this case, the
application will be removed from Location Centre. Hence, it would not be available
for any further Location Centre operations.
-
When a location based application is present on a removable media (like
Memory card) and the media is removed. In this case, for all practical purposes
the application behaves as in the previous context. The difference being that
the application does not get removed from Location Centre but is marked as
an Absent application. When the removable media is reinserted, the application
immediately becomes available for all Location Centre operations.
-
When an removable media containing an Absent application is reinserted.
In this case, the application would be immediately available for all Location
Centre operations.
-
When Location Centre server terminates prematurely. In this case, no further
notification would be issued and all further operations on Location Centre
would fail.
The Client application can listen to notifications by setting the Notification
observer to Location Centre. In case it want to stop listening for notifications,
it can remove the observer.
class CMyLcClient : public MLcNotification
{
// ...
// ...
// CMyLcClient member functions
// ...
// ...
public: // Inherited from MLcNotification
void LcStatusChangedL( TInt aErrorCode );
private:
// ...
// Data members
// ...
CLcService* iLcService;
}
void CMyLocClient::LcStatusChangedL( TInt aErrorCode )
{
// Handle Location centre status changed operations
// Generally this means that the previous information obtained from LC
// stands stale. For eg. If the client application had fetched a list
// of location based applications before the status change event was
// called then possibly, the list is now stale and the Client has to
// re-fetch the list.
}
CMyLcClient::MyLocationCentreOperationL()
{
// Register for notification
// CMyLcClient is inherited from MLcNotification. Hence, it acts as the
// observer to Location Centre where it communicates changes in states to
// location based applications
iLcService-> StartNotifyL( *this );
}
Error handling
Location Centre API uses the standard error reporting mechanism. In case
of irrecoverable error, panics are used. In all other conditions, errors are
reported using return codes and leaves.
The following table gives the summarization of all the error codes used
in Location Centre API
Location Centre API error codes
|
|
|
KErrInUse
|
If there is an outstanding request present on Location Centre.
|
|
KErrNotFound
|
If there is no location based application corresponding to the filter
parameters or identifier passed to Location Centre API.
|
|
KErrServerTerminated
|
If there is a premature termination of an outstanding request. This
might generally be due to the termination of the Location Centre server. On
occurrence of this error, any further requests to Location Centre would also
fail with the same error code.
|
|
KErrNotSupported
|
If the requested operation is not supported by Location Centre. For
e.g. this might occur when a Client application which does not have a UI context
requests for launching the Location Centre pop-up dialog.
|
The following table summarizes the panic codes defined by Location Centre
API. All Panics would be generated with a Panic category: LocationCentre
Location Centre API panic codes
| 0 |
ELcInvalidIndex |
Code with which Location Centre panics when the Client application
has requested for a Location Application information object from an index
which does not exit. |
Related APIs
KErrInUseKErrNotFoundKErrNotSupportedKErrServerTerminated
Memory overhead
Each location based application is identified by a Location Application
Information object. On an average considering that, the identifier for an
application is 256 characters long (considering UTF-8 format this would be
512 bytes), the display name being 64 characters long (128 bytes) and including
the memory for the icon object and the flags, the memory consumption would
be around 1K bytes for each object.
When the Client application is using Location Centre API for retrieving
the list of location based applications then the memory overhead is dependent
on the number of application informations that are returned. Since, the ownership
of the list is transferred back to the Client application it is advised that
they should destroy them as soon as they are not needed in order to release
unused heap memory.
When the Client application is using Location Centre API for displaying
Location Centre as a popup then in addition to fetching the list of location
based applications some additional memory is also required for displaying
the list in a popup dialog.
Extensions to the API
The list of characteristics (i.e. both System and Application characteristics)
and the type of location based applications can be extended in future.
Limitations of the API
There are no known limitations in the usage of this API.
Related APIs
CLcServiceCLcService::NewL()